Eve library

DNS & SSL Configuration

Guide

Revision 1

On this page

Comprehensive guide for DNS management and SSL/TLS certificate configuration for the Lilith platform.

Table of Contents#

Overview#

DNS Architecture#

text
┌─────────────────────────────────────────────────────────────────────────┐
│                          Route53 Hosted Zones                            │
│  ┌──────────────────────┐    ┌──────────────────────┐                   │
│  │   Public Zone        │    │   Private Zone       │                   │
│  │   lilith.app         │    │   internal.lilith    │                   │
│  │                      │    │                      │                   │
│  │  api.lilith.app      │    │  auth.internal       │                   │
│  │  app.lilith.app      │    │  content.internal    │                   │
│  │  cdn.lilith.app      │    │  ai.internal         │                   │
│  └──────────────────────┘    └──────────────────────┘                   │
└─────────────────────────────────────────────────────────────────────────┘
              │                              │
              ▼                              ▼
┌─────────────────────────┐    ┌─────────────────────────┐
│      CloudFront         │    │        EKS Cluster      │
│   (CDN & Edge)          │    │   (Internal Services)   │
│                         │    │                         │
│   ALB/NLB               │    │   CoreDNS               │
│   API Gateway           │    │   Service Discovery     │
└─────────────────────────┘    └─────────────────────────┘

Domain Hierarchy#

Domain Purpose Environment
lilith.app Production Production
staging.lilith.app Staging Staging
dev.lilith.app Development Development
internal.lilith.app Internal services All

Domain Strategy#

Subdomain Structure#

text
lilith.app                    # Main website
├── api.lilith.app           # API Gateway / BFF
├── app.lilith.app           # Web application
├── cdn.lilith.app           # CloudFront CDN
├── ws.lilith.app            # WebSocket endpoints
├── auth.lilith.app          # Authentication endpoints
├── admin.lilith.app         # Admin dashboard
├── docs.lilith.app          # Documentation
└── status.lilith.app        # Status page

staging.lilith.app           # Staging environment
├── api.staging.lilith.app
├── app.staging.lilith.app
└── ...

internal.lilith.app          # Private hosted zone
├── auth.internal.lilith.app
├── content.internal.lilith.app
├── ai.internal.lilith.app
└── ...

Environment DNS#

Environment API Domain App Domain
Production api.lilith.app app.lilith.app
Staging api.staging.lilith.app app.staging.lilith.app
Development api.dev.lilith.app app.dev.lilith.app

Route53 Configuration#

Terraform Configuration#

hcl
# Public hosted zone
resource "aws_route53_zone" "public" {
  name    = var.domain_name
  comment = "Lilith public DNS zone"

  tags = {
    Environment = var.environment
    Project     = "lilith"
    ManagedBy   = "terraform"
  }
}

# Private hosted zone for internal services
resource "aws_route53_zone" "private" {
  name    = "internal.${var.domain_name}"
  comment = "Lilith private DNS zone for service discovery"

  vpc {
    vpc_id = module.networking.vpc_id
  }

  tags = {
    Environment = var.environment
    Project     = "lilith"
    ManagedBy   = "terraform"
  }
}

# Staging subdomain zone (delegated)
resource "aws_route53_zone" "staging" {
  count = var.environment == "prod" ? 1 : 0
  name  = "staging.${var.domain_name}"

  tags = {
    Environment = "staging"
    Project     = "lilith"
  }
}

# NS records for subdomain delegation
resource "aws_route53_record" "staging_ns" {
  count   = var.environment == "prod" ? 1 : 0
  zone_id = aws_route53_zone.public.zone_id
  name    = "staging.${var.domain_name}"
  type    = "NS"
  ttl     = 300
  records = aws_route53_zone.staging[0].name_servers
}

DNS Records#

hcl
# API endpoint (ALB)
resource "aws_route53_record" "api" {
  zone_id = aws_route53_zone.public.zone_id
  name    = "api.${var.domain_name}"
  type    = "A"

  alias {
    name                   = module.load_balancer.alb_dns_name
    zone_id                = module.load_balancer.alb_zone_id
    evaluate_target_health = true
  }
}

# CDN endpoint (CloudFront)
resource "aws_route53_record" "cdn" {
  zone_id = aws_route53_zone.public.zone_id
  name    = "cdn.${var.domain_name}"
  type    = "A"

  alias {
    name                   = module.cdn.cloudfront_domain_name
    zone_id                = module.cdn.cloudfront_hosted_zone_id
    evaluate_target_health = false
  }
}

# WebSocket endpoint (NLB)
resource "aws_route53_record" "ws" {
  zone_id = aws_route53_zone.public.zone_id
  name    = "ws.${var.domain_name}"
  type    = "A"

  alias {
    name                   = module.load_balancer.nlb_dns_name
    zone_id                = module.load_balancer.nlb_zone_id
    evaluate_target_health = true
  }
}

