DNS

how does dns work

Managing the Domains

The project uses a single primary domain:

wiperinstall.rainx.com — main domain serving the frontend, backend API and infrastructure services (ArgoCD, Tekton, Grafana, Sentry, Karma, Alertmanager, Teleport)

DNS management is handled via Amazon Route53. This means that DNS configurations—such as A records, CNAMEs, and other record types—are handled and stored in hosted zones within Route53.

The name servers (NS records) provided by Route53 were configured in the domain registrar settings. This delegates DNS resolution control to AWS Route53.

Kubernetes and ExternalDNS Integration

Inside the Kubernetes cluster where our applications are deployed, we use ExternalDNS, a tool that automatically synchronizes Kubernetes resources (like Ingress and Service objects) with DNS records in the DNS provider—in this case, Amazon Route53.

What is `external-dns` and How It Works

external-dns is a Kubernetes add-on that automatically manages DNS records for your services and ingress resources based on what’s running in cluster.

It enables you to automate the creation or update of DNS records in AWS Route53 — without manual zone updates.

How `external-dns` Works

Monitors Kubernetes Resources external-dns watches resources like Ingress and Service in cluster.
Extracts Hostnames Based on annotations or specific fields (e.g., spec.rules.host in Ingress), it determines which DNS records should exist.
Syncs with DNS Provider Using your DNS provider’s API (e.g., AWS Route53), it creates or updates the corresponding DNS records (A, CNAME, etc.).
Handles Updates and Deletions Automatically If the underlying resources are changed or deleted, external-dns will automatically update or remove the DNS records.

Example Use Case

Here’s a sample Ingress configuration (mirrors apps/prod/values.frontend.yaml):

ingress:
  enabled: true
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/add-base-url: "true"
    nginx.ingress.kubernetes.io/rewrite-target: /
  hosts:
    - host: wiperinstall.rainx.com
      paths:
        - path: /
          pathType: Prefix
          serviceName: frontend
          servicePort: http
  tls:
    - hosts:
        - wiperinstall.rainx.com
      secretName: wiperinstall.rainx.com-crt

ExternalDNS Configuration

ExternalDNS has IAM access to Route53 hosted zones.
It is configured in upsert-only, meaning it does not delete DNS records that were created manually or by other tools.
It only creates records that are relevant to current Kubernetes objects.
Domain filters: wiperinstall.rainx.com.

See more instruction in the official documentation

Workflow: DNS Record Creation During Application Deployment

When deploying a new application in the cluster, an Ingress object is created with a specified host, such as api.wiperinstall.rainx.com.
ExternalDNS scans all Ingress and Service objects in the cluster, collecting host information.
Upon detecting the new Ingress with the host api.wiperinstall.rainx.com, ExternalDNS interacts with the Route53 API and creates the corresponding DNS record (typically an A record with an ALIAS to a Load Balancer address).
Once the record appears in Route53, the domain name begins resolving to the correct IP or ALIAS target, enabling access to the application via the specified URL.

Hosted Zones Overview

`wiperinstall.rainx.com` hosted zone

This is our main hosted zone, managing all production traffic, core and service applications, as well as infrastructure-related services. It includes DNS records for:

Argo CD (argo-cd.wiperinstall.rainx.com)
Backend API (api.wiperinstall.rainx.com)
CDN (cdn.wiperinstall.rainx.com)
Docs (docs.wiperinstall.rainx.com)
Frontend (wiperinstall.rainx.com)
Grafana (grafana.wiperinstall.rainx.com)
Tekton Dashboard (tekton.wiperinstall.rainx.com)
Tekton Webhook (tekton-webhook.wiperinstall.rainx.com)

DNS