Skip to content
by Shift Engineering

DNS & TLS

Admin guide

Greenlight uses one delegated DNS zone for the control plane and every app. You make a single change in your parent DNS — delegating that zone to Greenlight’s managed DNS zone — and Greenlight owns every record inside it from then on. There is no per-app DNS step, ever.

The one thing you do: delegate the zone

Section titled “The one thing you do: delegate the zone”

At install you chose a Greenlight host, for example greenlight.acme.com. That host is the delegated zone: Greenlight lives at the zone apex, and apps live one level down at <app>.greenlight.acme.com.

To delegate it, create NS records for that zone in your parent DNS (the zone for acme.com), pointing at the four nameservers the wizard shows you:

greenlight.acme.com.   NS   ns1-NN.azure-dns.com.
greenlight.acme.com.   NS   ns2-NN.azure-dns.net.
greenlight.acme.com.   NS   ns3-NN.azure-dns.org.
greenlight.acme.com.   NS   ns4-NN.azure-dns.info.

This NS delegation is the only manual DNS action. Once the records are in, there is nothing to click: the wizard re-checks every few seconds and moves on by itself when delegation goes live. After NS delegation is confirmed, the wizard stops re-checking it — a later stale lookup cannot undo that step while the certificate issues. Expect a short wait — public resolvers cache “this name doesn’t exist yet” answers for a few minutes.

The records Greenlight creates for you

Section titled “The records Greenlight creates for you”

As soon as you reach the DNS & HTTPS step, Greenlight writes the platform records itself — no button, and it does not wait for your delegation to propagate, so they are in place the moment the referral goes live:

Record Points at Covers
greenlight.acme.com A (apex) Traefik load-balancer address or addresses the control plane
*.greenlight.acme.com A (wildcard) the same ingress target every deployed app

You never hand-create the control-plane A record or any per-app record. The wildcard already resolves every app host.

On a private install the public zone holds NS, SOA, and the _acme-challenge TXT records only. Greenlight writes no apex A, and deletes the apex and wildcard A records an install wrote while it was public. You publish the control-plane name and the app wildcard in private DNS, for your company networks only: at the internal address the installer prints, or, when you reach the install through Azure Private Link, Private Service Connect, or AWS PrivateLink, at your endpoint’s address.

The certificate: one DNS-01 wildcard

Section titled “The certificate: one DNS-01 wildcard”

Because the whole zone is delegated to Greenlight, a single Let’s Encrypt wildcard certificate secures everything:

dnsNames: [ greenlight.acme.com, *.greenlight.acme.com ]
  • ACME is the protocol cert-manager uses to request and renew the certificate.
  • DNS-01 is the challenge it uses: cert-manager writes a temporary _acme-challenge TXT record into the delegated zone, which is possible precisely because Greenlight controls the zone. The challenge never touches the edge proxy.
  • HTTP-01 is not used in this model. It returns only for custom domains in your own un-delegated zone Deferred.

How the wizard verifies it

Section titled “How the wizard verifies it”

The DNS & HTTPS step runs four checks, in order, on a repeating timer — you never press Verify — and only enables the identity-provider and GitHub App steps once they pass:

  1. NS records resolve — the zone’s NS records resolve through a recursive resolver reachable from inside your cluster and match your zone’s own nameservers. This catches “you haven’t created the NS records yet” early.

  2. Delegation confirmed — the apex A resolves to the ingress IP through a recursive resolver. Because the zone is public, this only succeeds once delegation is actually live.

  3. Certificate ready — Greenlight requests the wildcard Certificate the moment delegation is confirmed, then cert-manager reports it Ready (the DNS-01 challenge succeeded end-to-end).

  4. HTTPS healthz — an HTTPS request to https://greenlight.acme.com/healthz returns 200 over a valid Let’s Encrypt chain.

A check that is simply not finished yet — delegation still propagating, the certificate still issuing — shows as in progress, with the elapsed time and a countdown to the next check, not as a failure. Certificates typically issue a few minutes after delegation is confirmed, so you can leave the page open. Only something that needs you shows up as a failure.

Before the control plane has a name

Section titled “Before the control plane has a name”

Until the apex A resolves and the certificate issues, https://greenlight.acme.com is unreachable, so you run the wizard on a bootstrap URL that reaches the ingress directly:

The raw Azure bootstrap URL: http://<label>.<region>.cloudapp.azure.com/install.

Once HTTPS verifies, Continue saves that step and opens the Greenlight host over HTTPS so you land on identity-provider setup.

Continuing also retires the bootstrap URL, permanently. It is a temporary address for exactly this gap, so once you are demonstrably on https://greenlight.acme.com it stops routing: from then on that plain-HTTP address — and any other name pointed at the ingress — answers nothing, while greenlight.acme.com and every app hostname work as normal. The ingress address itself does not change; only the temporary route is withdrawn. Nothing reopens it: not a repeated installer run, not a repair, not an automatic update. Bookmark the HTTPS URL before you continue.

Greenlight withdraws it only after checking for itself that https://greenlight.acme.com is serving with a trusted certificate. Until it is, Continue keeps you on this step and the bootstrap URL keeps working, so no one who can reach that address can cut you off mid-install.

If the wizard cannot withdraw the route, it stops on this step instead of moving on and gives you the HTTPS URL to open, because the temporary address may already have stopped working. Opening that URL finishes the step automatically. Your DNS records and certificate are unaffected.

On an installation that finished setup while the bootstrap URL still answered, Greenlight withdraws it within a minute of the control plane updating. Nothing changes for anyone already using https://greenlight.acme.com.