# Health check for API endpoint
resource "aws_route53_health_check" "api" {
  fqdn              = "api.${var.domain_name}"
  port              = 443
  type              = "HTTPS"
  resource_path     = "/health"
  failure_threshold = 3
  request_interval  = 30

  tags = {
    Name = "api-health-check"
  }
}

Failover Configuration#

hcl
# Primary record (us-east-1)
resource "aws_route53_record" "api_primary" {
  zone_id = aws_route53_zone.public.zone_id
  name    = "api.${var.domain_name}"
  type    = "A"

  failover_routing_policy {
    type = "PRIMARY"
  }

  set_identifier  = "primary"
  health_check_id = aws_route53_health_check.api_primary.id

  alias {
    name                   = module.load_balancer_primary.alb_dns_name
    zone_id                = module.load_balancer_primary.alb_zone_id
    evaluate_target_health = true
  }
}

# Secondary record (eu-west-1)
resource "aws_route53_record" "api_secondary" {
  zone_id = aws_route53_zone.public.zone_id
  name    = "api.${var.domain_name}"
  type    = "A"

  failover_routing_policy {
    type = "SECONDARY"
  }

  set_identifier = "secondary"

  alias {
    name                   = module.load_balancer_secondary.alb_dns_name
    zone_id                = module.load_balancer_secondary.alb_zone_id
    evaluate_target_health = true
  }
}

SSL/TLS Certificates#

AWS Certificate Manager (ACM)#

hcl
# Primary domain certificate
resource "aws_acm_certificate" "main" {
  domain_name               = var.domain_name
  subject_alternative_names = [
    "*.${var.domain_name}",
    "*.staging.${var.domain_name}",
    "*.dev.${var.domain_name}"
  ]
  validation_method = "DNS"

  lifecycle {
    create_before_destroy = true
  }

  tags = {
    Environment = var.environment
    Project     = "lilith"
  }
}

# DNS validation records
resource "aws_route53_record" "cert_validation" {
  for_each = {
    for dvo in aws_acm_certificate.main.domain_validation_options : dvo.domain_name => {
      name   = dvo.resource_record_name
      record = dvo.resource_record_value
      type   = dvo.resource_record_type
    }
  }

  allow_overwrite = true
  name            = each.value.name
  records         = [each.value.record]
  ttl             = 60
  type            = each.value.type
  zone_id         = aws_route53_zone.public.zone_id
}

# Certificate validation
resource "aws_acm_certificate_validation" "main" {
  certificate_arn         = aws_acm_certificate.main.arn
  validation_record_fqdns = [for record in aws_route53_record.cert_validation : record.fqdn]
}

CloudFront Certificate (us-east-1)#

hcl
# CloudFront requires certificates in us-east-1
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

resource "aws_acm_certificate" "cloudfront" {
  provider                  = aws.us_east_1
  domain_name               = "cdn.${var.domain_name}"
  subject_alternative_names = ["*.cdn.${var.domain_name}"]
  validation_method         = "DNS"

  lifecycle {
    create_before_destroy = true
  }
}

External DNS#

Installation#

yaml
# External DNS deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: external-dns
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: external-dns
  template:
    metadata:
      labels:
        app: external-dns
    spec:
      serviceAccountName: external-dns
      containers:
        - name: external-dns
          image: registry.k8s.io/external-dns/external-dns:v0.14.0
          args:
            - --source=service
            - --source=ingress
            - --domain-filter=lilith.app
            - --provider=aws
            - --policy=sync
            - --aws-zone-type=public
            - --registry=txt
            - --txt-owner-id=lilith-eks-${ENVIRONMENT}
            - --txt-prefix=externaldns-
          env:
            - name: AWS_DEFAULT_REGION
              value: us-east-1

Service Account with IRSA#

hcl
resource "aws_iam_role" "external_dns" {
  name = "${var.environment}-lilith-external-dns"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = module.eks.oidc_provider_arn
        }
        Action = "sts:AssumeRoleWithWebIdentity"
        Condition = {
          StringEquals = {
            "${module.eks.oidc_issuer}:sub" = "system:serviceaccount:kube-system:external-dns"
          }
        }
      }
    ]
  })
}

resource "aws_iam_role_policy" "external_dns" {
  name = "external-dns-policy"
  role = aws_iam_role.external_dns.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "route53:ChangeResourceRecordSets"
        ]
        Resource = [
          "arn:aws:route53:::hostedzone/${aws_route53_zone.public.zone_id}"
        ]
      },
      {
        Effect = "Allow"
        Action = [
          "route53:ListHostedZones",
          "route53:ListResourceRecordSets"
        ]
        Resource = ["*"]
      }
    ]
  })
}

Ingress Annotations#

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: lilith-api
  annotations:
    external-dns.alpha.kubernetes.io/hostname: api.lilith.app
    external-dns.alpha.kubernetes.io/ttl: '300'
spec:
  ingressClassName: alb
  rules:
    - host: api.lilith.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: bff
                port:
                  number: 3000

