docs: restructure machines.md
Change-Id: I9f35574e193605952b98d7995adfe1540c4291d7
diff --git a/docs/machines.md b/docs/machines.md
index 9890b54..035cd27 100644
--- a/docs/machines.md
+++ b/docs/machines.md
@@ -1,61 +1,85 @@
-# Handling machines
+# CI machines
-# Quick description of the architecture
+This document describes the architecture and administration of the Bazel CI
+(Continuous Integration) machines.
-Bazel's CI use Jenkins in a docker container to run the various test jobs.
-The Jenkins controller distribute this work on various nodes:
+## Architecture
-* Virtual machines on GCE (Linux and Windows nodes)
-* Docker container (the deploy node which is used for deploying
- release and the website)
-* Physical machines (mac nodes)
+Bazel's CI uses Jenkins.
-The docker containers are run on the jenkins controller virtual machine, the Jenkins
-controller runs in a docker container itself. They are administered through the
-`gce/jenkins.yml` and `gce/jenkins-staging.yml` files (a Google Container
-Engine pod configuration).
+The Jenkins controller runs in a Docker container on a virtual machine (VM).
-The virtual machines are administered through the `gce/vm.sh` script.
+The Jenkins controller distributes the work to various nodes:
-## Virtual machines admininstration
+* VMs on GCE (e.g. Linux and Windows nodes)
+* Physical machines (e.g Mac nodes)
+* Docker containers (e.g. the deploy node that deploys Bazel releases and the
+ Bazel homepage)
-Commands from the `gce/vm.sh` script can be applied to all machines,
-individual machines or all machines from `staging` or `prod`:
+ The Docker containers run on the Jenkins controller's VM.
-* `create` and `delete`: create a machine (unless it already exists) or delete it.
-* `reimage`: `delete` a machine, then `create` it again.
-* `start` and `stop`: start or stop the specified VMs, classically used to shut down the
- staging instance.
-* `update_metadata`: update the metadata for the VM. It is the data
- that we pass to the `--metadata` flags when we do `gcloud
- instances create` which includes the startup scripts and
- the pod configuration for the docker containers.
+## Administration
-This script needs access to `gcloud` and assumes your default GCE project is pointing to the
-CI project. You can install `gcloud` from https://cloud.google.com/sdk/ and set it
-up so the default project is "bazel-public".
+* VMs: through the `//gce/vm.sh` script
+* Physical machines: physically or through Chrome Remote Desktop
+* Docker containers: through the `//gce/jenkins.yml` and
+ `//gce/jenkins-staging.yml` files (Google Container Engine pod
+ configurations)
+
+### Virtual machines admininstration
+
+You can administer the VMs using the `//gce/vm.sh` script.
+
+You can apply the script's changes to:
+
+* individual machines, or
+* all machines, or
+* all machines from `staging` or `prod` instance
+
+`//gce/vm.sh` script commands:
+
+* `create` and `delete`: create a machine (unless it already exists) or delete
+ it
+* `reimage`: `delete` a machine, then `create` it again
+* `start` and `stop`: start or stop the specified machine(s).
+
+ We typically use this to shut down the staging instance.
+
+* `update_metadata`: update the metadata for the VM
+
+ The metadata is what we pass to the `--metadata` flags when we run `gcloud
+ instances create` commands. The metadata includes the startup scripts and
+ the pod configuration for the Docker containers.
+
+The `//gce/vm.sh` script runs `gcloud` and assumes your default GCE project
+is the Bazel CI project.
+
+You can install `gcloud` from https://cloud.google.com/sdk/
+
+To set the default `gcloud` project to "bazel-public", run:
```
-$ gcloud config set project bazel-public
-$ gcloud auth login
+gcloud config set project bazel-public
+gcloud auth login
```
-## Physical machines administration
+### Physical machines administration
-The physical machines needs to be in a network allowed for port 50000, see the list of IP
-ranges provided to the [`init.sh`](init.md) script.
+The physical machines need to be on a network allowed for port 50000. See the
+list of IP ranges provided to the [`init.sh`](init.md) script.
-They need to have installed a service that talks to the Jenkins controller. The only kind of
-physical nodes we currently use are Mac nodes. For licensing reasons, those nodes
-have to be set up manually.
+The physical manually need to have a service installed that talks to the Jenkins
+controller. The only kind of physical nodes we use are Mac nodes and we need to
+set them up manually (for licensing reasons).
-### Setting up a Mac executor node
+To set up a Mac executor node:
-1. Install [Xcode](https://developer.apple.com/xcode/downloads/)
- and [JDK 8](https://jdk8.java.net/download.html)
-2. Create a "ci" user with "sudo" right, download the
- `mac/setup_mac.sh` script, and run it as that user:
-```
-$ curl -o setup_mac.sh "https://raw.githubusercontent.com/bazelbuild/continuous-integration/master/mac/setup_mac.sh"
-$ sudo su ci -c "/bin/bash setup_mac.sh <node_name>"
-```
+1. install [Xcode](https://developer.apple.com/xcode/downloads/)
+2. install [JDK 8](https://jdk8.java.net/download.html)
+3. create a "ci" user with "sudo" rights
+4. download the `mac/setup_mac.sh` script and run it as the "ci" user:
+
+ ```
+ curl -o setup_mac.sh "https://raw.githubusercontent.com/bazelbuild/continuous-integration/master/mac/setup_mac.sh"
+ sudo su ci -c "/bin/bash setup_mac.sh <node_name>"
+ ```
