From 968949a23dd95f64bba75a9135fc424f682c888f Mon Sep 17 00:00:00 2001 From: Mark Goddard Date: Fri, 30 Jun 2017 16:08:16 +0100 Subject: [PATCH] Move administration tasks from the deployment guide to a new page --- doc/source/administration.rst | 90 +++++++++++++++++++++++++++++++++++ doc/source/deployment.rst | 86 --------------------------------- doc/source/index.rst | 1 + 3 files changed, 91 insertions(+), 86 deletions(-) create mode 100644 doc/source/administration.rst diff --git a/doc/source/administration.rst b/doc/source/administration.rst new file mode 100644 index 000000000..7e6327ac5 --- /dev/null +++ b/doc/source/administration.rst @@ -0,0 +1,90 @@ +============== +Administration +============== + +This section describes how to use kayobe to simplify post-deployment +administrative tasks. + +Reconfiguring Containerised Services +==================================== + +When configuration is changed, it is necessary to apply these changes across +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 + +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 +kolla-ansible's playbooks. This may require knowledge of the inner workings of +these tools but in general, kolla-ansible tags the play used to configure each +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 + +Upgrading Containerised Services +================================ + +Containerised control plane services may be upgraded by replacing existing +containers with new containers using updated images which have been pulled from +a registry or built locally. If using an updated version of Kayobe or +upgrading from one release of OpenStack to another, be sure to follow the +:ref:`kayobe upgrade guide `. It may be necessary to upgrade one +or more services within a release, for example to apply a patch or minor +release. + +To upgrade the containerised control plane services:: + + (kayobe-venv) $ 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 + +Deprovisioning The Cloud +======================== + +.. note:: + + This step will power down the overcloud hosts and delete their nodes' + instance state from the seed's ironic service. + +To deprovision the overcloud:: + + (kayobe-venv) $ kayobe overcloud deprovision + +Running Kayobe Playbooks on Demand +================================== + +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 [] + +Running Kolla-ansible Commands +============================== + +To execute a kolla-ansible command:: + + (kayobe-venv) $ kayobe kolla ansible run + +Dumping Kayobe Configuration +============================ + +The Ansible configuration space is quite large, and it can be hard to determine +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 + +The output is a JSON-formatted object mapping hosts to their hostvars. + +We can use the ``--var-name`` argument to inspect a particular variable or the +``--host`` or ``--hosts`` arguments to view a variable or variables for a +specific host or set of hosts. diff --git a/doc/source/deployment.rst b/doc/source/deployment.rst index cdae215f4..23da23321 100644 --- a/doc/source/deployment.rst +++ b/doc/source/deployment.rst @@ -294,89 +294,3 @@ This will perform the following tasks: - Register Ironic Python Agent (IPA) images with glance - Register introspection rules with ironic inspector - Register a provisioning network and subnet with neutron - -Reconfiguring Containerised Services ------------------------------------- - -When configuration is changed, it is necessary to apply these changes across -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 - -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 -kolla-ansible's playbooks. This may require knowledge of the inner workings of -these tools but in general, kolla-ansible tags the play used to configure each -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 - -Upgrading Containerised Services --------------------------------- - -Containerised control plane services may be upgraded by replacing existing -containers with new containers using updated images which have been pulled from -a registry or built locally. If using an updated version of Kayobe, it should -be upgraded before upgrading the overcloud services. If Kayobe has been -upgraded, ensure that any required configuration changes have been performed as -described in the release notes. - -To upgrade the containerised control plane services:: - - (kayobe-venv) $ 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 - -Other Useful Commands -===================== - -Deprovisioning --------------- - -.. note:: - - This step will power down the overcloud hosts and delete their nodes' - instance state from the seed's ironic service. - -To deprovision the overcloud:: - - (kayobe-venv) $ kayobe overcloud deprovision - -Running Kayobe Playbooks on Demand ----------------------------------- - -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 [] - -Running Kolla-ansible Commands ------------------------------- - -To execute a kolla-ansible command:: - - (kayobe-venv) $ kayobe kolla ansible run - -Dumping Kayobe Configuration ----------------------------- - -The Ansible configuration space is quite large, and it can be hard to determine -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 - -The output is a JSON-formatted object mapping hosts to their hostvars. - -We can use the ``--var-name`` argument to inspect a particular variable or the -``--host`` or ``--hosts`` arguments to view a variable or variables for a -specific host or set of hosts. diff --git a/doc/source/index.rst b/doc/source/index.rst index 4da59d48f..a4de3e817 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -26,6 +26,7 @@ Documentation configuration deployment upgrading + administration Developer Documentation -----------------------