AWS meshPlatform Module

meshStack is a Cloud Foundation Platform by meshcloud. AWS is a proprietary public cloud platform provided by Amazon Web Services. meshStack supports project and user management for AWS to include AWS services into cloud projects managed by meshStack.

This terraform module is used to integrate AWS into a meshStack instance as a meshPlatform. The output of this module is a set of credentials that need to be configured in meshStack as described in meshcloud public docs.

Prerequisites

• Terraform installed
• AWS CLI installed
• Three accounts to segregate accounts by function.
  • management account: organization management account, the account that hosts the AWS Organization
  • meshcloud account: meshStack will use this account to host the IAM users used by meshStack
  • automation account: meshStack will use this account to manage CloudFormation templates that are used in Landing Zones.
• AdministratorAccess in those accounts.

While not strictly necessary, we recommend to configure a terraform backend to store your state. Storing terraform state will allow you to maintain your meshStack integration after the initial provisioning.

Overview of the integration

Here is how the users and roles for the meshplatform fit together:

graph LR;
    subgraph Management Account
        meshfedServiceRole("🪖 MeshfedServiceRole");
        costExplorerServiceRole("🪖 MeshCostExplorerServiceRole");
    end
    subgraph meshcloud Account
        replicatorUser["👤 ReplicatorUser & AccessKey"];
        costExplorerUser["👤 CostExplorerUser & AccessKey"];
    end
    replicatorUser--Trusted Entity with External-id-->meshfedServiceRole;
    costExplorerUser--Trusted Entity with External-id-->costExplorerServiceRole;
    subgraph Automation Account
        meshfedAutomationRole("🪖 MeshfedAutomationRole");
    end
    replicatorUser--Trusted Entity with External-id-->meshfedAutomationRole

How to authenticate against the three accounts

One way to set up authentication is using three different profiles on your AWS CLI and include those IAM users' access and secret keys in your ~/.aws/credentials file as described below.

provider aws {
  alias = "management"
  profile = "management"
}

provider aws {
  alias = "meshcloud"
  profile = "meshcloud"
}

provider aws {
  alias = "automation"
  profile = "automation"
}

module "meshplatform" {
  source = "git::https://github.com/meshcloud/terraform-aws-meshplatform.git"

  providers = {
    aws.management = aws.management
    aws.meshcloud  = aws.meshcloud
    aws.automation = aws.automation
  }

  # set input variables
}

See the aws provider documentation for other support authentication methods.

Module Structure

For an overview of the module structure, refer to generated terraform docs

How to Use This Module

Using AWS Portal

1. Open AWS CloudShell Service on your management account.¹

   • Install terraform into CloudShell.

     # Terminal Commands For Amazon Linux
     sudo yum install -y yum-utils
     sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
     sudo yum -y install terraform

   • Configure credentials for AWS CLI.

     cat > ~/.aws/credentials << EOF
     [management]
     aws_access_key_id = XXXX
     aws_secret_access_key = XXXX
     [meshcloud]
     aws_access_key_id = XXXX
     aws_secret_access_key = XXXX
     [automation]
     aws_access_key_id = XXXX
     aws_secret_access_key = XXXX
     EOF

2. Create a terraform file that calls this module and produces outputs. Similar to:

   module "meshplatform" {
     source = "git::https://github.com/meshcloud/terraform-aws-meshplatform.git"
     # FILL INPUTS
   }
   output "meshplatform" {
     sensitive = true
     value     = module.meshplatform
   }

   It is highly recommended to configure a terraform backend, otherwise you risk losing track of your applied resources.

3. Execute the module.

   # Changes into ~/terraform-aws-meshplatform and applies terraform
   cd ~/terraform-aws-meshplatform
   terraform init
   terraform apply

4. Use the information from terraform output to configure the platform in meshStack.

   # The JSON output contains sensitive values that must not be transmitted anywhere other then the platform config screen in meshStack.
   terraform output -json

Contributing Guide

Before opening a Pull Request, please do the following:

1. Install pre-commit

   We use pre-commit to perform several terraform related tasks such as terraform validate, terraform fmt, and generating terraform docs with terraform_docs

2. Execute pre-commit install: Hooks configured in .pre-commit-config.yaml will be executed automatically on commit. For manual execution, you can use pre-commit run -a.

Requirements

Name	Version
aws	>= 2.7.0

Providers

Name	Version
aws.automation	>= 2.7.0
aws.management	>= 2.7.0
aws.meshcloud	>= 2.7.0

Modules

