Google Cloud Media CDN Workshop: Architecture & End-to-End Lab Guide

A Media CDN deployment is composed of modular, loosely coupled resources that separate backend connectivity (EdgeCacheOrigin), client-facing routing and caching (EdgeCacheService), TLS certificate lifecycle management (Certificate Manager), and cryptographic access control (EdgeCacheKeyset). Understanding how these components interact allows you to update routing rules or swap storage backends independently without disrupting global edge traffic.

2.1 EdgeCacheService (Services, Routing & CDN Policies)

The EdgeCacheService is the primary client-facing resource in Media CDN. When you create an EdgeCacheService, Google Cloud allocates dedicated global Anycast IPv4 and IPv6 addresses at the edge of Google's network. The service resource is typically managed declaratively via a YAML configuration file (gcloud edge-cache services import) and governs three layers of request processing:

• TLS & Listener Configuration (edgeSslCertificates, requireTls): Binds up to five Certificate Manager certificates (with EDGE_CACHE scope) to terminate HTTPS/HTTP2/HTTP3 (QUIC) connections at the Google edge PoP closest to the end user.
• Host & Path Routing (routing.hostRules and routing.pathMatchers): Evaluates the incoming HTTP Host header (such as ws-test.pleys.net) and dispatches the request to a named pathMatcher. Inside the pathMatcher, prioritized routeRules inspect the URL path (via prefixMatch, fullPathMatch, or pathTemplateMatch), headers, or query parameters to select the target EdgeCacheOrigin.
• Route Actions & CDN Policies (routeAction.cdnPolicy and routeAction.urlRewrite): Controls how requests and responses are transformed and cached per route. This includes URL path rewriting (pathPrefixRewrite), CORS headers, and the cdnPolicy block which dictates the cacheMode (CACHE_ALL_STATIC, USE_ORIGIN_HEADERS, FORCE_CACHE_ALL, or BYPASS_CACHE), Time-To-Live durations (defaultTtl, maxTtl, clientTtl), and custom cacheKeyPolicy settings.

2.2 EdgeCacheOrigin (Backend Origins & Failover)

An EdgeCacheOrigin defines an upstream backend server or storage bucket from which Media CDN fetches content when an edge cache miss occurs (known as an origin fill). Multiple routes within one or more EdgeCacheService configurations can reference the same EdgeCacheOrigin. Key capabilities include:

