DNS Resolution

Simfra runs a per-account DNS container when SIMFRA_DOCKER=true. This container resolves Route53 hosted zones, service DNS names (ALB, RDS, ElastiCache endpoints), and the simfra.local hostname. All Docker containers managed by Simfra use this DNS server automatically.

Prerequisites

  • SIMFRA_DOCKER=true
  • Docker running on the host

Per-Account DNS Container

Each AWS account in Simfra gets its own DNS container. The DNS container is created on the first Docker-backed resource creation for that account (or on bootstrap if SIMFRA_BOOTSTRAP=standard).

The DNS container:

  • Listens on UDP and TCP port 53 inside Docker
  • Publishes to a host port from the SIMFRA_DNS_PORT_RANGE (default 10000-10099)
  • Connects to every VPC Docker network in the account at the CIDR+2 address

Resolution Priority

The DNS container resolves queries in this order:

  1. simfra.local - resolves to the Simfra gateway IP (so containers can reach the Simfra API)
  2. Route53 hosted zones - any records in hosted zones for the account are resolved from zone data
  3. Service DNS names - ALB DNS names, RDS endpoints, ElastiCache endpoints, and other service-registered names resolve to the container's Docker network IP
  4. Upstream - anything else is forwarded to upstream DNS (8.8.8.8) for real internet resolution

Service DNS Registration

When a Docker-backed service creates a resource with a DNS endpoint, it registers the DNS name automatically:

Service DNS Name Pattern Example
ELBv2 {name}.elb.{region}.simfra.dev my-alb-123.elb.us-east-1.simfra.dev
RDS {id}.{random}.{region}.rds.simfra.dev mydb.abc123.us-east-1.rds.simfra.dev
ElastiCache {id}.{random}.{region}.cache.simfra.dev mycluster.abc123.us-east-1.cache.simfra.dev
CloudFront {id}.cloudfront.simfra.dev d111111abcdef8.cloudfront.simfra.dev
API Gateway {id}.execute-api.{region}.simfra.dev abc123.execute-api.us-east-1.simfra.dev
RDS Proxy {name}.proxy-{random}.{region}.rds.simfra.dev myproxy.proxy-abc123.us-east-1.rds.simfra.dev
Redshift {id}.{random}.{region}.redshift.simfra.dev mycluster.abc123.us-east-1.redshift.simfra.dev
Amazon MQ {id}.mq.{region}.simfra.dev mybroker.mq.us-east-1.simfra.dev
MSK {broker}.{cluster}.kafka.{region}.simfra.dev b-1.mycluster.kafka.us-east-1.simfra.dev
OpenSearch {domain}.{region}.es.simfra.dev mydomain.us-east-1.es.simfra.dev
DSQL {id}.dsql.{region}.simfra.dev abc123.dsql.us-east-1.simfra.dev

These entries are injected into the DNS container configuration. When a resource is deleted, its DNS entry is deregistered.

Domain Suffix

All service DNS names use the SIMFRA_DOMAIN_SUFFIX (default simfra.dev). To change it:

export SIMFRA_DOMAIN_SUFFIX=mycompany.local

This changes all service DNS names (e.g., my-alb-123.elb.us-east-1.mycompany.local).

VPC DNS (CIDR+2)

Following AWS convention, the DNS container attaches to each VPC Docker network at the CIDR+2 address. For example, if a VPC network has subnet 172.18.0.0/16, the DNS container is placed at 172.18.0.2.

All containers on the VPC network are started with --dns 172.18.0.2 (the CIDR+2 address of their VPC network), so DNS resolution works automatically without any container-side configuration.

Route53 ALIAS Records

Route53 ALIAS records pointing to service DNS names (e.g., an ALIAS to an ALB) are resolved at zone-sync time. When the DNS container reloads its configuration, ALIAS targets are resolved to their current IPs and included in the zone data.

Resolving from the Host

Inside Docker containers, DNS resolution is automatic. From your host machine, you have two options:

  • Simple: add 127.0.0.1 simfra.local to /etc/hosts and use simfra.local:{port} to reach services
  • Advanced: forward *.simfra.dev queries to the DNS container for full service DNS name resolution

See Host DNS Setup for instructions.

Next Steps