[couchdb-infra-cm] 01/02: Update README.md

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

davisp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb-infra-cm.git

commit c8f16a7d5296e5534036ebb82b74e32720670aef
Author: Paul J. Davis <pa...@gmail.com>
AuthorDate: Wed Jan 8 13:05:33 2020 -0600

    Update README.md
---
 README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 62 insertions(+), 25 deletions(-)

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 @@ Setup
 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,40 +42,55 @@ There should be a single bastion VM setup for each subnet. We just use the
 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:
 
-Generating Inventory Listings
----
+1. Provision the VM using https://cloud.ibm.com
+2. Run `./tools/gen-config`
+3. Run `ansible-playbook bastions.yml`
 
-Create a `~/.couchdb-infra-cm.cfg` file that contains the following options:
+Bastion names should follow this pattern:
 
-    [ibmcloud]
-    api_key = <REDACTED>
+```
+couchdb-bastion-$arch-$osname-$zone-$node_id
+```
 
-The `tools/gen-inventory` script can then be used to generate our `production`
-inventory file:
+I.e.,
 
-    $ ./tools/gen-inventory > production
+```
+couchdb-bastion-x86-64-debian-dal-1-01
+```
 
 
-Configuring Jenkins
+Running `./tools/gen-config`
 ---
 
-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.
+Create a `~/.couchdb-infra-cm.cfg` file that contains the following options:
+
+    [ibmcloud]
+    api_key = <REDACTED>
 
+The `tools/gen-config` script can then be used to generate our `production`
+inventory and `ssh.cfg` configuration:
+
+    $ ./tools/gen-config
+
+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 @@ Useful Commands:
 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
 ```