terraform-aws-iam-role

A Terraform base module for creating and managing IAM Roles on Amazon Web Services (AWS).

This module supports Terraform v1.x, v0.15, v0.14, v0.13 as well as v0.12.20 and above and is compatible with the terraform AWS provider v3 as well as v2.0 and above.

• Module Features
• Getting Started
• Module Argument Reference
  • Module Configuration
  • Top-level Arguments
    • Main Resource Configuration
    • Extended Resource configuration
      • Custom & Managed Policies
      • Inline Policiy
      • Instance Profile
• Module Outputs
• External Documentation
  • AWS Documentation IAM
  • Terraform AWS Provider Documentation
• Module Versioning
  • Backwards compatibility in 0.0.z and 0.y.z version
• About Mineiros
• Reporting Issues
• Contributing
• Makefile Targets
• License

Module Features

In contrast to the plain aws_iam_role resource this module simplifies adding IAM Policies to the role.

• Standard Module Features: Create an IAM role.

• Extended Module Features: Create an inline IAM policy, Attach custom or AWS managed policies. Create an IAM instance profile.

Getting Started

Basic usage for granting an AWS Account with Account ID 123456789012 access to assume a role that grants full access to AWS Simple Storage Service (S3)

module "role-s3-full-access" {
  source  = "mineiros-io/iam-role/aws"
  version = "~> 0.6.0"

  name = "S3FullAccess"

  assume_role_principals = [
    {
      type        = "AWS"
      identifiers = ["arn:aws:iam::123456789012:root"]
    }
  ]

  policy_statements = [
    {
      sid = "FullS3Access"

      effect    = "Allow"
      actions   = ["s3:*"]
      resources = ["*"]
    }
  ]
}

Module Argument Reference

See variables.tf and examples/ for details and use-cases.

Module Configuration

• module_enabled: (Optional bool)

  Specifies whether resources in the module will be created.

  Default is true.

• module_tags: (Optional map(string))

  A map of tags that will be applied to all created resources that accept tags. Tags defined with 'module_tags' can be overwritten by resource-specific tags.

  Default is {}.

• module_depends_on: (Optional list(any))

  A list of dependencies. Any object can be assigned to this list to define a hidden external dependency.

Top-level Arguments

Main Resource Configuration

• name: (Optional string)

  The name of the role. Invalid characters will be replaced with dashes. If omitted, Terraform will assign a random, unique name. Forces new resource.

• name_prefix: (Optional string)

  If omitted, Terraform will assign a random, unique name. Invalid characters will be replaced with dashes. Creates a unique name beginning with the specified prefix. Conflicts with name. Forces new resource.

• assume_role_policy: (Required string)

  A JSON String representing the policy that grants an entity permission to assume the role. (only required if assume_role_principals is not set)

  Example:

  assume_role_policy = <<EOF
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Action": "sts:AssumeRole",
          "Principal": {
            "Service": "ec2.amazonaws.com"
          },
          "Effect": "Allow",
          "Sid": ""
        }
      ]
    }
  EOF

• assume_role_principals: (Required set(principal))

  A Set of objects representing Principals in an IAM policy document. (only required if assume_role_policy is not set)

  Example:

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

• assume_role_conditions: (Optional set(condition))

  A Set of objects representing Conditions in an IAM policy document. (only evaluated when assume_role_principals is used)

  Example:

  assume_role_conditions = [
    {
      test     = "Bool"
      variable = "aws:MultiFactorAuthPresent"
      values   = [ "true" ]
    }
  ]

• assume_role_actions: (Optional list(string))

  A list of strings representing Action in an IAM policy document. (only evaluated when assume_role_principals is used)

  Default is ["sts:AssumeRole"].

  Example:

  assume_role_actions = [
    "sts:TagSession",
    "sts:AssumeRoleWithSAML"
  ]

• force_detach_policies: (Optional bool)

  Specifies to force detaching any policies the role has before destroying it. Defaults to false.

  Default is false.

• path: (Optional string)

  The path to the role. See IAM Identifiers for more information.

  Default is "/".

• description: (Optional string)

  The description of the role.

• max_session_duration: (Optional number)

  The 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.

  Default is 3600.

