Merge remote-tracking branch 'skeleton/develop' into lineage/skeleton

Author: jsf9k

.github/workflows/build.yml

@@ -170,6 +170,9 @@ jobs:
         uses: mxschmitt/action-tmate@v3
         if: env.RUN_TMATE
   test:
+    # TODO:  Figure out a plan to test in all environments, not just dev-a.
+    # See cisagov/skeleton-ansible-role-with-test-user#183 for more details.
+    environment: dev-a
     name: >-
       test (${{ matrix.scenario }}) -
       ${{ matrix.platform }}-${{ matrix.architecture }}
@@ -275,7 +278,12 @@ jobs:
           sudo apt-get install apparmor-utils
           sudo aa-disable /usr/sbin/unix_chkpwd
         if: ${{ startsWith(matrix.platform, 'fedora') }}
-      - name: Run molecule tests
+      - # This is an example of how to pass GHA secrets to Molecule
+        # via an environment variable.  See also
+        # molecule/default/converge.yml in this repository.
+        # env:
+        #   THIRD_PARTY_BUCKET: ${{ secrets.THIRD_PARTY_BUCKET }}
+        name: Run molecule tests
         run: >-
           molecule test
           --platform-name ${{ matrix.platform }}-${{ matrix.architecture }}

.gitignore

@@ -10,3 +10,5 @@ __pycache__
 ## Terraform ##
 .terraform
 .terraform.lock.hcl
+*.tfconfig
+*.tfvars

README.md

@@ -8,46 +8,90 @@ An Ansible role for installing
 
 ## Pre-requisites (Ignore Until the COOL Migration) ##
 
