Origins overview

Media CDN lets you fetch content from your origin infrastructure, whether content is hosted within Google Cloud, in another cloud, or on-premises.

Each configuration can have one or more origins associated with it. Origin configurations tell Media CDN how to connect to your infrastructure, when and how to fail over, retry, and time out, and what protocol to use when connecting.

Origins have the following features:

Origins can be defined per host and per route, which allows a single EdgeCacheService resource to map to multiple origins that contain (for example) manifests, video segments, other static content, and so on.
Origins can be reached over HTTP/2, HTTPS, and unencrypted HTTP/1.1.
Retries and failover behaviors are configured per origin, and can allow the service to fail over on hard errors (such as connectivity failure) or retry based on HTTP 404 Not Found or HTTP 429 Too Many Requests responses.
Private resources inside Google Cloud or on-premises can be reached by configuring an external Application Load Balancer as an origin behind Media CDN.
Redirect-following behavior is configured per origin. You can enable Media CDN to follow redirects to other origin servers.

Origin requirements

To allow Media CDN to cache origin responses larger than 1 MiB, an origin must include the following in the response headers for both HEAD and GET requests, unless specified otherwise:

A Last-Modified or ETag HTTP response header (a validator).
A valid HTTP Date header.
A valid Content-Length header.
The Content-Range response header, in response to a Range GET request. The Content-Range header must have a valid value in the form of bytes x-y/z (where z is the object size).

The default origin protocol is HTTP/2. If your origins only support HTTP/1.1, you can set the protocol field explicitly for each origin.

Origin shielding

Media CDN provides a deeply tiered edge infrastructure that is designed to actively minimize cache fill wherever possible.

There are three primary layers of caching infrastructure:

Deep edge caches, which serve the majority of traffic and off-load within a service providers network.
Google's peering edge, which is connected to thousands of ISPs and acts as the mid-tier cache for edge caches, and for cases where those are not present within a given ISP, the user-facing cache.
Long-tail caches within Google's network that other downstream caches fill from prior to the origin. These caches support significant fan-in, have substantial cache storage capacity, and act as an origin shield.

An overview of this topology is shown here:

Topology overview. — Topology overview (click to enlarge).

All layers of caching support request collapsing (or coalescing) to further reduce origin load. Based on observed, real-world workloads at scale:

> 95% of cache fill uses a dedicated long-tail cache node within the region, in order to reduce cache fill costs and latency.
Cache fill between the origin and Google's own edge infrastructure is entirely over Google's global private backbone network, which reduces cache fill latency and improves reliability—both are active benefits for live streaming workloads.
Caches cross-fill from each other where advantageous to do so, further driving down cache fill rates.
Media CDN has significant storage capacity across caches, which minimizes the eviction rates even for long-tail, less popular content.

Customers might see different offload rates depending on their cache configuration, user load, workloads (such as live versus on-demand), user distribution, and how much long-tail content (total corpus size) they serve to users across regions.

Request collapsing

Request collapsing actively collapses multiple user-driven cache fill requests for the same cache key into a single origin request, per edge node.

Combined with origin shielding, this further reduces origin load and egress bandwidth needs, and is the default behavior for Media CDN.

Collapsed requests have both the client-facing request logged and the (collapsed) cache fill request logged. The leader of the collapsed session is used to make the origin fill request, which means that the origin sees the headers (including the User-Agent) of only that client.

Requests that don't share the same cache key cannot be collapsed.

Origin connectivity

The following sections describe how Media CDN connects to origins, how HTTP requests are made, and how you can authenticate requests.

Supported origins and protocols

Media CDN directly supports any publicly reachable HTTP endpoint as an origin, including the following:

Cloud Storage buckets, including private buckets through Identity and Access Management service accounts
External Application Load Balancers
Amazon S3-compatible buckets, including private buckets that use AWS Signature Version 4
Other publicly available object storage, such as Azure Blob Storage
Publicly available web servers, such as public VMs or on-premises hosts

Connectivity to origins is over secure tunnels and Google's global backbone network.

The following table details the supported origin protocols.

Protocol	Supported	SSL (TLS) required
HTTP/2	Yes (default)	Yes
HTTPS (HTTP/1.1 over TLS)	Yes	Yes
HTTP/1.1	Yes	No

