AWS IAM Role Terraform module

Description

This module creates an AWS IAM Role together with a policy defining the permissions that can be attached to the role using a policy attachment resource.

Why Use This Module Over Standard Resources

When managing AWS Identity and Access Management (IAM) roles within your infrastructure as code (IAC) setup, you have several options, including manually defining IAM roles and policies or using Terraform's built-in AWS provider resources. However, the boldlink/iam-role/aws Terraform module offers distinct advantages over these standard approaches, making it a compelling choice for your IAM role management needs.

• Simplified IAM Role Creation

Creating IAM roles with the boldlink/iam-role/aws module is straightforward and concise. You can define IAM roles and associated policies in a clear and structured manner using Terraform. This module abstracts many of the low-level AWS IAM API details, saving you time and effort in writing and maintaining IAM configurations.

• Version Compatibility and Consistency

The module ensures compatibility with specific Terraform and AWS provider versions, reducing the risk of compatibility issues and ensuring a smooth deployment process. This version alignment minimizes the need for manual adjustments, providing a consistent IAM role management experience.

• Policy Management Flexibility

With this module, you have the flexibility to manage IAM role policies using various methods, including inline policies and managed policy attachments. You can easily specify custom policies to meet your specific security and access control requirements.

• Documentation and Examples

The module is well-documented, providing clear guidance on how to use it effectively. Additionally, a set of examples is available in the repository, demonstrating real-world use cases and helping you get started quickly.

Examples available here

Usage

NOTE: These examples use the latest version of this module

module "minimum" {
  source             = "boldlink/iam-role/aws"
  version            = "<insert_latest_version_here>"
  assume_role_policy = local.policy
}

locals.tf file

locals {
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Action = "sts:AssumeRole"
        Effect = "Allow"
        Sid    = ""
        Principal = {
          Service = "ec2.amazonaws.com"
        }
      },
    ]
  })
}

Documentation

AWS Identity and Access Management Documentation

Terraform provider documentation

Requirements

Name	Version
terraform	>= 0.14.11
aws	>=4.15.1

Providers

Name	Version
aws	5.50.0

Modules

No modules.

Resources

Name	Type
aws_iam_policy.main	resource
aws_iam_role.main	resource
aws_iam_role_policy_attachment.main	resource

Inputs

Name	Description	Type	Default	Required
assume_role_policy	(Required) Policy that grants an entity permission to assume the role.	string	n/a	yes
description	(Optional) Description of the role.	string	null	no
force_detach_policies	(Optional) Whether to force detaching any policies the role has before destroying it. Defaults to false	bool	false	no
inline_policy	(Optional) Configuration block defining an exclusive set of IAM inline policies associated with the IAM role. Defined below. If no blocks are configured, Terraform will ignore any inline policies in this resource. Configuring one empty block (i.e., inline_policy {}) will cause Terraform to remove all inline policies.	list(map(string))	[]	no
managed_policy_arns	(Optional) Set of exclusive IAM managed policy ARNs to attach to the IAM role. If this attribute is not configured, Terraform will ignore policy attachments to this resource. When configured, Terraform will align the role's managed policy attachments with this set by attaching or detaching managed policies. Configuring an empty set (i.e., managed_policy_arns = []) will cause Terraform to remove all managed policy attachments.	list(string)	[]	no
max_session_duration	(Optional) Maximum session duration (in seconds) that you want to set for the specified role. If you do not specify a value for this setting, the default maximum of one hour is applied. This setting can have a value from 1 hour to 12 hours. Since the value is in seconds, please provide a number between 3600 (1 hr) and 43200 (12 hrs).	string	3600	no
name	(Optional, Forces new resource) Friendly name of the role. If omitted, Terraform will assign a random, unique name	string	null	no
name_prefix	(Optional, Forces new resource) Creates a unique friendly name beginning with the specified prefix. Conflicts with name	string	null	no
path	(Optional) Path to the role	string	"/"	no
permissions_boundary	(Optional) ARN of the policy that is used to set the permissions boundary for the role.	string	null	no
policies	A map of policies to be created.	map(any)	{}	no
tags	Key-value mapping of tags for the IAM role. If configured with a provider default_tags configuration block present, tags with matching keys will overwrite those defined at the provider-level.	map(string)	{}	no

Outputs

Name	Description
arn	Amazon Resource Name (ARN) specifying the role.
create_date	Creation date of the IAM role.
id	Name of the role.
name	Name of the role.
policy_arns	The ARN(s) assigned by AWS to this policy/policies.
policy_descriptions	The description(s) of the policy/ policies.
policy_ids	The policy's ID(s).
policy_names	The name(s) of the policy/policies.
policy_paths	The path(s) of the policy/policies in IAM.
policy_tags_all	A map of tags assigned to the resource(s), including those inherited from the provider default_tags
tags_all	A map of tags assigned to the resource, including those inherited from the provider default_tags
unique_id	Stable and unique string identifying the role.

Third party software

This repository uses third party software:

• pre-commit - Used to help ensure code and documentation consistency
  • Install with brew install pre-commit
  • Manually use with pre-commit run
• terraform 0.14.11 For backwards compatibility we are using version 0.14.11 for testing making this the min version tested and without issues with terraform-docs.
• terraform-docs - Used to generate the Inputs and Outputs sections
  • Install with brew install terraform-docs
  • Manually use via pre-commit
• tflint - Used to lint the Terraform code
  • Install with brew install tflint
  • Manually use via pre-commit

Makefile

The makefile contained in this repo is optimized for linux paths and the main purpose is to execute testing for now.

• Create all tests: $ make tests
• Clean all tests: $ make clean

BOLDLink-SIG 2023