Document and update fileserver roles

The add-fileserver role needs to be used by a job in a config repo as it
performs local actions such as adding a host to the inventory and needs to
be run on localhost.

publish-artifacts-to-fileserver doesn't have any special requirements, but
it's fairly useless without the first role.

Change-Id: I0e37ee297b13dceb70300a4f8f4accc233254df3

roles/add-fileserver/README.rst

@@ -0,0 +1,34 @@
+Add a remote fileserver to the inventory so that content can be uploaded
+in subsequent tasks or roles.
+
+**Role Variables**
+
+.. zuul:rolevar:: fileserver
+
+  Complex argument which contains the information about the remote
+  destination as well as the authentication information needed. It is
+  expected that this argument comes from a `Secret`.
+
+  .. zuul:rolevar:: fqdn
+
+    The FQDN of the remote host.
+
+  .. zuul:rolevar:: path
+
+    The remote path. Content will be put into a directory below this path
+    that matches ``zuul.project.short_name``. The full path including
+    the project short name will be added to the hostvars of the host
+    as ``zuul_fileserver_project_path``.
+
+  .. zuul:rolevar:: ssh_known_hosts
+
+    String containing known host signature for the remote host.
+
+  .. zuul:rolevar:: ssh_private_key
+
+    Contents of the ssh private key to use.
+
+  .. zuul:rolevar:: ssh_username
+     :default: ansible_user
+
+    Remote ssh user name to use.

roles/add-fileserver/tasks/main.yaml

@@ -1,21 +1,22 @@
 - name: Create SSH private key from secret
   copy:
     content: "{{ fileserver.ssh_private_key }}"
-    dest: ~/.ssh/tarballs_id_rsa
+    dest: ~/.ssh/fileserver_id_rsa
     mode: 0600
 
-- name: Add tarballs server ssh key
-  command: ssh-add ~/.ssh/tarballs_id_rsa
+- name: Add fileserver ssh key
+  command: ssh-add ~/.ssh/fileserver_id_rsa
 
 - name: Remove SSH private key from disk
-  command: shred ~/.ssh/tarballs_id_rsa
+  command: shred ~/.ssh/fileserver_id_rsa
 
-- name: Add tarballs server to inventory
+- name: Add fileserver to inventory
   add_host:
     name: "{{ fileserver.fqdn }}"
-    ansible_user: "{{ fileserver.ssh_username }}"
+    ansible_user: "{{ fileserver.ssh_username|default(ansible_user) }}"
+    zuul_fileserver_project_path: "{{ fileserver.path }}/{{ zuul.project.short_name }}"
 
-- name: Add tarballs server to known hosts
+- name: Add fileserver server to known hosts
   known_hosts:
     name: "{{ fileserver.fqdn }}"
     key: "{{ fileserver.ssh_known_hosts }}"

roles/publish-artifacts-to-fileserver/README.rst

@@ -0,0 +1,15 @@
+Publish contents of ``{{ zuul.executor.work_root }}/artifacts/`` dir using
+rsync over ssh to a remote fileserver that has previously been added to
+the inventory by :zuul:role:`add-fileserver`.
+
+**Role Variables**
+
+:zuul:role:`add-fileserver` sets the following variable in the hostvars of the
+hosts it adds, but it is documented for reference.
+
+.. zuul:rolevar:: zuul_fileserver_project_path
+
+  The remote path. Content will be put into a directory below this path
+  that matches ``zuul.project.short_name``. The full path including
+  the project short name will be added to the hostvars of the host
+  as ``zuul_fileserver_project_path``.

roles/publish-artifacts-to-fileserver/tasks/main.yaml

@@ -1,10 +1,6 @@
-- name: Set tarball path
-  set_fact:
-    tarball_path: "{{ fileserver.path }}/{{ zuul.project.short_name }}"
-
-- name: Ensure project directory exists
+- name: Ensure project artifact directory exists
   file:
-    path: "{{ tarball_path }}"
+    path: "{{ zuul_fileserver_project_path }}"
     state: directory
     recurse: yes
     mode: 0775
@@ -12,4 +8,4 @@
 - name: Upload contents of the artifacts folder
   synchronize:
     src: "{{ zuul.executor.work_root }}/artifacts/"
-    dest: "{{ tarball_path }}/"
+    dest: "{{ zuul_fileserver_project_path }}/"