Reorganise administration guide into sections

The administration guide has become a bit bloated, and not well
organised. This change creates new subsections within it.

Change-Id: I8aa133c183fb6b7d87a86d5ab66cc7faa5e64112
Story: 2004337
Task: 28082

doc/source/administration/bare-metal.rst

+=================================
+Baremetal Compute Node Management
+=================================
+
+When enrolling new hardware or performing maintenance, it can be useful to be
+able to manage many bare metal compute nodes simultaneously.
+
+In all cases, commands are delegated to one of the controller hosts, and
+executed concurrently. Note that ansible's ``forks`` configuration option,
+which defaults to 5, may limit the number of nodes configured concurrently.
+
+By default these commands wait for the state transition to complete for each
+node. This behavior can be changed by overriding the variable
+``baremetal_compute_wait`` via ``-e baremetal_compute_wait=False``
+
+Manage
+------
+
+A node may need to be set to the ``manageable`` provision state in order to
+perform certain management operations, or when an enrolled node is
+transitioned into service. In order to manage a node, it must be in one of
+these states: ``enroll``, ``available``, ``cleaning``, ``clean failed``,
+``adopt failed`` or ``inspect failed``. To move the baremetal compute nodes
+to the ``manageable`` provision state::
+
+    (kayobe) $ kayobe baremetal compute manage
+
+Provide
+-------
+
+In order for nodes to be scheduled by nova, they must be ``available``. To
+move the baremetal compute nodes from the ``manageable`` state to the
+``available`` provision state::
+
+    (kayobe) $ kayobe baremetal compute provide
+
+Inspect
+-------
+
+Nodes must be in one of the following states: ``manageable``, ``inspect
+failed``, or ``available``. To trigger hardware inspection on the baremetal
+compute nodes::
+
+    (kayobe) $ kayobe baremetal compute inspect
+
+Rename
+------
+
+Once nodes have been discovered, it is helpful to associate them with a name
+to make them easier to work with. If you would like the nodes to be named
+according to their inventory host names, you can run the following command::
+
+    (kayobe) $ kayobe baremetal compute rename
+
+This command will use the ``ipmi_address`` host variable from the inventory
+to map the inventory host name to the correct node.
+
+.. _update_deployment_image:
+
+Update Deployment Image
+-----------------------
+
+When the overcloud deployment images have been rebuilt or there has been a change
+to one of the following variables:
+
+- ``ipa_kernel_upstream_url``
+- ``ipa_ramdisk_upstream_url``
+
+either by changing the url, or if the image to which they point
+has been changed, you need to update the ``deploy_ramdisk``
+and ``deploy_kernel`` properties on the Ironic nodes. To do
+this you can run::
+
+    (kayobe) $ kayobe baremetal compute update deployment image
+
+You can optionally limit the nodes in which this affects by setting ``baremetal-compute-limit``::
+
+    (kayobe) $ kayobe baremetal compute update deployment image --baremetal-compute-limit sand-6-1
+
+which should take the form of an `ansible host pattern <https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html>`_.
+This is matched against the Ironic node name.
+
+Ironic Serial Console
+---------------------
+
+To access the baremetal nodes from within Horizon you need to enable the serial
+console. For this to work the you must set
+``kolla_enable_nova_serialconsole_proxy`` to ``true`` in
+``etc/kayobe/kolla.yml``::
+
+    kolla_enable_nova_serialconsole_proxy: true
+
+The console interface on the Ironic nodes is expected to be ``ipmitool-socat``,
+you can check this with::
+
+    openstack baremetal node show <node_id> --fields console_interface
+
+where <node_id> should be the UUID or name of the Ironic node you want to check.
+
+If you have set ``kolla_ironic_enabled_console_interfaces`` in
+``etc/kayobe/ironic.yml``, it should include ``ipmitool-socat`` in the list of
+enabled interfaces.
+
+The playbook to enable the serial console currently only works if the Ironic
+node name matches the inventory hostname.
+
+Once these requirements have been satisfied, you can run::
+
+    (kayobe) $ kayobe baremetal compute serial console enable
+
+This will reserve a TCP port for each node to use for the serial console
+interface.  The allocations are stored in
+``${KAYOBE_CONFIG_PATH}/console-allocation.yml``. The current implementation
+uses a global pool, which is specified by
+``ironic_serial_console_tcp_pool_start`` and
+``ironic_serial_console_tcp_pool_end``; these variables can set in
+``etc/kayobe/ironic.yml``.
+
+To disable the serial console you can use::
+
+    (kayobe) $ kayobe baremetal compute serial console disable
+
+The port allocated for each node is retained and must be manually removed from
+``${KAYOBE_CONFIG_PATH}/console-allocation.yml`` if you want it to be reused by
+another Ironic node with a different name.
+
+You can optionally limit the nodes targeted by setting
+``baremetal-compute-limit``::
+
+    (kayobe) $ kayobe baremetal compute serial console enable --baremetal-compute-limit sand-6-1
+
+which should take the form of an `ansible host pattern
+<https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html>`_.

