dxaws-acm

AWS Certificate Manager (ACM) primitives for the dxaws ecosystem.

This module manages DNS-validated ACM certificates and (optionally) the Route53 validation records needed to issue them.

What it does

  • Requests a DNS-validated certificate for a domain (and optional SANs)

  • Waits for ACM to publish DNS validation records, then creates/updates those records in Route53

  • Waits for the certificate to reach ISSUED

  • Supports idempotent re-runs (planner diffs remain stable)

  • Supports drift recovery (deleted certificate is re-created)

What it does not do

  • Create or delegate Route53 hosted zones

  • Manage CloudFront distributions (that happens in dxaws-cloudfront / dxaws-website)

  • Manage application DNS records beyond ACM validation CNAMEs

Documentation

All docs live in docs/ and are designed to:

  • build with Sphinx (MyST Markdown)

  • be readable on GitHub

  • be aggregated into the main dxaws documentation site

Quick links:

  • docs/index.md – purpose + scope

  • docs/usage.md – runnable examples + how to run acceptance safely

  • docs/design.md – layering + normalization rules + what acceptance proves

  • docs/api.md – stable contracts + integration points

Local preview (Sphinx)

python -m pip install "./.[docs]"
cd docs
make html
open _build/html/index.html

Tip: while developing locally:

python -m pip install -e "./.[docs]"

Running tests

make test
make test-unit
make test-integration
make test-acceptance

AWS acceptance (real AWS)

Acceptance tests are opt-in and will only run when DXAWS_AWS_TESTS=1.

Recommended environment variables (you can export these once in your shell):

  • DXAWS_ACCEPTANCE_ACCOUNT – the dedicated test account id

  • DXAWS_ACCEPTANCE_ZONE_NAME – e.g. test.dxaws.com

  • DXAWS_TEST_REGION – e.g. ca-central-1

Run:

DXAWS_AWS_TESTS=1 make accept-acm

By default, acceptance tests clean up resources after the run. To keep resources for debugging:

DXAWS_AWS_TESTS=1 DXAWS_ACCEPTANCE_CLEANUP=0 make accept-acm