# 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)

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

Tip: while developing locally:

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

## Running tests

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

```bash
DXAWS_AWS_TESTS=1 make accept-acm
```

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

```bash
DXAWS_AWS_TESTS=1 DXAWS_ACCEPTANCE_CLEANUP=0 make accept-acm
```