Terragov
GOV.UK use Terraform to deploy infrastructure. Originally a lightweight bash script was built to support our opinionated Terraform project structure, but it quickly added further functionality and I decided it would be nicer to use a tool written in a more complete language.
Installation
gem install terragov
Project structure
This tool is only meant to be used specifically against the project structure defined here.
Usage
terragov [CMD] [OPTIONS]
Run --help for details.
You can run the following commands:
| Command | Description |
|---|---|
plan |
Plan Terraform resources |
apply |
Apply Terraform changes |
destroy |
Delete Terraform resources |
deploy |
Deploy multiple projects as defined by a deployment file |
clean |
Delete any files that have been left by Terraform |
There are several required arguments to pass when running apply, plan or destroy:
| Argument | Description |
|---|---|
stack |
Name of the stack you're deploying to |
environment |
Which environment to deploy to |
repo_dir |
The root of the repo containing terraform code |
data_dir |
The directory containing data |
project |
Name of the project you're deploying |
Configuration
There are three ways to pass arguments, detailed below.
CLI options
Use command line flags to pass the relevant argument. This has highest precedence.
Environment variables
Every command has an environment variable which can also be set. This has second highest precedence. The value is the name, in upper case, and prefixed with TERRAGOV. For example, to set environment:
export TERRAGOV_ENVIRONMENT=integration
Configuration file
Specify a configuration file with the -c or --config-file flags, or use TERRAGOV_CONFIG_FILE to set the location of the file.
If environment variables or CLI flags are set, they will be overridden.
The contents should be YAML, and look like the following:
---
default:
environment: 'integration'
stack: 'blue'
repo_dir: '~/govuk/govuk-aws'
data_dir: '~/govuk/govuk-aws-data/data'
app-some-project:
stack: 'green'
Specify default values under the "default" block, and if you need any project specific values, add them under the key of the same name of that project.
Project specific values will take precedence over default values.
Optional global arguments
These may be set in the same way as described above, with the same precedence, but they are not required.
| Argument | Description |
|---|---|
verbose |
Be more noisy |
test |
Output commands, but do not run anything. Useful for tests. |
skip_git_check |
Do not compare branches between the repo and data directories |
Deployment
You can run multiple projects using the deploy command. Create a deployment file with the following:
---
default:
- 'app-one'
- 'app-two'
- 'app-three'
development:
- 'app-foo'
- 'app-bar'
It will use whatever is defined in the default configuration:
terragov deploy --file integration.yaml --command plan
Define a specific group to deploy:
terragov deploy --file integration.yaml --command plan --group development
This will use the configuration set by all the methods described previously.
Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/surminus/terragov. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.