Migrate install to deploy-guide

The deployment guide is currently pointed at triplo-docs but it has been
requested that we actually publish a deployment guide. This change
extracts many of the installation doc pages and moves them into the
deploy-guide source tree.  Once the deploy-guide is published, we will
follow up to reference the deployment guide from tripleo-docs.

Change-Id: I0ebd26f014180a92c6cf4ab0929d99b2d860796f

deploy-guide/source/deployment/ansible_config_download.rst

@@ -173,7 +173,7 @@ take precendence over the defaults::
 
 config-download with deployed-server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When using ``config-download`` with :doc:`deployed-server <deployed_server>`
+When using ``config-download`` with :doc:`deployed-server <../features/deployed_server>`
 (pre-provisioned nodes), a ``HostnameMap`` parameter **must** be provided.
 Create an environment file to define the parameter, and assign the node
 hostnames in the parameter value. The following example shows a sample value::

deploy-guide/source/deployment/ansible_config_download_differences.rst

@@ -7,7 +7,7 @@ overcloud configuration. In the Rocky release, this method is the new default
 behavior.
 
 The feature is fully documented at
-:doc:`../advanced_deployment/ansible_config_download`, while this page details
+:doc:`ansible_config_download`, while this page details
 the differences to the deployer experience with config-download.
 
 Ansible vs. os-collect-config
@@ -88,7 +88,7 @@ The new steps are summarized as:
 #. (tripleoclient) Enable tripleo-admin ssh user
 #. (ansible) Applying the created software configuration to the Nova/Ironic instances
 
-See :doc:`../advanced_deployment/ansible_config_download` for details on the
+See :doc:`ansible_config_download` for details on the
 tripleo-admin ssh user step.
 
 Deployment CLI output

deploy-guide/source/deployment/index.rst

@@ -0,0 +1,33 @@
+TripleO OpenStack Deployment
+============================
+
+This section describes how to deploy OpenStack clouds on containers, either on
+the undercloud or the overcloud.
+
+.. toctree::
+   :maxdepth: 1
+
+   undercloud
+   install_undercloud
+   overcloud
+   install_overcloud
+
+TripleO Deployment Advanced Topics
+==================================
+
+This section has additional documentation around advanced deployment related topics.
+
+.. toctree::
+   :maxdepth: 1
+
+   3rd_party
+   ansible_config_download
+   ansible_config_download_differences
+   architecture
+   build_single_image
+   container_image_prepare
+   instack_undercloud
+   standalone
+   template_deploy
+   tips_tricks
+   upload_single_image

deploy-guide/source/deployment/instack_undercloud.rst

@@ -1,10 +1,10 @@
-Installing the Undercloud
---------------------------
+(DEPRECATED) Installing the Undercloud
+--------------------------------------
 
 .. note::
    Instack-undercloud is deprecated in Rocky cycle. Containerized undercloud
-   should be installed instead. See :doc:`../containers_deployment/undercloud`
-   for backward compatibility related information.
+   should be installed instead. See :doc:`undercloud` for backward
+   compatibility related information.
 
 .. note::
    Please ensure all your nodes (undercloud, compute, controllers, etc) have
@@ -160,12 +160,12 @@ Installing the Undercloud
    .. admonition:: SSL
       :class: optional
 
-      To deploy an undercloud with SSL, see :doc:`../advanced_deployment/ssl`.
+      To deploy an undercloud with SSL, see :doc:`../features/ssl`.
 
    .. admonition:: Validations
       :class: validations
 
-      :doc:`../../validations/index` will be installed and
+      :doc:`../post_deployment/validations/index` will be installed and
       configured during undercloud installation. You can set
       ``enable_validations = false`` in ``undercloud.conf`` to prevent
       that.

deploy-guide/source/deployment/install_overcloud.rst

@@ -15,10 +15,10 @@ the project defaults.
       experience.
 
       It's recommended to review these differences as documented at
-      :doc:`../advanced_deployment/ansible_config_download_differences`
+      :doc:`ansible_config_download_differences`
 
       **config-download** is fully documented at
-      :doc:`../advanced_deployment/ansible_config_download`
+      :doc:`ansible_config_download`
 
 
 Prepare Your Environment
@@ -26,8 +26,8 @@ Prepare Your Environment
 
 #. Make sure you have your environment ready and undercloud running:
 
-   * :doc:`../environments/environments`
-   * :doc:`../installation/installing`
+   * :doc:`../environments/index`
+   * :doc:`undercloud`
 
 #. Log into your undercloud virtual machine and become the non-root user (stack
    by default)::
@@ -264,7 +264,7 @@ created on the undercloud, one should use a non-root user.
 
 .. note::
 
-       If you want to use whole disk images with TripleO, please see :doc:`../advanced_deployment/whole_disk_images`.
+       If you want to use whole disk images with TripleO, please see :doc:`../provisioning/whole_disk_images`.
 
 .. _basic-deployment-cli-upload-images:
 
@@ -276,7 +276,7 @@ Load the images into the containerized undercloud Glance::
     openstack overcloud image upload
 
 