• Native Cloud Storage Integration (gs://): When originAddress is set to gs://bucket-name, Media CDN communicates directly with Google Cloud Storage over Google's private backbone using the Media CDN Service Agent identity.
• External & Third-Party Origins: Supports standard HTTP/HTTPS endpoints (such as Live Stream API packagers, GKE ingress, or Compute Engine load balancers) as well as AWS S3 and Azure Blob Storage buckets (including AWS Signature Version 4 origin authentication).
• Resiliency, Timeouts & Failover (failoverOrigin, retryConditions, timeout): Each origin can specify granular timeouts (connectTimeout, maxAttemptsTimeout, readTimeout), automatic retry conditions (such as CONNECT_FAILURE, HTTP_5XX, NOT_FOUND for live streaming segment availability), and a secondary failoverOrigin resource that automatically serves traffic if the primary origin experiences an outage.

2.3 Certificate Manager (EDGE_CACHE Certificates & DNS Authorizations)

Media CDN integrates directly with Google Cloud Certificate Manager (gcloud certificate-manager) to handle SSL/TLS certificates at scale. Rather than managing standalone certificate resources inside the CDN API, you provision certificates in Certificate Manager with --scope=EDGE_CACHE so they are distributed globally across all Media CDN edge locations:

• DNS Authorizations (dns-authorizations): Proves ownership of your domain (for example, ws-test.pleys.net) using an ACME DNS-01 challenge. Certificate Manager generates a unique CNAME record that you place in your DNS zone once, enabling automated certificate issuance and zero-touch renewal without requiring HTTP port 80 traffic to point to Google Cloud beforehand.
• Google-Managed Edge Certificates (certificates): Provisioned and automatically renewed by Google Certificate Authority once the linked DNS Authorization is verified. You can also upload self-managed PEM certificates if your organization mandates custom Certificate Authorities.

2.4 EdgeCacheKeyset (Signed Requests & Token Authentication)

For workloads requiring content protection—such as subscription VOD or pay-per-view live events—an EdgeCacheKeyset stores the cryptographic keys used by Media CDN to validate signed URLs, signed cookies, or Dual-Token authentication tokens at the edge before serving cached bytes:

• Ed25519 Public Keys: Used for asymmetric URL and cookie signature verification.
• Validation Shared Keys (Secret Manager): References HMAC secrets stored in Google Cloud Secret Manager for symmetric token verification.

2.5 Media CDN Service Agent (Private Origin Authentication)

When you enable and use Media CDN in a project, Google Cloud provisions a dedicated Google-managed service account known as the Media CDN Service Agent: service-<PROJECT_NUMBER>@gcp-sa-mediaedgefill.iam.gserviceaccount.com.

By granting this service agent the roles/storage.objectViewer IAM role on your Cloud Storage buckets (ws-test-mp4-bucket and ws-test-vast-bucket), Media CDN can fetch objects privately. You do not need to make your Cloud Storage buckets public (allUsers) on the internet; all viewer access is strictly funneled through your Media CDN EdgeCacheService policies.

2.6 Component Summary Matrix

The table below summarizes the core resources involved in our workshop deployment, their corresponding gcloud CLI command groups, and the specific resource names we will configure in the upcoming steps.

Understanding how FORCE_CACHE_ALL interacts with Private Cloud Storage origins is critical for this workshop. When Media CDN fetches an object from a private GCS bucket using its Service Agent, Cloud Storage automatically attaches a Cache-Control: private, max-age=0 header to the HTTP response because the request was authenticated. Under USE_ORIGIN_HEADERS or CACHE_ALL_STATIC, Media CDN would honor the private directive and refuse to cache the asset. Setting cacheMode: FORCE_CACHE_ALL instructs Media CDN to override origin Cache-Control headers and unconditionally cache every successful 200 OK / 206 Partial Content response for the duration specified in defaultTtl (86400s for /mp4 and 3600s for /vast).

Follow the sequential steps below in Cloud Shell or a local terminal with the Google Cloud SDK installed. Each code block is preceded by a description of the resources and parameters being configured.

First, set the shell environment variables for your Google Cloud project, target region for the Cloud Storage buckets, workshop domain (ws-test.pleys.net), and bucket names (ws-test-mp4-bucket and ws-test-vast-bucket). Retrieving the numeric PROJECT_NUMBER dynamically ensures we can reference the Media CDN Service Agent accurately in later IAM bindings.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)")
export BUCKET_LOCATION="europe-west4"
export DOMAIN="ws-test.pleys.net"
export MP4_BUCKET="ws-test-mp4-bucket"
export VAST_BUCKET="ws-test-vast-bucket"

echo "Project ID:     ${PROJECT_ID}"
echo "Project Number: ${PROJECT_NUMBER}"
echo "Domain:         ${DOMAIN}"

Next, enable the Network Services API (which hosts Media CDN edge-cache resources), the Certificate Manager API (for Google-managed EDGE_CACHE TLS certificates), and the Cloud Storage API.

gcloud services enable \
    networkservices.googleapis.com \
    certificatemanager.googleapis.com \
    storage.googleapis.com \
    --project="${PROJECT_ID}"

Create the ws-test-mp4-bucket Cloud Storage bucket to store video assets served under the /mp4 route. We enable --uniform-bucket-level-access and --pap (Public Access Prevention) so that objects remain strictly private and accessible only through Media CDN.

gcloud storage buckets create "gs://${MP4_BUCKET}" \
    --project="${PROJECT_ID}" \
    --location="${BUCKET_LOCATION}" \
    --uniform-bucket-level-access \
    --pap

