Enable and configure origin shielding

Origin Shielding places a shield server between CDN edge servers and the origin. The shield server, called the precache server in the Customer Portal, serves edge requests from its cache when possible, so the origin is contacted only on a cache miss. This reduces the number of requests reaching the origin during traffic bursts.

The shield uses the pull protocol configured on the CDN resource — HTTP or HTTPS. Selecting the shield location closest to the origin minimizes the distance on the shield-to-origin connection.

Enable Origin Shielding

ℹ️

Origin Shielding is a paid option. To make it available for a CDN resource, contact CDB support or the account manager.

1. 1

   Open the CDN resource settings

   In the CDB Technical Web Portal, navigate to CDN > CDN resources and click the CNAME of the resource to configure.

2. 2

   Open Origin Shielding

   In the resource settings sidebar, click Origin Shielding.

   
3. 3

   Enable the toggle

   Turn on the Enable Origin Shielding toggle.

4. 4

   Select the shield location

   In the Data center dropdown, select the location for the precache server. The location closest to the origin server minimizes the shield-to-origin latency.

5. 5

   Save

   Click Save changes.

Activation begins immediately and completes in under 15 minutes. This notification appears:

Shield cache space

Each CDN resource with Origin Shielding includes 400 GB of cache space on the shield. This space holds the content that edge servers request from the shield, so popular files stay on the shield and do not go back to the origin.

If the content library is larger than 400 GB, for example a video-on-demand library, contact CDB support or the account manager to request additional shield cache space. Include the CDN resource ID and the expected library size in the request.

Route CDN edge requests for one resource through a shield location so the origin is contacted only on a cache miss.

ℹ️

An API token is required. The CDN resource ID is visible under CDN → CDN Resources, or from the resources list call.

Origin shielding is a paid option. To make it available for a CDN resource, contact CDB Support.

Each CDN resource with Origin Shielding includes 400 GB of cache space on the shield. To request additional shield cache space for a larger content library, contact CDB Support with the CDN resource ID and the expected library size.

Select the shield location closest to the origin. The shield uses the HTTP or HTTPS pull protocol already configured on the CDN resource.

Open a terminal and export the required variables:

export GCORE_API_KEY="{YOUR_API_KEY}"
export CDN_RESOURCE_ID="{YOUR_CDN_RESOURCE_ID}"
export SHIELDING_POP="{YOUR_SHIELDING_LOCATION_ID}"

shielding_pop is the shield location ID. A value of null disables origin shielding.

List shield locations

List the available locations first, then use the ID of the location closest to the origin as SHIELDING_POP. Each location includes a datacenter name, a city, and a country.

from gcore import CDB

client = CDB()
locations = client.cdn.shielding_location.list()
for item in locations:
    print(item.id, item.datacenter, item.city, item.country)

package main

import (
    "context"
    "fmt"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()

    page, err := client.CDN.ShieldingLocation.List(ctx, cdn.ShieldingLocationListParams{})
    if err != nil {
        panic(err)
    }
    for _, item := range page.Results {
        fmt.Println(item.ID, item.Datacenter, item.City, item.Country)
    }
}

curl "https://api.cdb-staging.cdn.orange.com/cdn/shieldingpop_v2" \
  -H "Authorization: APIKey $GCORE_API_KEY"

The API returns HTTP 200:

[
  {
    "id": 172,
    "datacenter": "dc3",
    "city": "Ashburn",
    "country": "USA"
  }
]

Enable origin shielding

Set shielding_pop to a location id. The response returns that id immediately. Activation completes in under 15 minutes.

import os

from gcore import CDB

client = CDB()
resource_id = int(os.environ["CDN_RESOURCE_ID"])
shielding_pop = int(os.environ["SHIELDING_POP"])

updated = client.cdn.cdn_resources.shield.replace(
    resource_id,
    shielding_pop=shielding_pop,
)
print(updated["shielding_pop"])

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }
    shieldingPop, err := strconv.ParseInt(os.Getenv("SHIELDING_POP"), 10, 64)
    if err != nil {
        panic(err)
    }

    updated, err := client.CDN.CDNResources.Shield.Replace(ctx, resourceID, cdn.CDNResourceShieldReplaceParams{
        OriginShielding: cdn.OriginShieldingParam{
            ShieldingPop: gcore.Int(shieldingPop),
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println((*updated).(map[string]any)["shielding_pop"])
}

curl -X PUT "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID/shielding_v2" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"shielding_pop\": $SHIELDING_POP}"

The API returns HTTP 200:

{
  "shielding_pop": 172
}

Disable origin shielding

Set shielding_pop to null. The resource stops sending edge requests through a shield.

import os

from gcore import CDB

client = CDB()
resource_id = int(os.environ["CDN_RESOURCE_ID"])

updated = client.cdn.cdn_resources.shield.replace(
    resource_id,
    shielding_pop=None,
)
print(updated["shielding_pop"])

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
    "github.com/G-Core/gcore-go/packages/param"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    updated, err := client.CDN.CDNResources.Shield.Replace(ctx, resourceID, cdn.CDNResourceShieldReplaceParams{
        OriginShielding: cdn.OriginShieldingParam{
            ShieldingPop: param.Null[int64](),
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println((*updated).(map[string]any)["shielding_pop"])
}

curl -X PUT "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID/shielding_v2" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shielding_pop": null}'

The API returns HTTP 200:

{
  "shielding_pop": null
}

Route CDN edge requests through a shield location with the Terraform provider v2, so the origin is contacted only on a cache miss. Select the location closest to the origin, while the shield uses the HTTP or HTTPS pull protocol already configured on the CDN resource.

ℹ️

Origin shielding is a paid option. To make it available for a CDN resource, contact CDB support.

Enable origin shielding

Select the shield location by city and set shielding_pop on the CDN resource. Activation completes in under 15 minutes.

data "gcore_cdn_shielding_locations" "available" {}

locals {
  shielding_pop = one([
    for location in data.gcore_cdn_shielding_locations.available.items :
    location.id if location.city == "Ashburn"
  ])
}

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "shield.mywebsite.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"
}

resource "gcore_cdn_origin_shielding" "example" {
  resource_id   = gcore_cdn_resource.example.id
  shielding_pop = local.shielding_pop
}

Change the shield location

Edit the city and run terraform apply, so the shield uses the new location.

data "gcore_cdn_shielding_locations" "available" {}

locals {
  shielding_pop = one([
    for location in data.gcore_cdn_shielding_locations.available.items :
    location.id if location.city == "Singapore"
  ])
}

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "shield.mywebsite.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"
}

resource "gcore_cdn_origin_shielding" "example" {
  resource_id   = gcore_cdn_resource.example.id
  shielding_pop = local.shielding_pop
}

Disable origin shielding

Remove the gcore_cdn_origin_shielding block and run terraform apply, so the resource stops sending edge requests through a shield and shielding_pop becomes null.

data "gcore_cdn_shielding_locations" "available" {}

locals {
  shielding_pop = one([
    for location in data.gcore_cdn_shielding_locations.available.items :
    location.id if location.city == "Singapore"
  ])
}

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "shield.mywebsite.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"
}

# Remove or comment out this block:
# resource "gcore_cdn_origin_shielding" "example" {
#   resource_id   = gcore_cdn_resource.example.id
#   shielding_pop = local.shielding_pop
# }

terraform apply