Custom Domains & WAF

Custom domains

A custom domain needs a hosted zone, a certificate, and DNS records pointing to the load balancer. Set domain.dns according to where the hosted zone is managed.

Mode	The zone	What Keel does	Manual steps
route53 (default)	Already exists in this AWS account	Writes validation + alias records; the apply waits for the certificate	None
route53-managed	Keel creates it	Everything, once you set the nameservers at your registrar	Set 4 nameservers
external	Stays where it is (Cloudflare, another account, corporate DNS)	Issues the certificate; prints the records; writes none	Create the records, then keel domains verify

keel domains add app.example.com          # looks the zone up once and records the mode
keel domains add app.example.com --dns route53-managed
keel domains add app.example.com --dns external
keel domains status                       # live state: zone, delegation, certificate, what's left (--json)
keel domains records                      # the records to create by hand, in provider-form shape
keel domains verify                       # recheck; for external, records an issued certificate (--wait, --timeout 15m)
keel domains remove app.example.com

domains add supports --zone, --zone-id, --dns, repeatable --alias, --certificate-arn, and --no-force-https. It updates the target environment in keel.yml; run keel up to apply the change in AWS.

Declared in keel.yml:

domain:
  name: app.example.com
  zone: example.com          # required for the route53 modes; ignored for external
  # dns: route53             # route53 | route53-managed | external
  # aliases:
  #   - www.app.example.com
  #   - "*.app.example.com"  # on the certificate, deliberately not routed
  # certificate_arn: arn:aws:acm:...   # bring your own; Keel then issues nothing
  # certificate_issued: true # external only — written by 'keel domains verify'
  # force_https: true        # takes effect only once a certificate exists
  # validation_timeout: 20m

HTTPS activation

While a certificate is pending, port 80 continues to serve the application. force_https defaults to true and starts redirecting only after the certificate is issued and attached.

Delegation checks

keel domains status queries public DNS instead of relying only on Route 53, so it can detect a registrar that still delegates to another provider. It reports the next required step in order: zone, delegation, certificate, then attachment. For apex domains it also notes that DNS providers must use ALIAS or ANAME records rather than CNAME.

Retained managed zones

Keel retains hosted zones created with route53-managed when you run domains remove or keel destroy. Recreating a zone assigns different nameservers and would invalidate registrar delegation and remove records Keel may not manage. Delete a retained zone manually in AWS when it is no longer needed; AWS charges $0.50 per month for it.

External DNS takes two applies

With dns: external, run keel up to provision HTTP and print the validation records. Add those records at your DNS provider, run keel domains verify --wait, then run keel up again to attach HTTPS. Static sites use the same sequence with keel sites verify.

WAF

Keel supports AWS WAF with managed rule sets to protect your ALB. WAF requires load_balancer.enabled: true — and therefore at least one service; a sites-only app has no ALB to attach it to.

waf:
  enabled: true
  managed_rules:
    - AWSManagedRulesCommonRuleSet

keel waf enable                # default rule set: AWSManagedRulesCommonRuleSet
keel waf enable --rules AWSManagedRulesCommonRuleSet,AWSManagedRulesSQLiRuleSet
keel waf status
keel waf disable

Changes are applied on the next keel up.