Skip to main content
Sponsor @cloudposse

Module: ssm-iam-role

Terraform module to provision an IAM role with configurable permissions to access SSM Parameter Store.

Introduction​

For more information on how to control access to Systems Manager parameters by using AWS Identity and Access Management, see Controlling Access to Systems Manager Parameters.

For more information on how to use parameter hierarchies to help organize and manage parameters, see Organizing Parameters into Hierarchies.

NOTE: This module can be used to provision IAM roles with SSM permissions for chamber.

Usage​

This example creates a role with the name cp-prod-app-all with permission to read all SSM parameters, and gives permission to the entities specified in assume_role_arns to assume the role.

module "ssm_iam_role" {
  source           = "git::https://github.com/cloudposse/terraform-aws-ssm-iam-role.git?ref=master"
  namespace        = "cp"
  stage            = "prod"
  name             = "app"
  attributes       = ["all"]
  region           = "us-west-2"
  account_id       = "XXXXXXXXXXX"
  assume_role_arns = ["arn:aws:xxxxxxxxxx", "arn:aws:yyyyyyyyyyyy"]
  kms_key_arn      = "arn:aws:kms:us-west-2:123454095951:key/aced568e-3375-4ece-85e5-b35abc46c243"
  ssm_parameters   = ["*"]
  ssm_actions      = ["ssm:GetParametersByPath", "ssm:GetParameters"]
}

Examples​

Example With Permission For Specific Resources​

This example creates a role with the name cp-prod-app-secrets with permission to read the SSM parameters that begin with secret-, and gives permission to the entities specified in assume_role_arns to assume the role.

module "ssm_iam_role" {
  source           = "git::https://github.com/cloudposse/terraform-aws-ssm-iam-role.git?ref=master"
  namespace        = "cp"
  stage            = "prod"
  name             = "app"
  attributes       = ["secrets"]
  region           = "us-west-2"
  account_id       = "XXXXXXXXXXX"
  assume_role_arns = ["arn:aws:xxxxxxxxxx", "arn:aws:yyyyyyyyyyyy"]
  kms_key_arn      = "arn:aws:kms:us-west-2:123454095951:key/aced568e-3375-4ece-85e5-b35abc46c243"
  ssm_parameters   = ["secret-*"]
  ssm_actions      = ["ssm:GetParameters"]
}

Complete Example​

This example:

  • Provisions a KMS key to encrypt SSM Parameter Store secrets using terraform-aws-kms-key module
  • Performs Kops cluster lookup to find the ARNs of masters and nodes by using terraform-aws-kops-metadata module
  • Creates a role with the name cp-prod-chamber-kops with permission to read all SSM parameters from the path kops, and gives permission to the Kops masters and nodes to assume the role
module "kms_key" {
  source      = "git::https://github.com/cloudposse/terraform-aws-kms-key.git?ref=master"
  namespace   = "cp"
  stage       = "prod"
  name        = "chamber"
  description = "KMS key for SSM"
}

module "kops_metadata" {
  source       = "git::https://github.com/cloudposse/terraform-aws-kops-metadata.git?ref=master"
  dns_zone     = "us-west-2.prod.cloudposse.co"
  masters_name = "masters"
  nodes_name   = "nodes"
}

module "ssm_iam_role" {
  source           = "git::https://github.com/cloudposse/terraform-aws-ssm-iam-role.git?ref=master"
  namespace        = "cp"
  stage            = "prod"
  name             = "chamber"
  attributes       = ["kops"]
  region           = "us-west-2"
  account_id       = "XXXXXXXXXXX"
  assume_role_arns = ["${module.kops_metadata.masters_role_arn}", "${module.kops_metadata.nodes_role_arn}"]
  kms_key_arn      = "${module.kms_key.key_arn}"
  ssm_parameters   = ["kops/*"]
  ssm_actions      = ["ssm:GetParametersByPath", "ssm:GetParameters"]
}

Variables​

Required Variables​

account_id (string) required

AWS account ID

assume_role_arns (list(string)) required

List of ARNs to allow assuming the role. Could be AWS services or accounts, Kops nodes, IAM users or groups

kms_key_reference (any) required

The Key ID, Key ARN, Key Alias Name, or Key Alias ARN of the KMS key which will encrypt/decrypt SSM secret strings

region (string) required

AWS Region

ssm_parameters (list(string)) required

List of SSM parameters to apply the actions. A parameter can include a path and a name pattern that you define by using forward slashes, e.g. kops/secret-*

Optional Variables​

max_session_duration (number) optional

The maximum session duration (in seconds) for the role. Can have a value from 1 hour to 12 hours


Default value: 3600

ssm_actions (list(string)) optional

SSM actions to allow


Default value:

[
  "ssm:GetParametersByPath",
  "ssm:GetParameters"
]

Context Variables​

The following variables are defined in the context.tf file of this module and part of the terraform-null-label pattern.

name (string) required

Name (e.g. app or chamber)
Required: Yes

Default value: ``

namespace (string) required

Namespace (e.g. cp or cloudposse)
Required: Yes

Default value: ``

stage (string) required

Stage (e.g. prod, dev, staging)
Required: Yes

Default value: ``

attributes (list(string)) optional

Additional attributes (e.g. 1)
Required: No

Default value: [ ]

delimiter (string) optional

Delimiter to be used between namespace, stage, name and attributes
Required: No

Default value: "-"

tags (map(string)) optional

Additional tags (e.g. map(BusinessUnit,XYZ)
Required: No

Default value: { }

Outputs​

role_arn

The Amazon Resource Name (ARN) specifying the role

role_id

The stable and unique string identifying the role

role_name

The name of the crated role

role_policy_document

A copy of the IAM policy document (JSON) that grants permissions to this role.

Dependencies​

Providers​

  • aws

Modules​

NameVersionSourceDescription
label0.1.3git::https://github.com/cloudposse/terraform-terraform-label.gitn/a

Resources​

The following resources are used by this module:

Data Sources​

The following data sources are used by this module: