assessor-workbench-packer

This repository is used to create images containing the Assessor Workbench software.

Pre-requisites

This project requires a build user to 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 will also be used by GitHub Actions.

Before the build user can be created, the following profile must exist in your AWS credentials file:

• cool-terraform-backend

The easiest way to set up that profile is to use our aws-profile-sync utility. Follow the usage instructions in that repository before continuing with the next steps. Note that you will need to know where your team stores their remote profile data in order to use aws-profile-sync.

To create the build user, follow these instructions:

cd terraform-build-user
terraform init --upgrade=true
terraform apply

Once the user is created you will need to update the repository's secrets with the new encrypted environment variables. This should be done using the terraform-to-secrets tool available in the development guide. Instructions for how to use this tool can be found in the "Terraform IAM Credentials to GitHub Secrets" section. of the Project Setup README.

If you have appropriate permissions for the repository you can view existing secrets on the appropriate page in the repository's settings.

IMPORTANT: The account where your images will be built must have a VPC and a public subnet both tagged with the name "AMI Build", otherwise packer will not be able to build images.

Building the Image

Using GitHub Actions

1. Create a new release in GitHub.
2. There is no step 2!

GitHub Actions can build this project in three different modes depending on how the build was triggered from GitHub.

1. Non-release test: After a normal commit or pull request GitHub Actions will build the project, and run tests and validation on the packer configuration. It will not build an image.
2. Pre-release deploy: Publish a GitHub release with the "This is a pre-release" checkbox checked. An image will be built and deployed using the prerelease workflow. This should be configured to deploy the image to a single region using a non-production account (e.g. "staging").
3. Production release deploy: Publish a GitHub release with the "This is a pre-release" checkbox unchecked. An image will be built and deployed using the release workflow. This should be configured to deploy the image to multiple regions using a production account.

Using Your Local Environment

Packer will use your standard AWS environment to build the image, however you will need to set up one profile for the previously-created build user and another profile to assume the associated EC2AMICreate role. You will need the aws_access_key_id and aws_secret_access_key that you set as GitHub secrets earlier.

Add the following blocks to your AWS credentials file (be sure to replace the dummy account ID in the role_arn with your own):

[build-assessor-workbench-packer]
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

[cool-images-ec2amicreate-assessor-workbench-packer]
role_arn = arn:aws:iam::111111111111:role/EC2AMICreate-build-assessor-workbench-packer
source_profile = build-assessor-workbench-packer
role_session_name = example

The Packer template defines a number of variables:

Changing these defaults can be done through a .pkrvars.hcl file:

build_bucket = "installers-bucket"
build_region = "us-east-2"
build_region_kms = "alias/example-kms"
is_prerelease = "true"

Here is an example of how to kick off a pre-release build:

pip install --requirement requirements-dev.txt
ansible-galaxy install --force --force-with-deps --role-file src/requirements.yml
AWS_PROFILE=cool-images-ec2amicreate-assessor-workbench-packer packer build --timestamp-ui -var release_tag=$(./bump_version.sh show) -var build_bucket=installers-bucket -var is_prerelease=true src/packer.pkr.hcl

If you are satisfied with your pre-release image, you can easily create a release that deploys to all regions by adding additional regions to the packer configuration. This can be done by using a .pkrvars.hcl for example with release.pkrvars.hcl:

build_bucket = "installers-bucket"
ami_regions = ["us-east-2", "us-west-1", "us-west-2"]
region_kms_keys = {
  "us-east-2": "alias/cool-amis",
  "us-west-1": "alias/cool-amis",
  "us-west-2": "alias/cool-amis",
}

AWS_PROFILE=cool-images-ec2amicreate-assessor-workbench-packer packer build --timestamp-ui -var-file release.pkrvars.hcl src/packer.pkr.hcl

Giving Other AWS Accounts Permission to Launch the Image

After the AMI has been successfully created, you may want to allow other accounts in your AWS organization permission to launch it. For this project, we want to allow all accounts whose names begin with "env" to launch the most-recently-created AMI. To do that, follow these instructions, noting that "ENVIRONMENT_TYPE" below should be replaced with where the AMI was created (e.g "production", "staging", etc.):

cd terraform-post-packer
terraform workspace select ENVIRONMENT_TYPE
terraform init --upgrade=true
terraform apply

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.