Terraform guide to IAM Policies: The Two Cases You Need to Know

When to attach a ready made policy and when to write your own

When you first start writing IAM setup in Terraform, the examples online can feel like they contradict each other. One tutorial writes a long block called aws_iam_policy_document. Another just pastes a single line with a long string inside it. Both of them work, so which one is correct?

The answer is that both are correct. They simply solve two different problems. Once you can tell which situation you are in, IAM in Terraform stops feeling random and starts feeling obvious.

Before we get into the two cases, here are the words you will keep seeing:

IAM stands for Identity and Access Management. It is the AWS service that decides who is allowed to do what. An IAM role is an identity that an AWS service (like a Lambda function) takes on so it can act with certain permissions. An IAM policy is the document that lists which actions are allowed or denied. An ARN, short for Amazon Resource Name, is the unique address of a resource in AWS.

With that out of the way, let us look at the two cases.

Case 1: AWS Managed Policy (attach directly)

A managed policy is a policy that AWS already wrote and maintains for you. If AWS already provides the exact permissions you need, you do not create your own aws_iam_policy_document. You just point your role at the policy AWS already made.

For example, giving a Lambda function permission to write logs is a very common need, and AWS has a ready made policy for it:

resource "aws_iam_role_policy_attachment" "logs" {
  role       = aws_iam_role.this.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}

Another common one is letting a Lambda function run inside a VPC (a Virtual Private Cloud, which is your own private network in AWS):

resource "aws_iam_role_policy_attachment" "vpc" {
  role       = aws_iam_role.this.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
}

Notice what is happening here. You are not writing any permissions yourself. You are taking an existing AWS managed policy, referring to it by its ARN, and attaching it to your role. That is the whole job.

Case 2: Your own custom permissions

Sometimes AWS does not have a managed policy that matches exactly what you need. Maybe you want a Lambda function to read and write files in one specific S3 bucket and nothing else. In that case you build the policy yourself, and it takes three small steps.

Step 1: Create the policy document

First you describe the permissions. This aws_iam_policy_document is a data source, which means it does not create anything in AWS on its own. It is a way to write your permission rules in clean Terraform instead of raw JSON.

data "aws_iam_policy_document" "s3_access" {
  statement {
    effect = "Allow"

    actions = [
      "s3:GetObject",
      "s3:PutObject"
    ]

    resources = [
      aws_s3_bucket.uploads.arn,
      "${aws_s3_bucket.uploads.arn}/*"
    ]
  }
}

Reading this in plain English: allow the actions of getting an object and putting an object, and only on the uploads bucket and everything inside it.

Step 2: Create the IAM policy

Now you turn that document into a real IAM policy that exists in AWS. The policy field pulls in the JSON produced by the document from Step 1.

resource "aws_iam_policy" "s3_access" {
  name   = "${var.project}-${var.environment}-s3-access"
  policy = data.aws_iam_policy_document.s3_access.json
}

Step 3: Attach it

Finally you attach the policy you just created to your role. This looks almost the same as Case 1, but the ARN now comes from your own policy instead of an AWS managed one.

resource "aws_iam_role_policy_attachment" "s3_access" {
  role       = aws_iam_role.this.name
  policy_arn = aws_iam_policy.s3_access.arn
}

The mental model

The easiest way to remember the difference is this. In Case 1 the policy already exists, so you skip straight to attaching. In Case 2 you have to build the policy first, then attach it.

The custom flow always moves in the same direction:

Policy Document
      │
      ▼
IAM Policy
      │
      ▼
Attach to Role

You write the document, the document becomes a policy, and the policy gets attached to the role. If you ever feel lost, just ask yourself one question: does AWS already have a policy for this? If yes, attach it directly. If no, build your own with the three steps above.

Conclusion

IAM in Terraform is not as confusing as it first looks. There are really only two situations. When AWS already provides the exact permissions, you attach a managed policy by its ARN in a single resource. When you need something specific that AWS does not offer, you create a policy document, turn it into an IAM policy, and attach that.

Keep that fork in mind and you will always know which approach the moment fits, instead of copying an example and hoping it is the right one.

Let us connect

If you have questions or want to share how you handle IAM in your own projects, reach out at [e-mail]. I am always happy to talk Terraform and AWS.

---