iam-role

iam-role

Features

• Create IAM roles with customizable trust policies
• Attach AWS managed or customer managed policies
• Define inline policies for role-specific permissions
• Optional instance profile creation for EC2 use cases
• Permissions boundary support for delegated administration
• Comprehensive input validation with helpful error messages

When to Use

Use this module when you need to:

• Create execution roles for Lambda functions, ECS tasks, or Step Functions
• Set up EC2 instance roles with automatic instance profile creation
• Enable cross-account access with proper security controls
• Implement GitHub Actions OIDC federation for keyless CI/CD
• Delegate role creation to teams while enforcing permissions boundaries

Usage

Basic Usage

module "lambda_role" {
  source = "../../"

  name = "example-lambda-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "lambda.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })

  managed_policy_arns = [
    "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
  ]

  tags = {
    Environment = "example"
  }
}

Complete Example

See examples/complete for a full-featured example demonstrating all module capabilities.

Inputs

For detailed input documentation including examples, see the registry page.

Outputs

Principle of Least Privilege

Always grant the minimum permissions required. Prefer specific resource ARNs over wildcards, and use inline policies for role-specific permissions that shouldn’t be reused.

Permissions Boundaries

Use permissions boundaries when delegating role creation to development teams. Boundaries set the maximum permissions a role can have, regardless of what policies are attached. This prevents privilege escalation in multi-tenant environments.

External IDs for Third-Party Access

Always use external IDs when granting cross-account access to third parties. This prevents the “confused deputy” problem where a malicious actor could trick a service into accessing your resources.

Session Duration

Use the shortest session duration that meets your needs. Shorter sessions reduce the window of exposure if credentials are compromised:

• 1 hour (3600): Default, suitable for most automated tasks
• 4 hours (14400): Long CI/CD pipelines
• 8 hours (28800): Workday console sessions
• 12 hours (43200): Maximum, rarely needed

OIDC Trust Policies

When using OIDC federation (e.g., GitHub Actions), always scope trust policies to specific repositories and branches. Never allow all repositories or all branches to assume production roles.

Common Trust Policy Patterns

Condition Keys

Common condition keys for trust policies:

Related Modules

• kms-key - Create KMS keys for encryption
• secrets-manager - Manage secrets with IAM access
• security-group - Network security for EC2/ECS

This README was generated from structured documentation. See spec.yaml for the complete module specification.