role: Inject public keys in case of failure

Add a role that injects given public keys on a build's node set
if the build fails. This is intended to be used with zuul's
`autohold` command so that privileged users can SSH into the node set
without having to use Zuul's ansible user's private key.

Change-Id: I963e82f32a99cacea663792049cb39453e776ece

roles/add-authorized-keys/README.rst

@@ -0,0 +1,36 @@
+Install SSH public key(s) on all hosts
+
+This role is intended to be run at the end of a failed job for which the build
+node set will be held with zuul's `autohold` command.
+
+It copies the public key(s) into the authorized_keys file of every host in the
+inventory, allowing privileged users to access the node set for debugging or
+post-mortem analysis.
+
+Add this stanza at the end of your project's base post playbook to activate this
+functionality:
+
+.. code-block:: yaml
+
+   - hosts: all
+     roles:
+       - role: add-authorized-keys
+         public_keys:
+           - public_key: ssh-rsa AAAAB... venkman@parapsy.columbia.edu
+           - public_key: ssh-rsa AAAAB... spengler@parapsy.columbia.edu
+         when: not zuul_success | bool
+
+.. caution::
+   Including this role earlier in any playbook may allow the keys' owners to
+   tamper with the execution of the jobs. It is strongly advised against doing
+   so.
+
+**Role Variables**
+
+.. zuul:rolevar:: ssh_public_keys
+
+  A list of keys to inject.
+
+  .. zuul:rolevar:: public_key
+
+    A public key to inject into authorized_keys, or a URL to a public key.

roles/add-authorized-keys/tasks/main.yaml

@@ -0,0 +1,7 @@
+- name: Enable access via build key on all nodes
+  authorized_key:
+    user: "{{ ansible_ssh_user }}"
+    state: present
+    key: "{{ item.public_key }}"
+  with_items:
+    - "{{ public_keys }}"