README.md

terraform-aws-mcaf-avm

Terraform module providing an AWS Account Vending Machine (AVM). This module provisions an AWS account using the "AWS Control Tower Account Factory" product in Service Catalog with one or more Terraform Cloud/Enterprise (TFE) workspaces backed by a VCS project.

Workspace authentication

This module provides three modes of workspace authentication:

• (default) An IAM role using OpenID Connect integration with the AWS account. This works for remote runners or with using self-hosted Terraform Cloud agents (agent version v1.7.0+).
• An IAM role using an external ID to authenticate with the AWS account in combination with using self-hosted Terraform Cloud agents.
• An IAM user per workspace in the provisioned AWS account.

Using one of the first 2 authentication methods is in line with authentication best practices to use IAM roles over IAM users with long-lived tokens.

IAM Roles with OIDC (default)

The IAM roles with OIDC feature creates an IAM role with a trust policy allowing the OIDC provider created as part of this module. The workspace will be configured to use OIDC by feeding the AWS provider with the right environment variables.

Warning

When using using self-hosted Terraform Cloud agents, ensure that your agents use v1.12.0+ when using multiple configurations (e.g. provider aliases).

IAM Roles

To use IAM roles for authentication:

• Set var.tfe_workspace.agent_pool_id or (agent_pool_id if specifying additional workspaces) to the Terraform Cloud agent pool ID.
• Set var.tfe_workspace.auth_method or (auth_method if specifying additional workspaces) to iam_role.
• Set var.tfe_workspace.agent_role_arns or (agent_role_arns if specifying additional workspaces) to the IAM role assumed by the Terraform Cloud agents in the specified agent pool.

This will create an IAM role in the provisioned AWS account with a randomly generated external ID which can only be assumed by the Terraform Cloud agent role. The created role and external ID value are stored in the new workspace as Terraform variables which can be used to configure your AWS provider. Using the default workspace the created role will be called TPEPipelineRole, role names for additional workspaces will be calculated for you based on the workspace name but you can always set your own via the role_name variable (similarly you can set your own role name in the default workspace via var.tfe_workspace.role_name); but please be aware that each IAM role must have a unique name.

To use the created IAM role, use the following when configuring your AWS provider:

provider "aws" {
  assume_role {
    role_arn     = var.aws_assume_role
    external_id  = var.aws_assume_role_external_id
    session_name = "tfe-agent"
  }
}

IAM Users

• Set var.tfe_workspace.auth_method or (auth_method if specifying additional workspaces) to iam_user.

This will create an IAM user in the provisioned AWS account with the access key and secret access key added as environmental variables to the workspace.

Workspace team access

Team access can be configured per workspace using the team_access variable.

As the state is considered sensitive, we recommend the following custom role permissions which is similar to the pre-existing "write" permission but blocks read access to the state (viewing outputs is still allowed):

team_access = {
  "MyTeamName" = {
    permissions = {
      run_tasks         = false
      runs              = "apply"
      sentinel_mocks    = "read"
      state_versions    = "read-outputs"
      variables         = "write"
      workspace_locking = true
    }
  }
}

More complete usage information can be found in the underlying terraform-aws-mcaf-workspace module README.

Warning

The team should already exist, this module will not create it for you.

AWS SSO Configuration

In the account variable, the SSO attributes (sso_email, sso_firstname and sso_lastname) will be used by AWS Service Catalog to provide initial access to the newly created account.

You should use the details from the AWS Control Tower Admin user.

How to use

Basic configuration

module "aws_account" {
  source = "github.com/schubergphilis/terraform-aws-mcaf-avm?ref=VERSION"

  name = "my-aws-account"
  tags = { Terraform = true }

  account = {
    email               = "[email protected]"
    environment         = "prod"
    organizational_unit = "Production"
    sso_email           = "[email protected]"
  }

  tfe_workspace = {
    default_region        = "eu-west-1"
    repository_identifier = "myorg/myworkspacerepo"
    organization          = "myorg"
    vcs_oauth_token_id    = var.oauth_token_id
  }
}

Additional workspaces

module "aws_account" {
  source = "github.com/schubergphilis/terraform-aws-mcaf-avm?ref=VERSION"

  name = "my-aws-account"
  tags = { Terraform = true }

  account = {
    email               = "[email protected]"
    environment         = "prod"
    organizational_unit = "Production"
    sso_email           = "[email protected]"
  }

  tfe_workspace = {
    default_region        = "eu-west-1"
    repository_identifier = "schubergphilis/terraform-aws-mcaf-avm"
    organization          = "schubergphilis"
    vcs_oauth_token_id    = var.oauth_token_id
  }

  additional_tfe_workspaces = {
    baseline-my-aws-account = {
      auto_apply            = true
      repository_identifier = "schubergphilis/terraform-aws-mcaf-account-baseline"
    }
  }
}

