openstack/tripleo-docs
Code Issues Proposed changes

Update containerized undercloud installation doc

Browse Source 
Containerized UC becomes a default installation method.
Adjust the documentation to indicate that and note about
instack undercloud deprecation.

Clarify containers registry configuration steps and
undercloud config params for it.

Document the shared bits of the deployment framework
leveraging overcloud and undercloud deployments.

Say a few words for the CLI interface
openstack tripleo deploy --standalone, used underneath
instack-backwards-compatible undercloud installations.

Change-Id: I2352e31857f4044eced87607c8d53841af62df32
Signed-off-by: Bogdan Dobrelya <bdobreli@redhat.com>
This commit is contained in:
Bogdan Dobrelya 2018-05-25 16:51:51 +02:00
parent c83e966d63
commit 64163d1a1c
4 changed files with 121 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/install/advanced_deployment/template_deploy.rst
View File

@ -20,6 +20,8 @@ the packaged Heat templates::
`/usr/share/openstack-tripleo-heat-templates`.
.. _override-heat-templates:
Overriding specific templates with local versions
-------------------------------------------------

2
doc/source/install/containers_deployment/overcloud.rst
View File

@ -75,6 +75,8 @@ in the deployment by specifying the heat environment files with the
``--environment-file`` option and the roles file with the ``--roles-file``
option.
.. _populate-local-registry-containers:
Populate local docker registry
..............................

146
doc/source/install/installation/installing.rst
View File

@ -1,6 +1,11 @@
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.
#. 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)::
@ -19,10 +24,16 @@ Installing the Undercloud
su - stack
.. note::
The undercloud is intended to work correctly with SELinux enforcing, and
cannot be installed to a system with SELinux disabled. If SELinux
enforcement must be turned off for some reason, it should instead be set
to permissive.
The containerized undercloud is intended to work correctly with SELinux
permissive, and cannot be installed to a system with SELinux enforcing.
.. admonition:: Stable Branch
:class: stable
The instack undercloud is intended to work correctly with SELinux
enforcing, and cannot be installed to a system with SELinux disabled.
If SELinux enforcement must be turned off for some reason, like upgrading
an undercloud into containers, it should instead be set to permissive.
.. note::
vlan tagged interfaces must follow the if_name.vlan_id convention, like for
@ -65,7 +76,7 @@ Installing the Undercloud
.. We need to manually continue our list numbering here since the above
"include" directive breaks the numbering.
3. Install the TripleO CLI, which will pull in all other necessary packages as dependencies::
#. Install the TripleO CLI, which will pull in all other necessary packages as dependencies::
sudo yum install -y python-tripleoclient
@ -76,21 +87,70 @@ Installing the Undercloud
sudo yum install -y ceph-ansible
#. 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.
#. For a containerized undercloud, use this file::
#. 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.
#. Set up a containers registry (optional) and prepare container images
configuration.
See :ref:`prepare-environment-containers` for details on the containers
images preparations. The described workflow is applicable both for
overclouds and underclouds. Additional ``docker_insecure_registries`` and
``docker_registry_mirror`` parameters allow to customize container registries
via the ``undercloud.conf`` file.
.. note:: Local undercloud containers registry is not suitable for real
deployments. For production use, it is highly recommended that you use an
external container registry.
See :ref:`populate-local-registry-containers` for details on managing
containers images data populated into registries.
Once you have a containers images configuration file prepared and
containers images populated into registries, the images config file should
be explicitly specified in ``undercloud.conf: container_images_file``.
#. 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
@ -106,26 +166,24 @@ Installing the Undercloud
``enable_validations = false`` in ``undercloud.conf`` to prevent
that.
To deploy a containerized undercloud::
openstack undercloud install --use-heat
.. admonition:: Stable Branch
:class: stable
The containerized undercloud deployment isn't supported before Rocky release.
To install a deprecated instack undercloud::
Install the undercloud::
openstack undercloud install
To deploy a containerized undercloud, just add --use-heat option::
openstack undercloud install --use-heat
openstack undercloud install
.. note::
When installing a containerized undercloud, it's possible to enable verbose
logging with --verbose option.
.. note::
The `openstack undercloud install --use-heat` command
will run all the OpenStack services in a container runtime (docker)
The ``openstack undercloud install --use-heat`` command
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
@ -135,22 +193,38 @@ Installing the Undercloud
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. ``undercloud-passwords.conf``
contains the passwords used for each service in the undercloud. These passwords
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::
``openstack undercloud install`` 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.
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.
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.

8
doc/source/install/installation/updating.rst
View File

@ -1,6 +1,12 @@
Updating Undercloud Components
------------------------------
.. note::
Instack-undercloud is deprecated in Rocky cycle. Instack undercloud can
only be upgraded to containerized undercloud. See
:doc:`../containers_deployment/undercloud`
for backward compatibility related information.
#. Before upgrading the undercloud, it is highly suggested to perform
a :doc:`backup <../controlplane_backup_restore/01_undercloud_backup>`
of the undercloud and validate that a restore works fine.
@ -28,7 +34,7 @@ Updating Undercloud Components
.. We need to manually continue our list numbering here since the above
"include" directive breaks the numbering.
3. Clean the yum cache to ensure only the new repos are used
#. Clean the yum cache to ensure only the new repos are used
.. code-block:: bash