Set up a Media CDN service

This quickstart shows you how to set up a Media CDN service in front of a Cloud Storage bucket. You can use this configuration for testing or as the basis for a production environment.

This page walks you through the following procedures:

Create a Cloud Storage bucket to store your content.
Enable the required services.
Create an EdgeCacheOrigin resource to connect Media CDN to your bucket.
Create an EdgeCacheService resource to configure request routing and caching for content in the origin.
Assign the IP address of the service to the domain.
Test whether a response is being cached.

Before you begin

Make sure that you have the following:

Access to Media CDN for your current project.
The Google Cloud CLI installed. Use version 345.0.0 or later.

If required, use gcloud version to check the version and gcloud components update to update your installed gcloud CLI.
The Identity and Access Management (IAM) permissions required to create Media CDN resources. Media CDN has the following predefined IAM roles:
- roles/networkservices.edgeCacheAdmin
- roles/networkservices.edgeCacheUser
- roles/networkservices.edgeCacheViewer

Create a Cloud Storage bucket

Media CDN content can originate from locations such as a Cloud Storage bucket, a third-party storage location, or a load balancer.

In this quickstart, we'll store content in a Cloud Storage bucket.

Create a publicly accessible Cloud Storage bucket and name it my-bucket.

If you prefer not to make your Cloud Storage bucket publicly accessible, you must give Media CDN permissions to access the bucket. For more information, see Using private Cloud Storage buckets.
Upload a video or image file into the bucket.

Enable the required services

To configure and deploy Media CDN services, you need to enable both the Network Services API and the Certificate Manager API for your project.

Console

Enable the Network Services API.

Enable the API
Enable the Certificate Manager API.

Enable the API

gcloud

Enable the Network Services API:

gcloud services enable networkservices.googleapis.com

Enable the Certificate Manager API:

gcloud services enable certificatemanager.googleapis.com

For more information about enabling and disabling services, see the Service Usage documentation.

Create an origin

Create an origin that points to your Cloud Storage bucket.

Console

In the Google Cloud console, go to the Media CDN page.

Go to Media CDN
Click the Origins tab.
Click Create origin.
Enter the name for the origin as cloud-storage-origin.
Optional: Enter a description for the origin.
For Origin address, choose Select a Google Cloud Storage bucket, browse to the Cloud Storage bucket named my-bucket, and then click Select.

If you have an external origin instead, choose Specify an FQDN or IP address, and then enter the FQDN or IP address.
Retain other default settings, and then click Create origin.

The newly created EdgeCacheOrigin resource appears in the list of origins in your project on the Origins page.

To update an origin address, click the origin, and then click Edit.

gcloud

The gcloud CLI provides the gcloud edge-cache sub-command group for managing both new and existing Media CDN configurations.

To create an origin for a Cloud Storage bucket, use the create command and specify the bucket name as gs://my-bucket:

gcloud edge-cache origins create ORIGIN \
    --origin-address="gs://my-bucket"

Replace ORIGIN with the name of the origin.

If you have an external origin instead, use the gcloud edge-cache origins create command and replace DOMAIN with the FQDN or IP address:

gcloud edge-cache origins create ORIGIN \
    --origin-address="DOMAIN"

To view the newly created origin, use the list command.

To update the origin address, use the update command.

Terraform

media_cdn/quickstart/main.tf

View on GitHub Feedback

resource "google_network_services_edge_cache_origin" "default" {
  name           = "cloud-storage-origin"
  origin_address = "gs://my-bucket-123123" # Update bucket name
  description    = "Media Edge Origin with Cloud Storage as Origin"
  max_attempts   = 3 # Min is 1s, Default is 1s & Max 3
  timeout {
    connect_timeout  = "10s"  # Min is 1s, Default is 5s & Max 15s
    response_timeout = "120s" # Min is 1s, Default is 30s & Max 120s
    read_timeout     = "5s"   # Min is 1s, Default is 15s & Max 30s
  }
}

Create an `EdgeCacheService` resource

Your EdgeCacheService resource configures routing, certificate, and caching settings, and can point to EdgeCacheOrigin resources.

Create a basic EdgeCacheService resource that does the following:

Caches all responses from our configured origin for one hour
Sets an x-cache-status response header that returns the cache status (such as HIT or MISS)

Optionally, register a domain name for this service.

Console

In the Google Cloud console, go to the Media CDN page.

Go to Media CDN
Click the Services tab.
Click Create service.
Enter a unique name for your service—for example, my-service—and then click Next.
In the Routing section, click Add host rule, and then enter one or more host domain names.
Click Add route rule, and then do the following:
1. For Priority, specify 1.
2. Click Add match condition:
  - For Match type, specify Prefix match.
  - For Path match, specify /.
3. Select Fetch from an Origin, and then select the origin that you configured.
4. Click Add-on actions, specify the following actions, and then click Done:
  - A header action by the name x-cache-status. Set the value as {cdn_cache_status}.
  - A route action with the type CDN policy.
5. Click Save.
Click Create service.

The newly created EdgeCacheService resource appears on the Services page in the list of services in your project.

gcloud

In Cloud Shell, use a text editor to create a local file called my-service.yaml.

Such a file indicates the following:
- How routing works—by first matching the host and then the path
- How caching works—based on the cache mode and TTL
- How requests and responses are modified—for example, by inserting the cdn_cache_status variable into a response header

Paste the following sample content into the file, and then save it:

