add Cumin instructions

tsa/howto/puppet.mdwn

@@ -26,7 +26,9 @@ The currently known values are: `kvm`, `physical`, and `xenu`.
 
         curl -s -G http://localhost:8080/pdb/query/v4/facts  | jq -r ".[].certname"
 
- * Using [Cumin](https://doc.wikimedia.org/cumin/master/introduction.html)
+ * Using [Cumin][], see below
+
+[Cumin]: https://doc.wikimedia.org/cumin/master/introduction.html
 
  * Using LDAP:
  
@@ -58,3 +60,48 @@ To run batch commands through sudo that requires a password, you will need to fo
 
 You should then type your password then Control-d. Warning: this will
 show your password on your terminal and probably in the logs as well. 
+
+## Using Cumin
+
+You can also use [Cumin][] to operate arbitrary shell commands on
+Puppet hosts or a subset of hosts. First, install Cumin and setup a
+tunnel to connect to the Puppet locally:
+
+    virtualenv --python=python3 ~/.venv/cumin
+    ~/.venv/cumin/bin/pip3 install cumin
+    ssh -L8080:localhost:8080 pauli.torproject.org
+
+Notice how Cumin is installed in a [Python virtualenv](https://virtualenv.pypa.io/): it is not
+yet [in Debian](https://bugs.debian.org/924685). You'll also need a patch to enable plain HTTP
+access, see [this bug report](https://phabricator.wikimedia.org/T218441). You might also want to disable the
+[root check](https://phabricator.wikimedia.org/T218440) as well. Then drop the following configuration in
+`~/.config/cumin/config.yaml`:
+
+    transport: clustershell
+    puppetdb:
+        host: localhost
+        scheme: http
+        port: 8080
+        api_version: 4  # Supported versions are v3 and v4. If not specified, v4 will be used.
+    log_file: cumin.log
+    default_backend: puppetdb
+
+From here on we'll assume you use the following alias:
+
+    alias cumin="~/.venv/cumin/bin/cumin --config ~/.config/cumin/config.yaml"
+
+This will run the `uptime` command on all hosts:
+
+    cumin '*' uptime
+
+To run against only a subset, you need to use the Cumin grammar, which
+is [briefly described in the Wikimedia docs](https://wikitech.wikimedia.org/wiki/Cumin#PuppetDB_host_selection). For example, this
+will run the same command only on physical hosts:
+
+    cumin 'F:virtual=physical' uptime
+
+Just check the monitoring server:
+
+    cumin 'R:class=roles::monitoring' uptime
+
+Any Puppet fact or class can be queried that way.