-In order to execute the Molecule tests for this Ansible role in GitHub
-Actions, a build user must exist in AWS. The accompanying Terraform
-code will create the user with the appropriate name and
-permissions. This only needs to be run once per project, per AWS
-account. This user can also be used to run the Molecule tests on your
-local machine.
-
-Before the build user can be created, you will need a profile in your
-AWS credentials file that allows you to read and write your remote
-Terraform state.  (You almost certainly do not want to use local
-Terraform state for this long-lived build user.)  If the build user is
-to be created in the CISA COOL environment, for example, then you will
-need the `cool-terraform-backend` profile.
-
-The easiest way to set up the Terraform remote state profile is to
-make use of our
-[`aws-profile-sync`](https://github.com/cisagov/aws-profile-sync)
-utility. Follow the usage instructions in that repository before
-continuing with the next steps, and note that you will need to know
-where your team stores their remote profile data in order to use
+In order to execute the Molecule tests for this Ansible role in GitHub Actions,
+a test user must exist in AWS. The accompanying Terraform code will create the
+user with the appropriate name and permissions. This only needs to be run once
+per project, per AWS account. This user can also be used to run the Molecule
+tests on your local machine.
+
+Before the test user can be created, you will need a profile in your AWS
+credentials file that allows you to read and write your remote Terraform state.
+(You almost certainly do not want to use local Terraform state for this
+long-lived test user.)  If the test user is to be created in the CISA COOL
+environment, for example, then you will need the `cool-terraform-backend`
+profile.
+
+The easiest way to set up the Terraform remote state profile is to make use of
+our [`aws-profile-sync`](https://github.com/cisagov/aws-profile-sync) utility.
+Follow the usage instructions in that repository before continuing with the next
+steps, and note that you will need to know where your team stores their remote
+profile data in order to use
 [`aws-profile-sync`](https://github.com/cisagov/aws-profile-sync).
 
-To create the build user, follow these instructions:
+### Creating a test user ###
 
-```console
-cd terraform
-terraform init --upgrade=true
-terraform apply
-```
+You will need to create a test user for each environment that you use.  The
+following steps show how to create a test user for an environment named "dev".
+You will need to repeat this process for any additional environments.
+
+1. Change into the `terraform` directory:
+
+   ```console
+   cd terraform
+   ```
+
+1. Create a backend configuration file named `dev.tfconfig` containing the
+name of the bucket where "dev" environment Terraform state is stored - this file
+is required to initialize the Terraform backend in each environment:
+
+    ```hcl
+    bucket = "my-dev-terraform-state-bucket"
+    ```
+
+1. Initialize the Terraform backend for the "dev" environment using your backend
+   configuration file:
+
+    ```console
+    terraform init -backend-config=dev.tfconfig
+    ```
+
+    > [!NOTE]
+    > When performing this step for additional environments (i.e. not your first
+    > environment), use the `-reconfigure` flag:
+    >
+    > ```console
+    > terraform init -backend-config=other-env.tfconfig -reconfigure
+    > ```
+
+1. Create a Terraform variables file named `dev.tfvars` containing all
+required variables (currently only `terraform_state_bucket`):
+
+    ```hcl
+    terraform_state_bucket = "my-dev-terraform-state-bucket"
+    ```
+
+1. Create a Terraform workspace for the "dev" environment:
+
+    ```console
+   terraform workspace new dev
+   ```
+
+1. Initialize and upgrade the Terraform workspace, then apply the configuration
+   to create the test user in the "dev" environment:
+
+    ```console
+    terraform init -upgrade=true
+    terraform apply -var-file=dev.tfvars
+    ```
 
-Once the user is created you will need to update the [repository's
-secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)
-with the new encrypted environment variables. This should be done
-using the
+Once the test user is created you will need to update the
+[repository's secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)
+with the new encrypted environment variables. This should be done using the
 [`terraform-to-secrets`](https://github.com/cisagov/development-guide/tree/develop/project_setup#terraform-iam-credentials-to-github-secrets-)
-tool available in the [development
-guide](https://github.com/cisagov/development-guide). Instructions for
-how to use this tool can be found in the ["Terraform IAM Credentials
-to GitHub Secrets"
-section](https://github.com/cisagov/development-guide/tree/develop/project_setup#terraform-iam-credentials-to-github-secrets-).
+tool available in the
+[development guide](https://github.com/cisagov/development-guide). Instructions
+for how to use this tool can be found in the
+["Terraform IAM Credentials to GitHub Secrets" section](https://github.com/cisagov/development-guide/tree/develop/project_setup#terraform-iam-credentials-to-github-secrets-).
 of the Project Setup README.
 
 If you have appropriate permissions for the repository you can view

terraform/backend.tf

@@ -1,9 +1,14 @@
 terraform {
   backend "s3" {
-    bucket         = "ncats-terraform-state-storage"
+    # Use a partial configuration to avoid hardcoding the bucket name. This
+    # allows the bucket name to be set on a per-environment basis via the
+    # -backend-config command line option or other methods.  For details, see:
+    # https://developer.hashicorp.com/terraform/language/backend#partial-configuration
+    bucket         = ""
     dynamodb_table = "terraform-state-lock"
     encrypt        = true
     key            = "ansible-role-ncats-webd/terraform.tfstate"
+    profile        = "cool-terraform-backend"
     region         = "us-east-1"
   }
 }

terraform/outputs.tf

@@ -1,20 +1,15 @@
 output "access_key" {
-  value       = module.user.access_key
   description = "The IAM access key associated with the CI IAM user created by this module."
   sensitive   = true
+  value       = module.user.access_key
 }
 
-output "production_role" {
-  value       = module.user.production_role
-  description = "The IAM role that the CI user can assume to read SSM parameters in the production account."
-}
-
-output "staging_role" {
-  value       = module.user.staging_role
-  description = "The IAM role that the CI user can assume to read SSM parameters in the staging account."
+output "role" {
+  description = "The IAM role that the CI user can assume to read SSM parameters in the Images account."
+  value       = module.user.role
 }
 
 output "user" {
-  value       = module.user.user
   description = "The CI IAM user created by this module."
+  value       = module.user.user
 }

terraform/providers.tf

@@ -8,3 +8,44 @@ provider "aws" {
   }
   region = var.aws_region
 }
+
+# The provider used to create the role that can be assumed to do
+# everything the CI user needs to do in the Images account.
+provider "aws" {
+  alias = "images_provisionaccount"
+  assume_role {
+    role_arn     = data.terraform_remote_state.images.outputs.provisionaccount_role.arn
+    session_name = local.caller_user_name
+  }
+  default_tags {
+    tags = var.tags
+  }
+  region = var.aws_region
+}
+
+# The provider used to create policies and roles that can read
+# parameters from AWS SSM Parameter Store in the Images account.
+provider "aws" {
+  alias = "images_ssm"
+  assume_role {
+    role_arn     = data.terraform_remote_state.images_ssm.outputs.provisionparameterstorereadroles_role.arn
+    session_name = local.caller_user_name
+  }
+  default_tags {
+    tags = var.tags
+  }
+  region = var.aws_region
+}
+
+# The provider used to create the test user
+provider "aws" {
+  alias = "users"
+  assume_role {
+    role_arn     = data.terraform_remote_state.users.outputs.provisionaccount_role.arn
+    session_name = local.caller_user_name
+  }
+  default_tags {
+    tags = var.tags
+  }
+  region = var.aws_region
+}

terraform/remote_states.tf

@@ -0,0 +1,50 @@
+# ------------------------------------------------------------------------------
+# Retrieve state data from a Terraform backend. This allows use of the
+# root-level outputs of one or more Terraform configurations as input
+# data for this configuration.
+# ------------------------------------------------------------------------------
+
+data "terraform_remote_state" "images" {
+  backend = "s3"
+
+  config = {
+    bucket         = var.terraform_state_bucket
+    dynamodb_table = "terraform-state-lock"
+    encrypt        = true
+    key            = "cool-accounts/images.tfstate"
+    profile        = "cool-terraform-readstate"
+    region         = "us-east-1"
+  }
+
+  workspace = terraform.workspace
+}
+
+data "terraform_remote_state" "images_ssm" {
+  backend = "s3"
+
+  config = {
+    bucket         = var.terraform_state_bucket
+    dynamodb_table = "terraform-state-lock"
+    encrypt        = true
+    key            = "cool-images-parameterstore/terraform.tfstate"
+    profile        = "cool-terraform-readstate"
+    region         = "us-east-1"
+  }
+
+  workspace = terraform.workspace
+}
+
+data "terraform_remote_state" "users" {
+  backend = "s3"
+
+  config = {
+    bucket         = var.terraform_state_bucket
+    dynamodb_table = "terraform-state-lock"
+    encrypt        = true
+    key            = "cool-accounts/users.tfstate"
+    profile        = "cool-terraform-readstate"
+    region         = "us-east-1"
+  }
+
+  workspace = terraform.workspace
+}

terraform/user.tf

@@ -3,11 +3,9 @@ module "user" {
   source = "github.com/cisagov/molecule-iam-user-tf-module"
 
   providers = {
-    aws                                    = aws
-    aws.images-production-provisionaccount = aws
-    aws.images-staging-provisionaccount    = aws
-    aws.images-production-ssm              = aws
-    aws.images-staging-ssm                 = aws
+    aws                         = aws.users
+    aws.images-provisionaccount = aws.images_provisionaccount
+    aws.images-ssm              = aws.images_ssm
   }
 
   entity = "ansible-role-ncats-webd"

terraform/variables.tf

@@ -1,21 +1,34 @@
+# ------------------------------------------------------------------------------
+# Required parameters
+#
+# You must provide a value for each of these parameters.
+# ------------------------------------------------------------------------------
+
+variable "terraform_state_bucket" {
+  description = "The name of the S3 bucket where Terraform state is stored."
+  nullable    = false
+  type        = string
+}
+
 # ------------------------------------------------------------------------------
 # Optional parameters
 #
 # These parameters have reasonable defaults.
 # ------------------------------------------------------------------------------
 
 variable "aws_region" {
-  type        = string
-  description = "The AWS region to deploy into (e.g. us-east-1)."
   default     = "us-east-1"
+  description = "The AWS region to deploy into (e.g. us-east-1)."
+  nullable    = false
+  type        = string
 }
 
 variable "tags" {
-  type        = map(string)
-  description = "Tags to apply to all AWS resources created"
-
   default = {
     Team        = "VM Fusion - Development"
     Application = "ansible-role-ncats-webd testing"
   }
+  description = "Tags to apply to all AWS resources created"
+  nullable    = false
+  type        = map(string)
 }