From 454de62d6dbfd0b08c1accbd7d1ca069b7cae6b0 Mon Sep 17 00:00:00 2001 From: Mark Goddard 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 52ce834dc..a896a764c 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 ``/ansible/*.yml``. To run an arbitrary Kayobe playbook:: - (kayobe-venv) $ kayobe playbook run [] + (kayobe) $ kayobe playbook run [] Running Kolla-ansible Commands ============================== To execute a kolla-ansible command:: - (kayobe-venv) $ kayobe kolla ansible run + (kayobe) $ kayobe kolla ansible run 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 ece70f1c4..5466fa1b8 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 b0235a817..363ffaa2b 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 [--enable-discovery] + (kayobe) $ kayobe physical network configure --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 `_ 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 78a861757..b09681b02 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 ```` is the path to a top +level directory:: + + / + 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 + $ mkdir -p src venvs + +Next, obtain the Kayobe source code. For example:: + + $ cd /src $ git clone https://github.com/stackhpc/kayobe Create a virtualenv for Kayobe:: - $ cd kayobe - $ virtualenv kayobe-venv + $ virtualenv /venvs/kayobe Activate the virtualenv and update pip:: - $ source kayobe-venv/bin/activate - (kayobe-venv) $ pip install -U pip + $ source /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 /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`_. 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 ed76642d1..84ee26f52 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 `_ 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 764b4f686..45912d751 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 --------------------------