Cache invalidation, sometimes called cache purging, is the process of declaring cached content to be invalid. This causes the entry to be removed from the cache and then refilled from the origin server the next time that the content is requested.
Media CDN supports multiple ways of selecting content to be invalidated, as follows:
- Host and URL path
- URL prefix (wildcard)
- Cache tags, including built-in tags for
status
,origin
, andcontent-type
You can combine these invalidation parameters to target specific cached responses and minimize origin load on the subsequent cache fill.
Supported invalidation syntax
The supported invalidation syntax is as follows:
Type | Syntax | Example |
---|---|---|
Host invalidation | Invalidate cached responses for the specified host. |
gcloud edge-cache services invalidate-cache
SERVICE_NAME \
|
Path invalidation | Invalidate cached responses for the specified path or path prefix. |
gcloud edge-cache services invalidate-cache
SERVICE_NAME \
gcloud edge-cache services invalidate-cache
SERVICE_NAME \
|
Cache tag invalidation on HTTP status code, origin name, or MIME type |
Invalidate cached responses with a matching tag. Multiple tags are
treated as a boolean OR .
|
gcloud edge-cache services invalidate-cache
SERVICE_NAME \
gcloud edge-cache services invalidate-cache
SERVICE_NAME \
|
Notes:
- Up to 10 cache tags can be specified in a single invalidation request.
- You can combine
host
,path
, andtags
in a single invalidation request. They are treated as a booleanAND
. - When multiple cache tags are specified, they are treated as a boolean
OR
. For example, if you specify--tags="status=404,origin=staging-origin"
, all responses with a cache tag ofstatus=404
are invalidated, as are all responses with a cache tag oforigin=staging-origin
.
Cache tags
Cache tags (or surrogate keys) let you invalidate content based on arbitrary metadata.
These tags are defined by the following:
- Setting the
Cache-Tag
HTTP header in an origin response, with tags specified as a comma-separated list of values. - Built-in tags based on the HTTP status code of the response, the MIME type
from the
Content-Type
HTTP response header, or the name of the origin that the response was fetched from.
When multiple tags are specified in a single invalidation request, they are
treated as a boolean OR
.
Consider the following example:
You have the following cached objects:
- Cached object #1 with tags
status=200
,content-type=video/mp4
- Cached object #2 with tags
status=404
,content-type=text/plain
- Cached object #3 with tags
status=200
,content-type=application/x-mpegurl
- Cached object #1 with tags
You issue a request to invalidate objects with
tags="status=200,content-type=text/plain"
Outcome: All three cached objects are invalidated at the same time. This is to prevent having to specify all possible tag combinations, some of which might be unknown.
Notes:
- The default cache tags are not included in the client-facing response because they reflect either existing headers (such as the status line or Content-Type) or internal configuration details.
- Cache tags sent by the origin in the
Cache-Tag
HTTP response header are sent to the client. If you want to prevent these from being sent to the client, use theresponseHeadersToRemove
feature on arouteRule
to remove theCache-Tag
header. For examples, see the custom headers documentation.
Built-in tags
Responses automatically have the following cache tags applied to support invalidating content based on status code, MIME type, or the origin that the content was fetched from. You don't need to specify these tags in your origin responses.
Tag | Details |
---|---|
status=HTTP_STATUS_CODE
|
The For example, you can invalidate all cached HTTP 404 responses by
specifying |
content-type=MIME_TYPE
|
The For example, the MIME type of a HLS playlist is
This allows you to invalidate specific types of content. |
origin=ORIGIN_NAME
|
The The |
Cache tag limitations
Cache tags have the following restrictions:
- Must not exceed 120 bytes per tag
- Must not exceed 4 KiB (4096 bytes) of total tag names per cached object
- Must not exceed 50 tags per object, not including default tags added by Media CDN
- Must be a valid HTTP token name, as defined in Section 3.2.6 of HTTP RFC 7230
- Must not include the built-in
status=
,origin=
, orcontent-type=
prefixes (which are ignored).
Tags that do not fall within these limits or meet these requirements are ignored. In some cases (such as when the response headers are too large), the response fails and isn't cached.
Permissions
The networkservices.EdgeCacheServices.invalidateCache
permission controls access to the invalidateCache
API.
This permission is included in the networkservices.edgeCacheAdmin
and
networkservices.edgeCacheUser
Identity and Access Management roles.
Examples
The following examples show how to invalidate cached responses for a Media CDN service.
You can combine the host
, path
, and tags
fields in a single invalidation request to invalidate a specific set of content.
Invalidate by host
Console
- Go to the Media CDN page in the Google Cloud console.
Go to Media CDN - Click the Services tab.
- Click your service.
- Click the Cache invalidation tab.
- For the path pattern to invalidate, enter a hostname, followed by a path.
For example:
media.example.com/cats
ormedia.example.com/cat*
. The hostname can't include*
.
gcloud
gcloud edge-cache services invalidate-cache SERVICE_NAME \ --host=HOST
Replace the following:
SERVICE_NAME
with the name of the Edge Cache service.HOST
with the complete hostname of the cache entry to be invalidated.
For example:
gcloud edge-cache services invalidate-cache SERVICE_NAME \ --host="media.example.com"
Invalidate by path
Console
- Go to the Media CDN page in the Google Cloud console.
Go to Media CDN - Click the Services tab.
- Click your service.
- Click the Cache invalidation tab.
- For the path pattern to invalidate, enter a path.
For example:
/videos/funny.mp4
or/segments/e94a6b1f731/*
.
gcloud
gcloud edge-cache services invalidate-cache SERVICE_NAME \ --path=PREFIX
Replace the following:
SERVICE_NAME
with the name of the Edge Cache service.HOST
with the hostname of the cache entries to be invalidated. To match on any hostname, omit the host flag.PREFIX
with a path prefix ending in '*' that matches cache entries to be invalidated.
For example:
gcloud edge-cache services invalidate-cache SERVICE_NAME \ --path="/segments/e94a6b1f731/*"
You can also invalidate an exact path by omitting the trailing *
character. Passing --path="/videos/funny.mp4"
invalidates the
cached response (if any) matching that path.
Invalidate by cache tag
Console
Invalidating by cache tag isn't supported in the Google Cloud console.
gcloud
gcloud edge-cache services invalidate-cache SERVICE_NAME \ --tags=TAGS
Replace the following:
SERVICE_NAME
with the name of the Edge Cache service.TAGS
with a comma-separated list of tags.
For example:
gcloud edge-cache services invalidate-cache SERVICE_NAME \ --tags="status=404,content-type=text/plain"
Invalidation latency
Cache invalidation across Media CDN's thousands of locations typically completes within one minute globally.
In some cases, invalidation can take longer, depending on system load, connectivity, and the volume of content being invalidated.
Logging
If audit logs are enabled, invalidation calls are logged to Cloud Logging.
Limitations
Invalidations are rate-limited. If you exceed the invalidations rate limit,
you get an HTTP 429
error message with the status RESOURCE_EXHAUSTED
.
An invalidation can be of any size. For example, invalidating
/images/my-image.png
counts as one invalidation. Invalidating /images/*
also
counts as one invalidation.
This behavior differs from the behavior in Cloud CDN. Cloud CDN supports one invalidation per minute.