Inputs

Human-readable description of the role's purpose. A good description helps with: - Auditing and compliance reviews - Understanding role purpose months later - Identifying roles for cleanup **Example descriptions:** - "Allows Lambda functions to process S3 events and write to DynamoDB" - "ECS task execution role for production API containers" - "Cross-account access for CI/CD pipeline deployment"

Path for the IAM role. Use paths to organize roles hierarchically. **Path patterns:** - `/service-roles/` - AWS service-linked roles - `/application/{app-name}/` - Application-specific roles - `/environment/{env}/` - Environment-based organization - `/team/{team-name}/` - Team ownership **Benefits of using paths:** - Organize roles by application, team, or environment - Apply IAM policies that scope to path prefixes - Easier auditing and role discovery **Example:** `/production/api/` would allow policies like: ```json { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::*:role/production/api/*" } ```

Set of managed policy ARNs to attach to the role. **AWS managed policies** (recommended for common use cases): - `arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole` - `arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy` - `arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess` - `arn:aws:iam::aws:policy/CloudWatchLogsFullAccess` **Customer managed policies** (for custom permissions): - `arn:aws:iam::123456789012:policy/MyCustomPolicy` **Best practices:** - Prefer managed policies over inline for reusability - Use AWS managed policies when they fit your needs - Create customer managed policies for organization-specific permissions - Maximum 10 managed policies per role (AWS limit)

ARN of the policy to use as a permissions boundary. **What is a permissions boundary?** A permissions boundary sets the maximum permissions a role can have, regardless of what policies are attached. The effective permissions are the intersection of the identity-based policies and the boundary. **Use cases:** - Delegate role creation to developers while limiting maximum permissions - Enforce organization-wide security controls - Prevent privilege escalation in multi-tenant environments **Example boundary policy:** A boundary that prevents IAM modifications: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "*", "Resource": "*" }, { "Effect": "Deny", "Action": [ "iam:CreateRole", "iam:DeleteRole", "iam:AttachRolePolicy", "iam:PutRolePolicy" ], "Resource": "*" } ] } ``` **Best practices:** - Apply boundaries to all roles created by delegated administrators - Include the boundary in the boundary policy itself to prevent removal - Test thoroughly - boundaries can cause unexpected permission denials

Maximum session duration in seconds for role assumption. **Range:** 3600 (1 hour) to 43200 (12 hours) **Default:** 3600 (1 hour) **When to increase:** - Long-running CI/CD pipelines - Cross-account access requiring extended sessions - Interactive console sessions for debugging **Security consideration:** Use the shortest duration that meets your needs. Shorter sessions reduce the window of exposure if credentials are compromised. **Common durations:** - 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

Whether to force detach policies before destroying the role. **Default:** false When set to `true`, Terraform will automatically detach all managed and inline policies before attempting to delete the role. **When to enable:** - Development environments where roles are frequently recreated - Automated cleanup processes - When policies might be attached outside of Terraform **Caution:** In production, keeping this `false` ensures you're aware of all policies attached to a role before deletion.

Whether to create an EC2 instance profile for this role. **What is an instance profile?** An instance profile is a container for an IAM role that allows EC2 instances to assume the role. EC2 instances cannot directly use IAM roles - they must use instance profiles. **When to enable:** - The role will be used by EC2 instances - The role will be used by ECS container instances (not Fargate) - You need to pass credentials to applications running on EC2 **When NOT needed:** - Lambda functions (use role ARN directly) - ECS Fargate tasks (use task role ARN) - Cross-account access (use role ARN with AssumeRole)

Name of the instance profile. Defaults to the role name if not specified. Only used when `create_instance_profile = true`. **When to customize:** - You need a different name for the instance profile than the role - Migrating from an existing instance profile with a specific name - Organization naming conventions differ for profiles vs roles

Map of tags to apply to all resources created by this module. **Required tags (recommended):** - `Environment`: prod, staging, dev - `Owner`: Team or individual responsible **Optional tags:** - `CostCenter`: For cost allocation - `Service`: Application or service name - `Compliance`: Regulatory requirements (PCI, HIPAA, etc.) **Example:** ```hcl tags = { Environment = "production" Owner = "platform-team" Service = "payment-api" CostCenter = "engineering" } ``` **Note:** The module automatically adds: - `ManagedBy = "terraform"` - `Module = "patterneddesigns/iam-role/aws"`