Configuring Yandex Cloud CDN when the origin is unavailable

To ensure your CDN resource continues delivering content when the primary origin is unavailable, enable caching, configure origin shielding, and connect a standby origin in advance. If your application supports older file versions, you can also allow serving stale content from the cache.

How Yandex Cloud CDN handles origin unavailabilityHow Yandex Cloud CDN handles origin unavailability

CDN servers located at various points of presence deliver content directly to users. An outage at the origin data center does not automatically stop content delivery through the CDN.

If your CDN resource only has one origin that becomes unavailable, the outcome depends on the current state of the cache:

If there is a cache miss and the origin is unavailable, the user will get an error. In case of a timeout, this may be 504 Gateway Timeout. On other failures, the error code may vary.

To improve resource fault tolerance:

1. Enable caching on the resource.
2. Enable origin shielding.
3. Prepare a standby origin.
4. Add the second origin to the origin group.
5. Allow delivery of outdated content, if applicable.
6. Complete the setup before an outage occurs.
7. Test the standby origin.

Enable caching on the resourceEnable caching on the resource

1. In the management console, select the folder where your resource is located and navigate to Cloud CDN.
2. Click the resource name.
3. Navigate to the Caching tab and click Edit.
4. Under CDN, enable CDN caching.
5. Select the setting type: Same as origin or Custom settings. Set the cache lifetime.
6. Click Save.

For a step-by-step guide, see Configuring caching.

Caching behavior depends on the resource settings and origin response headers. Browser caching is configured separately and does not replace CDN server caching.

If caching is disabled or a file is excluded from caching, Cloud CDN will access the origin each time the file is requested. Set your cache TTL based on how frequently your content updates.

Enable origin shieldingEnable origin shielding

Origin shielding adds an intermediate caching layer between the CDN servers and origins. If a file is not in the CDN server's cache, the request goes to the shielding server first. If a valid cached copy exists there, no requests are sent to the origin.

The shielding server also consolidates duplicate requests for a single file. This reduces redundant content downloads from the origin and lowers its load.

Origin shielding can significantly improve caching efficiency, especially when users request the same files through different points of presence. The result depends on request patterns and cache settings. For details, see Origin shielding.

To enable shielding:

1. Open the resource in Cloud CDN.
2. Navigate to the Origin shielding tab.
3. Click Activate, select an available location, and confirm.
4. Make sure the status has changed to Active.

It may take up to 15 minutes to apply the settings.

Learn more in this guide on enabling shielding.

Use origin shielding in addition to origin redundancy. If a file is missing from both the CDN server cache and the shielding server, the CDN must fetch it from an available origin.

Prepare a standby originPrepare a standby origin

To retrieve files when the primary origin is down, you need a secondary origin containing a copy of your content.

For VMs, you can use a different availability zone. To protect against a full cloud platform outage, host your standby origin in another cloud or independent infrastructure.

Before adding a standby origin, confirm the following:

• The files are accessible at the same paths as on the primary origin.
• All file copies are up-to-date.
• The origin is accessible to Cloud CDN, considering network restrictions and access permissions. Use an up-to-date list of Cloud CDN networks. If origin shielding is enabled, contact support to get the list of the shielding servers’ networks.
• Protocol configurations and the setting of HTTPS TLS certificates and Host headers are compatible with both origins.
• The standby origin can handle the load if the primary origin fails.

Add the second origin to the origin groupAdd the second origin to the origin group

In the management console, go to the Cloud CDN page and open the Origin groups tab. Create a new group or update an existing one. Add both origins, enable them, and set their priorities.

The following options are available:

In round-robin mode, individual requests are balanced across the origins. A single file is never fetched from two origins at the same time. For more information, see Origins and origin groups.

Once configured, add the group to the CDN resource.

It may take up to 15 minutes for settings to apply to the CDN servers. Wait for them to propagate, then test the standby origin. During failover, response times may increase while waiting for the primary origin to time out.

Allow delivery of outdated content, if applicableAllow delivery of outdated content, if applicable

For some types of content, delivering an outdated file version is often better than returning an error. In this scenario, you can allow Cloud CDN to deliver a cached copy after its TTL expires if the origin is unavailable.

When using the API, you can configure this behavior through the options.stale CDN resource parameter. Here is a configuration snippet example:

{
  "options": {
    "stale": {
      "enabled": true,
      "value": [
        "error",
        "timeout",
        "http_500",
        "http_502",
        "http_503",
        "http_504"
      ]
    }
  }
}

This example allows the CDN to deliver stale content during network errors, timeouts, and the specified HTTP status codes.

For a new resource, use the create REST API method for the Resource resource or the ResourceService/Create gRPC API call. For existing resources, use the update REST API method for the Resource resource or the ResourceService/Update gRPC API call.

export IAM_TOKEN=$(yc iam create-token)
curl \
  --request PATCH \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://cdn.api.cloud.yandex.net/cdn/v1/resources/<resource_ID>' \
  --data '{
    "options": {
      "stale": {
        "enabled": true,
        "value": [
          "error",
          "timeout",
          "http_500",
          "http_502",
          "http_503",
          "http_504"
        ]
      }
    }
  }'

Complete the setup before an outage occursComplete the setup before an outage occurs

During an outage, management operations for Cloud CDN may be unavailable along with your origins. This includes viewing resources, updating configurations, cache purging or pre-fetching.

Add your standby origin in advance and wait for the settings to apply. This enables Cloud CDN to automatically route traffic to the standby origin if the primary one goes down. You will not need to modify settings If the management console or API become unavailable.

Test the standby originTest the standby origin

For testing, use a separate, dedicated test CDN resource. You can create it by copying the configuration of your production resource. Copying is restricted to a folder. Make sure this new test resource has its own domain name and a CNAME record.

1. Place identical test files on both the primary and standby origins.
2. In the test resource, set the production standby origin as its sole primary origin. Use a separate origin group to avoid modifying your production resource group.
3. Wait for the settings to apply.
4. Send the exact same request through the test CDN resource as you would through production: use the same file path, query parameters, HTTP method, and required headers. Change only the CDN resource domain name to the test domain. Before testing, make sure the response is not fetched from a pre-populated cache of the test resource or shielding server.
5. Compare the HTTP status code, content, and key response headers with those of the production resource.
6. Check the standby origin logs to confirm request delivery.

This test confirms the backup origin is accessible to Cloud CDN and delivers content correctly.

To further test automatic failover, create a separate group with two test origins of the primary and standby priorities. Connect this group to your test CDN resource and wait for the settings to apply. Simulate a failover error, e.g., a 503 response, on the primary test origin. Request a file that is yet uncached by both the CDN and shielding servers. Check your standby origin’s logs to confirm it received the request. Restore the primary origin after testing.

Useful linksUseful links

• Recommendations on fault tolerance in Yandex Cloud
• Yandex Cloud CDN overview