# DNS & SSL Configuration

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

## Table of Contents

- [Overview](#overview)
- [Domain Strategy](#domain-strategy)
- [Route53 Configuration](#route53-configuration)
- [SSL/TLS Certificates](#ssltls-certificates)
- [External DNS](#external-dns)
- [Cert-Manager](#cert-manager)
- [CloudFront Integration](#cloudfront-integration)
- [Troubleshooting](#troubleshooting)

## Overview

### DNS Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                          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

```
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
```

## Related Documentation

- [AWS Setup](./aws-setup.md) - AWS configuration
- [Networking](./networking.md) - VPC and network setup
- [EKS Setup](./eks.md) - Kubernetes configuration
- [Secrets Management](./secrets-management.md) - TLS certificate storage
