Add documentation for bootstrap-servers command

Change-Id: I3bd50cb1e7db85acbf8ab20fc7bdd945b5232aaa

doc/source/reference/deployment-and-bootstrapping/bootstrap-servers.rst

+=====================
+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, particuarly 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 futher 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.

doc/source/reference/deployment-and-bootstrapping/index.rst

@@ -9,3 +9,4 @@ hosts.
    :maxdepth: 1
 
    bifrost
+   bootstrap-servers

doc/source/user/virtual-environments.rst

@@ -49,6 +49,8 @@ Note that the use of a virtual environment on the Ansible control host does not
 imply that a virtual environment will be used for execution of Ansible modules
 on the target hosts.
 
+.. _virtual-environments-target-hosts:
+
 Target Hosts
 ============