EKS collector custom domain — Customer-managed DNS, imported certificate

The customer owns the DNS and supplies the certificate. Snowplow only serves it.

Start at EKS collector custom domains overview if you are not sure this is the right path.

This is the common shape for a customer fronting the collector with Cloudflare: they keep the record, and they issue a Cloudflare Origin certificate for us to present.

Snowplow never writes a Route53 record for these domains. There is no certificate validation step either, because the customer already has the certificate.

Consul keys

customer/<client>/aws_rt_pipeline_<env>/input/collector/dns/external_imported_cert_map
customer/<client>/aws_rt_pipeline_<env>/input/collector/dns/staging/external_imported_cert_map

Both are a JSON object mapping domain to k8s_certificate environment name. Default is {}.

{"collector.acme.com": "cert1"}

Neither key touches DNS. The difference is bookkeeping: staging/ means we are serving the domain but the customer has not repointed yet, the final key means they have.

Steps

1. Get the certificate from the customer

Ask for the full certificate chain and the private key, in PEM format, covering the collector domain. Take it through an approved secure channel.

2. Deploy a k8s_certificate stack

Pick a short environment name for this certificate, for example cert1.

Store the material in Vault at:

secret/customer/<client>/k8s_certificate_<cert_env>

with fields cert (the full chain) and key (the private key).

Set the Consul inputs under customer/<client>/k8s_certificate_<cert_env>/input/:

Deploy the k8s_certificate stack with the stacks/deploy handler, using workspace
<client>-<cert_env>.

3. Stage the domain on the collector

Add the entry to collector/dns/staging/external_imported_cert_map and apply aws_rt_pipeline. The domain is now served on the NLB, while the customer's record still points wherever it pointed before.

4. Ask the customer to repoint the domain

Give them the NLB IPs from aws_eks_namespace_<env>/output/load_balancer_public_ip_addresses, or
run aws/external_collector_cert_validation 0.1.0 to print them. They replace their record with A records for each IP.

If they front the collector with a CDN or proxy, the origin must send the collector hostname as SNI. Traefik routes on SNI, where the old ALB did not. A proxy that sends its own hostname breaks TLS.

5. Promote

Once dig +short <domain> returns the NLB IPs, move the entry from
staging/external_imported_cert_map to external_imported_cert_map and apply. Remove it from the staging map — leaving it in both fails the apply.

Renewals

An imported certificate does not renew itself. Track the expiry, which the k8s_certificate stack publishes as cert_expiry. When the customer sends a replacement, update the Vault secret and redeploy the same k8s_certificate environment. The collector needs no change.

Verify

dig +short <domain>
curl -sI https://<domain>/health

aws/collector/validate_eks_collector 0.1.0 curls each ingress hostname pinned to the NLB IPs and prints the certificate served. For a Cloudflare Origin certificate it falls back to an unvalidated check with a SAN comparison, because that certificate is not trusted by public roots.

Common failures