Includes are Limited Availability
This feature is still in Limited Availability. If you're interested and would like to use includes now, contact your Akamai account team.
Some behaviors and products such as Adaptive Media Delivery, IoT Edge Connect, and Progressive Media Download may not be supported with includes yet. Adding them to an include results in an error. To use the unsupported behavior, add it to the parent property's rule tree instead.
Includes are compatible with all security products. However, note that you can't use includes to split up the security configurations maintained outside of Property Manager.
We are continually updating Property Manager behaviors to make them work in includes.
The COMMON_SETTINGS includes come in useful in configurations that share a significant number of settings, often managed by a central team. By referencing the same COMMON_SETTINGS include in different parent properties, you ensure there’s a single place to update standardized settings. This helps to improve consistency and avoid duplication of effort. When you update and activate the include, changes take effect immediately across all parent properties. For more information, see Includes.
Before you begin
Make sure you get these things done before you start with this workflow.
-
Determine the level of security. What level of security do you need to deliver your content to requesting clients? Have a look at Understand the levels of security to figure out if you need Enhanced or Standard TLS security.
-
Set up authentication. To make calls through the various Akamai APIs available for this workflow, you need to authenticate using tokens you generate and apply in requests from your API client tool.
- Property Manager API (PAPI). This is what you'll use to set up your property to deliver your traffic. You'll need to ensure that your authentication is set up for READ/WRITE access to PAPI.
- Make sure you have write access to your primary DNS servers. You'll need to modify DNS records during the process.
- Review limits imposed on PAPI operations. Make sure you don't exceed the rate and resource limits and familiarize yourself with the concurrency control rules this API applies.
Create a COMMON_SETTINGS include
COMMON_SETTINGS include1 - Get contracts, groups, and products
These identifiers specify what modules and features you'll be able to use in your include.
You manage access to properties and includes using groups. If you don't want a certain team to access settings in parent properties and other includes, you can place them in separate groups with restricted permissions.
2 - List available rule formats
Run the List rule formats operation to check the supported rule formats.
Includes and the parent properties that reference them must use the same
ruleFormat. It is best practice to use the most recent frozen rule format. Thelatestrule format is not supported. See Rule format schemas for more details.
3 - Create an include for common settings
Create an include that'll specify a set of rules you'll reuse in your properties. Each include of this type has an autonomous activation flow, so any changes take effect immediately across all parent properties.
4 - Set variables for your include (optional)
Do you have specific data you'll repeatedly use within your include? Create local variables and apply them in behavior or criteria options with variable support. See the section on local variables for more information.
5 - Set the include's rule tree
Specify a set of rules that's common for your properties. Rule trees are maintained in a special form of JSON that you can best edit and validate in the dedicated VS code or Eclipse IDE plugins.
Sample rule tree for an include:
{
"rules": {
"name": "default",
"children": [],
"behaviors": [
{
"name": "cpCode",
"options": {
"value": {
"id": 571798,
"description": "test.mapp-dsa20170503.example.com",
"products": [
"Site_Accel"
],
"createdDate": 1493738615000,
"cpCodeLimits": null,
"name": "test.mapp-dsa20170503.example.com"
}
}
},
{
"name": "origin",
"options": {
"originType": "CUSTOMER",
"forwardHostHeader": "REQUEST_HOST_HEADER",
"cacheKeyHostname": "ORIGIN_HOSTNAME",
"compress": true,
"enableTrueClientIp": true,
"trueClientIpHeader": "True-Client-IP",
"trueClientIpClientSetting": false,
"verificationMode": "PLATFORM_SETTINGS",
"originSni": true,
"httpPort": 80,
"httpsPort": 443,
"hostname": "alternative-origin.example.com",
"originCertificate": "",
"ports": ""
}
}
],
"options": {},
"variables": [],
"comments": "common_settings"
}
}
6 - Validate the rule tree
Make sure your JSON file is correct and complete. You need to resolve returned errors, as they block an activation, but you can activate an include version that yields less severe warnings. For more information, see Rule tree errors and warnings. Both VS code and Eclipse plugins support full rule tree validation.
7 - Push the rule tree to the include
Push your JSON file back to the include.
8 - Activate the include on staging and production
With new setups, you can activate your include on both networks at the same time.
9 - Confirm activation
Make sure the activation was successful. The response should contain "status": ACTIVE.
Add the include to a property
1 - Create a parent property or edit the existing one
To create a new property, follow either the workflow for a custom cert property or a secure by default property. You can also clone a property.
If you already have a property that you'd like to set as a parent for the COMMON_SETTINGS include, list properties to store its propertyId and propertyVersion, and get the rule tree.
2 - Add the include to the property's rule tree
Edit the property's rule tree using the VS code or Eclipse IDE plugins. Add the include behavior to the rule of your choice - COMMON_SETTINGS includes can be referenced anywhere in the parent configuration, even the default rule.
The include you're referencing should already be active on the same network that you would like to activate the parent property.
Sample rule tree for a parent property:
{
"rules": {
"name": "default",
"behaviors": [
{
"name": "include",
"options": {
"id": "864255"
}
},
{
"name": "origin",
"options": {
"cacheKeyHostname": "REQUEST_HOST_HEADER",
"compress": true,
"enableTrueClientIp": true,
"forwardHostHeader": "REQUEST_HOST_HEADER",
"httpPort": 80,
"httpsPort": 443,
"originCertificate": "",
"originSni": true,
"originType": "CUSTOMER",
"ports": "",
"trueClientIpClientSetting": false,
"trueClientIpHeader": "True-Client-IP",
"verificationMode": "PLATFORM_SETTINGS",
"hostname": "origin-www.example.com"
}
},
{
"name": "cpCode",
"options": {
"value": {
"id": 1234,
"description": "www.example.com",
"products": [
"Site_Accel"
],
"createdDate": 1.653506652E12,
"cpCodeLimits": null,
"name": "www.example.com"
}
}
},
{
"name": "caching",
"options": {
"behavior": "NO_STORE"
}
}
],
"comments": "These behaviors apply to all requests"
}
}
3 - Validate the rule tree changes
Make sure your JSON file is correct and complete before deploying it on edge servers. You need to resolve returned errors, as they block an activation, but you can activate a version that yields less severe warnings. For more information, see Rule tree errors and warnings. Both VS code and Eclipse plugins support full rule tree validation.
4 - Update the property's rule tree
Push your updated JSON file back to the property.
5 - Activate the parent property on staging
Activate the property with the include for common settings, setting "network": "STAGING".
6 - Confirm activation
Make sure the activation was successful. The response should contain "status": ACTIVE.
7 - Test on staging
In your DNS, add this CNAME record to test the property on the Akamai staging network. For example, assume the domain you set in your edge hostname was "example.com" and you're using a Standard TLS certificate that adds the edgesuite.net suffix to your hostname behind the scenes:
www.example.com. 300 IN CNAME www.example.com.edgesuite-staging.net.
Use your browser or send a request with other client, for example using curl.
http://www.example.com/videos
http://www.example.com/images
Verify you get the expected response, according to what you set in the include's behaviors.
To test on staging or production without adding the DNS record, see Activate a property.
8 - Activate the parent property on production
Activate the property with the include for common settings, setting "network": "PRODUCTION".
9 - Confirm activation
Make sure the activation was successful. The response should contain "status": ACTIVE.
10 - Go live
Start serving live traffic through the Akamai Edge Platform. Replace your existing CNAME record and with a new one, setting its value to the Akamai edge hostname.
Remember to remove any entries from your local hosts file that you may have set up for testing. Now, you can restart your browser and do a smoke test of your website or application.