peggy
Welcome to peggy!
Peggy (or peg
for short) is a CLI that helps you manage Terraform variables stored and loaded via JSON files. The primary goal is to ease the workflow necessary to pick and choose Docker images to be used for deployment.
Peggy helps by automating the process of connecting to a Docker registry, finding the image to deploy and updating the necessary files to have Terraform pick up changes. Peggy was inspired by previous work in a similar tool (Mimiron) with related goals. Since then the landscape has changed significantly and Peggy is the next iteration of the same tooling.
Supported registeries:
- AWS ECR
- Google Container Registry (coming soon)
- DockerHub (coming soon)
Workflow
There are often variable values used in your Terraform HCL which change based on environment. Most commonly updated is a reference to a Docker image stored in AWS ECR, DockerHub or any other image registry. You'll typically see them pulled out of HCL and placed into a variable definition file and then loaded when running plan
or apply
.
When you or a colleague wants to deploy or rollback to a previous image, a typical workflow might be:
- Log into your CI/CD app
- Navigate to your application's pipeline
- Scroll to the artifacts section and find the Docker image you want to deploy
- Manually copy the aritfact name, open your variables definitions file, and paste it over the current version
The process is tedious and error prone. Peggy
automates this process for you, allowing you stay within the terminal.
(see examples directory for sample HCL configurations with JSON variable definitions.)
Installation
yarn global add @voltronstudio/peggy
Usage
# Fetch the current status of your state by parsing your config
peg status
# Fetch the current status for a specific app
peg status <app>
# Fetch images in registry to deploy, targets production, and commits without pushing
peg bump <app> --env=production
# Fetches images in ECR to deploy, using the default env, commits, and pushes
peg bump <app> --push
# Fetches images from a differently name repository (by default it uses the same name as <app>)
peg bump <app> <repository>
# Validates the variables.json specified by <path>
peg validate <path>
# See help for more details
peg --help
peh <command> --help
Variables.json
Peggy
uses JSON to store variables outside of HCL. You can place these variables anywhere in your Terraform project, however it's expected that it should follow this directory structure:
└── variables
├── development.json
├── qa.json
├── preprod.json
├── uat.json
├── staging.json
└── production.json
A single directory holding all <env>.json
variables. Peggy
provides a validate
command to check the shape of your variables.json
:
peg validate ./variables/development.json
See ./data/variables for a sample variables.json. Also, see ./examples/kubernetes/variables.
apps
is an object where thekey
is the name of yourapplication
e.g.web
- Each value in
apps
is configuration specific to yourapplication
- An app can be thought of as a
pod
in Kubernetes orservice
in ECS - Each
pod
have one or many containers. When there's just one container, yourcontainers
can be an object rather than an array of objects - Each
container
has an optionalextraAgs
object. It's a freeform object where you can pass additional options
Configuration
Upon startup, Peggy
will attempt to load a .peggy
JSON file in the current working directory. You can override this behaviour, by passing --config <path>
in each command. For example,
peg status --config ./data/config.json
defaultEnvironment
- Default environment, can be overriden with--env <env>
defaultAwsProfile
- AWS profile in ~/.aws/credentials to use when calling ECRdefaultAwsRegion
- Region of your ECR repositoriesvariablesPath
- Location of the directory to your variable definitions
See ./data/config.json for a sample config.
Contributing
We're always happy to have others contribute to the project. To get started, clone the repository:
git clone git@github.com:voltronstudio/peggy.git
Install project dependencies:
yarn
Run tests:
yarn test
yarn test:coverage
Execute locally during development:
yarn ts-node ./src --help
If you don't have your editor configured to autoformat (eslint
& prettier
) and build (tsc
):
yarn lint
yarn build
Publishing
yarn \
&& yarn lint \
&& yarn version --patch --message "chore: bump peggy version" \
&& yarn build \
&& yarn publish --no-git-tag-version --access public --non-interactive
Made with