» Frequently Asked Questions

» Migrating a property to Terraform

If you have an existing property you would like to migrate to Terraform we recommend the following process:

  1. Export your rules.json from your existing property (using the API, CLI, or Control Center)
  2. Create a terraform configuration that pulls in the rules.json
  3. Assign a temporary hostname for testing (hint: you can use the edge hostname as the public hostname to allow testing without changing any DNS)
  4. Activate the property and test thoroughly
  5. Once testing has concluded successfully, update the configuration to assign the production public hostnames
  6. Activate again

Once this second activation completes Akamai will automatically route all traffic to the new property and will deactivate the original property entirely if all hostnames are no longer pointed at it.

Since Terraform assumes it is the de-facto state for any resource it leverages, we strongly recommend creating a new property based off an existing rules.json tree when starting with the provider to mitigate any risks to existing setups.

» Dynamic Rule Trees Using Templates

If you wish to inject terraform data into your rules.json, for example an origin address, you can use Terraform templates to do so like so:

First decide where your origin value will come from, this could be another Terraform resource such as your origin cloud provider, or it could be a terraform input variable like this:

variable "origin" { }

Because we have not specified a default, a value is required when executing the config. We can then reference this variable using ${vars.origin} in our template data source:

data "template_file" "init" {
  template = "${file("rules.json")}"
  vars = {
    origin = "${vars.origin}"
  }
}

Then in our rules.json we would have:

{
  "name": "origin",
  "options": {
    "hostname": "**${origin}**",
    ...
  }
},

You can also inject entire JSON blocks using the same mechanism:

{
    "rules": {
        "behaviors": [
            ${origin}

        ]
    }
}

» Leverage template_file and snippets to render your configuration file

The ‘rules’ argument within the akamai_property resource enables leveraging the full breadth of the Akamai’s property management capabilities. This requires that a valid json string is passed on as opposed to a filename. Terraform enables this via the "local_file" data source that loads the file.

data "local_file" "rules" {
  filename = "${path.module}/rules.json"
}

resource "akamai_property" "example" {
  ....
  rules = "${data.local_file.terraform-demo.content}"
}

Microservices driven and DevOps users typically want additional flexibility - using delegating snippets of the configuration to different users, and inserting variables within code. Terraform's "template_file" is provides that additoinal value. Use the example below to construct a template_file data resource that helps maintain a rules.json with variables inside it:

data "template_file" "rules" {
template = "${file("${path.module}/rules.json")}"
vars = {
origin = "${var.origin}"
  }
}

resource "akamai_property" "example" {
...
rules = "${data.template_file.rules.rendered}"
}

"rules": {
  "name": "default",
  "children": [
    ${file("${snippets}/performance.json")}
    ],
    ${file("${snippets}/default.json")}
  ],
"options": {
    "is_secure": true
  }
},
  "ruleFormat": "v2018-02-27"
}

More advanced users want different properties to use different rule sets. This can be done by maintaining a base rule set and then importing individual rule sets. To do this we first create a directory structure - something like:

rules/rules.json
rules/snippets/routing.json
rules/snippets/performance.json
…

The "rules" directory contains a single file "rules.json" and a sub directory containing all rule snippets. Here, we would provide a basic template for our json.

"rules": {
  "name": "default",
  "children": [
    ${file("${snippets}/performance.json")}
    ],
    ${file("${snippets}/routing.json")}
  ],
"options": {
    "is_secure": true
    }
  },
  "ruleFormat": "v2018-02-27"

Then remove the "template_file" section we added earlier and replace it with:

data "template_file" "rule_template" {
template = "${file("${path.module}/rules/rules.json")}"
vars = {
snippets = "${path.module}/rules/snippets"
  }
}
data "template_file" "rules" {
template = "${data.template_file.rule_template.rendered}"
vars = {
tdenabled = var.tdenabled
  }
}

This enables Terraform to process the rules.json & pull each fragment that's referenced and then to pass its output through another template_file section to process it a second time. This is because the first pass creates the entire json and the second pass replaces the variables that we need for each fragment. As before, we can utilize the rendered output in our property definition.

resource "akamai_property" "example" {
....
rules = "${data.template_file.rules.rendered}"
}

» How does Terraform handle changes made through other clients (UI, APIs)?

We recommend that anyone using Terraform should manage all changes through the provider. However in case this isn't true in emergency scenarios, the terraform state tree will become inconsistent. The next 'terraform plan' will warn and suggest changes. In case you make the same change in the UI and terraform, the state will go back to being consistent and the warning will go away.

» Upgrading the Akamai Provider

To upgrade the provider, simply run terraform init again, and all providers will be updated to their latest version within specified version constraints.