diff options
author | Jakob Odersky <jakob@odersky.com> | 2018-10-22 04:02:44 -0700 |
---|---|---|
committer | Jakob Odersky <jakob@odersky.com> | 2018-10-22 04:02:44 -0700 |
commit | 4d7a93c535ceeb720dc1873bfa61531099b611cb (patch) | |
tree | 5aa2c02bf756f72fecb5d7bf695a98edfdb417b2 /README.md | |
download | infra-4d7a93c535ceeb720dc1873bfa61531099b611cb.tar.gz infra-4d7a93c535ceeb720dc1873bfa61531099b611cb.tar.bz2 infra-4d7a93c535ceeb720dc1873bfa61531099b611cb.zip |
Initial commit
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..214f154 --- /dev/null +++ b/README.md @@ -0,0 +1,77 @@ +## Quasi-Immutable Infrastructure for Small-Scale Deployments + +This project combines [terraform](https://www.terraform.io) with +[debian configuration packages](https://wiki.debian.org/Packaging) to +manage infrastructure automatically. + +It has a very opinionated structure, ideal for managing a small amount +of (personal) servers. + +It is used to manage the crashbox.io services. + +## Overview + +Management of infrastructure revolves around two central concepts: + +1. Provisioning of infrastructure, such as virtual private + servers and DNS entries, with terraform. + +2. Configuration of servers with debian packages. Custom debian + packages integrate easily into the debian ecosystem and provide a + robust way of managing files. + +These two concepts are brought together by *roles* which aggregate DNS +entries and packages. + +**In a nutshell, all infrastructure is configured by assigning sets of +roles to servers. A role will apply a debian configuration package to +a server and create a CNAME to the server's A record.** + +For example, assigning the `ip` role to server `server.crashbox.io` will: + +1. Create the server and A record if it isn't already there. +2. Install the package `crashbox-ip-config` on the server. +3. Create a DNS CNAME, aliasing `ip.crashbox.io` to `server.crashbox.io`. + +In the given example, the ip-config package will ensure a webserver is +installed and configure it to serve an ip address echo website. + +## Structure + +- Provisioning scripts are in `terraform/`. + +- Configuration package sources are in `packages/`. Note that for a + given role `<role>`, the corresponding debian package is + `crasbox-<role>-config`. + +## Running + +### Bootstrap + +Before infrastructure configuration can be automated, a couple of +bootstrapping steps need to be performed manually: + +0. Create accounts for the various providers specified in the +terraform configuration. + +1. Provision a storage space for the terraform state file. + +2. Install dependencies for this project: + - make + - debhelper + - debuild + - terraform + - pass + +### Apply + +Run `make` to apply configuration. + +## Note about immutability + +This project uses debian packages for stronger consistency guarantees +when removing packages. Nevertheless, it is recommended to completely +reprovision a server if a role is removed. + +Keeping in mind that the goal of this project is to automate +deployments, regular reprovisions are encouraged. |