Media CDN uses HTTP/2 (h2) to connect to an origin by default. HTTP/2 and HTTPS both require a valid, publicly trusted TLS (SSL) certificate. A valid certificate is one that is unexpired, signed by a public Certificate Authority, and has a Subject Alternative Name matching the hostname sent to the origin.

Notes:

If your origin does not support HTTP/2, you can explicitly set the protocol (on a per-origin basis) to HTTP (HTTP/1.1) or HTTPS (HTTP/1.1 over TLS).
When configuring HTTPS or HTTP/1.1 as the origin protocol, Media CDN doesn't negotiate an alternative protocol (such as HTTP/2). Similarly, when configuring HTTP/2, the connection doesn't fall back to HTTP/1.1, in order to be explicit about origin connectivity behavior.
Media CDN automatically uses the correct port based on the protocol: port 80 for HTTP or port 443 for HTTPS and HTTP/2.

Origin request headers

When connecting to an origin, Media CDN uses the Host header from the client request by default.

The following table documents what the origin sees in the incoming request under different configuration scenarios:

Client Request	`EdgeCacheService.hostRewrite`	`EdgeCacheOrigin.hostRewrite`	originAddress	Host header / TLS SNI at origin
media.example.com	None	None	backend.example.com	media.example.com
media.example.com	service.example.com	None	backend.example.com	service.example.com
media.example.com	None	origin.example.com	backend.example.com	origin.example.com
media.example.com	service.example.com	origin.example.com	backend.example.com	origin.example.com
media.example.com	service.example.com	origin.example.com	gs://vod-content-bucket	set automatically based on the bucket name

The primary origin and any failover origins see the same host header if they share the same routeRule or hostRewrite configuration.

Any hostRewrite settings are ignored when using a Cloud Storage bucket as the origin because alternative host header values are not supported by Cloud Storage buckets. The host header is automatically set based on the bucket name.

The TLS SNI (Server Name Indication) value in the request (for HTTP/3, HTTP/2, and HTTPS requests) is set to the same value as the host header sent to the origin.

For information about rewriting host headers for per-route configuration, see Configure service routes. For information about setting per-origin override actions, see Origin failover without redirect following.

Failover and timeouts

The following sections describe these configuration options:

Timeouts: Determine how long Media CDN waits to connect to your origin or for it to respond to a request.
Retries: Determine whether Media CDN retries an origin HTTP request to your origin, and under what conditions.
Failover: Determine whether Media CDN attempts to connect to a failover origin if the first is unavailable or returns a specific status code.

Origin timeouts

Timeouts let you configure when origin retry and failover behaviors are triggered and when subsequent client failover can be triggered.

The following describes the configurable timeouts that Media CDN supports:

connectTimeout and maxAttemptsTimeout limit how long Media CDN takes to find a usable response.

Both timeouts include the time that the origin takes to return headers and to determine whether to use a failover or redirect. connectTimeout applies independently for each origin attempt, while maxAttemptsTimeout includes the time required to connect across all origin attempts, including failovers and redirects. Following a redirect counts as an additional attempt to connect to the origin, and counts toward the maxAttempts set for the configured origin.

When Media CDN encounters a non-redirect response, such as from a redirect or failover origin, the readTimeout and responseTimeout values apply. Redirected origins use the connectTimeout, readTimeout, and responseTimeout values configured for the EdgeCacheOrigin that encountered the redirect.
responseTimeout and readTimeout control how long a streamed response can take. After Media CDN determines that it's going to use an upstream response, neither connectTimeout nor maxAttemptsTimeout matter. At this point, readTimeout and responseTimeout come into effect.

Media CDN makes at most four origin attempts across all origins, regardless of the maxAttempts set by each EdgeCacheOrigin. Media CDN uses the maxAttemptsTimeout value from the primary EdgeCacheOrigin. The per-attempt timeout values (connectTimeout, readTimeout, and responseTimeout) are configured for the EdgeCacheOrigin of each attempt.

The following table describes the timeout fields:

