CloudFront via SDK Best Practices

CloudFront is cheap and fast when the cache key is tight and deploys use versioned URLs - and slow and expensive when the key is wide and every release fires a wall of invalidations. Most CloudFront SDK mistakes are not crashes; they are quietly low hit rates and quietly high invalidation bills.

Walk this list once now, then use it as a review checklist before shipping any code that creates, updates, or serves through a distribution.

How to Use This List

• Each item is a rule stated positively, with a one-line rationale.
• Groups run roughly in order of impact: cache-key and cost first, then the update contract, security, and operations.
• Check the boxes against your own code as a quick audit.
• Revisit whenever you add an origin, a behavior, or an edge function.

A - Cache-Key Design & Hit Rate

• Keep the cache key as narrow as correctness allows. Every query string, header, or cookie you add to a cache policy multiplies the number of cached copies and lowers the hit rate.
• Use managed cache policies where they fit. CachingOptimized for static assets and CachingDisabled for dynamic APIs cover most cases without a custom policy.
• Separate the cache key from what you forward. Forward a header to the origin via an origin request policy without adding it to the cache key, so the origin sees it but the cache does not fragment.
• Cache per path, not globally. Give static and dynamic paths their own behaviors and policies instead of one compromise setting for everything.

Attach a managed cache policy by id rather than a legacy ForwardedValues block.

# --- Python (boto3) ---
CACHING_OPTIMIZED = "658327ea-f89d-4fab-a63d-7e88639e58f6"   # managed policy id
default_behavior = {
    "TargetOriginId": "s3-assets",
    "ViewerProtocolPolicy": "redirect-to-https",
    "CachePolicyId": CACHING_OPTIMIZED,   # NOT ForwardedValues
}

// --- TypeScript (AWS SDK v3) ---
const CACHING_OPTIMIZED = "658327ea-f89d-4fab-a63d-7e88639e58f6";   // managed policy id
const defaultBehavior = {
  TargetOriginId: "s3-assets",
  ViewerProtocolPolicy: "redirect-to-https",
  CachePolicyId: CACHING_OPTIMIZED,   // NOT ForwardedValues
};

B - Invalidations & Cost

• Prefer versioned URLs over invalidations. Fingerprinted filenames (app.9f2a1c.js) change the cache key on each build, busting cache for free instead of paying per invalidation path.
• Set long TTLs on hashed assets, no-cache on HTML. Cache immutable assets for a year and always revalidate the small HTML entry point that references them.
• Invalidate with /*, not file lists, when you must. A single /* counts as one billable path; listing hundreds of files counts as hundreds.
• Generate a fresh CallerReference per invalidation. Reuse dedupes to the previous batch or errors on a changed one.
• Reserve invalidations for emergencies. A mistaken publish or takedown warrants one; a routine deploy should not.

Bust cache by changing the URL; keep invalidations for the rare forced purge.

# --- Python (boto3) ---
import boto3, time
 
cf = boto3.client("cloudfront", region_name="us-east-1")
cf.create_invalidation(
    DistributionId="E1234ABCDEF",
    InvalidationBatch={
        "CallerReference": f"emergency-{int(time.time())}",
        "Paths": {"Quantity": 1, "Items": ["/*"]},   # one billable path
    },
)

// --- TypeScript (AWS SDK v3) ---
import { CloudFrontClient, CreateInvalidationCommand } from "@aws-sdk/client-cloudfront";
 
const cf = new CloudFrontClient({ region: "us-east-1" });
await cf.send(new CreateInvalidationCommand({
  DistributionId: "E1234ABCDEF",
  InvalidationBatch: {
    CallerReference: `emergency-${Date.now()}`,
    Paths: { Quantity: 1, Items: ["/*"] },   // one billable path
  },
}));

C - The Update Contract

• Treat every update as read-modify-write. GetDistributionConfig, change the returned config, then UpdateDistribution with its ETag as IfMatch.
• Send the full config, not a patch. UpdateDistribution replaces the entire configuration; a partial object drops fields.
• Keep every Quantity in sync with its Items. Origins, CacheBehaviors, Paths, and AllowedMethods all reject a count that does not match the list length.
• Handle PreconditionFailed (412) by refetching. A stale ETag means someone else changed the config; re-read and reapply.
• Wait for Deployed before depending on a change. A returned call is InProgress; use the distribution_deployed waiter when correctness depends on propagation.

Read, mutate the whole config, then update with the ETag.

# --- Python (boto3) ---
import boto3
 
cf = boto3.client("cloudfront", region_name="us-east-1")
cur = cf.get_distribution_config(Id="E1234ABCDEF")
config, etag = cur["DistributionConfig"], cur["ETag"]
config["Comment"] = "updated"                       # mutate the full config
cf.update_distribution(Id="E1234ABCDEF", DistributionConfig=config, IfMatch=etag)

// --- TypeScript (AWS SDK v3) ---
import {
  CloudFrontClient, GetDistributionConfigCommand, UpdateDistributionCommand,
} from "@aws-sdk/client-cloudfront";
 
const cf = new CloudFrontClient({ region: "us-east-1" });
const cur = await cf.send(new GetDistributionConfigCommand({ Id: "E1234ABCDEF" }));
const config = cur.DistributionConfig!;
config.Comment = "updated";                         // mutate the full config
await cf.send(new UpdateDistributionCommand({
  Id: "E1234ABCDEF", DistributionConfig: config, IfMatch: cur.ETag,
}));

D - Origin Security & HTTPS

• Lock S3 origins with Origin Access Control. Use OAC (via CreateOriginAccessControl) plus a bucket policy so only CloudFront reads the bucket; do not expose it publicly.
• Prefer OAC over legacy OAI. OAC supports SigV4 and SSE-KMS buckets; CreateCloudFrontOriginAccessIdentity is legacy and should not be chosen for new work.
• Enforce HTTPS to the viewer. Set ViewerProtocolPolicy to redirect-to-https or https-only on every behavior.
• Use HTTPS to custom origins. Set OriginProtocolPolicy to https-only so the edge-to-origin hop is encrypted too.
• Gate private content with signed URLs/cookies and key groups. Register a public key in a key group and set TrustedKeyGroups on the behavior; keep the private key in a secret store.

E - Policies, Functions & Operations

• Use managed origin-request and response-headers policies. They add security, CORS, and forwarding behavior declaratively without a custom policy or edge function.
• Reach for CloudFront Functions before Lambda@Edge. Cheaper and faster for header rewrites, redirects, and URL normalization; escalate to Lambda@Edge only for origin events, network calls, or heavier compute.
• Associate only published, versioned Lambda@Edge ARNs in us-east-1. Never $LATEST; the function and version must be in us-east-1 to replicate.
• Test and publish edge functions before associating. Validate with TestFunction, then PublishFunction with the ETag; a runtime error on viewer-request fails the request.
• Rely on built-in retries and log the request id. Both SDKs retry throttling with backoff; capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) on failure for support.

FAQs

Related

• CloudFront's Edge Caching Model - the cache-key and policy model behind group A.
• Invalidations & Cache-Control Strategy - the versioned-URL and cost rules in group B.
• Cache Behaviors & Origin Groups - per-path caching and the Quantity rule in group C.
• Signed URLs & Signed Cookies - the private-content gating in group D.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).