Skip to main content

Domains

Verify a domain your organization owns once, and every image application and model in the organization can be served on it: at <app>.example.com, the application's name under the domain, or at a hostname you choose, such as shop.example.com. Verifying proves ownership with a DNS TXT record. It reserves hostnames for your applications; it does not create the DNS records that send traffic to them.

Before you start​

  • A domain or subdomain your organization controls, such as example.com or apps.example.com, and access to its DNS records.
  • To serve an application on it: a cluster with the Ingress and Certificates add-ons; for a model, the Gateway add-on. DNS Automation is optional.

In the console​

  1. Open Integrations > Domains and select Add domain.

  2. In Add a custom domain, enter the Domain name, for example apps.example.com, and select Claim domain. The console says "Claim created for apps.example.com. Add the DNS TXT record below, then verify."

  3. The domain opens under 1. Add this DNS record at your DNS provider, with a Type of TXT, a Name and a Value. Copy each and add the record at your DNS provider. The name is _astro-verification.<domain> and the value starts with astro-domain-verification=.

    Open zoom view

    A pending domain expanded, with its TXT record's Type, Name and Value, Copy buttons and Verify

    A pending domain expanded, with its TXT record's Type, Name and Value, Copy buttons and VerifyA pending domain expanded, with its TXT record's Type, Name and Value, Copy buttons and Verify
  4. Wait a few minutes for DNS to propagate, then select Verify. The console says "apps.example.com verified successfully." The challenge expires 24 hours after the claim; the expanded domain shows when.

You should see​

The domain reads Verified, with the date and "not used by an app yet". Expanded, it shows Ready to use and how its hostnames are formed.

Open zoom view

Integrations > Domains with apps.example.com Verified and the Ready to use note

Integrations > Domains with apps.example.com Verified and the Ready to use noteIntegrations > Domains with apps.example.com Verified and the Ready to use note

Once applications use it, the expanded domain lists each one under App hostnames: the hostname, the application, whether the name was generated or custom, and its status.

Serve an application on the domain​

On the Access step of Deploy application or Deploy model, pick Serve on <domain> under External access instead of Internal only (default). Leave Subdomain blank to serve at <app>.<domain>, or enter one to serve at <subdomain>.<domain>. The hostname is fixed once the application is created. A model also asks Who may call it: see Access policies.

The whole flow, domain to a working HTTPS endpoint: Custom domain.

How hostnames are reserved​

Hostnames are reserved per organization, so no two applications hold the same one. When <app>.<domain> is already held by another application, AstroPulse serves at a name with an id added instead, and the dry run says so, for example "shop.example.com is taken by app storefront; serving at …". Deleting an application frees its hostnames.

Custom domains serve image and model applications, whose exposure AstroPulse renders. A Helm chart or YAML application is reached the way its own manifests expose it.

Point DNS at your cluster​

Verifying a domain and reserving a hostname do not make it resolve. Point the hostname at the cluster's load balancer with a CNAME or A record, or install DNS Automation to create it. DNS Automation writes records with the cloud identity or credentials you give it; see Give it access to your cloud.

Until the record exists and propagates, the hostname is reserved but receives no traffic. If the hostname already points somewhere else, that service keeps receiving traffic until you change the record. AstroPulse never takes a hostname over.

Who owns a domain​

Several organizations may hold pending claims on the same domain; the first to verify it owns it, and an unverified claim never blocks the real owner. If your apex zone already hosts many services, claim a subdomain such as apps.example.com, so generated hostnames never collide with existing records.

Release a hostname or delete a domain​

Expand the domain. Under App hostnames, select Release on a row and confirm to free that hostname. Once no hostnames are left, select Delete domain and confirm. A domain with app hostnames cannot be deleted.

Other ways in​

  • Nova: ask it, for example "add example.com as a custom domain and show me the TXT record". Nova returns the record; publishing it is yours to do.
  • SDK and API: the same operations, in the API reference.

With astroctl​

Terminal
astroctl domain add example.com # claim it; prints the TXT record
astroctl domain get example.com # the record again, and the hostnames bound
astroctl domain verify example.com # after the record is published
astroctl domain list
astroctl domain unbind example.com --hostname shop.example.com --yes
astroctl domain delete example.com --yes

In an application manifest, set one of two fields under externalAccess:

application.yaml
apiVersion: platform.astropulse.io/v1
kind: Application
spec:
name: doc-shop
profileName: my-profile
source:
type: Image
image:
repository: nginxinc/nginx-unprivileged
tag: 1.27.5
externalAccess:
domain: apps.example.com # served at doc-shop.apps.example.com
# hostname: shop.apps.example.com # or at exactly this hostname

The dry run says where it will be served:

$ astroctl app apply -f application.yaml --dry-run
…
Where your app will be served
Your app will be at https://doc-shop.apps.example.com, presenting a certificate issued for doc-shop.apps.example.com.

Leave out externalAccess to keep the application inside the cluster. Every flag: astroctl domain.

Settings​

External accessexternalAccess.domain

A verified domain to serve the application under, at <app>.<domain>. Image and model applications only. Set this or hostname, never both.

Default
None: the application is internal only.
SubdomainexternalAccess.hostname

Serve the application at exactly this hostname: a verified domain's apex, or any hostname under a verified domain, such as shop.example.com or a.b.example.com. In the console, the Subdomain you enter forms it.

Default
None: domain generates the hostname.

If it's refused​

"The verification TXT record was not found at _astro-verification.example.com. Add the TXT record at your DNS provider, then retry. DNS changes can take a few minutes to reach every resolver."
Cause
The record is not published yet, or has not propagated.
Fix
Add the record with the Name the console shows, wait a few minutes, then select Verify again.
"The TXT record at _astro-verification.example.com does not contain the expected verification value."
Cause
The record holds another value, often one from an earlier claim.
Fix
Set it to the Value shown for this domain, then select Verify again.
"Verification failed: verification challenge expired. Delete and re-add the domain for a fresh challenge."
Cause
The domain was not verified within 24 hours of the claim.
Fix
Select Delete domain, add it again, and publish the new value: a new claim has a new value.
"domain "example.com" conflicts with an existing verified domain claim"
Cause
Another organization has verified this domain, or one that overlaps it.
Fix
Claim a subdomain only your organization controls, or have the other organization delete its claim.
"hostname "shop.example.com" is already bound"
Cause
Another application in the organization holds that hostname.
Fix
Pick another Subdomain, or release the hostname or delete the application that holds it.
"cannot be deleted while app bindings exist"
Cause
Applications still hold hostnames under the domain.
Fix
Release each hostname under App hostnames, or delete those applications, then delete the domain.
"is a hostname under a verified domain, not a verified domain itself: use externalAccess.hostname to serve at this exact hostname"
Cause
externalAccess.domain names a hostname, not the verified domain.
Fix
Move the value to externalAccess.hostname, or set domain to the verified domain.

Next​