1. Introduction
The CenturyLink (CTL) content delivery network (CDN) is a global service that securely delivers HTTP/HTTPS content to end clients with low latency, high reliability and fast transfer speeds. It also provides a flexible, programmable configuration platform to fully customize how your content is obtained (filled), handled and ultimately delivered to the end client.
This document describes the services and features supported by the CTL CDN and explains how to provision them in a customer’s service image.
All new customers have access to the Version 2 (v2) configuration model from activation. For existing customers to take advantage of our new configuration model, their existing configuration must be migrated and verified. Once verified, the configuration can be enabled for customer access.
A key concept to provisioning CDN services on the CTL CDN is the subscriber’s service image. The service image is a customized configuration of the CDN’s behavior when processing requests for subscriber content. It contains the complete view of the configuration being executed on the CTL CDN, represented in JSON and accessible via an API. In support of the service image is a JSON schema, which describes the valid syntax and existing constraints of any given configuration option.
The key concepts of a service image are:
- A service image is essentially an object in an object store; it can be named, copied, and deleted, and it is versioned when overwritten.
- A service image is activated by copying to an environment (e.g., Staging or Production).
- A service image represents a customer’s complete configuration in a single JSON file.
Given that updates follow object store semantics and result in the complete replacement of the existing service image of the same name, it is not possible to make incremental or partial updates.
Beyond the above key concepts, there are a few additional concepts related to the content of the service image (i.e., the subscriber’s actual configuration data): Reporting IDs, definitions and match rules.
1.1. Reporting IDs
The ReportingID is a future feature which will provide more flexibility in both how customers configure the CDN and view their data. Once fully implemented, customers will be able to group aliases or particular requests into common reporting groups with a common configuration. For example, a customer delivering hundreds of linear video channels may want to have separate usage reporting per channel, but the channels may all have the same underlying CDN configuration. Or the customer may choose to group requests based on internal business groups that have an interest in them.
For more details, see the ReportingID section.
1.2. Definitions
Definitions are collections of common configuration data that can be referenced and that influence system behavior. Examples of definitions are a geo or IP list. In and of itself, a definition does not influence how the system processes requests. Requests must be coupled with a match rule to create a policy that instructs the system how to handle specific requests.
The use of definitions avoids having to repeat common tasks across multiple match rules. They can be managed in a single list allowing for a single change to propagate through all references.
1.3. Match Rules
The match rule is the core of the service image. It provides the criteria for evaluating requests and responses and, when matched, specifies one or more actions (e.g., setting cache expiration, calling geo definitions, content/header processing modes, etc.) for the system to take.
For more details, see the Match Rules section.
1.4. Properties
Most customers are familiar with the concepts of a ‘subscriber’ and a ‘property’ from our legacy platform. With the introduction of our new service image, we have doubled down on the subscriber concept and consolidated all configuration data under the subscriber, rather than dividing the data between a subscriber and properties.
This does not mean that we have fully abandoned the concept of a property, however; in fact, the concept is preserved, till our backend systems can understand ReportingIDs, so that existing reports and usage metrics continue to provide property-level views. To create a new property, the following process must be followed:
- Step 1
- Add an AliasDefinition
{
"reportingId": 34,
"protocol": [
"HTTP"
],
"name": "A descriptive name",
"id": 20,
"originId": 34,
"aliases": [
"alias1",
"alias2"
]
}
Note that the ReportingID and OriginID values match and are defined in the following steps, so remember the value used…
- Step 2
- Add a reportingID and set the ‘name’ field to match the 1st item on the ‘aliases’ list (in the matching aliasDefinition)
{
"logEndpoints": [
0
],
"id": 34,
"name": "alias1"
}
- Step 3
- Add an originID
{
"description": "",
"host": "www2.centurylink.com",
"id": 34,
"name": "Another server",
"originDNS": "",
"port": 80,
"protocol": "HTTP",
"webroot": "/"
}
- Step 4
- Create A MatchRule in the MatchGroup 0 and assign a trafficType.
{
"matchGroups": [
{
"id": 0,
"matchRules": [
{
"expression": "$id.minor == 34",
"id": 1,
"features": {
"trafficType": {
"value": "Live"
}
}
}
]
}
]
}
- Step 5
- Create A MatchRule in the MatchGroup=OriginID.
{
"matchGroups": [
{
"id": 34,
}
]
}
To remove a property the same steps can be followed and remove (vs. add) the relevant data. Note that removing a property from the Service Image does not fully remove it from the backend infrastructure. The property will continue to exist with the primary alias associated with it. This means that the primary alias cannot be reused under a different property. The property can be ‘reactivated’ by following the create property steps described above, making sure to include the primary alias as the first alias in the list.
1.4.1. Primary Aliases
It is important to note that when creating a new property, a primary alias is designated by the system. The first Alias in the the Aliases array is selected as the primary alias. To keep track of the primary alias, it is best practice to use the primary alias as the corresponding reportingID name. If a different reportingID name is selected, the only way to determine the primary alias at this time is to contact CDN Operations.
The primary alias is needed by legacy back office systems and thus cannot be deleted at this time. If the primary alias is removed from the service image, an error will be returned. It is however possible to remove all attributes of a property (including the primary alias).
1.5. Chargeable Features
Certain CDN features are only available via explicit order for which an additional charge may apply. Such features may show up in the service image Schema, but can only be successfully provisioned if ordered. The following features fall into this category and can only be provisioned if ordered:
If a non-ordered Chargeable Feature is provisioned, the system will return an error when attempting to promote a service image to one of the defined environments (e.g., staging or production).
1.6. Read Only features
Not all features are available for self service, however they may be included as part of your service image as they were added by CTL CDN Support at your request. This allows customers to see a full view of their provisioned services while still allowing for the remaining services to be available for self service. Read only features are identified as part of their definition and a representative list is provided below. Note that the feature definition is authoritative as to whether a feature is available for self service.
- All HTTPS Services
- Standalone ReportingIDs
- Lua Scripts
Read only features can typically be identified by the presence of a “signature”: attribute. The “signature”: attribute contains a HMAC of the read only object data using a secret key. Any attempts to modify read only data will result in the signature contained in the service image to no longer match the one created by the system and the service image to be rejected.