-To upload a single image, see :doc:`../post_deployment/upload_single_image`.
+To upload a single image, see :doc:`upload_single_image`.
 
 If working with multiple architectures and/or plaforms with an architecure these
 attributes can be specified at upload time as in::
@@ -322,7 +322,7 @@ used::
     openstack overcloud node import --introspect --provide instackenv.json
 
 Starting with the Newton release you can take advantage of the ``enroll``
-provisioning state - see :doc:`../advanced_deployment/node_states` for details.
+provisioning state - see :doc:`../provisioning/node_states` for details.
 
 If your hardware has several hard drives, it's highly recommended that you
 specify the exact device to be used during introspection and deployment
@@ -336,10 +336,10 @@ as a root device. Please see :ref:`root_device` for details.
 
 If there is information from previous deployments on the nodes' disks, it is
 recommended to at least remove the partitions and partition table(s). See
-:doc:`../advanced_deployment/cleaning` for information on how to do it.
+:doc:`../provisioning/cleaning` for information on how to do it.
 
 Finally, if you want your nodes to boot in the UEFI mode, additional steps may
-have to be taken - see :doc:`../advanced_deployment/uefi_boot` for details.
+have to be taken - see :doc:`../provisioning/uefi_boot` for details.
 
 .. warning::
    It's not recommended to delete nodes and/or rerun this command after
@@ -350,7 +350,7 @@ have to be taken - see :doc:`../advanced_deployment/uefi_boot` for details.
    :ref:`node_registration_problems`.
 
 Another approach to enrolling node is
-:doc:`../advanced_deployment/node_discovery`.
+:doc:`../provisioning/node_discovery`.
 
 .. _introspection:
 
@@ -386,13 +386,13 @@ making the nodes available for deployment.
    the process takes longer, see :ref:`introspection_problems`.
 
 .. note:: If you need to introspect just a single node, see
-   :doc:`../advanced_deployment/introspect_single_node`
+   :doc:`../provisioning/introspect_single_node`
 
 Provide Nodes
 -------------
 
 Only nodes in the ``available`` provisioning state can be deployed to
-(see :doc:`../advanced_deployment/node_states` for details).  To move
+(see :doc:`../provisioning/node_states` for details).  To move
 nodes from ``manageable`` to ``available`` the following command can be
 used::
 
@@ -409,7 +409,7 @@ memory, disk, and cpu as that flavor.
 
 In addition, there are profile-specific flavors created which can be used with
 the profile-matching feature.  For more details on deploying with profiles,
-see :doc:`../advanced_deployment/profile_matching`.
+see :doc:`../provisioning/profile_matching`.
 
 .. _basic-deployment-cli-configure-namserver:
 
@@ -497,7 +497,7 @@ configured for the virtual environment.  To customize this, see the output of::
   The `hyperconverged-ceph.yaml` environment file will also enable a port on the
   `StorageMgmt` network for the Compute nodes. This will be the Ceph private
   network and the Compute NIC templates have to be configured to use that, see
-  :doc:`../advanced_deployment/network_isolation` for more details on how to do
+  :doc:`../features/network_isolation` for more details on how to do
   it.
 
 .. admonition:: RHEL Satellite Registration
@@ -525,7 +525,7 @@ configured for the virtual environment.  To customize this, see the output of::
 .. admonition:: SSL
    :class: optional
 
-   To deploy an overcloud with SSL, see :doc:`../advanced_deployment/ssl`.
+   To deploy an overcloud with SSL, see :doc:`../features/ssl`.
 
 Run the deploy command, including any additional parameters as necessary::
 
@@ -564,7 +564,7 @@ Run the deploy command, including any additional parameters as necessary::
           openstack overcloud deploy --templates
 
 To deploy an overcloud with multiple controllers and achieve HA,
-follow :doc:`../advanced_deployment/high_availability`.
+follow :doc:`../features/high_availability`.
 
 .. admonition:: Virtual
    :class: virtual
@@ -577,7 +577,7 @@ follow :doc:`../advanced_deployment/high_availability`.
 
    To deploy the overcloud with network isolation, bonds, and/or custom
    network interface configurations, instead follow the workflow here to
-   deploy: :doc:`../advanced_deployment/network_isolation`
+   deploy: :doc:`../features/network_isolation`
 
 .. note::
 
@@ -691,7 +691,7 @@ The overcloud can be redeployed when desired.
     openstack stack list
 
 #. It is recommended that you delete existing partitions from all nodes before
-   redeploying, see :doc:`../advanced_deployment/cleaning` for details.
+   redeploying, see :doc:`../provisioning/cleaning` for details.
 
 #. Deploy the Overcloud again::
 

deploy-guide/source/deployment/install_undercloud.rst