Only deploy additional workspaces

module "aws_account" {
  source = "github.com/schubergphilis/terraform-aws-mcaf-avm?ref=VERSION"

  create_default_workspace = false
  name                     = "my-aws-account"
  tags                     = { Terraform = true }

  account = {
    email               = "[email protected]"
    environment         = "prod"
    organizational_unit = "Production"
    sso_email           = "[email protected]"
  }

  tfe_workspace = {
    default_region        = "eu-west-1"
    repository_identifier = "schubergphilis/terraform-aws-mcaf-avm"
    organization          = "schubergphilis"
    vcs_oauth_token_id    = var.oauth_token_id
  }

  additional_tfe_workspaces = {
    my-aws-account-subsystem1 = {
      working_directory = "terraform/subsystem1"
    }
    my-aws-account-subsystem2 = {
      working_directory = "terraform/subsystem2"
    }
  }
}

IAM Permissions Boundaries

The module supports setting a Permission Boundary on the workspace iam_user or iam_role by passing down permissions_boundaries.workspace_boundary, which needs to be referencing the path where the permissions boundary is stored in git and the name: permissions_boundaries.workspace_boundary_name. By setting var.tfe_workspace.add_permissions_boundary or var.additional_tfe_workspaces.add_permissions_boundary to true, the permissions boundary will be attached to that specific workspace user/role.

In case you want to reference a permission boundary that needs to be attached to every IAM role/user that will be created by the workspace role/user then you can create this permission boundary by specifying permissions_boundaries.workload_boundary which needs to be referencing the path where the permissions boundary is stored in git and the name: permissions_boundaries.workload_boundary_name.

module "aws_account" {
  source = "github.com/schubergphilis/terraform-aws-mcaf-avm?ref=VERSION"
  ...
  permissions_boundaries = {
    workspace_boundary      = "${path.module}/workspace_boundary.json"
    workspace_boundary_name = "workspace_boundary"
    workload_boundary       = "${path.module}/workload_boundary.json"
    workload_boundary_name  = "workload_boundary"
  }
  ...
}

Tip

The workspace_boundary and workload_boundary can be templated files, account_id will be replaced by AVM by the account ID of the AWS account created.

Requirements

Name	Version
terraform	>= 1.3.0
aws	>= 4.9.0
mcaf	>= 0.4.2
tfe	>= 0.51.0
tls	>= 4.0.4

Providers

Name	Version
aws.account	>= 4.9.0
tfe	>= 0.51.0
tls	>= 4.0.4

Modules

Name	Source	Version
account	schubergphilis/mcaf-account/aws	~> 0.5.1
additional_tfe_workspaces	schubergphilis/mcaf-workspace/aws	~> 2.1.1
tfe_workspace	schubergphilis/mcaf-workspace/aws	~> 2.1.1

Resources

Name	Type
aws_account_alternate_contact.billing	resource
aws_account_alternate_contact.operations	resource
aws_account_alternate_contact.security	resource
aws_iam_account_alias.alias	resource
aws_iam_openid_connect_provider.tfc_provider	resource
aws_iam_policy.workload_boundary	resource
aws_iam_policy.workspace_boundary	resource
tfe_variable.account_variable_set_clear_text_env_variables	resource
tfe_variable.account_variable_set_clear_text_hcl_variables	resource
tfe_variable.account_variable_set_clear_text_terraform_variables	resource
tfe_variable_set.account	resource
tls_certificate.oidc_certificate	data source

Inputs