Name	Source	Version
automation_account_replicator_access	./modules/meshcloud-replicator/replicator-automation-account-access	n/a
management_account_metering_access	./modules/meshcloud-cost-explorer/ce-management-account-access	n/a
management_account_replicator_access	./modules/meshcloud-replicator/replicator-management-account-access	n/a
meshcloud_account_metering_access	./modules/meshcloud-cost-explorer/ce-meshcloud-account-access	n/a
meshcloud_account_replicator_access	./modules/meshcloud-replicator/replicator-meshcloud-account-access	n/a

Resources

Name	Type
aws_iam_openid_connect_provider.meshstack	resource
aws_caller_identity.automation	data source
aws_caller_identity.management	data source
aws_caller_identity.meshcloud	data source

Inputs

Name	Description	Type	Default	Required
automation_account_service_role_name	Name of the custom role in the automation account. See https://docs.meshcloud.io/docs/meshstack.how-to.integrate-meshplatform-aws-manually.html#set-up-aws-account-3-automation	string	"MeshfedAutomationRole"	no
aws_sso_instance_arn	AWS SSO Instance ARN. Needs to be of the form arn:aws:sso:::instance/ssoins-xxxxxxxxxxxxxxx. Setup instructions https://docs.meshcloud.io/docs/meshstack.aws.sso-setup.html.	string	n/a	yes
can_close_accounts_in_resource_org_paths	AWS ResourceOrgPaths that are used in Landing Zones and where meshStack is allowed to close accounts.	list(string)	[]	no
control_tower_enrollment_enabled	Set to true, to allow meshStack to enroll Accounts via AWS Control Tower for the meshPlatform.	bool	false	no
control_tower_portfolio_id	Must be set for AWS Control Tower	string	""	no
cost_explorer_management_account_service_role_name	Name of the custom role in the management account used by the cost explorer user.	string	"MeshCostExplorerServiceRole"	no
cost_explorer_meshcloud_account_service_user_name	Name of the user using cost explorer service to collect metering data.	string	"meshcloud-cost-explorer-user"	no
cost_explorer_privileged_external_id	Set this variable to a random UUID version 4. The external id is a secondary key to make an AssumeRole API call.	string	n/a	yes
create_access_keys	Set to false to disable creation of any service account access keys.	bool	true	no
landing_zone_ou_arns	Organizational Unit ARNs that are used in Landing Zones. We recommend to explicitly list the OU ARNs that meshStack should manage.	list(string)	[ "arn:aws:organizations:::ou/o-/ou-*" ]	no
management_account_service_role_name	Name of the custom role in the management account. See https://docs.meshcloud.io/docs/meshstack.how-to.integrate-meshplatform-aws-manually.html#set-up-aws-account-2-management	string	"MeshfedServiceRole"	no
meshcloud_account_service_user_name	Name of the meshfed-service user. This user is responsible for replication.	string	"meshfed-service-user"	no
replicator_privileged_external_id	Set this variable to a random UUID version 4. The external id is a secondary key to make an AssumeRole API call.	string	n/a	yes
support_root_account_via_aws_sso	Set to true to allow meshStack to manage the Organization's AWS Root account's access via AWS SSO.	bool	false	no
workload_identity_federation	Set these options to add a trusted identity provider from meshStack to allow workload identity federation for authentication which can be used instead of access keys.	object({ issuer = string, audience = string, thumbprint = string, replicator_subject = string, kraken_subject = string })	null	no

Outputs

Name	Description
automation_account_id	Automation Account ID
cost_explorer_identity_federation_role	n/a
cost_explorer_management_account_role_arn	Amazon Resource Name (ARN) of Management Account Role for replicator
cost_explorer_privileged_external_id	Cost explorer privileged_external_id
management_account_id	Management Account ID
meshcloud_account_id	Meshcloud Account ID
meshstack_access_role_name	The name for the Account Access Role that will be rolled out to all managed accounts.
metering_aws_iam_keys	You can access your credentials when you execute terraform output metering_aws_iam_keys command
replicator_automation_account_role_arn	Amazon Resource Name (ARN) of Automation Account Role for replicator
replicator_aws_iam_keys	You can access your credentials when you execute terraform output replicator_aws_iam_keys command
replicator_management_account_role_arn	Amazon Resource Name (ARN) of Management Account Role for replicator
replicator_privileged_external_id	Replicator privileged_external_id
replicator_workload_identity_federation_role	n/a

Footnotes

1. This How-To guides you through the setup from your Cloudshell. You can also run the terraform scripts on your local machine. ↩