@@ -0,0 +1,244 @@
+Undercloud Installation
+=======================
+
+This section contains instructions on how to install the undercloud. For update
+or upgrade to a deployed undercloud see undercloud_upgrade_.
+
+.. _undercloud_upgrade: ../post_deployment/upgrade/undercloud.html
+
+
+.. _install_undercloud:
+
+Installing the Undercloud
+--------------------------
+
+.. note::
+   Instack-undercloud is deprecated in Rocky cycle. Containerized undercloud
+   should be installed instead. See :doc:`undercloud`
+   for backward compatibility related information.
+
+.. note::
+   Please ensure all your nodes (undercloud, compute, controllers, etc) have
+   their internal clock set to UTC in order to prevent any issue with possible
+   file future-dated timestamp if hwclock is synced before any timezone offset
+   is applied.
+
+
+#. Log in to your machine (baremetal or VM) where you want to install the
+   undercloud as a non-root user (such as the stack user)::
+
+       ssh <non-root-user>@<undercloud-machine>
+
+   .. note::
+      If you don't have a non-root user created yet, log in as root and create
+      one with following commands::
+
+          sudo useradd stack
+          sudo passwd stack  # specify a password
+
+          echo "stack ALL=(root) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/stack
+          sudo chmod 0440 /etc/sudoers.d/stack
+
+          su - stack
+
+   .. note::
+      The undercloud is intended to work correctly with SELinux enforcing.
+      Installatoins with the permissive/disabled SELinux are not recommended.
+      The ``undercloud_enable_selinux`` config option controls that setting.
+
+   .. note::
+      vlan tagged interfaces must follow the if_name.vlan_id convention, like for
+      example: eth0.vlan100 or bond0.vlan120.
+
+   .. admonition:: Baremetal
+      :class: baremetal
+
+      Ensure that there is a FQDN hostname set and that the $HOSTNAME environment
+      variable matches that value.  The easiest way to do this is to set the
+      ``undercloud_hostname`` option in undercloud.conf before running the
+      install.  This will allow the installer to configure all of the hostname-
+      related settings appropriately.
+
+      Alternatively the hostname settings can be configured manually, but
+      this is strongly discouraged.  The manual steps are as follows::
+
+          sudo hostnamectl set-hostname myhost.mydomain
+          sudo hostnamectl set-hostname --transient myhost.mydomain
+
+      An entry for the system's FQDN hostname is also needed in /etc/hosts. For
+      example, if the system is named *myhost.mydomain*, /etc/hosts should have
+      an entry like::
+
+         127.0.0.1   myhost.mydomain myhost
+
+
+#. Enable needed repositories:
+
+   .. admonition:: RHEL
+      :class: rhel
+
+      Enable optional repo::
+
+          sudo yum install -y yum-utils
+          sudo yum-config-manager --enable rhelosp-rhel-7-server-opt
+
+   .. include:: ../repositories.rst
+
+
+#. Install the TripleO CLI, which will pull in all other necessary packages as dependencies::
+
+    sudo yum install -y python-tripleoclient
+
+   .. admonition:: Ceph
+      :class: ceph
+
+      If you intend to deploy Ceph in the overcloud, or configure the overcloud to use an external Ceph cluster, and are running Pike or newer, then install ceph-ansible on the undercloud::
+
+          sudo yum install -y ceph-ansible
+
+#. Prepare the configuration file::
+
+    cp /usr/share/python-tripleoclient/undercloud.conf.sample ~/undercloud.conf
+
+   It is backwards compatible with non-containerized instack underclouds.
+
+   .. admonition:: Stable Branch
+      :class: stable
+
+      For a non-containerized undercloud, copy in the sample configuration
+      file and edit it to reflect your environment::
+
+       cp /usr/share/instack-undercloud/undercloud.conf.sample ~/undercloud.conf
+
+      .. note:: There is a tool available that can help with writing a basic
+          ``undercloud.conf``:
+          `Undercloud Configuration Wizard <http://ucw.tripleo.org/>`_
+          It takes some basic information about the intended overcloud
+          environment and generates sane values for a number of the important
+          options.
+
+#. (OPTIONAL) Generate configuration for preparing container images
+
+   As part of the undercloud install, an image registry is configured on port
+   `8787`.  This is used to increase reliability of overcloud image pulls, and
+   minimise overall network transfers.  The undercloud registry will be
+   populated with images required by the undercloud by generating the following
+   `containers-prepare-parameter.yaml` file and including it in
+   ``undercloud.conf:
+   container_images_file=$HOME/containers-prepare-parameter.yaml``::
+
+      openstack tripleo container image prepare default \
+        --local-push-destination \
+        --output-env-file ~/containers-prepare-parameter.yaml
+
+   .. note::
+      This command is available since Rocky.
+
+   See :ref:`prepare-environment-containers` for details on using
+   `containers-prepare-parameter.yaml` to control what can be done
+   during the container images prepare phase of an undercloud install.
+
+   Additionally, ``docker_insecure_registries`` and ``docker_registry_mirror``
+   parameters allow to customize container registries via the
+   ``undercloud.conf`` file.
+
+#. (OPTIONAL) Override heat parameters and environment files used for undercloud
+   deployment.
+
+   Similarly to overcloud deployments, see :ref:`override-heat-templates` and
+   :ref:`custom-template-location`, the ``undercloud.conf: custom_env_files``
+   and ``undercloud.conf: templates`` configuration parameters allow to
+   use a custom heat templates location and override or specify additional
+   information for Heat resources used for undercloud deployment.
+
+   Additionally, the ``undercloud.conf: roles_file`` parameter brings in the
+   ultimate flexibility of :ref:`custom_roles` and :ref:`composable_services`.
+   This allows you to deploy an undercloud composed of highly customized
+   containerized services, with the same workflow that TripleO uses for
+   overcloud deployments.
+
+   .. note:: The CLI and configuration interface used to deploy a containerized
+       undercloud is the same as that used by 'legacy' non-containerized
+       underclouds. As noted above however mechanism by which the undercloud is
+       actually deployed is completely changed and what is more, for the first
+       time aligns with the overcloud deployment. See the command
+       ``openstack tripleo deploy --standalone`` help for details.
+       That interface extention for standalone clouds is experimental for Rocky.
+       It is normally should not be used directly for undercloud installations.
+
+#. Run the command to install the undercloud:
+
+   .. admonition:: SSL
+      :class: optional
+
+      To deploy an undercloud with SSL, see :doc:`../features/ssl`.
+
+   .. admonition:: Validations
+      :class: validations
+
+      :doc:`../post_deployment/validations/index` will be installed and
+      configured during undercloud installation. You can set
+      ``enable_validations = false`` in ``undercloud.conf`` to prevent
+      that.
+
+   To deploy an undercloud::
+
+       openstack undercloud install
+
+.. note::
+    The undercloud is containerized by default as of Rocky.
+
+.. note::
+    It's possible to enable verbose logging with ``--verbose`` option.
+
+.. note::
+    To install a deprecated instack undercloud, you'll need to deploy
+    with ``--use-heat=False`` option. It only works in Rocky
+    as instack-undercloud was retired in Stein.
+
+
+In Rocky, we will run all the OpenStack services in a moby container runtime
+unless the default settings are overwritten.
+This command requires 2 services to be running at all times. The first one is a
+basic keystone service, which is currently executed by `tripleoclient` itself, the
+second one is `heat-all` which executes the templates and installs the services.
+The latter can be run on baremetal or in a container (tripleoclient will run it
+in a container by default).
+
+Once the install has completed, you should take note of the files ``stackrc`` and
+``undercloud-passwords.conf``.  You can source ``stackrc`` to interact with the
+undercloud via the OpenStack command-line client.  The ``undercloud-passwords.conf``
+file contains the passwords used for each service in the undercloud.  These passwords
+will be automatically reused if the undercloud is reinstalled on the same system,
+so it is not necessary to copy them to ``undercloud.conf``.
+
+.. note:: Heat installer configuration, logs and state is ephemeral for
+    undercloud deployments. Generated artifacts for consequent deployments get
+    overwritten or removed (when ``undercloud.conf: cleanup = true``).
+    Although, you can still find them stored in compressed files.
+
+Miscellaneous undercloud deployment artifacts, like processed heat templates and
+compressed files, can be found in ``undercloud.conf: output_dir`` locations
+like ``~/tripleo-heat-installer-templates``.
+
+There is also a compressed file created and placed into the output dir, named as
+``undercloud-install-<TS>.tar.bzip2``, where TS represents a timestamp.
+
+Downloaded ansible playbooks and inventory files (see :ref:`config_download`)
+used for undercloud deployment are stored in the tempdir
+``~/undercloud-ansible-<XXXX>`` by default.
+
+.. note::
+    Any passwords set in ``undercloud.conf`` will take precedence over the ones in
+    ``undercloud-passwords.conf``.
+
+.. note::
+    The used undercloud installation command can be rerun to reapply changes from
+    ``undercloud.conf`` to the undercloud. Note that this should **not** be done
+    if an overcloud has already been deployed or is in progress.
+
+.. note::
+    If running ``docker`` commands as a stack user after an undercloud install fail
+    with a permission error, log out and log in again. The stack user does get added
+    to the docker group during install, but that change gets reflected only after a
+    new login.

