From 044bbb2c5bf5b5ccc77d3e90430383e0abc6daf3 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Wed, 21 Oct 2015 20:50:34 -0400 Subject: update docs for conductors --- doc/README.mdwn | 5 +- doc/automated_spins.mdwn | 127 ++++++++++++++++++++++++++++++++++++ doc/centralized_git_repository.mdwn | 37 ----------- 3 files changed, 130 insertions(+), 39 deletions(-) create mode 100644 doc/automated_spins.mdwn delete mode 100644 doc/centralized_git_repository.mdwn diff --git a/doc/README.mdwn b/doc/README.mdwn index 1c4247cf..62085fdb 100644 --- a/doc/README.mdwn +++ b/doc/README.mdwn @@ -53,6 +53,7 @@ see [configuration for the Haskell newbie](https://propellor.branchable.com/hask So, edit `~/.propellor/config.hs` to configure the host, add some properties to it, and re-run step 6. Repeat until happy and move on to the next host. :) -8. Optionally, set up a [centralized git repository](https://propellor.branchable.com/centralized_git_repository/) - so that multiple hosts can be updated with a simple `git commit -S; git push` +8. Once you have a lot of hosts, and running `propellor --spin HOST` for + each host becomes tiresome, you can + [automate that](http://propellor.branchable.com/automated_spins/). 9. Write some neat new properties and send patches! diff --git a/doc/automated_spins.mdwn b/doc/automated_spins.mdwn new file mode 100644 index 00000000..e8f44c75 --- /dev/null +++ b/doc/automated_spins.mdwn @@ -0,0 +1,127 @@ +Once you have several hosts managed with propellor, you'll probably find +yourself making changes to config.hs, that might affect multiple hosts. + +You can manually run `propellor --spin $HOST` for each affected host in +turn. But that can get old. Time to automate it. + +There are two approaches you can follow: + +* Set up a centralized git repository, and make your hosts + check it for updates using cron. Then you can `git commit -S` + and `git push` changes that affect any number of hosts. + +* Set up a conductor host. When propellor is run on this host, + it will automatically spin the other hosts. + +We'll start with a centralized git repository and cron, because that's +the easiest thing to set up, and it's a good idea to have one as a backup. +Especially if you have co-maintainers, you'll obviously want to use +a centralized repository to allow collaboration. + +## where to put the central repository + +The central repository does not need to be trusted; it can be hosted +anywhere, and propellor will only accept verified gpg signed git commits +from it. See [[security]] for details, but this means you can put it +on github without github being able to 0wn your propellor driven hosts, for +example. + +Or, you can just add some properties to one of your hosts to make it +serve the central repository. Using `Propellor.Property.Git.daemonRunning` +for example. + +## how to set up the central repository + +You can add a central git repository to your existing propellor setup easily: + +1. Push propellor's git repository to a central server (github or your own): + `cd ~/.propellor/; git remote add origin ssh://git.example.com/propellor.git; git push -u origin master` + +2. Configure the url your hosts should use for the git repository, if + it differs from the url above, by setting up a remote named "deploy": + `cd ~/.propellor/; git remote add deploy git://git.example.com/propellor.git` + +3. Add a crom job property to your hosts, which will make them periodically + check for changes that were committed to the central repository: + `Cron.runPropellor (Cron.Times "*/30 * * * *")` + +4. Let your hosts know about the changed configuration (including the url + to the central repository), by running `propellor --spin $HOST` for each + of your hosts. + +Now the hosts will automatically update every 30 minutes, and you can +`git commit -S` and `git push` changes that affect any number of +hosts. + +## setting up a conductor host + +When propellor is run on a conductor host, it will automatically +spin some other hosts. + +Using a conductor host has many benefits over a centralized git +repository and cron: + +1. Private data, set with `propellor --set`, is gpg encrypted, and + hosts cannot decrypt it when their cron job pulls changes from + the central repository. So after updating the private data of a host, + you still need to manually run `propellor --spin $HOST`. A conductor + avoids this problem. +2. You have to wait a while for a change you commit to be + deployed by cron. It would be nice to be able to run "propellor" + once and have it update all your hosts immediately. +3. When there's a problem, a cron job can hide it, while if you're + running propellor yourself, you can notice the problem more easily. +4. You might want to update hosts in a specific order. For example, + update your dns server last. Cron jobs can't do this, but conductors + can. + +Conductors are configured using the +[Propellor.Property.Conductor module](http://hackage.haskell.org/package/propellor/docs/Propellor-Property-Conductor.html). + +If you decide to go this route, pick the host you want to make a conductor, +and add some properties to it: + + mylaptop = host "mylaptop.example.com" + & conducts [somehost, otherhost, lasthost] + & Ssh.userKeys (User "root") + [(SshEd25519, somelongstring)] + +The Ssh.userKeys is used to give the root user on the conductor a known +ssh public key. You'll need to feed the private ssh key into propellor's +privdata store (see [[security]]). + +Each of the hosts that is being conducted needs to have its ssh host key +specified as well. This is needed so that the conductor can ssh into +the hosts. + + somehost = host "somehost.example.com" + -- This sets the private key as well, so it will need to + -- be fed into propellor's privdata store. + & Ssh.hostKeys hostContext [(SshEd25519, somelongstring)] + + lasthost = host "lasthost.example.com" + -- This way indicates the public key, but doesn't change + -- the actual host configuration. + & Ssh.hostPubKey SshEd25519, somelongstring + +Also, make this change: + + - main = defaultMain hosts + + main = defaultMain (orchestrate hosts) + +Give each of the hosts you changed one last manual --spin, to set +things up for the conductor. + +Now you're ready to use the conductor. When you spin the conductor +host, it will in turn spin each of the hosts it's conducting. + +This simple conductor configuration can be easily adapted to +better meet your needs. For example, if you have a host that should only +be spinned once all the other hosts have successfully been updated, +the conductor can be configured to do that: + + & conducts [somehost, otherhost] + `before` conducts lasthost + +Other possibilities include chains of conductors spinning other conductors +that spin hosts, etc. diff --git a/doc/centralized_git_repository.mdwn b/doc/centralized_git_repository.mdwn deleted file mode 100644 index c9429394..00000000 --- a/doc/centralized_git_repository.mdwn +++ /dev/null @@ -1,37 +0,0 @@ -Propellor can be used without any centralized git repsitory. When -`propellor --spin $HOST` is run, propellor pushes the local git repo -directly to the host. This makes it easy to get started with propellor. - -A central git repository allows hosts to run propellor from cron and pick -up any updates you may have pushed. This is useful when managing several -hosts with propellor. - -The central repository does not need to be trusted; it can be hosted -anywhere, and propellor will only accept verified gpg signed git commits -from it. See [[security]] for details, but this means you can put it -on github without github being able to 0wn your propellor driven hosts, for -example. - -You can add a central git repository to your existing propellor setup easily: - -1. Push propellor's git repository to a central server (github or your own): - `cd ~/.propellor/; git remote add origin ssh://git.example.com/propellor.git; git push -u origin master` - -2. Configure the url your hosts should use for the git repository, if - it differs from the url above, by setting up a remote named "deploy": - `cd ~/.propellor/; git remote add deploy git://git.example.com/propellor.git` - -2. Add a property to your hosts like: - `Cron.runPropellor (Cron.Times "*/30 * * * *")` - -3. Let your hosts know about the changed configuration (including the url - to the central repository), by running `propellor --spin $HOST` for each - of your hosts. - -Now the hosts will automatically update every 30 minutes, and you can -`git commit -S` and `git push` changes that affect any number of -hosts. - -Note that private data, set with `propellor --set`, is gpg encrypted, and -hosts cannot decrypt it! So after updating the private data of a host, -you still need to manually run `propellor --spin $HOST` -- cgit v1.2.3