doc/source/administration/general.rst

+======================
+General Administration
+======================
+
+Running Kayobe Playbooks on Demand
+==================================
+
+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) $ kayobe playbook run <playbook> [<playbook>]
+
+Running Kolla-ansible Commands
+==============================
+
+To execute a kolla-ansible command::
+
+    (kayobe) $ kayobe kolla ansible run <command>
+
+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) $ 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.
+
+Checking Network Connectivity
+=============================
+
+In complex networking environments it can be useful to be able to automatically
+check network connectivity and diagnose networking issues.  To perform some
+simple connectivity checks::
+
+    (kayobe) $ kayobe network connectivity check
+
+Note that this will run on the seed, seed hypervisor, and overcloud hosts. If
+any of these hosts are not expected to be active (e.g. prior to overcloud
+deployment), the set of target hosts may be limited using the ``--limit``
+argument.

doc/source/administration/index.rst

+==============
+Administration
+==============
+
+This section describes how to use kayobe to simplify post-deployment
+administrative tasks.
+
+.. toctree::
+   :maxdepth: 2
+
+   general
+   seed
+   overcloud
+   bare-metal

doc/source/administration.rst → doc/source/administration/overcloud.rst

-==============
-Administration
-==============
-
-This section describes how to use kayobe to simplify post-deployment
-administrative tasks.
+========================
+Overcloud Administration
+========================
 
 Updating Packages
 =================
 
-It is possible to update packages on the seed and overcloud hosts. To update
-one or more packages::
+It is possible to update packages on the overcloud hosts. To update one or more
+packages::
 
-    (kayobe) $ kayobe seed host package update --packages <package1>,<package2>
     (kayobe) $ kayobe overcloud host package update --packages <package1>,<package2>
 
 To update all eligible packages, use ``*``, escaping if necessary::
 
-    (kayobe) $ kayobe seed host package update --packages *
     (kayobe) $ kayobe overcloud host package update --packages *
 
 To only install updates that have been marked security related::
 
-    (kayobe) $ kayobe seed host package update --packages <packages> --security
     (kayobe) $ kayobe overcloud host package update --packages <packages> --security
 
 Note that these commands do not affect packages installed in containers, only
@@ -91,17 +85,6 @@ To deprovision the overcloud::
 
     (kayobe) $ kayobe overcloud deprovision
 
-Deprovisioning The Seed VM
-==========================
-
-.. note::
-
-   This step will destroy the seed VM and its data volumes.
-
-To deprovision the seed VM::
-
-    (kayobe) $ kayobe seed vm deprovision
-
 Saving Overcloud Service Configuration
 ======================================
 
@@ -132,177 +115,3 @@ The configuration will be generated remotely on the overcloud hosts in the
 specified directory, with one subdirectory per container. This command may be
 followed by ``kayobe ovecloud service configuration save`` to gather the
 generated configuration to the Ansible control host.