deploy-guide/source/deployment/template_deploy.rst

@@ -58,7 +58,7 @@ so the deployment uses the local version::
     ``--environment-file`` option) whenever you make subsequent changes to the
     overcloud, such as :doc:`../post_deployment/scale_roles`,
     :doc:`../post_deployment/delete_nodes` or
-    :doc:`../../upgrade/minor_update`.
+    :doc:`../post_deployment/upgrade/minor_update`.
 
 .. _custom-template-location:
 
@@ -75,7 +75,7 @@ where you wish to check the templates into a revision control system.
     changes on updates to the openstack-tripleo-heat-templates package, and
     care will be needed to avoid modifying anything in the tree which the CLI
     tools rely on (such as top-level parameters).  In many cases using the
-    :doc:`ExtraConfig <extra_config>` interfaces or specific template overrides
+    :doc:`ExtraConfig <../features/extra_config>` interfaces or specific template overrides
     as outlined above may be preferable.
 
 Here is an example of copying the entire tripleo-heat-templates tree to a

deploy-guide/source/deployment/undercloud.rst

@@ -17,7 +17,7 @@ directly on the host operating system. This reduces the required packages in
 the host to the bare minimum for running the container runtime and managing the
 base network layer.
 
-.. note:: Check the :doc:`../installation/installing` and :doc:`../../upgrade/undercloud`
+.. note:: Check the :doc:`install_undercloud` and :doc:`../post_deployment/upgrade/undercloud`
           sections for deploying and upgrading a containerized undercloud.
 
 .. note:: Check the :ref:`debug-containers` section for more tips and tricks for

