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: Your users can set up automation for the include and test and deploy on their own schedule. You can control access to an include with groups, so that an application team can only edit the settings within a designated include, without having access to the parent property. You can create up to 300 of this type per parent property.	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:
  1. Get an existing include's rules with the akamai_property_include_rules data source.
  2. Create a new JSON file with the returned rules and add your edits.
  3. 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. The akamai_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 run terraform 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 and rules 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 run terraform 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 the akamai_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 run terraform 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 three COMMON_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.