Name	Description	Type	Default	Required
account	AWS account settings	object({ alias_prefix = optional(string) contact_billing = optional(object({ email_address = string name = string phone_number = string title = string }), null) contact_operations = optional(object({ email_address = string name = string phone_number = string title = string }), null) contact_security = optional(object({ email_address = string name = string phone_number = string title = string }), null) email = string environment = optional(string) organizational_unit = string provisioned_product_name = optional(string) sso_email = string sso_firstname = optional(string, "AWS Control Tower") sso_lastname = optional(string, "Admin") })	n/a	yes
name	Name of the account and default TFE workspace	string	n/a	yes
tfe_workspace	TFE workspace settings	object({ add_permissions_boundary = optional(bool, false) agent_pool_id = optional(string) agent_role_arns = optional(list(string)) allow_destroy_plan = optional(bool, true) assessments_enabled = optional(bool, true) auth_method = optional(string, "iam_role_oidc") auto_apply = optional(bool, false) auto_apply_run_trigger = optional(bool, false) branch = optional(string, "main") clear_text_env_variables = optional(map(string), {}) clear_text_hcl_variables = optional(map(string), {}) clear_text_terraform_variables = optional(map(string), {}) connect_vcs_repo = optional(bool, true) default_region = string description = optional(string) execution_mode = optional(string, "remote") file_triggers_enabled = optional(bool, true) global_remote_state = optional(bool, false) name = optional(string) organization = string policy = optional(string) policy_arns = optional(list(string), ["arn:aws:iam::aws:policy/AdministratorAccess"]) project_id = optional(string) queue_all_runs = optional(bool) remote_state_consumer_ids = optional(set(string)) repository_identifier = optional(string) role_name = optional(string, "TFEPipeline") sensitive_env_variables = optional(map(string), {}) sensitive_hcl_variables = optional(map(object({ sensitive = string })), {}) sensitive_terraform_variables = optional(map(string), {}) ssh_key_id = optional(string) terraform_version = optional(string) trigger_patterns = optional(list(string)) trigger_prefixes = optional(list(string), ["modules"]) username = optional(string, "TFEPipeline") vcs_oauth_token_id = string variable_set_ids = optional(map(string), {}) working_directory = optional(string) workspace_tags = optional(list(string)) notification_configuration = optional(map(object({ destination_type = string enabled = optional(bool, true) url = string triggers = optional(list(string), [ "run:created", "run:planning", "run:needs_attention", "run:applying", "run:completed", "run:errored", ]) })), {}) team_access = optional(map(object({ access = optional(string, null), permissions = optional(object({ run_tasks = bool runs = string sentinel_mocks = string state_versions = string variables = string workspace_locking = bool }), null) })), {}) })	n/a	yes
account_variable_set	Settings of variable set that is attached to each workspace	object({ name = optional(string) clear_text_env_variables = optional(map(string), {}) clear_text_hcl_variables = optional(map(string), {}) clear_text_terraform_variables = optional(map(string), {}) })	{}	no
additional_tfe_workspaces	Additional TFE workspaces	map(object({ add_permissions_boundary = optional(bool, false) agent_pool_id = optional(string) agent_role_arns = optional(list(string)) allow_destroy_plan = optional(bool) assessments_enabled = optional(bool) auth_method = optional(string) auto_apply = optional(bool, false) auto_apply_run_trigger = optional(bool, false) branch = optional(string) clear_text_env_variables = optional(map(string), {}) clear_text_hcl_variables = optional(map(string), {}) clear_text_terraform_variables = optional(map(string), {}) connect_vcs_repo = optional(bool, true) default_region = optional(string) description = optional(string) execution_mode = optional(string) file_triggers_enabled = optional(bool, true) global_remote_state = optional(bool, false) name = optional(string) policy = optional(string) policy_arns = optional(list(string), ["arn:aws:iam::aws:policy/AdministratorAccess"]) project_id = optional(string) queue_all_runs = optional(bool) remote_state_consumer_ids = optional(set(string)) repository_identifier = optional(string) role_name = optional(string) sensitive_env_variables = optional(map(string), {}) sensitive_hcl_variables = optional(map(object({ sensitive = string })), {}) sensitive_terraform_variables = optional(map(string), {}) ssh_key_id = optional(string) terraform_version = optional(string) trigger_patterns = optional(list(string)) trigger_prefixes = optional(list(string)) username = optional(string) vcs_oauth_token_id = optional(string) variable_set_ids = optional(map(string), {}) working_directory = optional(string) workspace_tags = optional(list(string)) notification_configuration = optional(map(object({ destination_type = string enabled = optional(bool, true) url = string triggers = optional(list(string), [ "run:created", "run:planning", "run:needs_attention", "run:applying", "run:completed", "run:errored", ]) })), null) team_access = optional(map(object({ access = optional(string, null), permissions = optional(object({ run_tasks = bool runs = string sentinel_mocks = string state_versions = string variables = string workspace_locking = bool }), null) })), null) }))	{}	no
create_default_workspace	Set to false to skip creating default workspace	bool	true	no
path	Optional path for all IAM users, user groups, roles, and customer managed policies created by this module	string	"/"	no
permissions_boundaries	n/a	object({ workspace_boundary = optional(string) workspace_boundary_name = optional(string) workload_boundary = optional(string) workload_boundary_name = optional(string) })	{}	no
tags	A map of tags to assign to all resources	map(string)	{}	no

Outputs

Name	Description
account_variable_set_id	The ID of the account variable set
additional_tfe_workspaces	Map of any additional Terraform Cloud workspace names and IDs
environment	The environment name
id	The AWS account ID
name	The AWS account name
repository_identifier	The repository identifier if one is specified
tfe_workspace_id	Workspace ID of default workspace ID when create_default_workspace is true
tfe_workspaces	List of Terraform Cloud workspaces
workload_permissions_boundary_arn	The ARN of the workload permissions boundary
workspace_permissions_boundary_arn	The ARN of the workspace permissions boundary