• permissions_boundary: (Optional string)

  The ARN of the policy that is used to set the permissions boundary for the role.

• tags: (Optional map(string))

  Key-value map of tags for the IAM role.

  Default is {}.

Extended Resource configuration

Custom & Managed Policies

• policy_arns: (Optional list(string))

  List of IAM custom or managed policies ARNs to attach to the role.

  Default is [].

Inline Policiy

• policy_name: (Optional string)

  The name of the role policy. Invalid characters will be replaced with dashes. If omitted, Terraform will assign a random, unique name.

• policy_name_prefix: (Optional string)

  Creates a unique name beginning with the specified prefix. Invalid characters will be replaced with dashes. Conflicts with name.

• create_policy: (Optional bool)

  Force creation of inline policy, when policy_statements can not be computed. Defaults to true if policy_statements is a non-empty list and terraform can compute it.

• policy_statements: (Optional list(statement))

  List of IAM policy statements to attach to the role as an inline policy.

  Example:

  policy_statements = [
    {
      sid = "FullS3Access"
  
      effect = "Allow"
  
      actions     = [ "s3:*" ]
      not_actions = []
  
      resources     = [ "*" ]
      not_resources = []
  
      conditions = [
        { test     = "Bool"
          variable = "aws:MultiFactorAuthPresent"
          values   = [ "true" ]
        }
      ]
    }
  ]

Instance Profile

• create_instance_profile: (Optional bool)

  Whether to create an instance profile.

• instance_profile_name: (Optional string)

  Name of the instance profile. If omitted, Terraform will assign a random, unique name. Conflicts with name_prefix. Can be a string of characters consisting of upper and lowercase alphanumeric characters and these special characters: _, +, =, ,, ., @, -. Spaces are not allowed.

• instance_profile_name_prefix: (Optional string)

  Creates a unique name beginning with the specified prefix. Invalid characters will be replaced with dashes. Conflicts with name. Forces new resource.

• instance_profile_path: (Optional string)

  Path in which to create the profile.

  Default is "/".

• instance_profile_tags: (Optional map(string))

  Key-value map of tags for the IAM instance profile.

  Default is {}.

Module Outputs

The following attributes are exported by the module:

• role: (object(role))

  The aws_iam_role object.

• policy: (object(policy))

  The aws_iam_role_policy object.

• policy_attachments: (list(policy_attachment))

  An array of aws_iam_role_policy_attachment objects.

• instance_profile: (object(instance_profile))

  The aws_iam_instance_profile object.

External Documentation

AWS Documentation IAM

• Roles: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html
• Policies: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html
• Instance Profile: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html

Terraform AWS Provider Documentation

• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_instance_profile

Module Versioning

This Module follows the principles of Semantic Versioning (SemVer).

Given a version number MAJOR.MINOR.PATCH, we increment the:

1. MAJOR version when we make incompatible changes,
2. MINOR version when we add functionality in a backwards compatible manner, and
3. PATCH version when we make backwards compatible bug fixes.

Backwards compatibility in 0.0.z and 0.y.z version

• Backwards compatibility in versions 0.0.z is not guaranteed when z is increased. (Initial development)
• Backwards compatibility in versions 0.y.z is not guaranteed when y is increased. (Pre-release)

About Mineiros

Mineiros is a DevOps as a Service company based in Berlin, Germany. We offer commercial support for all of our projects and encourage you to reach out if you have any questions or need help. Feel free to send us an email at hello@mineiros.io or join our Community Slack channel.

We can also help you with:

• Terraform modules for all types of infrastructure such as VPCs, Docker clusters, databases, logging and monitoring, CI, etc.
• Consulting & training on AWS, Terraform and DevOps

Reporting Issues

We use GitHub Issues to track community reported issues and missing features.

Contributing

Contributions are always encouraged and welcome! For the process of accepting changes, we use Pull Requests. If you'd like more information, please see our Contribution Guidelines.

Makefile Targets

This repository comes with a handy Makefile. Run make help to see details on each available target.

License

This module is licensed under the Apache License Version 2.0, January 2004. Please see LICENSE for full details.

Copyright © 2020-2022 Mineiros GmbH