deploy-guide/source/environments/baremetal.rst

@@ -279,7 +279,7 @@ For example::
 
 .. note::
     You don't need to create this file, if you plan on using
-    :doc:`../advanced_deployment/node_discovery`.
+    :doc:`../provisioning/node_discovery`.
 
 Ironic Hardware Types
 ^^^^^^^^^^^^^^^^^^^^^

deploy-guide/source/features/baremetal_overcloud.rst

@@ -197,7 +197,7 @@ Additional configuration
   the `deploy interfaces documentation`_ for details. The default is ``iscsi``,
   starting with the Rocky release the ``direct`` deploy is also configured out
   of box. The ``ansible`` deploy interface requires extensive configuration as
-  described in :doc:`ansible_deploy_interface`.
+  described in :doc:`../provisioning/ansible_deploy_interface`.
 
 * ``IronicDefaultNetworkInterface`` specifies the network management
   implementation for bare metal nodes. The default value of ``flat`` means

deploy-guide/source/features/ceph_config.rst

@@ -5,7 +5,7 @@ This guide assumes that the undercloud is already installed and ready
 to deploy an overcloud and that the appropriate repositories
 containing Ceph packages, including ceph-ansible if applicable, have
 been enabled and installed as described in
-:doc:`../installation/installing`.
+:doc:`../deployment/index`.
 
 Deploying an Overcloud with Ceph
 --------------------------------

deploy-guide/source/features/ceph_external.rst

@@ -9,7 +9,7 @@ Overcloud. For Ocata and earlier use
 `environments/puppet-ceph-external.yaml`. For Pike and newer, use
 `environments/ceph-ansible/ceph-ansible-external.yaml` and install
 ceph-ansible on the Undercloud as described in
-:doc:`../installation/installing`.
+:doc:`../deployment/index`.
 
 Some of the parameters in the above environment file can be overridden::
 

deploy-guide/source/features/cinder_netapp.rst

@@ -8,7 +8,7 @@ Deploying the Overcloud
 -----------------------
 .. note::
 
-    The :doc:`template_deploy` doc has a more detailed explanation of the
+    The :doc:`../deployment/template_deploy` doc has a more detailed explanation of the
     following steps.
 
 #. Copy the NetApp configuration file to your home directory::

deploy-guide/source/features/custom_roles.rst

@@ -104,7 +104,7 @@ cluster::
 
 .. note::
    In the example above, if you wanted to deploy the Galera role on specific nodes
-   you would either use predictable placement :doc:`node_placement` or add a custom
+   you would either use predictable placement :doc:`../provisioning/node_placement` or add a custom
    parameter called OvercloudGaleraFlavor::
 
 

deploy-guide/source/features/deploy_manila.rst

@@ -136,7 +136,7 @@ Deploying the Overcloud with an External Backend
 ------------------------------------------------
 .. note::
 
-    The :doc:`template_deploy` doc has a more detailed explanation of the
+    The :doc:`../deployment/template_deploy` doc has a more detailed explanation of the
     following steps.
 
 #. Copy the Manila driver-specific configuration file to your home directory:
@@ -196,7 +196,7 @@ Creating the Share
 
 #. Create a share network to host the shares:
 
-   - Create the overcloud networks. The :doc:`../basic_deployment/basic_deployment_cli`
+   - Create the overcloud networks. The :doc:`../deployment/install_overcloud`
      doc has a more detailed explanation about creating the network
      and subnet. Note that you may also need to perform the following
      steps to get Manila working::

deploy-guide/source/features/deployed_server.rst

@@ -37,7 +37,7 @@ any networking configuration done by the OpenStack deployment.
 A separate interface, or set of interfaces should then be used for the
 OpenStack deployment itself, configured in the typical fashion with a set of
 NIC config templates during the Overcloud deployment. See
-:doc:`network_isolation` for more information on configuring networking.
+:doc:`../features/network_isolation` for more information on configuring networking.
 
 .. note::
 
@@ -76,7 +76,7 @@ a hostname that resolves to a routable IP address for the deployed servers. SSL
 also must be configured on the Undercloud so that HAProxy is bound to that
 configured hostname. Specify either ``undercloud_service_certifcate`` or
 ``generate_service_certificate`` to enable SSL during the Undercloud
-installation. See :doc:`ssl` for more information on configuring SSL.
+installation. See :doc:`../features/ssl` for more information on configuring SSL.
 
 Additionally, when the ctlplane is not routable from the deployed
 servers, Heat on the Undercloud must be configured to use the public
@@ -146,7 +146,7 @@ The servers will need to already have the appropriately enabled yum repositories
 as packages will be installed on the servers during the Overcloud deployment.
 The enabling of repositories on the Overcloud nodes is the same as it is for
 other areas of TripleO, such as Undercloud installation. See
