Purge CDN Cache After Every Deploy
Invalidate only the paths that changed, wait for completion, and verify that the new HTML is served from the edge.
Task
Make a deploy visible immediately without purging the entire distribution and hammering the origin.
When to use this
A deploy changes the homepage HTML, but the CDN keeps serving the old page for hours because the cache TTL is 24 hours and no invalidation runs.
Prerequisites
- A CloudFront distribution, or another CDN with an invalidation API
- Permission to create invalidations
- A deploy pipeline with the list of changed entry points
Steps
1. Invalidate only the HTML entry points and any changed non-hashed paths.
aws cloudfront create-invalidation --distribution-id E123456 --paths "/index.html" "/docs/*"Expected output: An invalidation is created with an ID and the requested paths.
2. Wait for the invalidation to complete before running smoke tests.
INVALIDATION_ID=$(aws cloudfront create-invalidation --distribution-id E123456 --paths "/index.html" --query 'Invalidation.Id' --output text); aws cloudfront wait invalidation-completed --distribution-id E123456 --id "$INVALIDATION_ID"Expected output: The waiter returns only after every edge has processed the invalidation.
3. Verify the edge is serving fresh content and report its cache status.
curl -sI https://app.example.com/index.html | grep -iE 'x-cache|age|etag'Expected output: x-cache reports a miss or refresh hit with an age near zero; the ETag matches the new build.
4. Keep the invalidation list small by relying on content hashes for assets.
Expected output: The path count stays low, so the distribution stays well below provider invalidation limits.
Troubleshooting
Problem
Invalidation is slow or gets throttled
Solution
CloudFront limits concurrent wildcard invalidations. Purge entry points only and rely on content hashing for assets.
Problem
Old content is still served
Solution
Check for a second cache layer or a service worker; a CDN purge does not clear the browser cache.
Limitations
- Invalidations are eventually consistent and can take minutes even after being reported complete.
- Purging does not fix a wrong Cache-Control header; the next response caches with the same wrong TTL.
Purging is not caching strategy
An invalidation is a repair tool, not a deployment step. If every deploy purges the whole distribution, the origin sees a traffic spike, edge caches start cold, and user latency rises exactly when the release is least proven. The better design is to cache immutable, hashed assets for a year and keep HTML short-lived, so a deploy only needs to invalidate the entry points that changed. Purging then becomes small, predictable, and fast enough to wait for in the pipeline.
Invalidate entry points, not everything
Build the path list from the files that actually changed and are not content-hashed. Usually that is the HTML documents, a manifest, and the service worker. Hashed JavaScript and CSS files get new names, so no invalidation is needed and the old files can stay cached. Wait for completion before smoke tests, otherwise the test may hit an edge that still serves the old page and produce a false failure, or worse, a false pass.
aws cloudfront create-invalidation --distribution-id E123456 \
--paths "/index.html" "/docs/*"Verify at the edge
A successful API call only means CloudFront accepted the request. Check the response headers from the edge: x-cache, age, and etag tell you whether the content is fresh and which build produced it. If the old page persists, look for a second cache layer, a reverse proxy, or a service worker that owns its own cache. And remember that a purge does not repair a wrong Cache-Control header; the next response will be cached with the same bad policy, so fix the header and the purge together.