Improve functionality and docs around ansible installation

This adds the ability to specify a different ansible install path when
running zuul-manage-ansible. Venv location list is also reversed so that
we prefer the venvs at the user specified location if present.

Finally docs are updated to more clearly specify there are two options
for managing ansible installations and why you should prefer
zuul-manage-ansible.

Change-Id: If84a92bc542e24eedac09f3dc9fd2954db43734c

doc/source/admin/installation.rst

@@ -22,6 +22,7 @@ directory.
 
 It is further required to run ``zuul-manage-ansible`` on the zuul-executor
 in order to install all supported ansible versions so zuul can use them.
+See :ref:`ansible-installation-options` for details.
 
 Zuul Components
 ---------------
@@ -97,17 +98,29 @@ components, and also to communicate with Zuul.  You can run a simple
 single-node ZooKeeper instance, or a multi-node cluster.  Ensure that
 the host running the Zuul scheduler has access to the cluster.
 
+.. _ansible-installation-options:
+
 Ansible
 ~~~~~~~
 
-Zuul uses Ansible to run jobs.  Each version of Zuul is designed to
-work with a specific, contemporary versions of Ansible. Zuul manages
-its Ansible installations using ``zuul-manage-ansible``. It is
-recommended to run ``zuul-manage-ansible`` before starting the zuul-executor
-the first time.
+There are two approaches that can be used to install Ansible for Zuul.
+
+First you may set ``manage_ansible`` to True in the executor config. If you
+do this Zuul will install all supported Ansible versions on zuul-executor
+startup. These installations end up in Zuul's state dir,
+``/var/lib/zuul/ansible-bin`` if unchanged.
+
+The second option is to use ``zuul-manage-ansible`` to install the supported
+Ansible versions. By default this will install Ansible to
+``zuul_install_prefix/lib/zuul/ansible``. This method is preferable to the
+first because it speeds up zuul-executor start time and allows you to
+preinstall ansible in containers (avoids problems with bind mounted zuul
+state dirs).
 
 .. program-output:: zuul-manage-ansible -h
 
+In both cases if using a non default path you will want to set
+``ansible_root`` in the executor config file.
 
 Zuul Setup
 ----------

zuul/cmd/manage_ansible.py

@@ -52,6 +52,8 @@ class ManageAnsible(zuul.cmd.ZuulApp):
                             help='upgrade ansible versions')
         parser.add_argument('-l', dest='list_supported', action='store_true',
                             help='list supported versions')
+        parser.add_argument('-r', dest='install_root', default=None,
+                            help='root path for ansible venv installations')
         return parser
 
     def _setup_logging(self):
@@ -71,7 +73,7 @@ class ManageAnsible(zuul.cmd.ZuulApp):
             pass
         self._setup_logging()
 
-        manager = AnsibleManager()
+        manager = AnsibleManager(runtime_install_root=self.args.install_root)
 
         if self.args.list_supported:
             versions = []

zuul/executor/server.py

@@ -2403,9 +2403,13 @@ class ExecutorServer(object):
         ansible_install_root = get_default(
             self.config, 'executor', 'ansible_root', None)
         if not ansible_install_root:
+            # NOTE: Even though we set this value the zuul installation
+            # adjacent virtualenv location is still checked by the ansible
+            # manager. ansible_install_root's value is only used if those
+            # default locations do not have venvs preinstalled.
             ansible_install_root = os.path.join(state_dir, 'ansible-bin')
         self.ansible_manager = self._ansible_manager_class(
-            ansible_dir, runtime_install_path=ansible_install_root)
+            ansible_dir, runtime_install_root=ansible_install_root)
         if not self.ansible_manager.validate():
             if not manage_ansible:
                 raise Exception('Error while validating ansible '

zuul/lib/ansible.py

@@ -105,7 +105,8 @@ class ManagedAnsible:
 
     @property
     def venv_path(self):
-        for root in self._ansible_roots:
+        for root in reversed(self._ansible_roots):
+            # Check user configured paths first
             venv_path = os.path.join(root, self.version)
             if os.path.exists(venv_path):
                 return venv_path
@@ -147,11 +148,11 @@ class AnsibleManager:
     log = logging.getLogger('zuul.ansible_manager')
 
     def __init__(self, zuul_ansible_dir=None, default_version=None,
-                 runtime_install_path=None):
+                 runtime_install_root=None):
         self._supported_versions = {}
         self.default_version = None
         self.zuul_ansible_dir = zuul_ansible_dir
-        self.runtime_install_root = runtime_install_path
+        self.runtime_install_root = runtime_install_root
 
         self.load_ansible_config()