account-map

This component is responsible for provisioning information only: it simply populates Terraform state with data (account ids, groups, and roles) that other root modules need via outputs.

Usage

Pre-requisites

account must be provisioned before account-map component

Usage

Stack Level: Global

Here is an example snippet for how to use this component. Include this snippet in the stack configuration for the management account (typically root) in the management tenant/OU (usually something like mgmt or core) in the global region (gbl). You can include the content directly, or create a stacks/catalog/account-map.yaml file and import it from there.

components:
  terraform:
    account-map:
      vars:
        enabled: true
        # Set profiles_enabled to false unless we are using AWS config profiles for Terraform access.
        # When profiles_enabled is false, role_arn must be provided instead of profile in each terraform component provider.
        # This is automatically handled by the component's `provider.tf` file in conjunction with
        # the `account-map/modules/iam-roles` module.
        profiles_enabled: false
        root_account_aws_name: "aws-root"
        root_account_account_name: root
        identity_account_account_name: identity
        dns_account_account_name: dns
        audit_account_account_name: audit

        # The following variables contain `format()` strings that take the labels from `null-label`
        # as arguments in the standard order. The default values are shown here, assuming
        # the `null-label.label_order` is
        # ["namespace", "tenant", "environment", "stage", "name", "attributes"]
        # Note that you can rearrange the order of the labels in the template by
        # using [explicit argument indexes](https://pkg.go.dev/fmt#hdr-Explicit_argument_indexes) just like in `go`.

        #  `iam_role_arn_template_template` is the template for the template [sic] used to render Role ARNs.
        #  The template is first used to render a template for the account that takes only the role name.
        #  Then that rendered template is used to create the final Role ARN for the account.
        iam_role_arn_template_template: "arn:%s:iam::%s:role/%s-%s-%s-%s-%%s"
        # `profile_template` is the template used to render AWS Profile names.
        profile_template: "%s-%s-%s-%s-%s"

Variables

Required Variables

region (string) required: AWS Region
root_account_aws_name (string) required: The name of the root account as reported by AWS

Optional Variables

account_configuration_export_enabled (bool) optional

If true, the account configuration information will be exported to a file under account-info/

Default value: true

artifacts_account_account_name (string) optional

The short name for the artifacts account

Default value: "artifacts"

audit_account_account_name (string) optional

The short name for the audit account

Default value: "audit"

aws_config_identity_profile_name (string) optional

The AWS config profile name to use as source_profile for credentials.

Default value: null

dns_account_account_name (string) optional

The short name for the primary DNS account

Default value: "dns"

iam_role_arn_template_template (string) optional

The template for the template used to render Role ARNs.
The template is first used to render a template for the account that takes only the role name.
Then that rendered template is used to create the final Role ARN for the account.
Default is appropriate when using tenant and default label order with null-label.
Use "arn:%s:iam::%s:role/%s-%s-%s-%%s" when not using tenant.

Note that if the null-label variable label_order is truncated or extended with additional labels, this template will
need to be updated to reflect the new number of labels.

Default value: "arn:%s:iam::%s:role/%s-%s-%s-%s-%%s"

identity_account_account_name (string) optional

The short name for the account holding primary IAM roles

Default value: "identity"

import_organization_accounts (bool) optional

Retrieve accounts from AWS Organizations and import them into the account map.
Set false for brownfield environments where you want to curate the list of
accounts manually via the account component with a static backend.
Note that the brownfield account component needs to include the root account
in the account_names_account_ids map, whereas the greenfield account component
does not.

Default value: true

legacy_terraform_uses_admin (bool) optional

If true, the legacy behavior of using the admin role rather than the terraform role in the
root and identity accounts will be preserved.
The default is to use the negations of the value of terraform_dynamic_role_enabled.

Default value: null

profile_template (string) optional

The template used to render AWS Profile names.
Default is appropriate when using tenant and default label order with null-label.
Use "%s-%s-%s-%s" when not using tenant.

Note that if the null-label variable label_order is truncated or extended with additional labels, this template will
need to be updated to reflect the new number of labels.

Default value: "%s-%s-%s-%s-%s"

profiles_enabled (bool) optional

Whether or not to enable profiles instead of roles for the backend. If true, profile must be set. If false, role_arn must be set.

Default value: false

root_account_account_name (string) optional

The short name for the root account

Default value: "root"

terraform_dynamic_role_enabled (bool) optional

If true, the IAM role Terraform will assume will depend on the identity of the user running terraform

Default value: false

terraform_role_name_map (map(string)) optional

Mapping of Terraform action (plan or apply) to aws-team-role name to assume for that action

Default value:

