Menu
Platform
AI
App store purchases
Database
Flags
Jobs and cron
Localization
Monitoring
Notifications
Payments
Queues
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Domains
A name a project controls, the record that proves it, and what deleting it does
Today this runs on the management API
Add a domain with POST /v1/projects/{id}/domains, attach hostnames under /v1/projects/{id}/domains/{domain_id}/hostnames, and check them with …/hostnames/{hostname_id}/check; the Network quickstart walks through it. The sylphx network domains commands below are not served at api.sylphx.com.
A Domain is a name a project controls. It is verified once, before any certificate or Route uses it, and nothing serves the name until it is. This page takes a name from creation to a verified Domain, and says what deletion is fenced by.
#Create the name
spec.domain_name is the fully qualified name, and it is the one field a
Domain needs. A wildcard is refused, so a Domain is always one exact name.
| Field | Type | What it is |
|---|---|---|
domain_name | stringrequired | The fully qualified name, for example example.com. Wildcards are refused. |
verification_method | VerificationMethod | How control is proven; default TXT. One of txt, cname. |
sylphx network domains create \
--parent orgs/acme/projects/shop \
--spec.domain-name shop.example.com \
--spec.verification-method txtThe id is the name with dots as dashes, so this Domain is shop-example-com
and its name is orgs/acme/projects/shop/domains/shop-example-com. The server
assigns an id when you leave it out, and the dom_ id it reports is never
reused.
#Prove you control it
Verification is a DNS record you publish. Read the Domain back and
status.verification has it: record_name is the name to publish, for example
_sylphx-verify.example.com, record_type is TXT or CNAME, and
record_value is the value.
sylphx network domains get orgs/acme/projects/shop/domains/shop-example-comThe platform checks the record at a sweep, and verify checks it now instead:
sylphx network domains verify orgs/acme/projects/shop/domains/shop-example-comstatus.verified says whether control was proven and status.verify_time is
when it was last proven. A Domain that is not verified reports it in
status.conditions: Ready, Reconciling or Stalled.
Verification is fail-closed
Nothing that serves traffic uses an unverified name. A Route's host must be a verified Domain or a subdomain of one, so an unproven name is not a slow name — it is a name that cannot be pointed anywhere. Routes covers what a host may be.
#Update it
verification_method changes through update like any other spec field, which
is useful when a zone will not take the record you first asked for. The same
call takes validate_only, which runs every check and writes nothing, and
allow_missing, which creates the Domain when it does not exist — the
declarative upsert a pipeline wants.
sylphx network domains update orgs/acme/projects/shop/domains/shop-example-com \
--spec.verification-method cnameEvery change to spec increases the Domain's generation, and the status reports
the generation it was computed from, so a change that has not landed yet is
visible as an older observed_generation.
#Delete it
Deleting a Domain is destructive: the CLI asks before it runs, and the API
takes an etag that must match the Domain's current one. Delete with the etag
of the Domain you read, not of the one you remember.
sylphx network domains delete orgs/acme/projects/shop/domains/shop-example-com --yesTwo more fields soften a delete: allow_missing succeeds when the Domain is
already gone, and validate_only reports what would happen without happening.
A delete that the Domain's own state forbids fails with INVALID_STATE rather
than removing something in use.