skeleton-packer 💀📦

This is a generic skeleton project that can be used to quickly get a new cisagov GitHub Packer project started. This skeleton project contains licensing information, as well as pre-commit hooks and GitHub Actions configurations appropriate for the major languages that we use.

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-skeleton-packer]
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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

The Packer template defines a number of variables:

Name	Description	Type	Default	Required
ami_regions	The list of AWS regions to copy the AMI to once it has been created. Example: ["us-east-1"]	list(string)	[]	no
build_region	The region in which to retrieve the base AMI from and build the new AMI.	string	"us-east-1"	no
build_region_kms	The ID or ARN of the KMS key to use for AMI encryption.	string	"alias/cool-amis"	no
is_prerelease	The pre-release status to use for the tags applied to the created AMI.	bool	false	no
region_kms_keys	A map of regions to copy the created AMI to and the KMS keys to use for encryption in that region. The keys for this map must match the values provided to the aws_regions variable. Example: {"us-east-1": "alias/example-kms"}	map(string)	{}	no
release_tag	The GitHub release tag to use for the tags applied to the created AMI.	string	""	no
release_url	The GitHub release URL to use for the tags applied to the created AMI.	string	""	no
skip_create_ami	Indicate if Packer should not create the AMI.	bool	false	no

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

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-skeleton-packer packer build --timestamp-ui -var release_tag=$(./bump_version.sh show) -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:

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-skeleton-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

New Repositories from a Skeleton

Please see our Project Setup guide for step-by-step instructions on how to start a new repository from a skeleton. This will save you time and effort when configuring a new repository!

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.