Field	Default	Description
connectTimeout	5 seconds	The maximum amount of time Media CDN can take from starting the request to the origin until Media CDN determines whether the response is usable. Practically, `connectTimeout` covers the time starting with creating the request, then doing DNS lookups, then doing TLS handshakes, TCP/QUIC connection establishment, through getting the response headers that contain the HTTP status code. The timeout must be a value between 1 second and 15 seconds.
maxAttemptsTimeout	15 seconds	The maximum time across all connection attempts to the origin, including failover origins, before returning an error to the client. An HTTP 504 is returned if the timeout is reached before a response is returned. The timeout must be a value between 1 second and 30 seconds. This setting defines the total duration for all origin connection attempts, including failover origins, in order to cap the total time clients have to wait for content to start streaming. Only the first `maxAttemptsTimeout` value is used, where the first is defined by the origin configured for the given route.
readTimeout	15 seconds	The maximum duration to wait between reads of a single HTTP response. The `readTimeout` is capped by the `responseTimeout`. All reads of the HTTP response must be completed by the deadline set by the `responseTimeout`. The timeout must be a value between 1 second and 30 seconds. If this timeout is reached before the response is complete, the response is truncated and logged.
responseTimeout	30 seconds	The maximum duration to allow for a response to complete. The timeout must be a value between 1 second and 120 seconds. The duration is measured from the time that the first body bytes are received. If this timeout is reached before the response is complete, the response is truncated and logged.

Consider the following examples:

Origin A matches requests to "/segments/" and has a maxAttemptsTimeout value of 5s, a maxAttempts value of 1, and a failover_origin value of Origin B. The connectTimeout value is at its default of 5s. If you attempt to connect to Origin A, and it fails within 1 second due to an invalid TLS certificate, you have ~4 seconds left to make a successful connection to Origin B.
Origin C matches requests to "/manifests/*, has a maxAttemptsTimeout value of 10s, a maxAttempts value of 3, and failover_origin not configured. The connectTimeout value is at its default of 5s. Media CDN attempts to connect to Origin C up to three times, allowing up to 10 seconds (the maxAttemptsTimeout limit) to make a successful connection.

Retry origin requests

Media CDN supports origin retries, allowing unsuccessful requests to the origin to be retried. You can specify how many times the current origin can be retried against before a failover origin (if configured) is attempted.

Media CDN attempts to reach the primary origin up to the configured maxAttempts value, which defaults to 1.
Media CDN retries origin connections up to a maximum of three times before failing and returning an HTTP 502 Bad Gateway error to the user. This includes any failover origin connections, which count towards the limit of three.
When configuring an origin resource, you can configure a primary origin by using the originAddress field, and then an optional failoverOrigin. The failoverOrigin points at another origin resource.

The retryConditions for each origin specifies what types of failures triggers a retry:

Condition	Default	Description
CONNECT_FAILURE	✔️	Retry on failures include routing, DNS and TLS handshake errors, and TCP/UDP timeouts.
HTTP_5XX		Retry on any HTTP `5xx` response code.
GATEWAY_ERROR		Similar to `5xx`, but applies only to response codes `502`, `503`, or `504`.
RETRIABLE_4XX		Retry for `4xx` response codes that can be retried, including `409` and `429`.
NOT_FOUND		Retry on an HTTP `404` response code.
FORBIDDEN		Retry on an HTTP `403` response code.

If you require active health-checking, round-robin, or load-aware steering across origins, you can configure an external Application Load Balancer as the primary origin.

Failover behavior

The following table describes how failover operates, and what response a client would observe:

Scenario	Failover configured	User-facing status
Media CDN attempts to connect to your origin, and receives no HTTP response after two attempts (default).	No	HTTP `502 Bad Gateway`
Media CDN attempts to connect to your primary origin, and fails to connect (TLS handshake error). An attempt is made against your configured failover origin, which returns an HTTP `404` error.	Yes	HTTP `404 Not Found`
Media CDN attempts to connect to both your primary and failover origin, but receives no HTTP status code.	Yes	HTTP `502 Bad Gateway`

If Media CDN receives a status code matching any configured retryConditions, such as an HTTP 404 Not Found or HTTP 429 Too Many Requests error, and subsequent retry and failover origin requests continue to fail, an HTTP 502 Bad Gateway error is returned to the client after origin attempts are exhausted.

Best practices for origin failover

When configuring multiple origins for failover or load balancing, ensure that your media content and Vary, ETag, and Last-Modified header behaviors are consistent between your origins.

As a best practice, configure origin redirection only for origins that you trust and control. Ensure that you trust every origin in a redirect chain because each origin produces content that is served by your EdgeCacheService.