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.
With MICROSERVICE includes, you can delegate the management of different parts of a single domain to responsible teams. Includes have a separate activation flow, which allows different teams to work independently of each other. You can control access to an include with groups, so that an application team can only edit the settings within a designated include, having read-only access to the parent property.
Breaking up your configuration into MICROSERVICE includes improves flexibility and makes it easier to incorporate automation. Developers can push changes to staging or production networks on their own schedule. They no longer have to wait for other teams to approve and test their updates. 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 MICROSERVICE includes
MICROSERVICE includes1 - 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 have edit access to 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 a microservice
Create an include that'll specify a set of rules for a microservice. Each include of this type has an autonomous activation flow and may have a separate access control, which allows different teams to work independently on different parts of a single site.
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 to control how the content for your microservice is delivered. 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": "/videos"
}
}
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.
10 - Create an include for another microservice
To create and activate includes for your other microserives, for example images, follow steps 1 to 8.
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 MICROSERVICE includes, 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. Create a separate rule for each microservice, adding the include behavior and the mutually exclusive path match.
If you don't set a
pathmatch within the same rule or the match isn't mutually exclusive, you'll get a validation error that prevents activation.
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",
"children": [
{
"name": "/videos",
"children": [],
"behaviors": [
{
"name": "include",
"options": {
"id": "inc_1234"
}
}
],
"criteria": [
{
"name": "path",
"options": {
"matchOperator": "MATCHES_ONE_OF",
"matchCaseSensitive": false,
"normalize": false,
"values": [
"/videos",
"/videos/*"
]
}
}
],
"criteriaMustSatisfy": "all",
"comments": "These behaviors apply to /api1"
},
{
"name": "/images",
"children": [],
"behaviors": [
{
"name": "include",
"options": {
"id": "inc_5678"
}
}
],
"criteria": [
{
"name": "path",
"options": {
"matchOperator": "MATCHES_ONE_OF",
"matchCaseSensitive": false,
"normalize": false,
"values": [
"/images",
"/images/*"
]
}
}
],
"criteriaMustSatisfy": "all",
"comments": "These behaviors apply to /images"
}
],
"behaviors": [
{
"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.
Double-check if the response returns any further errors or warnings. You need to resolve validation 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.
5 - Activate the parent property on staging
Activate the property with the includes for microservices, 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 includes' 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 includes for microservices, 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.