» AWS IAM Policy Documents with Terraform

AWS leverages a standard JSON Identity and Access Management (IAM) policy document format across many services to control authorization to resources and API actions. This guide is designed to highlight some recommended configuration patterns with how Terraform and the AWS provider can build these policy documents.

The example policy documents and resources in this guide are for illustrative purposes only. Full documentation about the IAM policy format and supported elements can be found in the AWS IAM User Guide.

NOTE: Some AWS services only allow a subset of the policy elements or policy variables. For more information, see the AWS User Guide for the service you are configuring.

NOTE: IAM policy variables, e.g. ${aws:username}, use the same configuration syntax (${...}) as Terraform interpolation. When implementing IAM policy documents with these IAM variables, you may receive syntax errors from Terraform. You can escape the dollar character within your Terraform configration to prevent the error, e.g. $${aws:username}.

Choosing a Configuration Method
Recommended Configuration Method Examples
- aws_iam_policy_document Data Source
- Multiple Line Heredoc Syntax
Other Configuration Method Examples

» Choosing a Configuration Method

Terraform offers flexibility when creating configurations to match the architectural structure of teams and infrastructure. In most situations, using native functionality within Terraform and its providers will be the simplest to understand, eliminating context switching with other tooling, file sprawl, or differing file formats. Configuration examples of the available methods can be found later in the guide.

The recommended approach to building AWS IAM policy documents within Terraform is the highly customizable aws_iam_policy_document data source. A short list of benefits over other methods include:

Native Terraform configuration - no need to worry about JSON formatting or syntax
Policy layering - create policy documents that combine and/or overwrite other policy documents
Built-in policy error checking

Otherwise in simple cases, such as a statically defined assume role policy for an IAM role, Terraform's multiple line heredoc syntax allows the easiest formatting without any indirection of a separate data source configuration or file.

Additional methods are available, such single line string syntax, the file() interpolation function, and the template_file data source, however their usage is discouraged due to their complexity.

» Recommended Configuration Method Examples

These configuration methods are the simplest and most powerful within Terraform.

» aws_iam_policy_document Data Source

For complete implementation information and examples, see the aws_iam_policy_document data source documentation.

data "aws_iam_policy_document" "example" {
  statement {
    actions   = ["*"]
    resources = ["*"]
  }
}

resource "aws_iam_policy" "example" {
  # ... other configuration ...

  policy = "${data.aws_iam_policy_document.example.json}"
}

» Multiple Line Heredoc Syntax

Interpolation is available within the heredoc string if necessary.

For example:

resource "aws_iam_policy" "example" {
  # ... other configuration ...
  policy = <<POLICY
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "*",
    "Resource": "*"
  }
}
POLICY
}

» Other Configuration Method Examples

These other configuration methods are provided only for reference and not meant to be an authoritative source of information.

» Single Line String Syntax

Single line IAM policy documents can be constructed with regular string syntax. Interpolation is available within the string if necessary. Since the double quotes within the IAM policy JSON conflict with Terraform's double quotes for declaring a string, they need to be escaped (\").

For example:

resource "aws_iam_policy" "example" {
  # ... other configuration ...

  policy = "{\"Version\": \"2012-10-17\", \"Statement\": {\"Effect\": \"Allow\", \"Action\": \"*\", \"Resource\": \"*\"}}"
}

» file() Interpolation Function

To decouple the IAM policy JSON from the Terraform configuration, Terraform has a built-in file() function, which can read the contents of a local file into the configuration.

For example, creating a file called policy.json with the contents:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "*",
    "Resource": "*"
  }
}

Those contents can be read into the Terraform configuration via:

resource "aws_iam_policy" "example" {
  # ... other configuration ...

  policy = "${file("policy.json")}"
}

» template_file Data Source

To enable interpolation in decoupled files, the template_file data source is available.

For example, creating a file called policy.json.tpl with the contents:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "*",
    "Resource": "${resource}"
  }
}

Those contents can be read and interpolated into the Terraform configuration via:

data "template_file" "example" {
  template = "${file("policy.json.tpl")}"

  vars {
    resource = "${aws_vpc.example.arn}"
  }
}

resource "aws_iam_policy" "example" {
  # ... other configuration ...

  policy = "${data.template_file.example.rendered}"
}