-:doc:`../basic_deployment/repositories` for the detailed steps on how to
+:doc:`../repositories` for the detailed steps on how to
 enable the standard repositories for TripleO.
 
 Initial Package Installation
@@ -257,7 +257,7 @@ object names as described in the
 
 deployed-server with config-download
 ____________________________________
-When using :doc:`config-download <ansible_config_download>` with
+When using :doc:`config-download <../deployment/ansible_config_download>` with
 ``deployed-server`` (pre-provisioned nodes), a ``HostnameMap`` parameter must
 be provided. Create an environment file to define the parameter, and assign the
 node hostnames in the parameter value. The following example shows a sample

deploy-guide/source/features/designate.rst

@@ -38,7 +38,7 @@ configure it.
 
 Because this configuration requires the node IPs to be known ahead of time, it
 is necessary to use predictable IPs.  Full details on configuring those can be
-found at :doc:`node_placement`.
+found at :doc:`../provisioning/node_placement`.
 
 Only the external (public) and internal_api networks need to be predictable
 for Designate.  The following is an example of the addresses that need to be

deploy-guide/source/features/index.rst

@@ -0,0 +1,42 @@
+Feature Configurations
+======================
+
+Documentation on additional features for |project|.
+
+.. toctree::
+
+   api_policies
+   backends
+   baremetal_overcloud
+   composable_services
+   custom_networks
+   custom_roles
+   deploy_cellv2
+   deploy_swift
+   deployed_server
+   designate
+   disable_telemetry
+   distributed_compute_node
+   extra_config
+   high_availability
+   instance_ha
+   ipsec
+   keystone_security_compliance
+   mistral-api
+   multiple_overclouds
+   network_isolation
+   network_isolation_virt
+   node_config
+   node_specific_hieradata
+   ops_tools
+   oslo_messaging_config
+   ovs_dpdk_config
+   rhsm
+   role_specific_parameters
+   routed_spine_leaf_network
+   server_blacklist
+   security_hardening
+   split_stack
+   ssl
+   tuned
+   undercloud_minion

deploy-guide/source/features/ipsec.rst

@@ -69,7 +69,7 @@ Deployment
 
 .. note:: Please note that the IPSec deployment depends on Ansible being used
           for the overcloud deployment. For more information on this, please
-          see :doc:`ansible_config_download`
+          see :doc:`../deployment/ansible_config_download`
 
 .. note:: Also note that the IPSec deployment assumes that you're using network
           isolation. For more information on this, please see

deploy-guide/source/features/multiple_overclouds.rst

@@ -21,12 +21,12 @@ provisioning network.
 Undercloud Deployment
 ---------------------
 
-Deploy the Undercloud :doc:`as usual <../installation/installation>`.
+Deploy the Undercloud :doc:`as usual <../deployment/install_undercloud>`.
 
 First Overcloud
 ---------------
 
-The first Overcloud can be deployed as usual using the :doc:`cli <../basic_deployment/basic_deployment_cli>`.
+The first Overcloud can be deployed as usual using the :doc:`cli <../deployment/install_overcloud>`.
 
 Deploying Additional Overclouds
 -------------------------------

deploy-guide/source/features/network_isolation.rst

@@ -902,7 +902,7 @@ tenant VLANs were on a bridge named ``br-vlan``, then use these values in
     ``--environment-file`` option) whenever you make subsequent changes to the
     overcloud, such as :doc:`../post_deployment/scale_roles`,
     :doc:`../post_deployment/delete_nodes` or
-    :doc:`../../upgrade/minor_update`.
+    :doc:`../post_deployment/upgrade/minor_update`.
 
 Creating Floating IP Networks
 -----------------------------

deploy-guide/source/features/node_specific_hieradata.rst

@@ -19,7 +19,7 @@ hardware dependent and immutable across reboots/reinstalls.
 
 First make sure the introspection data is available for the target node, if it
 isn't one may run introspection for a particular node as described in:
-:doc:`introspect_single_node`. If the `undercloud.conf` does not have
+:doc:`../provisioning/introspect_single_node`. If the `undercloud.conf` does not have
 `inspection_extras = true` prior to undercloud installation/upgrade
 and introspection, then the machine unique UUID will not be in the
 Ironic database.

deploy-guide/source/features/ops_tools.rst

@@ -65,7 +65,7 @@ Before deploying the Overcloud
 
 .. note::
 
-    The :doc:`template_deploy` document has a more detailed explanation of the
+    The :doc:`../deployment/template_deploy` document has a more detailed explanation of the
     following steps.
 
 

deploy-guide/source/features/routed_spine_leaf_network.rst

@@ -134,7 +134,7 @@ the undercloud by running the following command::
 Once the ``undercloud`` is installed complete the post-install tasks such as
 uploading images and registering baremetal nodes. (For addition details
 regarding the post-install tasks, see
-:doc:`../basic_deployment/basic_deployment_cli`.)
+:doc:`../deployment/install_overcloud`.)
 
 DHCP relay configuration
 ------------------------
