New Guide: AWS IAM Policy Documents

[bflad]

We have fielded quite a few issues and documentation requests surrounding IAM policy document building in the past. This guide is designed to highlight some examples how Terraform and the AWS provider allow for many configuration styles to implement these policies. We then can cross reference this guide in all documentation where IAM policy documents are used.

Closes #5984

Changes proposed in this pull request:

• New Guide: AWS IAM Policy Documents
• Link to AWS IAM Policy Documents guide from various resources that require building these documents

Output from acceptance testing: N/A

[rifelpet]

This suggests using &{...} syntax but L17 of the guide suggests using $${...}. Which one is officially recommended? It should probably be consistent.

[bflad]

@rifelpet outside the aws_iam_policy_document data source, the $$ syntax must be used for escaping, but it does also work within the data source too.

Given this example configuration:

terraform {
  required_version = "0.11.8"
}

provider "aws" {
  region  = "us-east-1"
  version = "1.38.0"
}

data "aws_iam_policy_document" "example" {
  statement {
    actions   = ["s3:GetObject"]
    resources = ["arn:aws:s3:::$${aws:username}/*"]
  }
}

resource "aws_iam_policy" "example" {
  name_prefix = "escaped-iam-variable-example"
  policy      = "${data.aws_iam_policy_document.example.json}"
}

output "example" {
  value = "${aws_iam_policy.example.policy}"
}

$ terraform apply
...
aws_iam_policy.example: Creating...
  arn:         "" => "<computed>"
  name:        "" => "<computed>"
  name_prefix: "" => "escaped-iam-variable-example"
  path:        "" => "/"
  policy:      "" => "{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Sid\": \"\",\n      \"Effect\": \"Allow\",\n      \"Action\": \"s3:GetObject\",\n      \"Resource\": \"arn:aws:s3:::${aws:username}/*\"\n    }\n  ]\n}"
aws_iam_policy.example: Creation complete after 1s (ID: arn:aws:iam::--OMITTED--:policy/escape...able-example20181001201640491400000001)

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

example = {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::${aws:username}/*"
    }
  ]
}

And verified via the AWS CLI:

$ aws iam get-policy-version --policy arn:aws:iam::--OMITTED--:policy/escaped-iam-variable-example20181001201640491400000001 --version-id v1
{
    "PolicyVersion": {
        "Document": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Sid": "",
                    "Effect": "Allow",
                    "Action": "s3:GetObject",
                    "Resource": "arn:aws:s3:::${aws:username}/*"
                }
            ]
        },
        "VersionId": "v1",
        "IsDefaultVersion": true,
        "CreateDate": "2018-10-01T20:16:40Z"
    }
}

I am not sure if there were additional reasons for the original implementation of &{...} syntax though. It should definitely still be noted in the data source documentation that the data source supports that syntax until if/when its removed. If you have suggestions for the verbiage (its just copy paste of the existing documentation), please let us know.

[rifelpet]

It looks like the &{...} format originated with the datasource itself two years ago. As a TF user I think it would be good to settle on one of the two formats, though I agree mentioning the alternative format would be beneficial for users trying to understand an existing aws_iam_policy_document that may use the alternative format. I'm not sure if its worth deprecating one entirely, but it's something to consider.

[YakDriver]

This is a very useful guide!

[YakDriver]

It would be very helpful to make statement optional so that policies can be layered more flexibly. Even if statement policy docs provide the foundational level, when layering policies, you need the capability to just compose policies without needing a new statement. To get around this, you have to specify a dummy statement that will be purposely overridden, when all you really want is the source_json and override_json. See PR #6052.

[radeksimko]

Just a handful of nitpicks, mostly unimportant.

[radeksimko]

staticly -> statically

[radeksimko]

Also it may be worth linking to a document/docs page which explains what is "assume role policy".
AFAIK it often causes some confusion for IAM beginners as they mismatch that with the actual resource policy.

[bflad]

Great catches! Will update with fixed word and https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html

[radeksimko]

are possible -> are available? Admittedly I'm not a native english speaker, but "available methods" sounds a bit more natural compared to "possible methods". Feel free to ignore this though.

[bflad]

👍 that's a good catch

[radeksimko]

Can we link to any doc page which explains HEREDOC? I'm not sure if we have such page in our docs 🤔

[bflad]

Turns out the 0.12 branch has a whole section on it! https://github.com/hashicorp/terraform/blob/v0.12-dev/website/docs/configuration/expressions.html.md#string-literals

Unfortunately the current documentation has it listed as just a bullet point under syntax 😅 https://www.terraform.io/docs/configuration/syntax.html (which will be removed with 0.12 documentation updates)

Not sure if we link to the soon-to-be removed place or somewhere else. Open to opinions!

[radeksimko]

We seem to be missing a verb here ^ 👓

[radeksimko]

We seem to be missing a verb here ^ 👓

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.