cool-accounts-userservices

This project contains Terraform code to perform the initial configuration of a COOL User Services account. This Terraform code creates and configures the most basic resources needed to build out services and environments.

It creates an IAM role that allows sufficient permissions to provision all AWS resources in this account. This role has a trust relationship with the COOL users account.

Bootstrapping this account

Note that the COOL User Services account must be bootstrapped. This is because initially there is no IAM role that can be assumed to build out these resources. Therefore you must first apply the Terraform code using programmatic credentials for AWSAdministratorAccess as obtained for the COOL User Services account from the COOL AWS SSO page.

After this initial apply your desired IAM role will exist, and it will be assumable from your IAM user that exists in the COOL users account. Therefore you can apply future changes using your IAM user credentials.

To do this bootstrapping, follow these steps:

1. Comment out the profile = "cool-userservices-provisionaccount" line for the "default" provider in providers.tf and directly below that uncomment the line profile = "cool-userservices-account-admin".

2. Create a new AWS profile called cool-userservices-account-admin in your local configuration using the "AWSAdministratorAccess" credentials (access key ID, secret access key, and session token) as obtained from the COOL User Services account:

   [cool-userservices-account-admin]
   aws_access_key_id = <MY_ACCESS_KEY_ID>
   aws_secret_access_key = <MY_SECRET_ACCESS_KEY>
   aws_session_token = <MY_SESSION_TOKEN>

3. Create a Terraform workspace (if you haven't already done so) by running terraform workspace new <workspace_name>

4. Create a <workspace_name>.tfvars file with any optional variables that you wish to override (see Inputs below for details):

   tags = {
     Team        = "VM Fusion - Development"
     Application = "COOL - User Services"
     Workspace   = "production"
   }

5. Run the command terraform init.

6. Run the command terraform apply -var-file=<workspace_name>.tfvars.

7. Revert the changes you made to providers.tf in step 1.

8. Create a new AWS profile called cool-userservices-provisionaccount in your local configuration that includes the provisionaccount_role ARN output from the previous step, for example:

   [cool-userservices-provisionaccount]
   role_arn = arn:aws:iam::111111111111:role/ProvisionAccount
   role_session_name = your.session.name
   source_profile = cool-user-base-profile

9. Run the command terraform apply -var-file=<workspace_name>.tfvars.

At this point the account has been bootstrapped, and you can apply future changes by simply running terraform apply -var-file=<workspace_name>.tfvars.

Requirements

Name	Version
terraform	~> 1.0
aws	~> 4.9

Providers

Name	Version
aws	~> 4.9
aws.organizationsreadonly	~> 4.9

Modules

Name	Source	Version
cw_alarm_sns	github.com/cisagov/sns-send-to-account-email-tf-module	n/a
provisionaccount	github.com/cisagov/provisionaccount-role-tf-module	n/a
session_manager	github.com/cisagov/session-manager-tf-module	n/a
user_group_mod_event	github.com/cisagov/user-group-mod-alert-tf-module	n/a
user_group_mod_sns	github.com/cisagov/sns-send-to-account-email-tf-module	n/a

Resources

Name	Type
aws_iam_policy.provisionssmsessionmanager_policy	resource
aws_iam_role_policy_attachment.provisionssmsessionmanager_policy_attachment	resource
aws_caller_identity.userservices	data source
aws_iam_policy_document.assume_role_doc	data source
aws_iam_policy_document.provisionssmsessionmanager_policy_doc	data source
aws_iam_policy_document.sns_topic_access_policy_doc	data source
aws_organizations_organization.cool	data source

Inputs

Name	Description	Type	Default	Required
aws_region	The AWS region where the non-global resources for the User Services account are to be provisioned (e.g. "us-east-1").	string	"us-east-1"	no
provisionaccount_role_description	The description to associate with the IAM role that allows sufficient permissions to provision all AWS resources in the User Services account.	string	"Allows sufficient permissions to provision all AWS resources in the User Services account."	no
provisionaccount_role_name	The name to assign the IAM role that allows sufficient permissions to provision all AWS resources in the User Services account.	string	"ProvisionAccount"	no
provisionssmsessionmanager_policy_description	The description to associate with the IAM policy that allows sufficient permissions to provision the SSM Document resource and set up SSM session logging in the User Services account.	string	"Allows sufficient permissions to provision the SSM Document resource and set up SSM session logging in the User Services account."	no
provisionssmsessionmanager_policy_name	The name to assign the IAM policy that allows sufficient permissions to provision the SSM Document resource and set up SSM session logging in the User Services account.	string	"ProvisionSSMSessionManager"	no
tags	Tags to apply to all AWS resources provisioned.	map(string)	{}	no

Outputs

Name	Description
cw_alarm_sns_topic	The SNS topic to which a message is sent when a CloudWatch alarm is triggered.
provisionaccount_role	The IAM role that allows sufficient permissions to provision all AWS resources in the User Services account.
ssm_session_role	An IAM role that allows creation of SSM SessionManager sessions to any EC2 instance in this account.

Notes

Running pre-commit requires running terraform init in every directory that contains Terraform code. In this repository, this is just the main directory.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

This project is in the worldwide public domain.

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.