@@ -266,7 +266,7 @@ the ones used in the ``subnets`` option in the undercloud configuration.
    or *manageable*. If the baremetal node is not in one of these states the
    command used to set the ``physical_network`` property on the baremetal port
    will fail. (For additional details regarding node states see
-   :doc:`../advanced_deployment/node_states`.)
+   :doc:`../provisioning/node_states`.)
 
    To set all nodes to ``manageable`` state run the following command::
 
@@ -464,7 +464,7 @@ Configure node placement
 ------------------------
 
 Use node placement to map the baremetal nodes to roles, with each role using a
-different set of local layer 2 segments. Please refer to :doc:`node_placement`
+different set of local layer 2 segments. Please refer to :doc:`../provisioning/node_placement`
 for details on how to configure node placement.
 
 Add role specific configuration to ``parameter_defaults``

deploy-guide/source/features/ssl.rst

@@ -8,7 +8,7 @@ as deploying SSL in the internal network for most services.
 
 This document will focus on deployments using network isolation.  For more
 details on deploying that way, see
-:doc:`../advanced_deployment/network_isolation`
+:doc:`network_isolation`
 
 Undercloud SSL
 --------------
@@ -316,7 +316,7 @@ Self-signed DNS-based certificate::
     -e ~/ssl-heat-templates/environments/ssl/enable-tls.yaml -e ~/ssl-heat-templates/environments/ssl/tls-endpoints-public-dns.yaml -e ~/cloudname.yaml -e ~/ssl-heat-templates/environments/ssl/inject-trust-anchor.yaml
 
 .. note:: It is also possible to get the public certificate from a CA. See
-          :doc:`../advanced_deployment/tls_everywhere`
+          :doc:`tls_everywhere`
 
 .. _ca-trust:
 

deploy-guide/source/features/tls_everywhere.rst

@@ -192,7 +192,7 @@ to FreeIPA. We can do this by setting the ``DnsServers`` parameter via
 parameter_defaults. You can create an environment file for it, however, since
 you probably are deploying with network isolation, you can already set this
 parameter in the **network-environment.yaml** file that's referenced in
-:doc:`../advanced_deployment/network_isolation`. So that setting would look
+:doc:`network_isolation`. So that setting would look
 like this::
 
     parameter_defaults:

deploy-guide/source/features/tuned.rst

@@ -16,7 +16,7 @@ content:
       TunedProfileName: throughput-performance
 
 Deploy the Overcloud as usual using the :doc:`CLI
-<../basic_deployment/basic_deployment_cli>` and pass the environment
+<../deployment/install_overcloud>` and pass the environment
 file using the `-e` option:
 
 .. code-block:: bash

deploy-guide/source/index.rst

@@ -7,3 +7,13 @@ clouds using OpenStack's own cloud facilities as the foundation - building on
 Nova, Ironic, Neutron and Heat to automate cloud management at datacenter
 scale.
 
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
+
+   environments/index
+   provisioning/index
+   features/index
+   deployment/index
+   post_deployment/index
+   troubleshooting/index

deploy-guide/source/post_deployment/delete_nodes.rst

@@ -13,7 +13,7 @@ IDs (which represent nodes) to be deleted.
 .. note::
    If you passed any extra environment files when you created the overcloud (for
    instance, in order to configure :doc:`network isolation
-   <../advanced_deployment/network_isolation>`), you must pass them again here
+   <../features/network_isolation>`), you must pass them again here
    using the ``-e`` or ``--environment-file`` option to avoid making undesired
    changes to the overcloud.
 

deploy-guide/source/post_deployment/index.rst

@@ -0,0 +1,34 @@
+Post Cloud Deployment
+=====================
+
+This section describes additional items that can be performed or configured
+post cloud deployment.
+
+.. toctree::
+   :maxdepth: 1
+
+   backup_and_restore/00_index.rst
+   delete_nodes
+   fernet_key_rotation
+   scale_roles
+   tempest/index
+   update_undercloud_ssh_keys
+   updating-stacks-notes
+   upgrade/index
+   validations/index
+
+
+Post Cloud Deployment Advanced Topics
+=====================================
+
+This section describes advanced post deployment tasks that can be performed
+or configured post cloud deployment.
+
+.. toctree::
+   :maxdepth: 1
+
+   migration
+   quiesce_cephstorage
+   quiesce_compute
+   updating_network_configuration_post_deployment
+   vm_snapshot

deploy-guide/source/post_deployment/migration.rst

