AWS IAM Policy Documents

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 tutorial 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 tutorial are for illustrative purposes only. Full documentation about the IAM policy format and supported elements can be found in the AWS IAM User Guide.

$\${aws:username}

»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 tutorial.

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

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() interpolation function, which can read the contents of a local file into the configuration. Interpolation is not available when using the file() function by itself.

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
 }