224 lines
8.5 KiB
ReStructuredText
224 lines
8.5 KiB
ReStructuredText
=====================
|
|
Bootstrapping Servers
|
|
=====================
|
|
|
|
Kolla-ansible provides support for bootstrapping host configuration prior to
|
|
deploying containers via the ``bootstrap-servers`` subcommand. This includes
|
|
support for the following:
|
|
|
|
* Customisation of ``/etc/hosts``
|
|
* Creation of user and group
|
|
* Kolla configuration directory
|
|
* Package installation and removal
|
|
* Docker engine installation and configuration
|
|
* Disabling firewalls
|
|
* Creation of Python virtual environment
|
|
* Configuration of Apparmor
|
|
* Configuration of SELinux
|
|
* Configuration of NTP daemon
|
|
|
|
All bootstrapping support is provided by the ``baremetal`` Ansible role.
|
|
|
|
Running the command
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
The base command to perform a bootstrap is:
|
|
|
|
.. code-block:: console
|
|
|
|
kolla-ansible bootstrap-servers -i INVENTORY
|
|
|
|
Further options may be necessary, as described in the following sections.
|
|
|
|
Initial bootstrap considerations
|
|
--------------------------------
|
|
|
|
The nature of bootstrapping means that the environment that Ansible executes in
|
|
during the initial bootstrap may look different to that seen after
|
|
bootstrapping is complete. For example:
|
|
|
|
* The ``kolla_user`` user account may not yet have been created. If this is
|
|
normally used as the ``ansible_user`` when executing Kolla Ansible, a
|
|
different user account must be used for bootstrapping.
|
|
* The Python virtual environment may not exist. If a virtualenv is normally
|
|
used as the ``ansible_python_interpreter`` when executing Kolla Ansible, the
|
|
system python interpreter must be used for bootstrapping.
|
|
|
|
Each of these variables may be passed via the ``-e`` argument to Kolla Ansible
|
|
to override the inventory defaults:
|
|
|
|
.. code-block:: console
|
|
|
|
kolla-ansible bootstrap-servers -i INVENTORY -e ansible_user=<bootstrap user> -e ansible_python_interpreter=/usr/bin/python
|
|
|
|
Subsequent bootstrap considerations
|
|
-----------------------------------
|
|
|
|
It is possible to run the bootstrapping process against a cloud that has
|
|
already been bootstrapped, for example to apply configuration from a newer
|
|
release of Kolla Ansible. In this case, further considerations should be
|
|
made.
|
|
|
|
It is possible that the Docker engine package will be updated. This will cause
|
|
the Docker engine to restart, in addition to all running containers. There are
|
|
three main approaches to avoiding all control plane services restarting
|
|
simultaneously.
|
|
|
|
The first option is to use the ``--limit`` command line argument to apply the
|
|
command to hosts in batches, ensuring there is always a quorum for clustered
|
|
services (e.g. MariaDB):
|
|
|
|
.. code-block:: console
|
|
|
|
kolla-ansible bootstrap-servers -i INVENTORY --limit controller0,compute[0-1]
|
|
kolla-ansible bootstrap-servers -i INVENTORY --limit controller1,compute[2-3]
|
|
kolla-ansible bootstrap-servers -i INVENTORY --limit controller2,compute[4-5]
|
|
|
|
The second option is to execute individual plays on hosts in batches:
|
|
|
|
.. code-block:: console
|
|
|
|
kolla-ansible bootstrap-servers -i INVENTORY -e kolla_serial=30%
|
|
|
|
The last option is to use the Docker ``live-restore`` configuration option to
|
|
avoid restarting containers when the Docker engine is restarted. There have
|
|
been issues reported with using this option however, so use it at your own
|
|
risk.
|
|
|
|
Ensure that any operation that causes the Docker engine to be updated has been
|
|
tested, particularly when moving from legacy Docker packages to Docker
|
|
Community Edition. See :ref:`bootstrap-servers-docker-package-repos` for
|
|
details.
|
|
|
|
Customisation of ``/etc/hosts``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This is optional, and enabled by ``customize_etc_hosts``, which is ``true`` by
|
|
default.
|
|
|
|
* Ensures that ``localhost`` is in ``/etc/hosts``
|
|
* Adds an entry for the IP of the API interface of each host to ``/etc/hosts``.
|
|
|
|
Creation of user and group
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This is optional, and enabled by ``create_kolla_user``, which is ``true`` by
|
|
default.
|
|
|
|
* Ensures that a group exists with the name defined by the variable
|
|
``kolla_group`` with default ``kolla``.
|
|
* Ensures that a user exists with the name defined by the variable
|
|
``kolla_user`` with default ``kolla``. The user's primary group is defined by
|
|
``kolla_group``. The user is added to the ``sudo`` group.
|
|
* An SSH public key is authorised for ``kolla_user``. The key is defined by
|
|
the ``public_key`` value of the ``kolla_ssh_key`` mapping variable, typically
|
|
defined in ``passwords.yml``.
|
|
* If the ``create_kolla_user_sudoers`` variable is set, a sudoers profile
|
|
will be configured for ``kolla_user``, which grants passwordless sudo.
|
|
|
|
Kolla configuration directory
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Kolla ansible service configuration is written to hosts in a directory defined
|
|
by ``node_config_directory``, which by default is ``/etc/kolla/``. This
|
|
directory will be created. If ``create_kolla_user`` is set, the owner and group
|
|
of the directory will be set to ``kolla_user`` and ``kolla_group``
|
|
respectively.
|
|
|
|
Package installation and removal
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Lists of packages are defined for installation and removal. On Debian family
|
|
systems, these are defined by ``debian_pkg_install`` and
|
|
``ubuntu_pkg_removals`` respectively. On Red Hat family systems, these are
|
|
defined by ``redhat_pkg_install`` and ``redhat_pkg_removals`` respectively.
|
|
|
|
Docker engine installation and configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Docker engine is a key dependency of Kolla Ansible, and various configuration
|
|
options are provided.
|
|
|
|
.. _bootstrap-servers-docker-package-repos:
|
|
|
|
Package repositories
|
|
--------------------
|
|
|
|
If the ``enable_docker_repo`` flag is set, then a package repository for Docker
|
|
packages will be configured. There are two sets of package repositories
|
|
provided by Docker - 'legacy' packages from https://dockerproject.org, and new
|
|
'Community Edition' packages from https://download.docker.com. To use legacy
|
|
packages, set ``docker_legacy_packages`` to ``true``, or to use new packages
|
|
set it to ``false``. The new packages are used by default.
|
|
|
|
Various other configuration options are available beginning
|
|
``docker[_(new|legacy)]_(apt|yum)_``. Typically these do not need to be
|
|
changed.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
The ``docker_storage_driver`` variable is optional. If set, it defines the
|
|
`storage (graph) driver
|
|
<https://docs.docker.com/storage/storagedriver/select-storage-driver/>`__ to
|
|
use for Docker.
|
|
|
|
The ``docker_runtime_directory`` variable is optional. If set, it defines the
|
|
runtime (``--graph``) directory for Docker.
|
|
|
|
The ``docker_registry`` variable, which is not set by default, defines the
|
|
address of the Docker registry. If the variable is not set, Dockerhub will be
|
|
used.
|
|
|
|
The ``docker_registry_insecure`` variable, which defaults to ``true`` if
|
|
``docker_registry`` is set, or ``false`` otherwise, defines whether to
|
|
configure ``docker_registry`` as an insecure registry. Insecure registries use
|
|
HTTP rather than HTTPS.
|
|
|
|
The ``docker_log_max_file`` variable, which defaults to ``5``, defines the
|
|
maximum number of log files to retain per container. The
|
|
``docker_log_max_size`` variable, which defaults to ``50m``, defines the
|
|
maximum size of each rotated log file per container.
|
|
|
|
The ``docker_custom_option`` variable is optional. If set, it defines
|
|
additional options to pass to the Docker engine via the Systemd unit file.
|
|
|
|
Disabling firewalls
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Kolla Ansible does not support configuration of host firewalls, and instead
|
|
attempts to disable them.
|
|
|
|
On Debian family systems where the UFW firewall is enabled, a default policy
|
|
will be added to allow all traffic.
|
|
|
|
On Red Hat family systems where firewalld is installed, it will be disabled.
|
|
|
|
Creation of Python virtual environment
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This is optional, and enabled by setting ``virtualenv`` to a path to a Python
|
|
virtual environment to create. By default, a virtual environment is not used.
|
|
If ``virtualenv_site_packages`` is set, (default is ``true``) the virtual
|
|
environment will inherit packages from the global site-packages directory. This
|
|
is typically required for modules such as yum and apt which are not available
|
|
on PyPI. See :ref:`virtual-environments-target-hosts` for further information.
|
|
|
|
Configuration of Apparmor
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
On Ubuntu systems, the ``libvirtd`` Apparmor profile will be removed.
|
|
|
|
Configuration of SELinux
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
On Red Hat family systems, if ``change_selinux`` is set (default is ``true``),
|
|
then the SELinux state will be set to ``selinux_state`` (default
|
|
``permissive``). See :doc:`../../user/security` for further information.
|
|
|
|
Configuration of NTP daemon
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This is optional, and enabled by ``enable_host_ntp``, which is ``false`` by
|
|
default.
|