diff --git a/doc/source/install/containers_deployment/undercloud.rst b/doc/source/install/containers_deployment/undercloud.rst index 82eadcc7..dcb898e7 100644 --- a/doc/source/install/containers_deployment/undercloud.rst +++ b/doc/source/install/containers_deployment/undercloud.rst @@ -1,24 +1,10 @@ Containers based Undercloud Deployment ====================================== -This documentation explains how to deploy a fully containerized undercloud on -Docker. - -.. warning:: - This feature isn't supported yet but we hope to support it by the end - of Rocky cycle. - -While this is not currently used to deploy the overcloud, it is a great -development tool as it uses the same templates and infrastructure as the -overcloud. This lets you do faster iterations for development. - The requirements for a containerized undercloud are the same as for any other undercloud deployment. The real difference is in where the undercloud services will be deployed (containers vs base OS). -Architecture ------------- - The docker based undercloud architecture is not very different from the baremetal/VM based one. The services deployed in the traditional baremetal undercloud are also deployed in the docker based one. @@ -29,141 +15,8 @@ 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. - -Manual undercloud deployment ----------------------------- - -This section explains how to deploy a containerized undercloud manually. For an -automated undercloud deployment. A Quickstart version also exists and is -documented here https://docs.openstack.org/developer/tripleo-quickstart/ - -Preparing the environment -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Prepare a host (either baremetal or VM) following the normal undercloud -provisioning steps (see :doc:`../installation/installing`) and stop right before -the undercloud install command. This should leave you with an updated base -operating system with no openstack packages installed but required repositories -configured. - -Make sure these packages are installed before proceeding with the undercloud -installation: - -* python-tripleoclient -* python-tripleoclient-heat-installer -* python-openstackclient -* docker >= 1.12.5 -* openvswitch (minimum version supported by neutron) - -See also -`Docker installation documentation `_. - -Start the required host services:: - - $ sudo systemctl start openvswitch - $ sudo systemctl start docker - -Verify that your docker environment is up and that your user can use sudo:: - - $ sudo docker info +.. note:: Check the :doc:`../installation/installing` and :doc:`../installation/updating` + sections for deploying and upgrading a containerized undercloud. .. note:: Check the :ref:`debug-containers` section for more tips and tricks for debugging containers. - -The above should show no containers running. If it shows running containers, -please refer to the `Cleaning up`_ section below. - -Configuring the undercloud -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The containers based undercloud uses the same heat templates that are used for -an overcloud deployment. Therefore, controlling the undercloud configuration can -be done by modifying the existing environment files or creating new ones. - -A basic `custom.yaml` file would look like this:: - - parameter_defaults: - UndercloudNameserver: 8.8.8.8 - NeutronServicePlugins: "" - -The above configuration file overwrites the default nameserver and sets the -service plugins for neutron. If your undercloud node has a single nic and you -don't want to create a new one, it's possible to set the network configuration -to noop by changing the `custom.yaml` file to (substitute $THT_ROOT with the -right path):: - - resource_registry: - OS::TripleO::Undercloud::Net::SoftwareConfig: $THT_ROOT/net-config-noop.yaml - - parameter_defaults: - UndercloudNameserver: 8.8.8.8 - NeutronServicePlugins: "" - -Preparing container images --------------------------- - -Images for undercloud services should be prepared with the -``openstack overcloud container image prepare`` command. The process is very -similar to the containerized overcloud case, see -:ref:`prepare-environment-containers`. The simplified command looks like:: - - $ openstack overcloud container image prepare \ - --output-env-file $HOME/docker_registry.yaml - -Deploying the undercloud -~~~~~~~~~~~~~~~~~~~~~~~~ - -The following command will install an undercloud with ironic, mistral and zaqar:: - - $ openstack undercloud install --use-heat - - -A minimal `stackrc` file will be required to query both, the keystone and the heat, APIs:: - - export OS_NO_CACHE=True - export OS_CLOUDNAME=overcloud - export OS_AUTH_URL=http://127.0.0.1:35358 - export NOVA_VERSION=1.1 - export COMPUTE_API_VERSION=1.1 - export OS_USERNAME=foo - export OS_PROJECT_NAME=foo - export OS_PASSWORD=bar - -Cleaning up -~~~~~~~~~~~ - -The following commands will help cleaning up your undercloud environment to -start the deployment from scratch: - -To stop and remove all running containers:: - - $ sudo docker ps -qa --filter label=managed_by=docker-cmd | xargs sudo docker rm -f - -To remove the existing named volumes (bear in mind this will remove your -database files too):: - - $ sudo docker volume rm $(sudo docker volume ls -q) - -Configuration files are generated and overwritten on every run. However, you can -also remove them by running:: - - $ sudo rm -Rf /var/lib/docker-puppet - $ sudo rm -Rf /var/lib/config-data - $ sudo rm -Rf /var/lib/kolla - - -How does the undercloud deploy work? ------------------------------------- - -The `undercloud install` command as written in the `Deploying the undercloud`_ -section will run all the OpenStack services in a container runtime (docker) -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 mocked 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). - -Checkout the :doc:`architecture` for more detailed info on how -TripleO builds, creates and runs containers. diff --git a/doc/source/install/installation/installing.rst b/doc/source/install/installation/installing.rst index f1f6ba2c..00f9d565 100644 --- a/doc/source/install/installation/installing.rst +++ b/doc/source/install/installation/installing.rst @@ -76,7 +76,7 @@ Installing the Undercloud sudo yum install -y ceph-ansible -#. Copy in the sample configuration file and edit it to reflect your environment:: +#. 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 @@ -87,6 +87,10 @@ Installing the Undercloud environment and generates sane values for a number of the important options. +#. For a containerized undercloud, use this file:: + + cp /usr/share/python-tripleoclient/undercloud.conf.sample ~/undercloud.conf + #. Run the command to install the undercloud: .. admonition:: SSL @@ -102,11 +106,28 @@ Installing the Undercloud ``enable_validations = false`` in ``undercloud.conf`` to prevent that. + .. admonition:: Stable Branch + :class: stable + + The containerized undercloud deployment isn't supported before Rocky release. Install the undercloud:: openstack undercloud install + To deploy a containerized undercloud, just add --use-heat option:: + + openstack undercloud install --use-heat + +.. note:: + The `openstack undercloud install --use-heat` command + will run all the OpenStack services in a container runtime (docker) + 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 diff --git a/doc/source/install/installation/updating.rst b/doc/source/install/installation/updating.rst index b6441c8b..d01d9fa2 100644 --- a/doc/source/install/installation/updating.rst +++ b/doc/source/install/installation/updating.rst @@ -85,7 +85,7 @@ You can upgrade any packages that are installed on the undercloud machine. .. code-block:: bash - sudo yum update python-tripleoclient + sudo yum update python-tripleoclient* #. Run the undercloud upgrade command. This command will upgrade all packages @@ -96,6 +96,17 @@ You can upgrade any packages that are installed on the undercloud machine. openstack undercloud upgrade + To upgrade to a containerized undercloud, just add --use-heat option:: + + openstack undercloud upgrade --use-heat + + .. admonition:: Queens to Rocky and later + :class: otop + + The containerized undercloud deployment isn't supported before Rocky release. + Therefore, the upgrade is supported in Rocky, from a non containerized undercloud + in Queens to a containerized undercloud in Rocky. + .. note:: You may wish to use time and capture the output to a file for any debug