What is a domain in SeaGit?

A domain is a DNS zone that SeaGit manages on your behalf — for example example.com — backed by a DNS provider. It is a first-class resource, exactly like a provider, network, or cluster. You attach a domain to an environment, and from then on every deployment in that environment gets its own subdomain under it — my-app.example.com, api.example.com, pr-42.example.com — each with DNS and HTTPS handled for you.

The two add-ons that make a domain live

A domain on its own is just a zone and some credentials. What makes it actually resolve and serve HTTPS are two controllers running inside the cluster attached to the environment. This is the link between a domain and your clusters:

How it all connects: the flow

Put together, a domain is the hub that connects a DNS provider, an environment, and a cluster. Reading it end to end:

1. You connect a DNS provider and add a domain (zone) to it.
2. You create an environment and set that domain as its root domain, then attach one or more clusters.
3. Each attached cluster runs external-dns (writes records into the zone) and cert-manager (issues the wildcard certificate for the domain).
4. Now every deployment to that environment is published under the domain — dep-name.example.com — resolving to the cluster and served over HTTPS, with zero manual DNS or certificate steps.

The records SeaGit creates in your zone

You never edit records by hand, but it helps to know what appears in the zone. For each exposed deployment, external-dns writes an address record pointing the subdomain at the live load balancer, plus a TXT ownership record so it can tell which records it manages — and safely leave any records you created yourself untouched.

; ── managed automatically by external-dns ──

; address records — one per exposed subdomain, pointed at the live LB
my-app.example.com.        A      ALIAS → k8s-abc123….elb.amazonaws.com
api.example.com.           A      ALIAS → k8s-abc123….elb.amazonaws.com
pr-42.example.com.         A      ALIAS → k8s-abc123….elb.amazonaws.com

; ownership records — external-dns uses these to track what it owns
my-app.example.com.        TXT    "heritage=external-dns,external-dns/owner=…"

; on non-AWS DNS (Cloudflare / PowerDNS) the address record is a CNAME:
; my-app.example.com.      CNAME  <load-balancer-hostname>

Because the address record targets the load balancer indirectly, external-dns can silently re-point it if the load balancer is ever rebuilt (for example after a cluster stop/start) — your subdomain never changes.

How a request resolves, end to end

Following a single request to my-app.example.com shows how the domain, the add-ons, and the cluster fit together:

1. DNS lookup — the domain is delegated to its zone, where external-dns has published the address record. The name resolves to the cluster's load balancer.
2. TLS handshake — the load balancer (or in-cluster NGINX) presents the wildcard certificate cert-manager issued for *.example.com, so HTTPS is valid with no per-subdomain setup.
3. Ingress routing — inside the cluster the ingress controller matches the host header and forwards the request to the right service and pod.
4. Response — your app answers. Every other subdomain under the domain follows the exact same path.

Wildcards & per-deployment subdomains

Because cert-manager issues a wildcard for the domain and external-dns writes a record per ingress, anything under the domain is covered the moment it exists. This is what makes ephemeral deployments and preview environments work: a new preview slot such as pr-42.example.com gets its own record and is already inside the wildcard certificate — no new certificate request, no DNS edit.

One domain across multiple clusters

When an environment has more than one cluster attached, the same hostname is served from several clusters at once. Each cluster's external-dns contributes its own record for that hostname, and SeaGit distinguishes them with a routing policy so they don't collide:

• Weighted — used for multiple clusters in the same region. Each cluster gets a weighted record for the hostname, so traffic is spread across them.
• Latency-based — used across different regions. Each region's record is tagged with its region, and visitors resolve to the nearest one. See the multi-region guide.
• Failover — one cluster serves traffic; another is a standby that only receives traffic if the primary is unhealthy.

In every case there is still one domain and one wildcard certificate — only the record shape underneath differs. Routing policies are configured on the environment and require a paid plan.

Bring your own vs. managed subdomain

The ingress class you choose decides which authority issues the cert (cert-manager/Let's Encrypt on nginx, AWS ACM on ALB). See Certificates & TLS for the full matrix.

Provider-specific setup & delegation

Adding the DNS provider is a one-time step. What each needs — and the delegation gotchas to know:

Domain lifecycle

A domain moves through a few clear states:

1. Connect — add the DNS provider and register the domain (zone) against it.
2. Delegate — for a bring-your-own domain, point the registrar's name servers at the zone so it becomes authoritative. Managed subdomains skip this.
3. Active — attach the domain to an environment. As deployments go out, external-dns and cert-manager populate records and certificates automatically.
4. Destroy — tears down the cloud-side zone and the records SeaGit created. A domain must be destroyed before it can be deleted.
5. Delete — removes the domain from SeaGit entirely.

Cross-account domains

The domain's zone does not have to live in the same cloud account as the cluster. When they differ, external-dns assumes a role into the account that owns the zone to write records, and cert-manager solves its DNS-01 challenge in that same zone to issue the certificate. This is common in multi-account setups and in multi-region clusters, where one shared domain fronts clusters in several accounts or regions.

Troubleshooting

A subdomain doesn't resolve

Check three things in order: (1) the domain is delegated to the right zone (registrar NS records match); (2) the cluster's external-dns add-on is installed and healthy, with write access to the zone; (3) enough time has passed for propagation. A freshly started cluster also needs a few minutes to rebuild its load balancer before records update.

My TLS certificate is stuck "pending"

cert-manager issues wildcard certs with a DNS-01 challenge, so it needs solver access to the same zone external-dns writes to. If the zone lives in another account, confirm the cross-account role is in place. On Cloudflare, make sure the relevant records are DNS-only (grey cloud). See Certificates & TLS.

A record points at the wrong load balancer

Never CNAME anything directly at the raw *.elb.amazonaws.com hostname — it changes on stop/start. Point custom domains at your stable SeaGit subdomain instead, and let external-dns own the underlying record. Full detail in DNS in Practice.

Frequently Asked Questions

Related