@@ -48,6 +48,6 @@ the old cloud, additional compute nodes can be added to the new cloud with
 
 First, register and introspect the additional hardware with Ironic just as you
 would have done when :doc:`initially deploying
-<../basic_deployment/basic_deployment_cli>` the cloud with |project|. Then
+<../deployment/install_overcloud>` the cloud with |project|. Then
 :doc:`scale out <scale_roles>` the 'Compute' role in the new overcloud to start
 making use of the additional capacity.

deploy-guide/source/post_deployment/tempest/index.rst

@@ -0,0 +1,11 @@
+Tempest
+=======
+
+This section describes tempest related items.
+
+.. toctree::
+   :maxdepth: 1
+
+   os_tempest
+   tempest
+   tempest_plugins

deploy-guide/source/post_deployment/upgrade/fast_forward_upgrade.rst

@@ -184,7 +184,7 @@ When moving from Newton to Queens, the setup will be changing from baremetal to
 containers. So as a part of the upgrade the container images for the target
 release should be downloaded to the Undercloud.
 Please see the `openstack overcloud container image prepare`
-:doc:`../install/containers_deployment/overcloud` for more information.
+:doc:`../../deployment/install_overcloud` for more information.
 
 The output of this step will be a Heat environment file that contains
 references to the latest container images. You will need to pass this file
@@ -642,7 +642,7 @@ Following there is a list of all the changes needed:
    ceph-ansible. It is possible to use the ``CephAnsibleExtraConfig`` and
    `CephAnsibleDisksConfig`` parameters to pass arbitrary variables to
    ceph-ansible, like ``devices`` and ``dedicated_devices``.  See the
-   :doc:`TripleO Ceph config guide <../install/advanced_deployment/ceph_config>`
+   :doc:`TripleO Ceph config guide <../../../features/ceph_config>`
 
    The other parameters (for example ``CinderRbdPoolName``,
    ``CephClientUserName``, ...) will behave as they used to with puppet-ceph

deploy-guide/source/post_deployment/upgrade/index.rst

@@ -0,0 +1,12 @@
+Upgrades
+========
+
+This section describes upgrade related items.
+
+.. toctree::
+   :maxdepth: 1
+
+   minor_update
+   undercloud
+   major_upgrade
+   fast_forward_upgrade

deploy-guide/source/post_deployment/upgrade/major_upgrade.rst

@@ -81,7 +81,7 @@ First we prepare an environment file for new container images:
    As part of the upgrade to Queens, the container images for the
    target release should be downloaded to the Undercloud. Please see
    the `openstack overcloud container image prepare`.
-   :doc:`../install/containers_deployment/overcloud` for more information.
+   :doc:`../../deployment/install_overcloud` for more information.
 
    The output of this step will be a Heat environment file that contains
    references to the latest container images. You will need to pass the path to
@@ -93,7 +93,7 @@ First we prepare an environment file for new container images:
 
    In Rocky we only generate a new environment file with
    ``ContainerImagePrepare`` parameter at this point in the workflow. See
-   :doc:`container image preparation documentation<../install/advanced_deployment/container_image_prepare>`.
+   :doc:`container image preparation documentation<../../deployment/container_image_prepare>`.
    for details how to generate this environment file.
 
    The file is then passed to the `upgrade prepare` command, and
@@ -500,7 +500,7 @@ major-upgrade-composable-steps that come first, as described above.
       actions mentioned here to prepare your environment. In particular
       *image prepare* to generate the docker registry which you must include
       as one of the environment files specified below:
-      * :doc:`../install/containers_deployment/overcloud`
+      * :doc:`../../deployment/install_overcloud`
 
    .. __:
 
@@ -561,7 +561,7 @@ major-upgrade-composable-steps that come first, as described above.
       ``CephAnsibleDisksConfig`` parameters to pass arbitrary variables to
       ceph-ansible, like ``devices`` and ``dedicated_devices``.  See the
       `ceph-ansible scenarios`_ or the :doc:`TripleO Ceph config guide
-      <../install/advanced_deployment/ceph_config>`
+      <../../features/ceph_config>`
 
       The other parameters (for example ``CinderRbdPoolName``,
       ``CephClientUserName``, ...) will behave as they used to with puppet-ceph

deploy-guide/source/post_deployment/upgrade/minor_update.rst

@@ -36,14 +36,14 @@ the OpenStack release that you currently operate, perform these steps:
       Fetch latest container images to your undercloud registry and
       generate a Heat environment file pointing to new container
       images. This is done via workflow described in
-      :doc:`containerized deployment documentation<../install/containers_deployment/overcloud>`.
+      :doc:`containerized deployment documentation<../../deployment/overcloud>`.
 
    .. admonition:: Rocky
       :class: rocky
 
       Prepare an environment file with new ``ContainerImagePrepare``
       parameter. This is done via a command described in
-      :doc:`container image preparation documentation<../install/advanced_deployment/container_image_prepare>`.
+      :doc:`container image preparation documentation<../../deployment/container_image_prepare>`.
 
 #. **Update preparation**
 

deploy-guide/source/post_deployment/upgrade/undercloud.rst

@@ -4,7 +4,7 @@ Updating Undercloud Components
 .. note::
    Instack-undercloud is deprecated in Rocky cycle. Instack undercloud can
    only be upgraded to containerized undercloud. See
-   :doc:`../install/containers_deployment/undercloud`
+   :doc:`../../deployment/undercloud`
    for backward compatibility related information.
 
 .. note::
@@ -33,7 +33,7 @@ Updating Undercloud Components
 
 #. Enable new Delorean repositories:
 
-   .. include:: ../install/repositories.rst
+   .. include:: ../../repositories.rst
 
 .. We need to manually continue our list numbering here since the above
   "include" directive breaks the numbering.