Create the second Cloud Storage bucket, ws-test-vast-bucket, which will serve VAST ad-tag XML manifests requested under the /vast route, using the same security posture.

gcloud storage buckets create "gs://${VAST_BUCKET}" \
    --project="${PROJECT_ID}" \
    --location="${BUCKET_LOCATION}" \
    --uniform-bucket-level-access \
    --pap

Create and upload a sample MP4 placeholder file (sample.mp4) and a sample VAST 4.0 XML manifest (ad-tag.xml) to their respective buckets so we can test end-to-end routing and verify TTL headers once the CDN service is live.

# Generate a 1 MB dummy MP4 file and upload to ws-test-mp4-bucket
dd if=/dev/urandom of=/tmp/sample.mp4 bs=1024 count=1024
gcloud storage cp /tmp/sample.mp4 "gs://${MP4_BUCKET}/sample.mp4" \
    --content-type="video/mp4"

# Generate a sample VAST XML response and upload to ws-test-vast-bucket
cat << 'EOF' > /tmp/ad-tag.xml
<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.0">
  <Ad id="workshop-vast-ad-001">
    <InLine>
      <AdSystem>MediaCDN-Workshop</AdSystem>
      <AdTitle>Sample Pre-Roll Ad</AdTitle>
    </InLine>
  </Ad>
</VAST>
EOF
gcloud storage cp /tmp/ad-tag.xml "gs://${VAST_BUCKET}/ad-tag.xml" \
    --content-type="application/xml"

Provision the Google-managed Media CDN Service Agent identity (service-${PROJECT_NUMBER}@gcp-sa-mediaedgefill.iam.gserviceaccount.com) for your project. Running services identity create explicitly creates the service account immediately so you can bind IAM permissions before creating your first EdgeCacheOrigin.

gcloud beta services identity create \
    --service=networkservices.googleapis.com \
    --project="${PROJECT_ID}"

Grant the Media CDN Service Agent the Storage Object Viewer role (roles/storage.objectViewer) on both ws-test-mp4-bucket and ws-test-vast-bucket. This allows Media CDN edge caches to pull objects from both private buckets during cache misses.

export MEDIA_CDN_SA="service-${PROJECT_NUMBER}@gcp-sa-mediaedgefill.iam.gserviceaccount.com"

gcloud storage buckets add-iam-policy-binding "gs://${MP4_BUCKET}" \
    --member="serviceAccount:${MEDIA_CDN_SA}" \
    --role="roles/storage.objectViewer"

gcloud storage buckets add-iam-policy-binding "gs://${VAST_BUCKET}" \
    --member="serviceAccount:${MEDIA_CDN_SA}" \
    --role="roles/storage.objectViewer"

Create a Certificate Manager DNS Authorization (ws-test-dns-auth) for ws-test.pleys.net. This initiates the ACME DNS-01 domain ownership challenge required to issue a Google-managed edge certificate.

gcloud certificate-manager dns-authorizations create ws-test-dns-auth \
    --domain="${DOMAIN}" \
    --description="DNS authorization for Media CDN workshop domain ${DOMAIN}" \
    --project="${PROJECT_ID}"

Retrieve the CNAME record details generated by the DNS Authorization. You must add the returned dnsResourceRecord.name (_acme-challenge.ws-test.pleys.net.) and dnsResourceRecord.data target to the authoritative DNS zone for pleys.net.

gcloud certificate-manager dns-authorizations describe ws-test-dns-auth \
    --project="${PROJECT_ID}" \
    --format="yaml(domain,dnsResourceRecord)"

Create the Google-managed SSL certificate (ws-test-edge-cert) for ws-test.pleys.net linked to ws-test-dns-auth. Setting --scope=EDGE_CACHE is mandatory so Certificate Manager distributes the certificate to Media CDN edge PoPs globally.

gcloud certificate-manager certificates create ws-test-edge-cert \
    --domains="${DOMAIN}" \
    --dns-authorizations="ws-test-dns-auth" \
    --scope=EDGE_CACHE \
    --description="Google-managed EDGE_CACHE certificate for ${DOMAIN}" \
    --project="${PROJECT_ID}"

