IAM Roles in Terraform: Trust Policies, Inline Policies, and Common Patterns

The four Terraform resources for an IAM role

Creating a functional IAM role in Terraform requires composing four resources:

# 1. Trust policy: who can assume this role
data "aws_iam_policy_document" "assume_role" {
  statement {
    effect = "Allow"
    principals {
      type        = "Service"
      identifiers = ["lambda.amazonaws.com"]
    }
    actions = ["sts:AssumeRole"]
  }
}

# 2. The role itself
resource "aws_iam_role" "lambda_exec" {
  name               = "lambda-execution-role"
  assume_role_policy = data.aws_iam_policy_document.assume_role.json
}

# 3. Permission policy: what the role can do
data "aws_iam_policy_document" "lambda_permissions" {
  statement {
    effect = "Allow"
    actions = [
      "logs:CreateLogGroup",
      "logs:CreateLogStream",
      "logs:PutLogEvents"
    ]
    resources = ["arn:aws:logs:*:*:*"]
  }

  statement {
    effect    = "Allow"
    actions   = ["s3:GetObject"]
    resources = ["arn:aws:s3:::my-bucket/*"]
  }
}

resource "aws_iam_policy" "lambda_permissions" {
  name   = "lambda-execution-permissions"
  policy = data.aws_iam_policy_document.lambda_permissions.json
}

# 4. Attachment: link the policy to the role
resource "aws_iam_role_policy_attachment" "lambda_permissions" {
  role       = aws_iam_role.lambda_exec.name
  policy_arn = aws_iam_policy.lambda_permissions.arn
}

Common trust policy patterns

Lambda:

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

ECS tasks:

principals {
  type        = "Service"
  identifiers = ["ecs-tasks.amazonaws.com"]
}

EC2 instance profiles:

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

Cross-account assumption (allowing another account's role to assume):

principals {
  type        = "AWS"
  identifiers = ["arn:aws:iam::987654321098:root"]  # entire account
  # or specific role: "arn:aws:iam::987654321098:role/SpecificRole"
}

EKS IRSA (OIDC-based service accounts):

data "aws_iam_openid_connect_provider" "eks" {
  url = aws_eks_cluster.main.identity[0].oidc[0].issuer
}

data "aws_iam_policy_document" "irsa_trust" {
  statement {
    effect = "Allow"
    principals {
      type        = "Federated"
      identifiers = [data.aws_iam_openid_connect_provider.eks.arn]
    }
    actions = ["sts:AssumeRoleWithWebIdentity"]
    condition {
      test     = "StringEquals"
      variable = "${data.aws_iam_openid_connect_provider.eks.url}:sub"
      values   = ["system:serviceaccount:default:my-service-account"]
    }
  }
}

Inline vs managed policies: lifecycle differences

Managed policy (aws_iam_policy + aws_iam_role_policy_attachment):

• The policy exists as a standalone resource with its own ARN
• Can be attached to multiple roles
• Deletion requires detaching from all roles first (or force_detach_policies = true)
• Terraform tracks attachments separately from the policy

Inline policy (aws_iam_role_policy):

• The policy is embedded in the role, deleted when the role is deleted
• Cannot be reused across roles
• Simpler Terraform when the policy is tightly coupled to one role

# Inline policy (simpler for role-specific permissions)
resource "aws_iam_role_policy" "lambda_s3" {
  name   = "s3-read"
  role   = aws_iam_role.lambda_exec.id
  policy = data.aws_iam_policy_document.lambda_permissions.json
}

Use inline policies when the permissions are conceptually part of the role's identity. Use managed policies when the same permission set needs to apply to multiple roles (e.g., a read-only S3 policy shared across many Lambda functions).

# Attach AWS managed policies
resource "aws_iam_role_policy_attachment" "lambda_basic" {
  role       = aws_iam_role.lambda_exec.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}

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

EC2 instance profiles: the extra step

EC2 instances don't directly use IAM roles — they use instance profiles, which are a wrapper around an IAM role. Instance profiles are created automatically in the console but require explicit Terraform resources:

resource "aws_iam_role" "ec2_role" {
  name               = "ec2-instance-role"
  assume_role_policy = data.aws_iam_policy_document.ec2_assume.json
}

resource "aws_iam_instance_profile" "ec2" {
  name = "ec2-instance-profile"
  role = aws_iam_role.ec2_role.name
}

resource "aws_instance" "app" {
  ami                  = data.aws_ami.amazon_linux.id
  instance_type        = "t3.medium"
  iam_instance_profile = aws_iam_instance_profile.ec2.name
}

Forgetting aws_iam_instance_profile and passing the role ARN directly to the instance is a common error — iam_instance_profile expects the profile name, not the role ARN or name.