Skip to main content
Security Modules 0.75.9Last updated in version 0.75.8

IAM Role for GitLab Pipelines

View Source Release Notes

This Terraform module can be used to create Assume Role policies and IAM Roles such that they can be used with GitLab Pipelines. This requires you to provision an IAM OpenID Connect Provider for GitLab Pipelines in your account. By using OpenID Connect, GitLab Pipelines can directly exchange credentials to access AWS without having to store and provide GitLab with permanent AWS access credentials. This is useful to prevent credential leaks from progressing undetected.

You can use the OpenID Connect Provider for GitLab Pipelines module in the IAM role creation process like so:

module "gitlab_pipelines_openid_connect_provider" {
  # Update <VERSION> with latest version of the module
  source = "github.com/gruntwork-io/terraform-aws-security//modules/gitlab-pipelines-openid-connect-provider?ref=<VERSION>"

  # Update <ALLOWED_GROUPS> with the list of GitLab top level groups that are allowed to assume roles in the account
  allowed_groups = <ALLOWED_GROUPS>
}

or use its contents to create a resource directly in the IAM role module.

Creating the IAM Role​

module "iam_role" {
  # Update <VERSION> with latest version of the module
  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/gitlab-pipelines-iam-role?ref=<VERSION>"


  gitlab_pipelines_openid_connect_provider_arn = module.gitlab_pipelines_openid_connect_provider.arn
  gitlab_pipelines_openid_connect_provider_url = module.gitlab_pipelines_openid_connect_provider.url

  allowed_sources = {
    "gruntwork-io/terraform-aws-security" = ["main"]
  }

  iam_role_name                  = "example-iam-role"
  permitted_full_access_services = ["ec2"]
}

Security Considerations​

The above example will configure the IAM role example-iam-role such that it is available to be assumed by GitLab Actions if it is run from the main branch of the gruntwork-io/terraform-aws-security repository. The IAM role would then have the ability to call any API in the ec2 namespace.

You can further customize the IAM role using the following variables:

  • permitted_full_access_services: List of AWS services that the IAM role will have full access to (set to SERVICE_NAME:*).
  • iam_policy: IAM policy statements that should be directly attached (inline) to the IAM role.
  • iam_policy_arns: List of IAM Policy ARNs that should be attached to the IAM role.
  • iam_customer_managed_policy_names: List of customer managed IAM policies that should be attached to the IAM role.
  • iam_aws_managed_policy_names: List of AWS managed IAM policies that should be attached to the IAM role.

Extend the allowed_sources map if you want to allow additional repositories or branches. For example, if you want to allow the dev branch on terraform-aws-security, as well as the main branch from terraform-aws-service-catalog:

module "iam_role" {
  # Update <VERSION> with latest version of the module
  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/gitlab-pipelines-iam-role?ref=<VERSION>"

  gitlab_pipelines_openid_connect_provider_arn = module.gitlab_pipelines_openid_connect_provider.arn
  gitlab_pipelines_openid_connect_provider_url = module.gitlab_pipelines_openid_connect_provider.url

  allowed_sources = {
    "gruntwork-io/terraform-aws-security"        = ["main", "dev"]
    "gruntwork-io/terraform-aws-service-catalog" = ["main"]
  }

  iam_role_name                  = "example-iam-role"
  permitted_full_access_services = ["ec2"]
}

You can also use the module to only manage the assume role policy. This is useful if you want more control over the IAM role creation. For example:

module "assume_role_policy" {
  # Update <VERSION> with latest version of the module
  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/github-actions-iam-role?ref=<VERSION>"

  gitlab_pipelines_openid_connect_provider_arn = module.gitlab_pipelines_openid_connect_provider.arn
  gitlab_pipelines_openid_connect_provider_url = module.gitlab_pipelines_openid_connect_provider.url

  allowed_sources = {
    "gruntwork-io/terraform-aws-security"        = ["main", "dev"]
    "gruntwork-io/terraform-aws-service-catalog" = ["main"]
  }

  create_iam_role = false
}

resource "aws_iam_role" "example" {
  name               = "example-iam-role"
  assume_role_policy = module.assume_role_policy.assume_role_policy_json
}

Using created IAM Role in GitLab Pipelines Workflow​

TODO

  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com/${CI_PROJECT_NAMESPACE}

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S GITLAB-PIPELINES-IAM-ROLE MODULE
# ------------------------------------------------------------------------------------------------------

