dxaws-cloudfront

Create and manage CloudFront distributions using the dxaws declarative convergence pattern.

Overview

This repository contains the dxaws-cloudfront module.

Version: 0.1.0

This module manages a single CloudFront distribution using:

  • S3 origin (via Origin Access Control)

  • Optional aliases (CNAMEs)

  • Optional ACM certificate (must be in us-east-1)

  • Deterministic convergence (create / update / wait / destroy)

It follows the dxaws architecture pattern:

  • Desired → target state

  • Current → observed state

  • Plan → diff

  • Executor → apply actions

  • Manager → orchestration + lifecycle

Installation

pip install dxaws-cloudfront

For development:

pip install -e ".[dev]"

Quick Example

from dxaws_cloudfront.manager import CloudFrontManager
from dxaws_cloudfront.models import DistributionDesired, S3OriginDesired
from dxaws_cloudfront.providers.aws import AwsProvider

provider = AwsProvider(aws=...)
mgr = CloudFrontManager(provider=provider)

desired = DistributionDesired(
    name="my-site",
    origin=S3OriginDesired(bucket_name="my-bucket"),
    aliases=("cdn.example.com",),
)

result = mgr.execute(desired)
print(result.domain_name)

Destroy:

mgr.destroy(desired)

Destroy converges to present=False while preserving aliases for deterministic discovery.

Acceptance Tests (Real AWS)

CloudFront acceptance tests run against real AWS.

Required Environment Variables

DXAWS_TEST_REGION=ca-central-1
DXAWS_ACCEPTANCE_ZONE_NAME=test.dxaws.com

Run:

make accept-cloudfront

Notes

  • The origin bucket is persistent and will NOT be deleted.

  • ACM wildcard certificate is reused if available.

  • CloudFront certificates must be in us-east-1.

  • If you see ExpiredToken, run:

dxaws whoami

Lifecycle Behavior

Create

  • Creates OAC (if needed)

  • Creates distribution

  • Waits until deployed

Update

  • Updates config if diff detected

  • Waits until deployed

Wait

  • If distribution exists but status != Deployed, manager waits

Destroy

  • Disable distribution

  • Wait until disabled + deployed

  • Delete distribution

CloudFront is eventually consistent. The provider ensures proper wait semantics before delete.

Local Docs Preview (Sphinx)

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

Tip: use editable install during development:

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

Current Scope (MVP)

Supported:

  • Single distribution

  • Single S3 origin

  • Default cache behavior

  • Aliases

  • ACM certificate

  • Custom SPA error responses

Not yet supported:

  • Multiple origins

  • Cache policies / origin request policies

  • Logging

  • WAF

  • Real-time logs

  • Advanced behaviors

Design Philosophy

This module is intentionally:

  • Deterministic

  • Explicit

  • Idempotent

  • Contract-driven

The planner compares summarized state to avoid AWS response drift.

Destroy is modeled as convergence to present=False.

License

MIT