Usage¶

This page shows common ways to use dxaws-cloudfront.

The primary entry point is CloudFrontManager.execute(desired).

Basic: Default certificate, no aliases¶

This creates (or updates) a distribution using the CloudFront default certificate.

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-origin-bucket"),
)

out = mgr.execute(desired)
print("id=", out.result.id)
print("domain_name=", out.result.domain_name)

Aliases + ACM certificate (CloudFront)¶

CloudFront requires ACM certificates in us-east-1.

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

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

cert_arn = "arn:aws:acm:us-east-1:123456789012:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

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

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

SPA custom error responses¶

This is useful for single-page apps that want index.html for 403/404.

from dxaws_cloudfront.manager import CloudFrontManager
from dxaws_cloudfront.models import (
    CustomErrorResponsesDesired,
    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-origin-bucket"),
    custom_errors=CustomErrorResponsesDesired(
        enabled=True,
        response_page_path="/index.html",
        error_codes=(403, 404),
        response_code=200,
    ),
)

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

Destroy¶

Destroy is modeled as convergence to present=False.

Call destroy() with the same desired you used for creation so aliases can locate the distribution deterministically.

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-origin-bucket"),
    aliases=("cdn.example.com",),
)

mgr.destroy(desired)

Notes:

CloudFront deletion is slow.
Destroy performs: disable → wait (disabled + deployed) → delete.

Running acceptance tests¶

Acceptance tests run against real AWS and are intentionally noisy/verbose.

Required environment variables:

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

Run:

DXAWS_AWS_TESTS=1 make accept-cloudfront

If you hit ExpiredToken, run:

dxaws whoami

Outputs and DNS integration¶

execute() returns a ManagerResult with a DistributionResult:

id
domain_name
hosted_zone_id (CloudFront constant)

These outputs are intended to feed DNS modules that create Route53 alias records.