Check the provisioning status of ws-test-edge-cert. Once your DNS CNAME record propagates, the managed.state field will transition from PROVISIONING to ACTIVE (typically within a few minutes).

gcloud certificate-manager certificates describe ws-test-edge-cert \
    --project="${PROJECT_ID}" \
    --format="yaml(name,scope,managed.state,managed.authorizationAttemptInfo)"

Create the first EdgeCacheOrigin resource (ws-test-mp4-origin) pointing to gs://ws-test-mp4-bucket. Notice that Cloud Storage origins must use the canonical gs://<bucket-name> URI format in --origin-address.

gcloud edge-cache origins create ws-test-mp4-origin \
    --origin-address="gs://${MP4_BUCKET}" \
    --description="GCS origin for /mp4 video assets" \
    --protocol=HTTP2 \
    --retry-conditions="CONNECT-FAILURE,HTTP-5XX,GATEWAY-ERROR" \
    --project="${PROJECT_ID}"

Create the second EdgeCacheOrigin resource (ws-test-vast-origin) pointing to gs://ws-test-vast-bucket to serve VAST ad-tag assets.

gcloud edge-cache origins create ws-test-vast-origin \
    --origin-address="gs://${VAST_BUCKET}" \
    --description="GCS origin for /vast ad manifests" \
    --protocol=HTTP2 \
    --retry-conditions="CONNECT_FAILURE,HTTP_5XX,GATEWAY_ERROR" \
    --project="${PROJECT_ID}"

List your configured EdgeCacheOrigin resources to confirm both origins are active and pointing to the right GCS buckets.

gcloud edge-cache origins list --project="${PROJECT_ID}"

Generate the declarative Media CDN service configuration file (ws-test-service.yaml). This specification performs the following configurations:

