Comprehensive guide for DNS management and SSL/TLS certificate configuration for the Lilith platform.
Table of Contents#
- Overview
- Domain Strategy
- Route53 Configuration
- SSL/TLS Certificates
- External DNS
- Cert-Manager
- CloudFront Integration
- Troubleshooting
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
Related Documentation#
- AWS Setup - AWS configuration
- Networking - VPC and network setup
- EKS Setup - Kubernetes configuration
- Secrets Management - TLS certificate storage