View a markdown version of this page

Invalidating content by cache tags - Amazon CloudFront
How tag invalidation worksTag format requirementsConfiguring a distribution for tag invalidationsCreating tag invalidationsChecking invalidation statusImportant considerationsUse case examples

Invalidating content by cache tags

Amazon CloudFront supports tag invalidations, which lets you invalidate cached objects based on semantic tags rather than URL paths. This gives you flexible control over cache invalidation without requiring your URL structure to match your invalidation strategy.

How tag invalidation works

  1. Configure your distribution: Add a CacheTagConfig to your distribution specifying the HTTP header name that your origin uses to return cache tags.

  2. Tag objects at your origin: When returning an object you want to cache with tags, configure your origin to include the specified header in HTTP responses with comma-separated tag values.

    HTTP/1.1 200 OK
Content-Type: text/html
x-amz-meta-cache-tag: product:electronics, category:tv, brand:example
Cache-Control: max-age=3600
    Note

    For S3 origins, you can attach cache tags to your S3 objects as metadata. You can add a metadata entry with a key of your choice (example: cache-tag) and a comma-separated list of tags as the value (example: product:electronics, category:tv, brand:example).

    S3 surfaces object metadata as response headers prefixed with x-amz-meta-<Key>, so a metadata key of cache-tag would be returned as a x-amz-meta-cache-tag header. You can set the HeaderName in your CacheTagConfig to x-amz-meta-cache-tag to enable sending invalidations to these tags.

    Note

    Alternatively, you can attach an origin response Lambda@Edge function to your cache behavior to add cache tag headers. If using Lambda@Edge, the header name does not need to follow the x-amz-meta-<Key> format.

  3. Invalidate by tag: Use the CreateInvalidation API with the # prefix to invalidate all objects cached with the specified tag.

    aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#product:electronics"

    This invalidates ALL cached objects that contain the tag product:electronics, regardless of their URL path.

Tag format requirements

Origin response header value:

  • Tags are comma-separated in the header value.

  • Leading and trailing spaces around each tag are trimmed.

  • Both tag1,tag2,tag3 and tag1, tag2, tag3 are valid and equivalent.

Individual tag values:

  • ASCII visible characters (33–126)

  • No control characters, spaces, or commas

  • Case-insensitive

  • Maximum 256 characters per tag

  • Maximum 50 tags per object (additional tags are ignored)

Configuring a distribution for tag invalidations

To enable tag invalidations, add a CacheTagConfig to your distribution configuration:

aws cloudfront create-distribution \
  --distribution-config '{
    "CallerReference": "my-distribution",
    "CacheTagConfig": {
      "HeaderName": "x-amz-meta-cache-tag"
    },
    "DefaultCacheBehavior": {
      "TargetOriginId": "myOrigin",
      "ViewerProtocolPolicy": "redirect-to-https",
      "CachePolicyId": "658327ea-f89d-4fab-a63d-7e88639e58f6"
    },
    "Origins": { ... },
    "Enabled": true,
    "Comment": "Distribution with tag support"
  }'

Creating tag invalidations

Use the # prefix in the --paths parameter to specify tags:

# Invalidate all objects tagged with "user1"
aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#user1"

# Invalidate objects matching any of multiple tags (OR logic)
aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#user1" "#product-category:electronics"

# Mix path and tag invalidations in one batch
aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "/index.html" "#user1" "/images/*" "#product-category:electronics"

Checking invalidation status

Use GetInvalidation to check the status. The response includes both path and tag items:

aws cloudfront get-invalidation \
  --distribution-id distribution_ID \
  --id invalidation_ID

Important considerations

  • Opt-in required: Tag invalidation only works on distributions that have CacheTagConfig configured. Distributions without this configuration ignore cache tag headers from the origin.

  • Tag processing limits: CloudFront processes up to 50 tags per cached object. If an origin response contains more than 50 tags, the additional tags beyond the limit are not stored.

  • Changing the header name: Tag invalidations are looked up against the current CacheTagConfig configuration. If you change the HeaderName in the CacheTagConfig, invalidations issued to objects cached with tags under the old header name will no longer be evaluated. If you need to change the header name, start returning both the new and the old cache tags headers with your objects, then issue a path invalidation (for example, /*) or invalidate existing tags before changing the header name to avoid serving stale content. Once that's done you can stop sending the old cache tags header with your objects.

  • Removing CacheTagConfig: When you remove CacheTagConfig from a distribution, CloudFront stops extracting tags from origin responses. Existing cached objects with tags are served normally until they expire or are invalidated by path.

  • Backward compatibility: Existing path and wildcard invalidations continue to work unchanged. Tag invalidations are additive — you can use both methods on the same distribution.

  • Distribution tenants: Tag invalidation is also supported for distribution tenants via the CreateInvalidationForDistributionTenant API.

Use case examples

Example 1: E-commerce product catalog

An e-commerce site tags cached product pages with product, category, and brand:

x-amz-meta-cache-tag: category:electronics, brand:acme, product:12345

When ACME updates their branding, invalidate all ACME products at once:

aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#brand:acme"

Example 2: User-generated content platform

A platform tags cached content with the owner's user ID:

x-amz-meta-cache-tag: user:12345, content-type:image

When a user closes their account, invalidate all their content after you've removed it from the origin:

aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#user:12345"

Example 3: Content versioning

A CMS tags content with version identifiers:

x-amz-meta-cache-tag: version:v2, template:homepage

When deploying a new version, invalidate all v2 content:

aws cloudfront create-invalidation \
  --distribution-id distribution_ID \
  --paths "#version:v2"