EKS collector custom domains overview

Internal support / SRE reference. Covers the EKS collector in aws_rt_pipeline 3.0.0.

The EKS collector serves custom domains through Traefik behind a static-IP NLB. To add a custom
domain you set one Consul key and redeploy the pipeline. This page tells you which key.

Pick the path

Two questions decide it.

1. Who manages the DNS record?

   • Snowplow-managed — the zone is delegated to the customer's Snowplow AWS account, so we write
     the Route53 record ourselves. The Consul keys call this delegated.

   • Customer-managed — the customer keeps DNS in their own provider (Cloudflare, Namecheap,
     Route53 in their own account). We never write a record; the customer points it at our NLB IPs.
     The Consul keys call this external.

2. Where does the certificate come from?

   • ACM — issued by AWS ACM through the in-cluster ACK controller. Default for custom domains.

   • Imported — the customer supplies their own certificate and private key. Requires a separate
     k8s_certificate stack deployment.

   • cert-manager — Let's Encrypt, issued in-cluster. Only works once DNS already resolves to the
     NLB, so it cannot be pre-staged.

The pipeline's own *.collector.snplow.net domain is separate: see
EKS collector primary snplow.net domain.

Where the keys live

All keys sit under:

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

Set them in the Snowdrift UI, or with the stacks/upsertor handler. Then apply the pipeline with
the stacks/deploy handler for aws_rt_pipeline.

Prerequisites

Before adding any custom domain to an EKS collector:

• collector/_deploy_eks is true — the collector runs on EKS.

• collector/_deploy_nlb is true — the primary record points at the Traefik NLB.

• The aws_eks_namespace stack has published the NLB IPs. If it has not, an apply that points a
  domain at the NLB fails with a clear error naming the domain.

Rules the apply enforces

Terraform fails the apply, with a readable message, if you break any of these:

• A domain appears in exactly one key. Not delegated and external. Not ACM and imported and
  cert-manager.

• A domain is not in both a staging/ key and its final key. Remove the staging entry when you
  promote.

• The primary *.collector.snplow.net domain is never listed in a cert-manager key.

The staging/ keys

Each ACM and imported-cert path has a staging/ twin, for example
collector/dns/staging/delegated_ack_managed_domains.

A staging key serves the domain on the EKS collector but leaves DNS alone. Use it when:

• You are migrating a domain off the old EC2/ALB collector and want to validate before cutover.

• You are waiting on the customer to act — to add a validation CNAME, or to repoint their record.

Once the certificate is issued and the customer has done their part, move the domain from the
staging/ key to the final key and reapply. That is the cutover.

cert-manager has no staging key, because the certificate cannot be issued until DNS already points
at the NLB.

Useful handlers