name: SERVICE_NAME
routing:
  hostRules:
  - hosts:
    - DOMAIN_NAME 
    pathMatcher: routes
  pathMatchers:
  - name: routes
    routeRules:
    - priority: 1
      matchRules:
      - prefixMatch: /
      origin: ORIGIN
      routeAction:
        cdnPolicy:
          # Cache static content - for example, video files
          cacheMode: CACHE_ALL_STATIC
          defaultTtl: 3600s
      headerAction:
        responseHeadersToAdd:
        - headerName: "x-cache-status"
          headerValue: "{cdn_cache_status}"

Update the variables to specify the names of the resources created in earlier steps. If you specify the domain name, Media CDN responds with a 404 error for other hosts.

Run the import command, and specify the .yaml file:

gcloud edge-cache services import SERVICE_NAME \
    --source=my-service.yaml

To view the newly created service in the list of EdgeCacheService resources in your project, use the list command.

Terraform

media_cdn/quickstart/main.tf

View on GitHub Feedback

resource "google_network_services_edge_cache_service" "default" {
  name        = "cloud-media-service"
  description = "Media Edge Service with Cloud Storage as Origin"
  routing {
    host_rule {
      description  = "host rule description"
      hosts        = ["googlecloudexample.com"]
      path_matcher = "routes"
    }
    path_matcher {
      name = "routes"
      route_rule {
        description = "a route rule to match against"
        priority    = 1
        match_rule {
          prefix_match = "/"
        }
        # Referring to previously defined Edge Cache Origin
        origin = google_network_services_edge_cache_origin.default.name
        route_action {
          cdn_policy {
            cache_mode  = "CACHE_ALL_STATIC"
            default_ttl = "3600s"
          }
        }
        header_action {
          response_header_to_add {
            header_name  = "x-cache-status"
            header_value = "{cdn_cache_status}"
          }
        }
      }
    }
  }
}

It might take several minutes for your first service to be created. Media CDN provisions dedicated IP addresses and pushes your configuration to thousands of edge locations. Subsequent updates to a service, such as changing a route configuration or matching parameters, are faster.

Assign the IP address of the service to the domain

Assign the IP address of the EdgeCacheService resource to the domain. For instructions, see Set up your domain using Cloud DNS.

To view the IP addresses for your newly created service, follow these steps:

Console

In the Google Cloud console, go to the Media CDN page.

Go to Media CDN
Click the Services tab.
For your service, see the Addresses column.

gcloud

Use the gcloud edge-cache services describe command:

gcloud edge-cache services describe SERVICE_NAME

Replace SERVICE_NAME with the name of the service.

The output shows the IP addresses assigned to your service:

ipv4Addresses:
    IPV4_ADDRESS
ipv6Addresses:
    IPV6_ADDRESS
name: projects/my-project/locations/global/edgeCacheServices/SERVICE_NAME
...

Test whether a response is being cached

Before testing the service, make sure that you have cacheable content stored at your origin so that Media CDN can retrieve it.

To test that your service is correctly configured to cache content, use the curl command-line tool to issue requests and check the responses. curl is also available in Cloud Shell in the Google Cloud console.

Use the following curl command to access the content:

curl -svo /dev/null "http://DOMAIN_NAME/file.mp4"

If you configured a domain, use the following command. Replace DOMAIN_NAME and IP_ADDRESS with appropriate values. Additionally, if you did not configure DNS to point to your provisioned IP addresses, use the resolve option to override the address that curl uses.
```
curl -svo /dev/null --resolve DOMAIN_NAME:80:IP_ADDRESS "http://DOMAIN_NAME/file.mp4"
```
The command initially produces output similar to the following, with the status MISS, because Media CDN doesn't have the requested data already retrieved from the origin:
```
< HTTP/2 200
...
< x-cache-status: MISS
...
```
When you submit the same request again any number of times, it produces an output similar to the following, with the status HIT:
```
< HTTP/2 200
...
< x-cache-status: HIT
...
```
If it doesn't show the status HIT, check the following:
- The response is cacheable.
- The configured cache mode allows caching of the content.
- The origin isn't setting cache directives that prevent caching. For more information, see Cache configuration.

You've now tested a basic EdgeCacheService resource that can serve content globally. A production-grade service might need SSL (TLS) certificates, multiple origins, and a Google Cloud Armor security policy.

Optional: Clean up

Delete any resources that you do not intend to use again.

Console

In the Google Cloud console, go to the Media CDN page.

Go to Media CDN
Click the Services tab.
Select your service, and then click Delete.
Click the Origins tab.
Select your origin, and then click Delete.

gcloud

To list the resources that you created, use the services list and origins list commands.

To delete an origin, follow these steps:

Delete the service:

gcloud edge-cache services delete SERVICE_NAME

Delete the origin:

gcloud edge-cache origins delete ORIGIN

Repeat this process for any other resources that you created and do not intend to use again, such as the Cloud Storage bucket.

What's next

Issue and attach an SSL (TLS) certificate to your EdgeCacheService.
View request logs with Cloud Logging.
Configure signed requests to protect your content.
Optimize cache keys and TTLs and improve cache hit rates.
Configure advanced route matching and create additional origins.

Set up a Media CDN service

Before you begin

Create a Cloud Storage bucket

Enable the required services

Console

gcloud

Create an origin

Console

gcloud

Terraform

Create an EdgeCacheService resource

Console

gcloud

Terraform

Assign the IP address of the service to the domain

Console

gcloud

Test whether a response is being cached

Optional: Clean up

Console

gcloud

What's next

Create an `EdgeCacheService` resource