1. Attaches the Google-managed ws-test-edge-cert certificate via edgeSslCertificates.
2. Maps the hostname ws-test.pleys.net to the workshop-routes path matcher.
3. Configures Route Rule 1 (priority: 10) to match /mp4/ (prefixMatch: "/mp4/") and exact /mp4, rewrite the /mp4/ prefix to / (pathPrefixRewrite: "/" so https://ws-test.pleys.net/mp4/sample.mp4 fetches gs://ws-test-mp4-bucket/sample.mp4), route to ws-test-mp4-origin, and enforce cacheMode: FORCE_CACHE_ALL with a 1-day TTL (86400s).
4. Configures Route Rule 2 (priority: 20) to match /vast/ (prefixMatch: "/vast/") and exact /vast, rewrite the /vast/ prefix to / (pathPrefixRewrite: "/" so https://ws-test.pleys.net/vast/ad-tag.xml fetches gs://ws-test-vast-bucket/ad-tag.xml), route to ws-test-vast-origin, and enforce cacheMode: FORCE_CACHE_ALL with a 1-hour TTL (3600s).

cat << EOF > /tmp/ws-test-service.yaml
name: ws-test-service
description: "Media CDN workshop service for ${DOMAIN}"
requireTls: false
edgeSslCertificates:
  - projects/${PROJECT_ID}/locations/global/certificates/ws-test-edge-cert
routing:
  hostRules:
    - description: "Route traffic for ${DOMAIN}"
      hosts:
        - "${DOMAIN}"
      pathMatcher: workshop-routes
  pathMatchers:
    - name: workshop-routes
      description: "Path-based routing for /mp4 and /vast GCS backends"
      routeRules:
        - priority: 10
          description: "Route /mp4 requests and force cache for 1 day (86400s)"
          origin: ws-test-mp4-origin
          matchRules:
            - prefixMatch: "/mp4/"
            - fullPathMatch: "/mp4"
          routeAction:
            urlRewrite:
              pathPrefixRewrite: "/"
            cdnPolicy:
              cacheMode: FORCE_CACHE_ALL
              defaultTtl: 86400s
              clientTtl: 86400s
        - priority: 20
          description: "Route /vast requests and force cache for 1 hour (3600s)"
          origin: ws-test-vast-origin
          matchRules:
            - prefixMatch: "/vast/"
            - fullPathMatch: "/vast"
          routeAction:
            urlRewrite:
              pathPrefixRewrite: "/"
            cdnPolicy:
              cacheMode: FORCE_CACHE_ALL
              defaultTtl: 3600s
              clientTtl: 3600s
EOF

Import the ws-test-service.yaml specification using gcloud edge-cache services import to deploy the EdgeCacheService globally across Google's edge network.

gcloud edge-cache services import ws-test-service \
    --source=/tmp/ws-test-service.yaml \
    --project="${PROJECT_ID}"

Retrieve the global Anycast IPv4 and IPv6 addresses allocated to ws-test-service. Create an A record (IPv4) and AAAA record (IPv6) for ws-test.pleys.net in your DNS provider pointing to these IP addresses.

gcloud edge-cache services describe ws-test-service \
    --project="${PROJECT_ID}" \
    --format="yaml(name,ipv4Addresses,ipv6Addresses,edgeSslCertificates)"

Test the /mp4 route (https://ws-test.pleys.net/mp4/sample.mp4) using curl. By passing --resolve, you can test immediately against the allocated Media CDN Anycast IPv4 address even before public DNS finishes propagating. Run the request twice: the first request populates the edge cache from gs://ws-test-mp4-bucket, and the second request is served directly from Media CDN edge memory with a Cache-Control: public, max-age=86400 header (1 day TTL) and an Age header.

export EDGE_IPV4=$(gcloud edge-cache services describe ws-test-service \
    --project="${PROJECT_ID}" \
    --format="value(ipv4Addresses[0])")

# First request (Origin Fill) and Second request (Edge Cache Hit - 1 Day / 86400s TTL)
curl -I -s --resolve "${DOMAIN}:443:${EDGE_IPV4}" "https://${DOMAIN}/mp4/sample.mp4" | grep -iE "HTTP/|cache-control|age|content-type|server"
sleep 2
curl -I -s --resolve "${DOMAIN}:443:${EDGE_IPV4}" "https://${DOMAIN}/mp4/sample.mp4" | grep -iE "HTTP/|cache-control|age|content-type|server"

Next, test the /vast route (https://ws-test.pleys.net/vast/ad-tag.xml) to verify that requests beginning with /vast/ are routed to gs://ws-test-vast-bucket and cached with a 1-hour (3600s) TTL (Cache-Control: public, max-age=3600).

# First request (Origin Fill) and Second request (Edge Cache Hit - 1 Hour / 3600s TTL)
curl -I -s --resolve "${DOMAIN}:443:${EDGE_IPV4}" "https://${DOMAIN}/vast/ad-tag.xml" | grep -iE "HTTP/|cache-control|age|content-type|server"
sleep 2
curl -I -s --resolve "${DOMAIN}:443:${EDGE_IPV4}" "https://${DOMAIN}/vast/ad-tag.xml" | grep -iE "HTTP/|cache-control|age|content-type|server"

When the workshop concludes, run the command block below to delete the EdgeCacheService, both EdgeCacheOrigin resources, the Certificate Manager certificate and DNS authorization, and the two Cloud Storage buckets to avoid ongoing resource charges.

gcloud edge-cache services delete ws-test-service --project="${PROJECT_ID}" --quiet
gcloud edge-cache origins delete ws-test-mp4-origin --project="${PROJECT_ID}" --quiet
gcloud edge-cache origins delete ws-test-vast-origin --project="${PROJECT_ID}" --quiet
gcloud certificate-manager certificates delete ws-test-edge-cert --project="${PROJECT_ID}" --quiet
gcloud certificate-manager dns-authorizations delete ws-test-dns-auth --project="${PROJECT_ID}" --quiet
gcloud storage rm --recursive "gs://${MP4_BUCKET}" "gs://${VAST_BUCKET}" --project="${PROJECT_ID}"