Update documentation for new control host directory layout

doc/source/administration.rst

@@ -13,7 +13,7 @@ the system in an automated manner.  To reconfigure the overcloud, first make
 any changes required to the configuration on the control host.  Next, run the
 following command::
 
-    (kayobe-venv) $ kayobe overcloud service reconfigure
+    (kayobe) $ kayobe overcloud service reconfigure
 
 In case not all services' configuration have been modified, performance can be
 improved by specifying Ansible tags to limit the tasks run in kayobe and/or
@@ -23,7 +23,7 @@ service by the name of that service.  For example: ``nova``, ``neutron`` or
 ``ironic``.  Use ``-t`` or ``--tags`` to specify kayobe tags and ``-kt`` or
 ``--kolla-tags`` to specify kolla-ansible tags.  For example::
 
-    (kayobe-venv) $ kayobe overcloud service reconfigure --tags config --kolla-tags nova,ironic
+    (kayobe) $ kayobe overcloud service reconfigure --tags config --kolla-tags nova,ironic
 
 Upgrading Containerised Services
 ================================
@@ -38,12 +38,12 @@ release.
 
 To upgrade the containerised control plane services::
 
-    (kayobe-venv) $ kayobe overcloud service upgrade
+    (kayobe) $ kayobe overcloud service upgrade
 
 As for the reconfiguration command, it is possible to specify tags for Kayobe
 and/or kolla-ansible::
 
-    (kayobe-venv) $ kayobe overcloud service upgrade --tags config --kolla-tags keystone
+    (kayobe) $ kayobe overcloud service upgrade --tags config --kolla-tags keystone
 
 Destroying the Overcloud Services
 =================================
@@ -55,7 +55,7 @@ Destroying the Overcloud Services
 
 To destroy the overcloud services::
 
-    (kayobe-venv) $ kayobe overcloud service destroy --yes-i-really-really-mean-it
+    (kayobe) $ kayobe overcloud service destroy --yes-i-really-really-mean-it
 
 Deprovisioning The Cloud
 ========================
@@ -67,7 +67,7 @@ Deprovisioning The Cloud
 
 To deprovision the overcloud::
 
-    (kayobe-venv) $ kayobe overcloud deprovision
+    (kayobe) $ kayobe overcloud deprovision
 
 Deprovisioning The Seed VM
 ==========================
@@ -78,7 +78,7 @@ Deprovisioning The Seed VM
 
 To deprovision the seed VM::
 
-    (kayobe-venv) $ kayobe seed vm deprovision
+    (kayobe) $ kayobe seed vm deprovision
 
 Saving Overcloud Service Configuration
 ======================================
@@ -88,7 +88,7 @@ plane services for inspection or comparison with another configuration set
 prior to a reconfiguration or upgrade. This command will gather and save the
 control plane configuration for all hosts to the ansible control host::
 
-    (kayobe-venv) $ kayobe overcloud service configuration save
+    (kayobe) $ kayobe overcloud service configuration save
 
 The default location for the saved configuration is ``$PWD/overcloud-config``,
 but this can be changed via the ``output-dir`` argument. To gather
@@ -104,7 +104,7 @@ applying it to the running containers. The configuration should typically be
 generated in a directory other than the default configuration directory of
 ``/etc/kolla``, to avoid overwriting the active configuration::
 
-    (kayobe-venv) $ kayobe overcloud service configuration generate --node-config-dir /path/to/generated/config
+    (kayobe) $ kayobe overcloud service configuration generate --node-config-dir /path/to/generated/config
 
 The configuration will be generated remotely on the overcloud hosts in the
 specified directory, with one subdirectory per container. This command may be