Cert-Manager#

Installation#

yaml
# Install cert-manager
apiVersion: v1
kind: Namespace
metadata:
  name: cert-manager
---
# Install via Helm
helm repo add jetstack https://charts.jetstack.io helm install cert-manager
jetstack/cert-manager \ --namespace cert-manager \ --set installCRDs=true \
--set
serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=arn:aws:iam::ACCOUNT_ID:role/cert-manager

Let's Encrypt Issuer#

yaml
# Production issuer
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: platform@lilith.app
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - selector:
          dnsZones:
            - 'lilith.app'
        dns01:
          route53:
            region: us-east-1
            hostedZoneID: ZONE_ID
---
# Staging issuer (for testing)
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: platform@lilith.app
    privateKeySecretRef:
      name: letsencrypt-staging
    solvers:
      - selector:
          dnsZones:
            - 'lilith.app'
        dns01:
          route53:
            region: us-east-1
            hostedZoneID: ZONE_ID

Certificate Request#

yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: lilith-api-tls
  namespace: lilith
spec:
  secretName: lilith-api-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - api.lilith.app
    - '*.api.lilith.app'

Ingress with TLS#

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: lilith-api
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: alb
  tls:
    - hosts:
        - api.lilith.app
      secretName: lilith-api-tls
  rules:
    - host: api.lilith.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: bff
                port:
                  number: 3000

CloudFront Integration#

CloudFront with Custom Domain#

hcl
resource "aws_cloudfront_distribution" "cdn" {
  enabled             = true
  is_ipv6_enabled     = true
  comment             = "Lilith CDN"
  default_root_object = "index.html"
  price_class         = "PriceClass_All"
  aliases             = ["cdn.${var.domain_name}"]

  origin {
    domain_name = aws_s3_bucket.media.bucket_regional_domain_name
    origin_id   = "S3-media"

    s3_origin_config {
      origin_access_identity = aws_cloudfront_origin_access_identity.main.cloudfront_access_identity_path
    }
  }

  default_cache_behavior {
    allowed_methods  = ["GET", "HEAD", "OPTIONS"]
    cached_methods   = ["GET", "HEAD"]
    target_origin_id = "S3-media"

    forwarded_values {
      query_string = false
      cookies {
        forward = "none"
      }
    }

    viewer_protocol_policy = "redirect-to-https"
    min_ttl                = 0
    default_ttl            = 3600
    max_ttl                = 86400
  }

  viewer_certificate {
    acm_certificate_arn      = aws_acm_certificate.cloudfront.arn
    ssl_support_method       = "sni-only"
    minimum_protocol_version = "TLSv1.2_2021"
  }

  restrictions {
    geo_restriction {
      restriction_type = "none"
    }
  }
}

Troubleshooting#

DNS Resolution Issues#

bash
# Check DNS propagation
dig api.lilith.app

# Query specific DNS server
dig @8.8.8.8 api.lilith.app

# Check NS records
dig NS lilith.app

# Trace DNS resolution
dig +trace api.lilith.app

# Check Route53 records
aws route53 list-resource-record-sets \
  --hosted-zone-id ZONE_ID \
  --query "ResourceRecordSets[?Name=='api.lilith.app.']"

Certificate Issues#

bash
# Check certificate status
aws acm describe-certificate \
  --certificate-arn arn:aws:acm:us-east-1:ACCOUNT:certificate/ID

# Check cert-manager certificates
kubectl get certificates -A
kubectl describe certificate lilith-api-tls -n lilith

# Check certificate request
kubectl get certificaterequest -A
kubectl describe certificaterequest <name> -n lilith

# Check cert-manager logs
kubectl logs -n cert-manager deploy/cert-manager

External DNS Issues#

bash
# Check external-dns logs
kubectl logs -n kube-system deploy/external-dns

# Verify service annotations
kubectl get ingress -A -o yaml | grep external-dns

# Check TXT registry records
dig TXT externaldns-api.lilith.app

Common Problems#

Issue Cause Solution
DNS not resolving Propagation delay Wait 5-10 minutes
Certificate pending DNS validation failed Check Route53 validation records
External DNS not updating Missing IAM permissions Check IRSA configuration
HTTPS not working Certificate not attached Verify ALB listener configuration

Quick Reference#

DNS Commands#

bash
# Create hosted zone
aws route53 create-hosted-zone --name lilith.app --caller-reference $(date +%s)

# List hosted zones
aws route53 list-hosted-zones

# Create record
aws route53 change-resource-record-sets \
  --hosted-zone-id ZONE_ID \
  --change-batch file://dns-change.json

Certificate Commands#

bash
# Request certificate
aws acm request-certificate \
  --domain-name lilith.app \
  --subject-alternative-names "*.lilith.app" \
  --validation-method DNS

# List certificates
aws acm list-certificates --region us-east-1

# Describe certificate
aws acm describe-certificate --certificate-arn ARN