From 454de62d6dbfd0b08c1accbd7d1ca069b7cae6b0 Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Wed, 20 Sep 2017 17:54:26 +0100
Subject: [PATCH] Update documentation for new control host directory layout
---
doc/source/administration.rst | 24 +++++++-------
doc/source/configuration/kayobe.rst | 2 ++
doc/source/deployment.rst | 50 ++++++++++++++---------------
doc/source/installation.rst | 40 +++++++++++++++++++----
doc/source/upgrading.rst | 24 +++++++-------
doc/source/usage.rst | 12 +++----
6 files changed, 90 insertions(+), 62 deletions(-)
diff --git a/doc/source/administration.rst b/doc/source/administration.rst
index 52ce834d..a896a764 100644
--- a/doc/source/administration.rst
+++ b/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.
diff --git a/doc/source/configuration/kayobe.rst b/doc/source/configuration/kayobe.rst
index ece70f1c..5466fa1b 100644
--- a/doc/source/configuration/kayobe.rst
+++ b/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
==================
diff --git a/doc/source/deployment.rst b/doc/source/deployment.rst
index b0235a81..363ffaa2 100644
--- a/doc/source/deployment.rst
+++ b/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:
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 78a86175..b09681b0 100644
--- a/doc/source/installation.rst
+++ b/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.
diff --git a/doc/source/upgrading.rst b/doc/source/upgrading.rst
index ed76642d..84ee26f5 100644
--- a/doc/source/upgrading.rst
+++ b/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
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 764b4f68..45912d75 100644
--- a/doc/source/usage.rst
+++ b/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
--------------------------
--
GitLab