@@ -118,14 +118,14 @@ In some situations it may be necessary to run an individual Kayobe playbook.
 Playbooks are stored in ``<kayobe repo>/ansible/*.yml``.  To run an arbitrary
 Kayobe playbook::
 
-    (kayobe-venv) $ kayobe playbook run <playbook> [<playbook>]
+    (kayobe) $ kayobe playbook run <playbook> [<playbook>]
 
 Running Kolla-ansible Commands
 ==============================
 
 To execute a kolla-ansible command::
 
-    (kayobe-venv) $ kayobe kolla ansible run <command>
+    (kayobe) $ kayobe kolla ansible run <command>
 
 Dumping Kayobe Configuration
 ============================
@@ -135,7 +135,7 @@ the final values of Ansible variables.  We can use Kayobe's
 ``configuration dump`` command to view individual variables or the variables
 for one or more hosts.  To dump Kayobe configuration for one or more hosts::
 
-    (kayobe-venv) $ kayobe configuration dump
+    (kayobe) $ kayobe configuration dump
 
 The output is a JSON-formatted object mapping hosts to their hostvars.
 

doc/source/configuration/kayobe.rst

@@ -57,6 +57,8 @@ variables files in ``${KAYOBE_CONFIG_PATH}/inventory/host_vars/*``.  It should
 be noted that variables set in extra-vars files take precedence over per-host
 variables.
 
+.. _configuring-kayobe:
+
 Configuring Kayobe
 ==================
 

doc/source/deployment.rst

@@ -21,7 +21,7 @@ performed here include:
 
 To bootstrap the Ansible control host::
 
-    (kayobe-venv) $ kayobe control host bootstrap
+    (kayobe) $ kayobe control host bootstrap
 
 Physical Network
 ================
@@ -31,7 +31,7 @@ modules.  Currently Dell Network OS 6 and Dell Network OS 9 switches are
 supported but this could easily be extended.  To provision the physical
 network::
 
-    (kayobe-venv) $ kayobe physical network configure --group <group> [--enable-discovery]
+    (kayobe) $ kayobe physical network configure --group <group> [--enable-discovery]
 
 The ``--group`` argument is used to specify an Ansible group containing
 the switches to be configured.
@@ -55,7 +55,7 @@ Host Configuration
 To configure the seed hypervisor's host OS, and the Libvirt/KVM virtualisation
 support::
 
-    (kayobe-venv) $ kayobe seed hypervisor host configure
+    (kayobe) $ kayobe seed hypervisor host configure
 
 Seed
 ====
@@ -74,7 +74,7 @@ have ``libvirt`` networks configured for all networks that the seed VM needs
 access to and a ``libvirt`` storage pool available for the seed VM's volumes.
 To provision the seed VM::
 
-    (kayobe-venv) $ kayobe seed vm provision
+    (kayobe) $ kayobe seed vm provision
 
 When this command has completed the seed VM should be active and accessible via
 SSH.  Kayobe will update the Ansible inventory with the IP address of the VM.
@@ -84,7 +84,7 @@ Host Configuration
 
 To configure the seed host OS::
 
-    (kayobe-venv) $ kayobe seed host configure
+    (kayobe) $ kayobe seed host configure
 
 .. note::
 
@@ -92,7 +92,7 @@ To configure the seed host OS::
    installation, it may be necessary to wipe partition and LVM data from those
    disks.  To wipe all disks that are not mounted during host configuration::
 
-       (kayobe-venv) $ kayobe seed host configure --wipe-disks
+       (kayobe) $ kayobe seed host configure --wipe-disks
 
 Building Container Images
 -------------------------
@@ -107,12 +107,12 @@ Dockerhub.  In some cases it may be necessary to build images locally either to
 apply local image customisation or to use a downstream version of kolla.  To
 build images locally::
 
-    (kayobe-venv) $ kayobe seed container image build
+    (kayobe) $ kayobe seed container image build
 
 It is possible to build a specific set of images by supplying one or more
 image name regular expressions::
 
-    (kayobe-venv) $ kayobe seed container image build bifrost-deploy
+    (kayobe) $ kayobe seed container image build bifrost-deploy
 
 In order to push images to a registry after they are built, add the ``--push``
 argument.
@@ -127,7 +127,7 @@ nodes using Disk Image Builder (DIB).
 
 To deploy the seed services in containers::
 
-    (kayobe-venv) $ kayobe seed service deploy
+    (kayobe) $ kayobe seed service deploy
 
 After this command has completed the seed services will be active.
 
@@ -146,7 +146,7 @@ apply local image customisation or to use a downstream version of Ironic Python
 Agent (IPA).  In order to build IPA images, the ``ipa_build_images`` variable
 should be set to ``True``.  To build images locally::
 
-    (kayobe-venv) $ kayobe seed deployment image build
+    (kayobe) $ kayobe seed deployment image build
 
 Accessing the Seed via SSH (Optional)
 -------------------------------------
@@ -155,7 +155,7 @@ For SSH access to the seed, first determine the seed's IP address. We can
 use the ``kayobe configuration dump`` command to inspect the seed's IP
 address::
 
-    (kayobe-venv) $ kayobe configuration dump --host seed --var-name ansible_host
+    (kayobe) $ kayobe configuration dump --host seed --var-name ansible_host
 
 The ``kayobe_ansible_user`` variable determines which user account will be used
 by Kayobe when accessing the machine via SSH.  By default this is ``stack``.
@@ -205,7 +205,7 @@ the following on the seed::
 In order to interact with these nodes using Kayobe, run the following command
 to add them to the Kayobe and bifrost Ansible inventories::
 
-    (kayobe-venv) $ kayobe overcloud inventory discover
+    (kayobe) $ kayobe overcloud inventory discover
 
 Saving Hardware Introspection Data
 ----------------------------------
@@ -214,7 +214,7 @@ If ironic inspector is in use on the seed host, introspection data will be
 stored in the local nginx service.  This data may be saved to the control
 host::
 
-    (kayobe-venv) $ kayobe overcloud introspection data save
+    (kayobe) $ kayobe overcloud introspection data save
 
 ``--output-dir`` may be used to specify the directory in which introspection
 data files will be saved. ``--output-format`` may be used to set the format of
@@ -232,13 +232,13 @@ Configuration of BIOS settings and RAID volumes is currently performed out of
 band as a separate task from hardware provisioning.  To configure the BIOS and
 RAID::
 
-    (kayobe-venv) $ kayobe overcloud bios raid configure
+    (kayobe) $ kayobe overcloud bios raid configure
 
 After configuring the nodes' RAID volumes it may be necessary to perform
 hardware inspection of the nodes to reconfigure the ironic nodes' scheduling
 properties and root device hints.  To perform manual hardware inspection::
 
-    (kayobe-venv) $ kayobe overcloud hardware inspect
+    (kayobe) $ kayobe overcloud hardware inspect
 
 Provisioning
 ------------
@@ -246,7 +246,7 @@ Provisioning
 Provisioning of the overcloud is performed by the ironic service running in the
 bifrost container on the seed.  To provision the overcloud nodes::
 
-    (kayobe-venv) $ kayobe overcloud provision
+    (kayobe) $ kayobe overcloud provision
 
 After this command has completed the overcloud nodes should have been
 provisioned with an OS image.  The command will wait for the nodes to become
@@ -257,7 +257,7 @@ Host Configuration
 
 To configure the overcloud hosts' OS::
 
-    (kayobe-venv) $ kayobe overcloud host configure
+    (kayobe) $ kayobe overcloud host configure
 
 .. note::
 
@@ -265,7 +265,7 @@ To configure the overcloud hosts' OS::
    installation, it may be necessary to wipe partition and LVM data from those
    disks.  To wipe all disks that are not mounted during host configuration::
 
-       (kayobe-venv) $ kayobe overcloud host configure --wipe-disks
+       (kayobe) $ kayobe overcloud host configure --wipe-disks
 
 Building Container Images
 -------------------------
@@ -279,12 +279,12 @@ In some cases it may be necessary to build images locally either to apply local
 image customisation or to use a downstream version of kolla.  To build images
 locally::
 
-    (kayobe-venv) $ kayobe overcloud container image build
+    (kayobe) $ kayobe overcloud container image build
 
 It is possible to build a specific set of images by supplying one or more
 image name regular expressions::
 
-    (kayobe-venv) $ kayobe overcloud container image build ironic- nova-api
+    (kayobe) $ kayobe overcloud container image build ironic- nova-api
 
 In order to push images to a registry after they are built, add the ``--push``
 argument.
@@ -302,7 +302,7 @@ The `stackhpc account <https://hub.docker.com/r/stackhpc/>`_ provides image
 repositories suitable for use with kayobe and will be used by default.  To
 pull images from the configured image registry::
 
-    (kayobe-venv) $ kayobe overcloud container image pull
+    (kayobe) $ kayobe overcloud container image pull
 
 Building Deployment Images
 --------------------------
@@ -319,14 +319,14 @@ apply local image customisation or to use a downstream version of Ironic Python
 Agent (IPA).  In order to build IPA images, the ``ipa_build_images`` variable
 should be set to ``True``.  To build images locally::
 
-    (kayobe-venv) $ kayobe overcloud deployment image build
+    (kayobe) $ kayobe overcloud deployment image build
 
 Deploying Containerised Services
 --------------------------------
 
 To deploy the overcloud services in containers::
 
-    (kayobe-venv) $ kayobe overcloud service deploy
+    (kayobe) $ kayobe overcloud service deploy
 
 Once this command has completed the overcloud nodes should have OpenStack
 services running in Docker containers.
@@ -350,8 +350,8 @@ Performing Post-deployment Configuration
 
 To perform post deployment configuration of the overcloud services::
 
-    (kayobe-venv) $ source ${KOLLA_CONFIG_PATH:-/etc/kolla}/admin-openrc.sh
-    (kayobe-venv) $ kayobe overcloud post configure
+    (kayobe) $ source ${KOLLA_CONFIG_PATH:-/etc/kolla}/admin-openrc.sh
+    (kayobe) $ kayobe overcloud post configure
 
 This will perform the following tasks:
 

doc/source/installation.rst

@@ -29,24 +29,50 @@ Installation
 ============
 
 This guide will describe how to install Kayobe from source in a virtualenv.
-First, obtain the Kayobe source code. For example::
 
+The directory structure for a kayobe control host environment is configurable,
+but the following is recommended, where ``<base_path>`` is the path to a top
+level directory::
+
+    <base_path>/
+        src/
+            kayobe/
+            kayobe-config/
+            kolla-ansible/
+        venvs/
+            kayobe/
+            kolla-ansible/
+
+First, change to the top level directory, and make the directories for source
+code repositories and python virtual environments::
+
+    $ cd <base_path>
+    $ mkdir -p src venvs
+
+Next, obtain the Kayobe source code. For example::
+
+    $ cd <base_path>/src
     $ git clone https://github.com/stackhpc/kayobe
 
 Create a virtualenv for Kayobe::
 
-    $ cd kayobe
-    $ virtualenv kayobe-venv
+    $ virtualenv <base_path>/venvs/kayobe
 
 Activate the virtualenv and update pip::
 
-    $ source kayobe-venv/bin/activate
-    (kayobe-venv) $ pip install -U pip
+    $ source <base_path>/venvs/kayobe/bin/activate
+    (kayobe) $ pip install -U pip
 
 Install Kayobe and its dependencies using the source code checkout::
 
-    (kayobe-venv) $ pip install .
+    (kayobe) $ cd <base_path>/src/kayobe
+    (kayobe) $ pip install .
 
 Finally, deactivate the virtualenv::
 
-    (kayobe-venv) $ deactivate
+    (kayobe) $ deactivate
+
+Creation of a ``kayobe-config`` source code repository will be covered in the
+:ref:`configuration guide<configuring-kayobe>`_. The kolla-ansible source code
+checkout and python virtual environment will be created automatically by
+kayobe.

doc/source/upgrading.rst

@@ -26,7 +26,7 @@ If local changes were made to kayobe, these should now be reapplied.
 
 The upgraded kayobe python module and dependencies should be installed::
 
-    (kayobe-venv) $ pip install -U .
+    (kayobe) $ pip install -U .
 
 Migrating Kayobe Configuration
 ------------------------------
@@ -54,7 +54,7 @@ default values:
 Once the configuration has been migrated, it is possible to view the global
 variables for all hosts::
 
-    (kayobe-venv) $ kayobe configuration dump
+    (kayobe) $ kayobe configuration dump
 
 The output of this command is a JSON object mapping hosts to their
 configuration.  The output of the command may be restricted using the
@@ -78,7 +78,7 @@ performed here include:
 
 To upgrade the Ansible control host::
 
-    (kayobe-venv) $ kayobe control host upgrade
+    (kayobe) $ kayobe control host upgrade
 
 Upgrading the Seed
 ==================
@@ -99,7 +99,7 @@ Upgrading Host Services
 Prior to upgrading the OpenStack control plane, the overcloud host services
 should be upgraded::
 
-    (kayobe-venv) $ kayobe overcloud host upgrade
+    (kayobe) $ kayobe overcloud host upgrade
 
 Note that this will not perform full configuration of the host, and will
 instead perform a targeted upgrade of specific services where necessary.
@@ -119,7 +119,7 @@ apply local image customisation or to use a downstream version of Ironic Python
 Agent (IPA).  In order to build IPA images, the ``ipa_build_images`` variable
 should be set to ``True``.  To build images locally::
 
-    (kayobe-venv) $ kayobe overcloud deployment image build
+    (kayobe) $ kayobe overcloud deployment image build
 
 Upgrading Ironic Deployment Images
 ----------------------------------
@@ -140,12 +140,12 @@ In some cases it may be necessary to build images locally either to apply local
 image customisation or to use a downstream version of kolla.  To build images
 locally::
 
-    (kayobe-venv) $ kayobe overcloud container image build
+    (kayobe) $ kayobe overcloud container image build
 
 It is possible to build a specific set of images by supplying one or more
 image name regular expressions::
 
-    (kayobe-venv) $ kayobe overcloud container image build ironic- nova-api
+    (kayobe) $ kayobe overcloud container image build ironic- nova-api
 
 In order to push images to a registry after they are built, add the ``--push``
 argument.
@@ -163,7 +163,7 @@ The `stackhpc account <https://hub.docker.com/r/stackhpc/>`_ provides image
 repositories suitable for use with kayobe and will be used by default.  To
 pull images from the configured image registry::
 
-    (kayobe-venv) $ kayobe overcloud container image pull
+    (kayobe) $ kayobe overcloud container image pull
 
 Saving Overcloud Service Configuration
 --------------------------------------
@@ -173,7 +173,7 @@ plane services for inspection or comparison with another configuration set
 prior to a reconfiguration or upgrade. This command will gather and save the
 control plane configuration for all hosts to the ansible control host::
 
-    (kayobe-venv) $ kayobe overcloud service configuration save
+    (kayobe) $ kayobe overcloud service configuration save
 
 The default location for the saved configuration is ``$PWD/overcloud-config``,
 but this can be changed via the ``output-dir`` argument. To gather
@@ -189,7 +189,7 @@ applying it to the running containers. The configuration should typically be
 generated in a directory other than the default configuration directory of
 ``/etc/kolla``, to avoid overwriting the active configuration::
 
-    (kayobe-venv) $ kayobe overcloud service configuration generate --node-config-dir /path/to/generated/config
+    (kayobe) $ kayobe overcloud service configuration generate --node-config-dir /path/to/generated/config
 
 The configuration will be generated remotely on the overcloud hosts in the
 specified directory, with one subdirectory per container. This command may be
@@ -205,9 +205,9 @@ a registry or built locally.
 
 To upgrade the containerised control plane services::
 
-    (kayobe-venv) $ kayobe overcloud service upgrade
+    (kayobe) $ kayobe overcloud service upgrade
 
 It is possible to specify tags for Kayobe and/or kolla-ansible to restrict the
 scope of the upgrade::
 
-    (kayobe-venv) $ kayobe overcloud service upgrade --tags config --kolla-tags keystone
+    (kayobe) $ kayobe overcloud service upgrade --tags config --kolla-tags keystone

doc/source/usage.rst

@@ -7,26 +7,26 @@ Command Line Interface
 
 .. note::
 
-   Where a prompt starts with ``(kayobe-venv)`` it is implied that the user has
+   Where a prompt starts with ``(kayobe)`` it is implied that the user has
    activated the Kayobe virtualenv. This can be done as follows::
 
-       $ source kayobe-venv/bin/activate
+       $ source kayobe/bin/activate
 
    To deactivate the virtualenv::
 
-       (kayobe-venv) $ deactivate
+       (kayobe) $ deactivate
 
 To see information on how to use the ``kayobe`` CLI and the commands it
 provides::
 
-    (kayobe-venv) $ kayobe help
+    (kayobe) $ kayobe help
 
 As the ``kayobe`` CLI is based on the ``cliff`` package (as used by the
 ``openstack`` client), it supports tab auto-completion of subcommands.  This
 can be activated by generating and then sourcing the bash completion script::
 
-    (kayobe-venv) $ kayobe complete > kayobe-complete
-    (kayobe-venv) $ source kayobe-complete
+    (kayobe) $ kayobe complete > kayobe-complete
+    (kayobe) $ source kayobe-complete
 
 Working with Ansible Vault
 --------------------------