fogg
Please note: If you believe you have found a security issue, please responsibly disclose by contacting us at security@chanzuckerberg.com.
Fogg is an opinionated tool for managing infrastructure-as-code repositories using Terraform.
Terraform is a powerful tool for managing infrastructure– great when things go right, but dangerous when they don't. Best practices are emerging for reducing this risk, but they require significant work and knowledge to apply consistently.
We built fogg to automate these practices and scale to a larger pool of engineers who don't have to be terraform experts to use it safely.
A few of the things fogg standardizes–
- repository layout
- remote state (locking coming soon)
- resource naming
- resource isolation
It makes life easy for folks working with cloud infrastructure. We've been using fogg and its predecessor internally at CZI for ~10 months. It has made it possible for many developers without terraform experience to safely roll new infrastructure with less stress and higher quality.
"I hope one day you might consider open sourcing fogg
, i really love it. This would have saved me so much time in the past." - @lenn0x
Getting Help
If you need help getting started with fogg, either open a github issue or join our gitter chat room.
Install
Mac
You can use homebrew to install fogg –
brew tap chanzuckerberg/tap
brew install fogg
Note– if you installed fogg from homebrew before version 0.15.0, the tap location has changed. Run this, then install as above–
brew uninstall fogg
brew untap chanzuckerberg/fogg
Linux
Binaries are available on the releases page. Download one for your architecture, put it in your path and make it executable.
Instructions on downloading the binary:
- Go here: https://github.com/chanzuckerberg/fogg/releases to find which version of fogg you want.
- Run
rm -r WHICH_FOGG_PATH; curl -s https://raw.githubusercontent.com/chanzuckerberg/fogg/master/download.sh | bash -s -- -b FOGG_PATH VERSION
where FOGG_PATH is where you want to install fogg and VERSION is the specific release version you want to install (format is vx.yy.z). To find the path of your current fogg, you can run which fogg
. Then use the path that is outputted as WHICH_FOGG_PATH in the command. The FOGG_PATH is the folder in which fogg will be installed.
- To verify you installed the desired version, you can run
fogg version
.
Usage
Fogg works entirely by generating code (terraform and make). It will generate directories and files to organize and standardize your repo and then it gets out of your way for you to use terraform and make to manage your infrastructure.
The basic workflow is –
- update fogg.yml
- run
fogg apply
to code generate
- use the generated Makefiles to run your Terraform commands
Enabling shell autocompletion
bash
Linux
# Might need to install bash-completion on CentOS
yum install bash-completion
# install completion
echo "source <(fogg completion bash)" >> ~/.bashrc
Mac
## If running Bash 3.2 included with macOS
brew install bash-completion
## or, if running Bash 4.1+
brew install bash-completion@2
# install completion
fogg completion bash > $(brew --prefix)/etc/bash_completion.d/fogg
zsh
You can add the file generated by fogg completion zsh
to a directory in your $fpath.
Design Principles
Convention over Configuration
Much like Ruby on Rails, we prefer to use conventions to organize our repos rather than a plethora of configuration. Our opinions might not be exactly the way you would do things, but our hope is that be having a set of clear opinions that are thoroughly applied will be productive.
Transparency
Fogg tries to stay out of your way– it will do its work by generating Terraform and Make files, and then it step aside for you to manage your infrastructure. Everything that could effect your infrastructure is right there in your repository for you to read and understand.
There is no magic.
And if you ever decide to stop using it, you have a working repo you can take in a different direction, just stop running fogg apply
and go your own way.
Releasing
The release process is mostly automated but has some rough edges. To run a release follow these steps
- you are running docker
- you have access to write to chanzuckerberg/homebrew-tap
- ensure that you have a
GITHUB_TOKEN
environment variable set that has permissions to do releases on this project
- run
git clean -fdx
- you have run
make setup
- run
make release
Contributing
We use standard go tools + makefiles to build fogg. Getting started should be as simple as-
- install go
$ go get github.com/chanzuckerberg/fogg
cd $GOPATH/src/github.com/chanzuckerberg/fogg
make
If you would like to contribute some code: Read through the documents located in the /docs
folder, fork this repo, and send a pull request.
Copyright
Copyright 2017-2020, Chan Zuckerberg Initiative, LLC
For license, see LICENSE.