Includes
Includes are small chunks of a property configuration that you can create, version, and activate independently from the rest of the property's rule tree.
With includes, you can delegate different parts of single domains to responsible teams or implement common settings you can share across multiple properties.
Before you begin
- Understand the basics of Terraform.
- Complete the steps in Get started
- Set up your property and its configuration.
Choose a rule format
For updates to rule formats, see Rule format changes.
Each rule format version contains the schema for a set of rules, behaviors, options, and criteria.
- To use non-declarative includes without behaviors, your rules and includes can use any supported rule format version as long as both your rules and includes are the same version.
- To use declarative includes with behaviors, your rules and includes must use a rule format no earlier than
v2023-01-05
.
Update rule format
To update your rule format, pass the required dated version in the property resource.
resource "akamai_property" "update-rule-format" {
name = "my-property"
product_id = "prd_product"
contract_id = "ctr_C-0N7RAC7"
group_id = "grp_12345"
rule_format = "v2023-01-05"
}
Create include
You can create a new include from scratch or base one on an existing include version. Each include you create is one of two types, MICROSERVICES
or COMMON_SETTINGS
.
Type | Description | Example |
---|---|---|
MICROSERVICES | Use when different teams will work independently on different parts of a single site. For each include of this type:
| Teams managing and deploying their own set of rules. |
COMMON_SETTINGS | Use when a central team manages property configurations for your site. This type of include functions as a single source of information for common settings used across different configurations. You can create up to three of this type per parent property. | Instead of repeating work for a number of settings used by both site A and site B, changes to an include managing the shared settings updates both sites. |
New with specific rule tree
You can create a new include with a specific rule tree. This rule tree can be a new one you've configured or one from an existing include that you've edited.
-
Create or edit a rule tree.
-
To create a new rule tree, use the akamai_property_rules_template data source.
-
To use and edit an existing include's rule tree:
- Get an existing include's rules with the akamai_property_include_rules data source.
- Create a new JSON file with the returned rules and add your edits.
- Use your new JSON as a template file in the akamai_property_rules_template data source.
-
-
Once you've got a rule tree, use the values from the
akamai_property_rules_template
as variables in the akamai_property_include resource to create your new include. Theakamai_property_rules_template
data source lets you define a rule tree.resource "akamai_property_include" "new_specific_rule_tree" { contract_id = "C-0N7RAC7" group_id = "X112233" product_id = "prd_123456" name = "example3" type = "COMMON_SETTINGS" rule_format = "v2023-01-05" rules = data.akamai_property_rules_template.example.json // Here "example" would be the local name of your data source. }
-
Run
terraform plan
to check your syntax and review your changes and then runterraform apply
to create an unactivated, editable include. -
When you're ready, activate your include.
New based on existing
Each iteration of an include increases its version number, and all of those versions are available to use as a starting point for a new include, no matter its activation status. Creating a new include this way uses an existing versions rules. You can use the rule set as is or use it as your base for an iteration.
You can create a new include version using any of its previous versions as a starting point.
-
Using the akamai_property_includes data source, run
terraform plan
to get all of the includes for your contract and group. This will give the include IDs and versions. Even though the parent's and include's rule formats needs to match, if the rule format of parent is the latest, this data source will list all the includes under the contract.data "akamai_property_includes" "get_all_includes" { contract_id = "C-0N7RAC7" group_id = "X112233" } output "get_all_includes" { value = data.akamai_property_includes.get_all_includes }
-
Add the ID and version of the include you want to use to your group and contract IDs in the akamai_property_include_rules data source to identify the rule set and format you want to use.
data "akamai_property_include_rules" "rules_v2" { include_id = "inc_X12345" contract_id = "C-0N7RAC7" group_id = "X112233" version = 2 } output "rules_v2" { value = data.akamai_property_include_rules.rules_v2 }
-
If you want to use the rules as is, pass your contract and group IDs, a unique name, and variables for both the
rule_format
andrules
in the akamai_property_include resource. If you have edited the rules, add in a pointer to the JSON file location instead and use the most recent version.resource "akamai_property_include" "new_from_existing" { contract_id = "C-0N7RAC7" group_id = "X112233" product_id = "prd_123456" name = "example2" rule_format = data.akamai_property_include_rules.rules_v2.rule_format rules = data.akamai_property_include_rules.rules_v2.rules }
-
Run
terraform plan
to check your syntax and review your changes and then runterraform apply
to create an unactivated, editable include. -
When you're ready, activate your include.
Activate include
Because includes can be deployed independently of and directly affect your larger property configurations, the importance of checking their behavior on staging before deployment to your production instances cannot be overstated. For this reason, each of your includes should have one activation in staging and one in production.
-
For new includes, activation does not immediately apply their rules because they're not directly assigned to hosts.
Instead, activation of new include makes the include available for use.
The actual application of their rules comes when you associate an includes to a property. -
For existing includes that are versioning up, activation immediately deploys the changes to the parent property.
To activate an include, send the include's version information and the network setting through the akamai_property_include_activation resource.
-
Using the akamai_property_includes data source, run
terraform plan
to get all of the includes for your contract and group. This will give the include IDs and versions.data "akamai_property_includes" "get_all_includes" { contract_id = "C-0N7RAC7" group_id = "X112233" } output "get_all_includes" { value = data.akamai_property_includes.get_all_includes }
-
Send the returned
include_id
for the one you want to activate as part of the required information in theakamai_property_include_activation
resource.resource "akamai_property_include_activation" "activate_include" { include_id = "inc_X12345" contract_id = "C-0N7RAC7" group_id = "X112233" version = 1 network = "STAGING" notify_emails = [ "example@example.com", "example2@example.com" ] note = "An optional statement about your activation" ticket_id = "JIRA-1234" customer_email = "example@example.com" peer_reviewed_by = "John Doe" unit_tested = true } }
-
Run
terraform plan
to check your syntax and review your changes and then runterraform apply
to activate your include. You can now add a new include to a property. An immediate deploy of changes for existing includes occurs in the designated environment.
Add include to property
Your include's rules do not affect the behavior of a host until it's added to a property. Includes are connected to a property in a parent-child relationship.
- You can add up to 300
MICROSERVICES
and threeCOMMON_SETTINGS
includes to a single parent property. - You can add an include to several different properties.
To add your include to a property, use the property_rules_template.
Deactivate, reactivate, and delete
When you activate a new version of an include, it automatically deactivates the previous version. If you decide you want to use a previous version again, pass an include ID and a specific version in the akamai_property_include_activation
resource to reactivate it.
To delete an include, remove the include from all of its parent properties, deactivate the active versions of your include, and then use terraform destroy
to delete it.
-
Use the akamai_property_include_parents data source to find out which properties use the include.
resource "akamai_property_include" "get_all_parents" { group_id = "X112233" contract_id = "C-0N7RAC7" include_id = "inc_X12345" }
-
Edit the rule tree for each property returned and remove the includes from the rule JSON using the property_rules_template.
-
Run
terraform destroy
on the akamai_property_include_activation resource. -
Run
terraform destroy
on the akamai_property_include resource.
Updated 4 days ago