> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How Amazon CloudFront Works: CDN Caching Explained

> Follow an Amazon CloudFront request through edge caching, cache keys, behaviors, origins, TTLs, invalidations, private S3, TLS, and AWS WAF.

Amazon CloudFront is a content delivery network. It accepts a request at an AWS edge location, checks whether it already has a reusable response, and either serves that response or forwards the request to an origin.

*Updated October 9, 2026.*

The origin can be an S3 bucket, an Application Load Balancer, an API, or another HTTP server. CloudFront is not limited to static files, but caching is most effective when many viewers can share the same response.

## A request from the browser

When a browser requests `https://assets.example.com/app.js`, the path looks like this:

1. DNS directs the hostname to the CloudFront distribution.
2. The viewer establishes TLS with a nearby CloudFront edge location.
3. CloudFront chooses the matching cache behavior.
4. CloudFront calculates a cache key from configured request fields.
5. A cache hit returns the stored object from the edge.
6. A cache miss sends an origin request.
7. The origin response returns to CloudFront and may be cached before it reaches the viewer.

CloudFront has many edge locations. An object cached in one location is not automatically present in every other location. Each location builds its cache from the traffic it receives, with regional layers and optional Origin Shield helping reduce repeated origin fetches.

## The cache key decides reuse

The cache key answers: can these two requests share one cached response?

The URL path is part of the key. You can also include selected query strings, headers, and cookies. Including more fields creates more cache variants and usually lowers the hit ratio.

For example, if a static image response never changes by cookie, forwarding every cookie can create unnecessary cache entries. If an API response changes by the `Accept-Language` header, excluding that header can serve the wrong language.

<Tip>
  Start with the smallest cache key that preserves correctness. Forward additional request values to the origin only when the application needs them.
</Tip>

CloudFront separates cache policies from origin request policies. A value can be forwarded to the origin without becoming part of the cache key, but use this carefully. If the origin changes the response based on a forwarded value that is absent from the key, viewers may receive a response generated for someone else.

## Cache behaviors and origins

A distribution can have multiple cache behaviors. Path patterns choose which behavior handles a request.

```text theme={null}
/assets/*   -> S3 origin, long cache lifetime
/api/*      -> load balancer origin, little or no caching
*           -> default application behavior
```

Each behavior controls the allowed HTTP methods, cache policy, origin request policy, compression, viewer protocol policy, and edge functions.

CloudFront can terminate HTTPS for viewers and use HTTPS to the origin. AWS Certificate Manager supplies the viewer certificate. The certificate for a CloudFront custom domain must be available in the AWS region required by CloudFront.

## Private S3 origins

A secure static-site design keeps the S3 bucket private. CloudFront uses Origin Access Control to sign origin requests, and the bucket policy allows reads from the specific distribution.

The viewer can fetch the object through CloudFront but cannot bypass it with a public S3 URL. This keeps the delivery policy, TLS, caching, and optional AWS WAF controls on one path.

Springwinter static websites use this model: a private S3 bucket stores the build output and CloudFront serves it globally. See [static websites](/deploy/static-websites) for the deployment flow.

## TTLs, revalidation, and invalidation

The time to live determines how long CloudFront can reuse an object before checking the origin again. Cache headers from the origin and the behavior's minimum, default, and maximum TTL settings work together.

Use long lifetimes for versioned assets such as `app.8f31c.js`. A new deployment publishes a new name, so old and new clients can safely use different files. Use shorter lifetimes or revalidation for HTML documents that point to those assets.

An invalidation tells CloudFront to remove matching cached paths before they expire. Invalidations are useful for urgent changes, but versioned file names are more predictable for routine deployments.

## Dynamic requests and security

CloudFront can accelerate dynamic traffic by reusing connections, terminating TLS near viewers, and routing over the AWS network even when a response is not cached. It can also integrate with AWS WAF, signed URLs, signed cookies, geographic restrictions, and edge functions.

None of these features removes the need to secure the origin. Restrict direct origin access where possible, validate application authorization, and avoid caching personalized responses under shared keys.

## What to measure

A high cache hit ratio usually reduces origin load and latency, but it is not the only goal. Track:

* Viewer latency and error rates
* Cache hit ratio by behavior
* Origin latency and errors
* Bytes transferred to viewers
* Invalidation frequency
* Requests and transfer cost

CloudFront works best when you design caching as part of the application contract. The CDN can only reuse a response safely when the cache key, headers, and origin behavior agree on what makes that response unique.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How does Amazon CloudFront work?">
    Amazon CloudFront receives a request at an edge location, calculates a cache key, and returns a cached response when available. On a cache miss, CloudFront forwards the request to an S3, load balancer, API, or HTTP origin and can cache the response.
  </Accordion>

  <Accordion title="What is a CloudFront cache key?">
    A CloudFront cache key identifies response variants using the URL path and configured query strings, headers, and cookies. Smaller correct keys improve cache reuse. Missing a value that changes the origin response can expose incorrect or personalized content to other viewers.
  </Accordion>

  <Accordion title="Should I invalidate CloudFront after every deployment?">
    Prefer content-hashed file names and long TTLs for static assets. Publish new names when assets change and use shorter caching for HTML entry points. Use invalidations for urgent corrections or stable paths that must refresh before their normal expiration.
  </Accordion>
</AccordionGroup>

## Sources and further reading

* [How CloudFront delivers content](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/HowCloudFrontWorks.html)
* [Understand the cache key](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/understanding-the-cache-key.html)
* [Restrict access to an S3 origin](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.