Update README.md
diff --git a/README.md b/README.md
index c1321b1..43edcb7 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
CouchDB Infrastructure Config Management
===
-This repository contains Ansible scripts for managing our VM testing infrastructure.
+This repository contains Ansible scripts for managing our VM testing
+infrastructure.
Setup
---
@@ -13,11 +14,26 @@
Provisioning VMs
---
-Our main workhorse is the cx2-4x8 instance type. There are also a few
-ppc64le nodes for doing full builds as well. Whoever provisions a VM should
-make sure to generate a new inventory as well as perform the first Ansible
-run against the new node so that other CouchDB infra members will have access.
+The basic steps to provisioning a new Jenkins agent node are:
+1. Provision new VM using https://cloud.ibm.com
+2. Run `./tools/gen-config`
+3. Create the agent in Jenkins (copying an existing node is easiest)
+4. Encrypt the Jenkins secret using `ansible-vault`
+5. Store the new secret in the appropriate `host_vars/hostname.yml` file
+6. Run `ansible-playbook ci_agents.yml`
+
+Node names should follow this pattern:
+
+```
+couchdb-worker-$arch-$osname-$zone-$node_id
+```
+
+I.e.:
+
+```
+couchdb-worker-x86-64-debian-dal-1-01
+```
Bastion VMs
---
@@ -26,13 +42,32 @@
cheapest cx2-2x4 instance for these nodes so that we can jump to the other
hosts.
-If the bastion changes public IP addresses we have to update `group_vars/ci_agents.yml`
-and set the `ansible_ssh_common_args` to use the new public IP for contacting
-servers. We should also update `ssh.cfg` in this repository to make it easier
-for contacting servers manually.
+Provisioning a bastion VM is much the same as for a ci_agent though should
+happen much more rarely. Currently the assumption is that each subnet has
+exactly one bastion. The `./tools/gen-config` script will complain if this
+assumption is violated so it should be obvious if we get this wrong. It will
+also complain if we have a subnet that is missing a bastion box.
+
+The steps for provisioning a new bastion box are:
+
+1. Provision the VM using https://cloud.ibm.com
+2. Run `./tools/gen-config`
+3. Run `ansible-playbook bastions.yml`
+
+Bastion names should follow this pattern:
+
+```
+couchdb-bastion-$arch-$osname-$zone-$node_id
+```
+
+I.e.,
+
+```
+couchdb-bastion-x86-64-debian-dal-1-01
+```
-Generating Inventory Listings
+Running `./tools/gen-config`
---
Create a `~/.couchdb-infra-cm.cfg` file that contains the following options:
@@ -40,26 +75,22 @@
[ibmcloud]
api_key = <REDACTED>
-The `tools/gen-inventory` script can then be used to generate our `production`
-inventory file:
+The `tools/gen-config` script can then be used to generate our `production`
+inventory and `ssh.cfg` configuration:
- $ ./tools/gen-inventory > production
+ $ ./tools/gen-config
-
-Configuring Jenkins
----
-
-Once a CI worker has been provisioned we must also configure Jenkins to have
-the JAR url and secret ready. The easiest approach here is to just copy the
-existing configuration from one of the existing nodes. When viewing the
-conifguration page we then dump the secret value into an encrypted vault
-file in the `host_vars` directory.
-
+This script requires access to the `https://cloud.ibm.com` account that hosts
+the VMs so not everyone will be able to run this script. However this is only
+important when provisioning new nodes. Modifying ansible scripts and apply
+changes to existing nodes can be done by any CouchDB PMC member that's been
+added to the CI nodes via this repository.
Running Ansible
---
- $ ansible-playbook -i production ci_agents.yml
+ $ ansible-playbook bastions.yml
+ $ ansible-playbook ci_agents.yml
Useful Commands:
@@ -68,5 +99,11 @@
If you want to ssh directly to a node, you can do:
```bash
-$ ssh -F ssh.cfg $private_ip
+$ ssh -F ssh.cfg $hostname
+```
+
+I.e.,
+
+```bash
+$ ssh -F ssh.cfg couchdb-worker-x86-64-debian-dal-1-01
```
