IAM roles

Understand the three IAM roles the module creates and how to customize or replace them with externally managed roles.

The module creates three IAM roles by default:

1. Service role — used by the EMR service to manage cluster resources.
2. Autoscaling role — used by Application Auto Scaling and EMR to scale instance groups.
3. EC2 instance profile role — assumed by EC2 instances in the cluster to access AWS services.

All three roles share common naming and path options controlled by the common IAM settings.

The service role is tagged with { "for-use-with-amazon-emr-managed-policies" = true } and is attached the AmazonEMRServicePolicy_v2 managed policy by default. This policy requires you to tag your VPC and subnets with the same key before EMR can create and manage cluster resources. See the AWS documentation for details.

Service IAM role

create_service_iam_role · bool · default: "true"

Set to false to skip creating the service role and supply an existing role via service_iam_role_arn.

service_iam_role_arn · string

ARN of an existing service role to use when create_service_iam_role = false.

service_iam_role_name · string

Name for the service IAM role. Defaults to "<cluster-name>-service". When iam_role_use_name_prefix = true this value is used as a name prefix.

service_iam_role_description · string

Description attached to the service IAM role.

service_iam_role_policies · map(string)

Map of IAM policy ARNs to attach to the service role. Defaults to AmazonEMRServicePolicy_v2. The key is used as a logical identifier; the value is the policy ARN. You can add additional policies or replace the default.

service_iam_role_policies = {
  AmazonEMRServicePolicy_v2 = "arn:aws:iam::aws:policy/service-role/AmazonEMRServicePolicy_v2"
  CustomPolicy              = "arn:aws:iam::123456789012:policy/my-custom-policy"
}

Service pass-role policy

The module also creates an inline iam:PassRole policy and attaches it to the service role. This allows the EMR service to pass the autoscaling and instance profile roles to Application Auto Scaling and EC2.

service_pass_role_policy_name · string

Name for the pass-role policy. Defaults to "<cluster-name>-passrole".

service_pass_role_policy_description · string

Description attached to the pass-role policy.

Autoscaling IAM role

The autoscaling role is only created when using instance groups. It is automatically skipped when you configure instance fleets (master_instance_fleet or core_instance_fleet).

create_autoscaling_iam_role · bool · default: "true"

Set to false to skip creating the autoscaling role and supply an existing role via autoscaling_iam_role_arn.

autoscaling_iam_role_arn · string

ARN of an existing autoscaling role to use when create_autoscaling_iam_role = false.

autoscaling_iam_role_name · string

Name for the autoscaling IAM role. Defaults to "<cluster-name>-autoscaling".

autoscaling_iam_role_description · string

Description attached to the autoscaling IAM role.

The module attaches the AmazonElasticMapReduceforAutoScalingRole AWS managed policy to this role.

EC2 instance profile

create_iam_instance_profile · bool · default: "true"

Set to false to skip creating the EC2 IAM role and instance profile. You must then supply an existing profile name via iam_instance_profile_name.

iam_instance_profile_name · string

Name for the EC2 IAM role and instance profile. Defaults to "<cluster-name>-instance". Also used to reference an existing profile when create_iam_instance_profile = false.

iam_instance_profile_description · string

Description for the EC2 IAM role.

iam_instance_profile_policies · map(string)

Map of IAM policy ARNs to attach to the instance profile role. Defaults to AmazonElasticMapReduceforEC2Role.

iam_instance_profile_policies = {
  AmazonElasticMapReduceforEC2Role = "arn:aws:iam::aws:policy/service-role/AmazonElasticMapReduceforEC2Role"
  S3ReadAccess                     = "arn:aws:iam::123456789012:policy/my-s3-read-policy"
}

iam_instance_profile_role_arn · string

ARN of an existing IAM role to use when you supply a custom instance profile but still want the module to create a service role (for the pass-role policy).

Common IAM settings

The following variables apply to all three roles.

iam_role_use_name_prefix · bool · default: "true"

When true, the role name is used as a prefix and AWS appends a unique suffix. This avoids name collisions when deploying multiple clusters.

iam_role_path · string

IAM path for all roles created by the module, for example "/emr/".

iam_role_permissions_boundary · string

ARN of an IAM policy to use as the permissions boundary for all roles.

iam_role_tags · map(string) · default: "{}"

Additional tags to merge onto all IAM roles.

Using external roles

To bring your own roles, disable role creation and supply the existing identifiers:

module "emr" {
  source = "terraform-aws-modules/emr/aws"

  # Disable role creation
  create_service_iam_role     = false
  create_autoscaling_iam_role = false
  create_iam_instance_profile = false

  # Supply existing identifiers
  service_iam_role_arn        = "arn:aws:iam::123456789012:role/my-emr-service-role"
  autoscaling_iam_role_arn    = "arn:aws:iam::123456789012:role/my-emr-autoscaling-role"
  iam_instance_profile_name   = "my-emr-instance-profile"
}