-
-Checking Network Connectivity
-=============================
-
-In complex networking environments it can be useful to be able to automatically
-check network connectivity and diagnose networking issues.  To perform some
-simple connectivity checks::
-
-    (kayobe) $ kayobe network connectivity check
-
-Note that this will run on the seed, seed hypervisor, and overcloud hosts. If
-any of these hosts are not expected to be active (e.g. prior to overcloud
-deployment), the set of target hosts may be limited using the ``--limit``
-argument.
-
-Baremetal Compute Node Management
-=================================
-
-When enrolling new hardware or performing maintenance, it can be useful to be
-able to manage many bare metal compute nodes simulteneously.
-
-In all cases, commands are delegated to one of the controller hosts, and
-executed concurrently. Note that ansible's ``forks`` configuration option,
-which defaults to 5, may limit the number of nodes configured concurrently.
-
-By default these commands wait for the state transition to complete for each
-node. This behavior can be changed by overriding the variable
-``baremetal_compute_wait`` via ``-e baremetal_compute_wait=False``
-
-Manage
-------
-
-A node may need to be set to the ``manageable`` provision state in order to
-perform certain management operations, or when an enrolled node is
-transitioned into service. In order to manage a node, it must be in one of
-these states: ``enroll``, ``available``, ``cleaning``, ``clean failed``,
-``adopt failed`` or ``inspect failed``. To move the baremetal compute nodes
-to the ``manageable`` provision state::
-
-    (kayobe) $ kayobe baremetal compute manage
-
-Provide
--------
-
-In order for nodes to be scheduled by nova, they must be ``available``. To
-move the baremetal compute nodes from the ``manageable`` state to the
-``available`` provision state::
-
-    (kayobe) $ kayobe baremetal compute provide
-
-Inspect
--------
-
-Nodes must be in one of the following states: ``manageable``, ``inspect
-failed``, or ``available``. To trigger hardware inspection on the baremetal
-compute nodes::
-
-    (kayobe) $ kayobe baremetal compute inspect
-
-Rename
-------
-
-Once nodes have been discovered, it is helpful to associate them with a name
-to make them easier to work with. If you would like the nodes to be named
-according to their inventory host names, you can run the following command::
-
-    (kayobe) $ kayobe baremetal compute rename
-
-This command will use the ``ipmi_address`` host variable from the inventory
-to map the inventory host name to the correct node.
-
-
-Ironic Serial Console
----------------------
-
-To access the baremetal nodes from within Horizon you need to enable the serial
-console. For this to work the you must set ``kolla_enable_nova_serialconsole_proxy``
-to ``true`` in ``etc/kayobe/kolla.yml``::
-
-    kolla_enable_nova_serialconsole_proxy: true
-
-The console interface on the Ironic nodes is expected to be ``ipmitool-socat``, you
-can check this with::
-
-    openstack baremetal node show <node_id> --fields console_interface
-
-where <node_id> should be the UUID or name of the Ironic node you want to check.
-
-If you have set ``kolla_ironic_enabled_console_interfaces`` in ``etc/kayobe/ironic.yml``,
-it should include ``ipmitool-socat`` in the list of enabled interfaces.
-
-The playbook to enable the serial console currently only works if the Ironic node
-name matches the inventory hostname.
-
-Once these requirements have been satisfied, you can run::
-
-    (kayobe) $ kayobe baremetal compute serial console enable
-
-This will reserve a TCP port for each node to use for the serial console interface.
-The allocations are stored in ``${KAYOBE_CONFIG_PATH}/console-allocation.yml``. The
-current implementation uses a global pool, which is specified by
-``ironic_serial_console_tcp_pool_start`` and ``ironic_serial_console_tcp_pool_end``;
-these variables can set in ``etc/kayobe/ironic.yml``.
-
-To disable the serial console you can use::
-
-    (kayobe) $ kayobe baremetal compute serial console disable
-
-The port allocated for each node is retained and must be manually removed from
-``${KAYOBE_CONFIG_PATH}/console-allocation.yml`` if you want it to be reused by another
-Ironic node with a different name.
-
-You can optionally limit the nodes targeted by setting ``baremetal-compute-limit``::
-
-    (kayobe) $ kayobe baremetal compute serial console enable --baremetal-compute-limit sand-6-1
-
-which should take the form of an `ansible host pattern <https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html>`_.
-
-.. _update_deployment_image:
-
-Update Deployment Image
------------------------
-
-When the overcloud deployment images have been rebuilt or there has been a change
-to one of the following variables:
-
-- ``ipa_kernel_upstream_url``
-- ``ipa_ramdisk_upstream_url``
-
-either by changing the url, or if the image to which they point
-has been changed, you need to update the ``deploy_ramdisk``
-and ``deploy_kernel`` properties on the Ironic nodes. To do
-this you can run::
-
-    (kayobe) $ kayobe baremetal compute update deployment image
-
-You can optionally limit the nodes in which this affects by setting ``baremetal-compute-limit``::
-
-    (kayobe) $ kayobe baremetal compute update deployment image --baremetal-compute-limit sand-6-1
-
-which should take the form of an `ansible host pattern <https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html>`_.
-This is matched against the Ironic node name.
-
-Running Kayobe Playbooks on Demand
-==================================
-
-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) $ kayobe playbook run <playbook> [<playbook>]
-
-Running Kolla-ansible Commands
-==============================
-
-To execute a kolla-ansible command::
-
-    (kayobe) $ kayobe kolla ansible run <command>
-
-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) $ 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.

doc/source/administration/seed.rst

+===================
+Seed Administration
+===================
+
+Deprovisioning The Seed VM
+==========================
+
+.. note::
+
+   This step will destroy the seed VM and its data volumes.
+
+To deprovision the seed VM::
+
+    (kayobe) $ kayobe seed vm deprovision
+
+Updating Packages
+=================
+
+It is possible to update packages on the seed host. To update one or more
+packages::
+
+    (kayobe) $ kayobe seed host package update --packages <package1>,<package2>
+
+To update all eligible packages, use ``*``, escaping if necessary::
+
+    (kayobe) $ kayobe seed host package update --packages *
+
+To only install updates that have been marked security related::
+
+    (kayobe) $ kayobe seed host package update --packages <packages> --security
+
+Note that these commands do not affect packages installed in containers, only
+those installed on the host.

doc/source/index.rst

@@ -26,7 +26,7 @@ Documentation
    configuration/index
    deployment
    upgrading
-   administration
+   administration/index
 
 Advanced Documentation
 ----------------------