{
  "apply": "terraform",
  "plan": "planner"
}

Context Variables

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

additional_tag_map (map(string)) optional

Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.

Required: No

Default value: { }

attributes (list(string)) optional

ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.

Required: No

Default value: [ ]

context (any) optional

Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.

Required: No

Default value:

{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}

delimiter (string) optional

Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.

Required: No

Default value: null

descriptor_formats (any) optional

Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
\{<br/> format = string<br/> labels = list(string)<br/> \}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).

Required: No

Default value: { }

enabled (bool) optional

Set to false to prevent the module from creating any resources
Required: No

Default value: null

environment (string) optional

ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'
Required: No

Default value: null

id_length_limit (number) optional

Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.

Required: No

Default value: null

label_key_case (string) optional

Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.

Required: No

Default value: null

label_order (list(string)) optional

The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.

Required: No

Default value: null

label_value_case (string) optional

Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.

Required: No

Default value: null

labels_as_tags (set(string)) optional

Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.

Required: No

Default value:

[
  "default"
]

name (string) optional

ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.

Required: No

Default value: null

namespace (string) optional

ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique
Required: No

Default value: null

regex_replace_chars (string) optional

Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.

Required: No

Default value: null

stage (string) optional

ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'
Required: No

Default value: null

tags (map(string)) optional

Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.

Required: No

Default value: { }

tenant (string) optional

ID element (Rarely used, not included by default). A customer identifier, indicating who this instance of a resource is for
Required: No

Default value: null

Outputs

account_info_map

A map from account name to various information about the account.
See the account_info_map output of account for more detail.

all_accounts

A list of all accounts in the AWS Organization

artifacts_account_account_name

The short name for the artifacts account

audit_account_account_name

The short name for the audit account

aws_partition

The AWS "partition" to use when constructing resource ARNs

cicd_profiles OBSOLETE

dummy results returned to avoid breaking code that depends on this output

cicd_roles OBSOLETE

dummy results returned to avoid breaking code that depends on this output

dns_account_account_name

The short name for the primary DNS account

eks_accounts

A list of all accounts in the AWS Organization that contain EKS clusters

full_account_map

The map of account name to account ID (number).

helm_profiles OBSOLETE

dummy results returned to avoid breaking code that depends on this output

helm_roles OBSOLETE

dummy results returned to avoid breaking code that depends on this output

iam_role_arn_templates

Map of accounts to corresponding IAM Role ARN templates

identity_account_account_name

The short name for the account holding primary IAM roles

non_eks_accounts

A list of all accounts in the AWS Organization that do not contain EKS clusters

org

The name of the AWS Organization

profiles_enabled

Whether or not to enable profiles instead of roles for the backend

root_account_account_name

The short name for the root account

root_account_aws_name

The name of the root account as reported by AWS

terraform_access_map

Mapping of team Role ARN to map of account name to terraform action role ARN to assume

For each team in aws-teams, look at every account and see if that team has access to the designated "apply" role.
If so, add an entry <account-name> = "apply" to the terraform_access_map entry for that team.
If not, see if it has access to the "plan" role, and if so, add a "plan" entry.
Otherwise, no entry is added.

terraform_dynamic_role_enabled

True if dynamic role for Terraform is enabled

terraform_profiles

A list of all SSO profiles used to run terraform updates

terraform_role_name_map

Mapping of Terraform action (plan or apply) to aws-team-role name to assume for that action

terraform_roles

A list of all IAM roles used to run terraform updates

Dependencies

Requirements

terraform, version: >= 1.2.0
aws, version: >= 4.9.0
local, version: >= 1.3
utils, version: >= 1.10.0

Providers

aws, version: >= 4.9.0
local, version: >= 1.3
utils, version: >= 1.10.0

Modules

Name	Version	Source	Description
`accounts`	1.8.0	`cloudposse/stack-config/yaml//modules/remote-state`	n/a
`atmos`	0.25.0	`cloudposse/label/null`	n/a
`this`	0.25.0	`cloudposse/label/null`	n/a

Resources

The following resources are used by this module:

local_file.account_info (resource)

Data Sources

The following data sources are used by this module:

aws_organizations_organization.organization (data source)
aws_partition.current (data source)
utils_describe_stacks.team_roles (data source)
utils_describe_stacks.teams (data source)

Usage​

Pre-requisites​

Usage​

Variables​

Required Variables​

Optional Variables​

Context Variables​

Outputs​

Dependencies​

Requirements​

Providers​

Modules​

Resources​

Data Sources​

Usage

Pre-requisites

Usage

Variables

Required Variables

Optional Variables

Context Variables

Outputs

Dependencies

Requirements

Providers

Modules

Resources

Data Sources