api-company/docs/dns.md

DNS Configuration

Last updated: 2026-05-30
Status: Planned (Phase 6 pre-launch)

---

DNS Provider

DNS for leeworks.dev is managed externally (by the human operator via their registrar/DNS provider). The agent cannot directly create DNS records. This document tracks the required records for human operator action.

---

Required Records

All records should point to the cluster ingress IP. To find the current ingress IP:

kubectl get svc -n ingress-nginx ingress-nginx-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Subdomain	Type	Target	Purpose	TLS Required
zip.leeworks.dev	A	<cluster-ingress-ip>	ZIP Enrichment API	Yes (cert-manager)
holidays.leeworks.dev	A	<cluster-ingress-ip>	Holidays API	Yes (cert-manager)
aqi.leeworks.dev	A	<cluster-ingress-ip>	Air Quality API	Yes (cert-manager)
docs.leeworks.dev	A	<cluster-ingress-ip>	Documentation site	Yes (cert-manager)
status.leeworks.dev	A	<cluster-ingress-ip>	Gatus status page	Yes (cert-manager)
registry.leeworks.dev	A	<cluster-ingress-ip>	Container registry (Gitea)	Yes (cert-manager)
grafana.leeworks.dev	A	<cluster-ingress-ip>	Grafana (internal/restricted)	Yes (cert-manager)
vin.leeworks.dev	A	<cluster-ingress-ip>	VIN Decoder API	Yes (cert-manager)

---

TLS Certificate Management

TLS certificates are issued automatically by cert-manager using Let's Encrypt (ACME HTTP-01 or DNS-01 challenge).

Prerequisites

• cert-manager deployed in the cluster (part of Talos setup)
• A ClusterIssuer configured for Let's Encrypt

ClusterIssuer (Let's Encrypt Production)

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: legal@leeworks.dev
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
      - http01:
          ingress:
            class: nginx

Example Ingress with TLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: zip-enrichment-ingress
  namespace: zip-enrichment
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - zip.leeworks.dev
      secretName: zip-tls
  rules:
    - host: zip.leeworks.dev
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: zip-enrichment
                port:
                  number: 3000

---

Verification Steps

After DNS records are created:

# Check DNS resolution
dig zip.leeworks.dev +short
dig holidays.leeworks.dev +short
dig aqi.leeworks.dev +short
dig docs.leeworks.dev +short
dig status.leeworks.dev +short
dig registry.leeworks.dev +short
dig grafana.leeworks.dev +short
dig vin.leeworks.dev +short

# Check TLS certificates (once services are deployed)
curl -v https://zip.leeworks.dev/health 2>&1 | grep -E "SSL|certificate|issuer"

# Check cert-manager issued certs
kubectl get certificates -A

# Expect HTTP 200 on health endpoints
for host in zip.leeworks.dev holidays.leeworks.dev aqi.leeworks.dev; do
  echo -n "$host: "
  curl -s -o /dev/null -w "%{http_code}" https://$host/health
  echo
done

---

Action Required (Human Operator)

The following actions require human operator access to the DNS provider:

1. Log into the DNS provider managing leeworks.dev
2. Find the cluster ingress IP: kubectl get svc -n ingress-nginx ingress-nginx-controller
3. Create/update the 8 A records listed in the table above
4. Verify propagation: dig +trace zip.leeworks.dev

DNS propagation typically takes 5–60 minutes.

---

Current Status

• Cluster ingress IP confirmed
• zip.leeworks.dev → DNS record created
• holidays.leeworks.dev → DNS record created
• aqi.leeworks.dev → DNS record created
• docs.leeworks.dev → DNS record created
• status.leeworks.dev → DNS record created
• registry.leeworks.dev → DNS record created
• grafana.leeworks.dev → DNS record created
• vin.leeworks.dev → DNS record created
• TLS certificates issued and valid for all 8 subdomains