module "gitlab_pipelines_iam_role" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/gitlab-pipelines-iam-role?ref=v0.75.9"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Map of GitLab project path to the list of branches that are allowed to
  # assume the IAM role. The repository should be encoded as
  # group/subgroup/repo-name (e.g., gruntwork-io/terrraform-aws-ci).
  allowed_sources = <map(list(string))>

  # ARN of the OpenID Connect Provider provisioned for GitLab Pipelines.
  gitlab_pipelines_openid_connect_provider_arn = <string>

  # URL of the OpenID Connect Provider provisioned for GitLab Pipelines.
  gitlab_pipelines_openid_connect_provider_url = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The string operator to use when evaluating the AWS IAM condition for
  # determining which GitLab repos are allowed to assume the IAM role. Examples:
  # StringEquals, StringLike, etc.
  allowed_sources_condition_operator = "StringEquals"

  # Whether to create the IAM role and attach permissions for GitLab Pipelines
  # to assume.
  create_iam_role = true

  # The name to use for the custom inline IAM policy that is attached to the
  # Role/Group when var.iam_policy is configured.
  custom_iam_policy_name = "GrantCustomIAMPolicy"

  # A list of IAM AWS Managed Policy names to attach to the group.
  iam_aws_managed_policy_names = null

  # A list of IAM AWS Customer Managed policy names to attach to the group.
  iam_customer_managed_policy_names = null

  # An object defining the IAM policy statements that should be attached
  # directly to the IAM role/group. The input is a map of objects where the map
  # keys are SIDs for IAM policy statements, and the object fields are the
  # resources, actions, and the effect of the statement.
  iam_policy = {}

  # A list of policies (by ARN) to attach to this group.
  iam_policy_arns = null

  # The name of an IAM role to create. Required when var.create_iam_role is
  # true.
  iam_role_name = null

  # The maximum allowable session duration, in seconds, for the credentials you
  # get when assuming the IAM roles created by this module.
  max_session_duration = 43200

  # A list of AWS services for which the IAM role will receive full permissions.
  # See
  # https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html
  # to find the service name. For example, to grant developers access only to
  # EC2 and Amazon Machine Learning, use the value ["ec2","machinelearning"].
  permitted_full_access_services = []

}


Reference​

Required​

allowed_sourcesmap(list(…))required

Map of GitLab project path to the list of branches that are allowed to assume the IAM role. The repository should be encoded as group/subgroup/repo-name (e.g., gruntwork-io/terrraform-aws-ci).

map(list(string))

ARN of the OpenID Connect Provider provisioned for GitLab Pipelines.

URL of the OpenID Connect Provider provisioned for GitLab Pipelines.

Optional​

The string operator to use when evaluating the AWS IAM condition for determining which GitLab repos are allowed to assume the IAM role. Examples: StringEquals, StringLike, etc.

"StringEquals"
create_iam_rolebooloptional

Whether to create the IAM role and attach permissions for GitLab Pipelines to assume.

true

The name to use for the custom inline IAM policy that is attached to the Role/Group when iam_policy is configured.

"GrantCustomIAMPolicy"
iam_aws_managed_policy_nameslist(string)optional

A list of IAM AWS Managed Policy names to attach to the group.

null

A list of IAM AWS Customer Managed policy names to attach to the group.

null
iam_policymap(object(…))optional

An object defining the IAM policy statements that should be attached directly to the IAM role/group. The input is a map of objects where the map keys are SIDs for IAM policy statements, and the object fields are the resources, actions, and the effect of the statement.

map(object({
    resources = list(string)
    actions   = list(string)
    effect    = string
  }))
{}
Example
     iam_policy = {
       S3Access = {
         actions = ["s3:*"]
         resources = ["arn:aws:s3:::mybucket"]
         effect = "Allow"
       },
       EC2Access = {
         actions = ["ec2:*"]
         resources = ["*"]
         effect = "Allow"
       }
     }

iam_policy_arnslist(string)optional

A list of policies (by ARN) to attach to this group.

null
iam_role_namestringoptional

The name of an IAM role to create. Required when create_iam_role is true.

null
max_session_durationnumberoptional

The maximum allowable session duration, in seconds, for the credentials you get when assuming the IAM roles created by this module.

43200
permitted_full_access_serviceslist(string)optional

A list of AWS services for which the IAM role will receive full permissions. See https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html to find the service name. For example, to grant developers access only to EC2 and Amazon Machine Learning, use the value ['ec2','machinelearning'].

[]