Terraform: AWS IAM role policy attachment documentation is unclear

[ajcrites]

Link: https://www.terraform.io/docs/providers/aws/r/iam_policy_attachment.html

The documentation includes an example of creating a role and attaching a policy to the role, but roles require an "assume_role_policy." -- https://www.terraform.io/docs/providers/aws/r/iam_role.html

This is not only missing from the policy attachment documentation, but it is also unclear how the assume role policy is created. Even though this is a policy, you cannot create it using aws_iam_policy:

resource "aws_iam_policy" "test" {
  name = "test"
  policy = <<EOF
{
  "Version" : "2012-10-17",
  "Statement": [{
    "Action": "sts:AssumeRole",
    "Principal": {"Service": "lambda.amazonaws.com"},
    "Effect": "Allow"
  }]
}
EOF
}

The above will not work and Terraform will complain about Principal in the policy document. However, you can copy the above to assume_role_policy for aws_iam_role and it will work.

There are a couple of issues here:

1. The iam policy attachment documentation is missing the critical assume_role_policy piece
2. Generating the assume_role_policy is unclear. The docs just say it is "the policy that grants an entity permission to assume the role" without specifying what the policy can be (JSON, string, file, name, etc.) Seemingly it has to be written inline.
3. This may be intentional or a limitation of AWS, but since you cannot use Principal in aws_iam_policy there is no way for roles to reuse an assume_role_policy and you would have to rewrite it every time.

[anapsix]

see example https://www.terraform.io/docs/providers/aws/r/iam_instance_profile.html

resource "aws_iam_instance_profile" "test_profile" {
    name = "test_profile"
    roles = ["${aws_iam_role.role.name}"]
}

resource "aws_iam_role" "role" {
    name = "test_role"
    path = "/"
    assume_role_policy = <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": "sts:AssumeRole",
            "Principal": {"AWS": "*"},
            "Effect": "Allow",
            "Sid": ""
        }
    ]
}
EOF
}

[cu12]

You also could do

data "aws_iam_policy_document" "instance-assume-role-policy" {
  statement {
    actions = [ "sts:AssumeRole" ]

    principals {
      type = "Service"
      identifiers = ["ec2.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "instance" {
  name = "instance_role"
  path = "/system/"
  assume_role_policy = "${data.aws_iam_policy_document.instance-assume-role-policy.json}"
}

[matschaffer]

Would love to see @cu12's example in the docs. The mapping from HCL principals to the JSON object wasn't clear to me either.

[arsdehnel]

@matschaffer @cu12 I took a shot at adding that data source option to the aws_iam_role page in the documentation. Let me know if that's at least sort of what you were thinking or if there could/should be more details on that page or others? I found @cu12 's note particularly helpful so wanted to get it into the docs rather than relying on more people finding this issue.

[arsdehnel]

Also mentioned it on another PR that adds it to the data source page as well: https://github.com/hashicorp/terraform/pull/11495

[hashibot[bot]]

I'm going to lock this issue 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 similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.