9b484c25e4
Also better organise the 'tips and tricks' section. Change-Id: If20a89ae93b64b5a1b5895bb9dc73c4e70adaba7 Related-Bug: #1862649
239 lines
8.3 KiB
ReStructuredText
239 lines
8.3 KiB
ReStructuredText
.. _operating-kolla:
|
|
|
|
===============
|
|
Operating Kolla
|
|
===============
|
|
|
|
Versioning
|
|
~~~~~~~~~~
|
|
|
|
Kolla uses the ``x.y.z`` `semver <https://semver.org/>`_ nomenclature for
|
|
naming versions. Kolla's initial Pike release was ``5.0.0`` and the initial
|
|
Queens release is ``6.0.0``. The Kolla community commits to release z-stream
|
|
updates every 45 days that resolve defects in the stable version in use and
|
|
publish those images to the Docker Hub registry.
|
|
|
|
To prevent confusion, the Kolla community recommends using an alpha identifier
|
|
``x.y.z.a`` where ``a`` represents any customization done on the part of the
|
|
operator. For example, if an operator intends to modify one of the Docker files
|
|
or the repos from the originals and build custom images for the Pike version,
|
|
the operator should start with version 5.0.0.0 and increase alpha for each
|
|
release. Alpha tag usage is at discretion of the operator. The alpha identifier
|
|
could be a number as recommended or a string of the operator's choosing.
|
|
|
|
To customize the version number uncomment ``openstack_release`` in globals.yml
|
|
and specify the version number desired. If ``openstack_release`` is not
|
|
specified, Kolla will deploy or upgrade using the version number information
|
|
contained in the kolla-ansible package.
|
|
|
|
Upgrade procedure
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
.. note::
|
|
|
|
If you have set ``enable_cells`` to ``yes`` then you should read the
|
|
upgrade notes in the :ref:`Nova cells guide<nova-cells-upgrade>`.
|
|
|
|
Kolla's strategy for upgrades is to never make a mess and to follow consistent
|
|
patterns during deployment such that upgrades from one environment to the next
|
|
are simple to automate.
|
|
|
|
Kolla implements a one command operation for upgrading an existing deployment
|
|
consisting of a set of containers and configuration data to a new deployment.
|
|
|
|
Limitations and Recommendations
|
|
-------------------------------
|
|
|
|
.. note::
|
|
|
|
Varying degrees of success have been reported with upgrading the libvirt
|
|
container with a running virtual machine in it. The libvirt upgrade still
|
|
needs a bit more validation, but the Kolla community feels confident this
|
|
mechanism can be used with the correct Docker storage driver.
|
|
|
|
.. note::
|
|
|
|
Because of system technical limitations, upgrade of a libvirt container when
|
|
using software emulation (``virt_type = qemu`` in nova.conf), does not work
|
|
at all. This is acceptable because KVM is the recommended virtualization
|
|
driver to use with Nova.
|
|
|
|
.. note::
|
|
|
|
Please note that when the ``use_preconfigured_databases`` flag is set to
|
|
``"yes"``, you need to have the ``log_bin_trust_function_creators`` set to
|
|
``1`` by your database administrator before performing the upgrade.
|
|
|
|
Preparation
|
|
-----------
|
|
|
|
While there may be some cases where it is possible to upgrade by skipping this
|
|
step (i.e. by upgrading only the ``openstack_release`` version) - generally,
|
|
when looking at a more comprehensive upgrade, the kolla-ansible package itself
|
|
should be upgraded first. This will include reviewing some of the configuration
|
|
and inventory files. On the operator/master node, a backup of the
|
|
``/etc/kolla`` directory may be desirable.
|
|
|
|
If upgrading from ``5.0.0`` to ``6.0.0``, upgrade the kolla-ansible package:
|
|
|
|
.. code-block:: console
|
|
|
|
pip install --upgrade kolla-ansible==6.0.0
|
|
|
|
If this is a minor upgrade, and you do not wish to upgrade kolla-ansible
|
|
itself, you may skip this step.
|
|
|
|
The inventory file for the deployment should be updated, as the newer sample
|
|
inventory files may have updated layout or other relevant changes.
|
|
Use the newer ``6.0.0`` one as a starting template, and merge your existing
|
|
inventory layout into a copy of the one from here::
|
|
|
|
/usr/share/kolla-ansible/ansible/inventory/
|
|
|
|
In addition the ``6.0.0`` sample configuration files should be taken from::
|
|
|
|
# CentOS
|
|
/usr/share/kolla-ansible/etc_examples/kolla
|
|
|
|
# Ubuntu
|
|
/usr/local/share/kolla-ansible/etc_examples/kolla
|
|
|
|
At this stage, files that are still at the ``5.0.0`` version - which need
|
|
manual updating are:
|
|
|
|
- ``/etc/kolla/globals.yml``
|
|
- ``/etc/kolla/passwords.yml``
|
|
|
|
For ``globals.yml`` relevant changes should be merged into a copy of the new
|
|
template, and then replace the file in ``/etc/kolla`` with the updated version.
|
|
For ``passwords.yml``, see the ``kolla-mergepwd`` instructions in
|
|
`Tips and Tricks`.
|
|
|
|
For the kolla docker images, the ``openstack_release`` is updated to ``6.0.0``:
|
|
|
|
.. code-block:: yaml
|
|
|
|
openstack_release: 6.0.0
|
|
|
|
Once the kolla release, the inventory file, and the relevant configuration
|
|
files have been updated in this way, the operator may first want to 'pull'
|
|
down the images to stage the ``6.0.0`` versions. This can be done safely
|
|
ahead of time, and does not impact the existing services. (optional)
|
|
|
|
Run the command to pull the ``6.0.0`` images for staging:
|
|
|
|
.. code-block:: console
|
|
|
|
kolla-ansible pull
|
|
|
|
At a convenient time, the upgrade can now be run (it will complete more
|
|
quickly if the images have been staged ahead of time).
|
|
|
|
Perform the Upgrade
|
|
-------------------
|
|
|
|
To perform the upgrade:
|
|
|
|
.. code-block:: console
|
|
|
|
kolla-ansible upgrade
|
|
|
|
After this command is complete the containers will have been recreated from the
|
|
new images.
|
|
|
|
Tips and Tricks
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Kolla Ansible CLI
|
|
-----------------
|
|
|
|
When running the ``kolla-ansible`` CLI, additional arguments may be passed to
|
|
``ansible-playbook`` via the ``EXTRA_OPTS`` environment variable.
|
|
|
|
``kolla-ansible -i INVENTORY deploy`` is used to deploy and start all Kolla
|
|
containers.
|
|
|
|
``kolla-ansible -i INVENTORY destroy`` is used to clean up containers and
|
|
volumes in the cluster.
|
|
|
|
``kolla-ansible -i INVENTORY mariadb_recovery`` is used to recover a
|
|
completely stopped mariadb cluster.
|
|
|
|
``kolla-ansible -i INVENTORY prechecks`` is used to check if all requirements
|
|
are meet before deploy for each of the OpenStack services.
|
|
|
|
``kolla-ansible -i INVENTORY post-deploy`` is used to do post deploy on deploy
|
|
node to get the admin openrc file.
|
|
|
|
``kolla-ansible -i INVENTORY pull`` is used to pull all images for containers.
|
|
|
|
``kolla-ansible -i INVENTORY reconfigure`` is used to reconfigure OpenStack
|
|
service.
|
|
|
|
``kolla-ansible -i INVENTORY upgrade`` is used to upgrades existing OpenStack
|
|
Environment.
|
|
|
|
``kolla-ansible -i INVENTORY check`` is used to do post-deployment smoke
|
|
tests.
|
|
|
|
``kolla-ansible -i INVENTORY stop`` is used to stop running containers.
|
|
|
|
``kolla-ansible -i INVENTORY deploy-containers`` is used to check and if
|
|
necessary update containers, without generating configuration.
|
|
|
|
``kolla-ansible -i INVENTORY prune-images`` is used to prune orphaned Docker
|
|
images on hosts.
|
|
|
|
.. note::
|
|
|
|
In order to do smoke tests, requires ``kolla_enable_sanity_checks=yes``.
|
|
|
|
Passwords
|
|
---------
|
|
|
|
The following commands manage the Kolla Ansible passwords file.
|
|
|
|
``kolla-mergepwd --old OLD_PASSWDS --new NEW_PASSWDS --final FINAL_PASSWDS``
|
|
is used to merge passwords from old installation with newly generated
|
|
passwords during upgrade of Kolla release. The workflow is:
|
|
|
|
#. Save old passwords from ``/etc/kolla/passwords.yml`` into
|
|
``passwords.yml.old``.
|
|
#. Generate new passwords via ``kolla-genpwd`` as ``passwords.yml.new``.
|
|
#. Merge ``passwords.yml.old`` and ``passwords.yml.new`` into
|
|
``/etc/kolla/passwords.yml``.
|
|
|
|
For example:
|
|
|
|
.. code-block:: console
|
|
|
|
mv /etc/kolla/passwords.yml passwords.yml.old
|
|
cp kolla-ansible/etc/kolla/passwords.yml passwords.yml.new
|
|
kolla-genpwd -p passwords.yml.new
|
|
kolla-mergepwd --old passwords.yml.old --new passwords.yml.new --final /etc/kolla/passwords.yml
|
|
|
|
.. note::
|
|
|
|
``kolla-mergepwd``, by default, keeps old, unused passwords intact.
|
|
To alter this behavior, and remove such entries, use the ``--clean``
|
|
argument when invoking ``kolla-mergepwd``.
|
|
|
|
Tools
|
|
-----
|
|
|
|
Kolla ships with several utilities intended to facilitate ease of operation.
|
|
|
|
``tools/cleanup-containers`` is used to remove deployed containers from the
|
|
system. This can be useful when you want to do a new clean deployment. It will
|
|
preserve the registry and the locally built images in the registry, but will
|
|
remove all running Kolla containers from the local Docker daemon. It also
|
|
removes the named volumes.
|
|
|
|
``tools/cleanup-host`` is used to remove remnants of network changes
|
|
triggered on the Docker host when the neutron-agents containers are launched.
|
|
This can be useful when you want to do a new clean deployment, particularly one
|
|
changing the network topology.
|
|
|
|
``tools/cleanup-images --all`` is used to remove all Docker images built by
|
|
Kolla from the local Docker cache.
|