Merge "docs: Improve all-in-one scenario"

doc/source/configuration/scenarios/all-in-one/index.rst

@@ -2,8 +2,39 @@
 All in one scenario
 ===================
 
+.. note::
+   This documentation is intended as a walk through of the configuration
+   required for a minimal all-in-one overcloud host. If you are looking
+   for an all-in-one environment for test or development, see
+   :ref:`contributor-automated`.
+
 This scenario describes how to configure an all-in-one controller and compute
-node using Kayobe.
+node using Kayobe. This is a very minimal setup, and not one that is
+recommended for a production environment, but is useful for learning about how
+to use and configure Kayobe.
+
+.. _configuration-scenario-aio-prerequisites:
+
+Prerequisites
+=============
+
+This scenario requires a basic understanding of Linux, networking and
+OpenStack.
+
+It also requires a single host running a :ref:`supported operating system
+<support-matrix-supported-os>` (VM or bare metal), with:
+
+* 1 CPU
+* 8GB RAM
+* 40GB disk
+* at least one network interface that has Internet access
+
+You will need access to a user account with passwordless sudo. The default user
+in a cloud image (e.g. ``centos`` or ``ubuntu``) is typically sufficient. This
+user will be used to run Kayobe commands. It will also be used by Kayobe to
+bootstrap other user accounts.
+
+.. _configuration-scenario-aio-overview:
 
 Overview
 ========
@@ -18,11 +49,11 @@ required configuration in Kayobe::
        |                           |
        |                           |
        |      +-------------+      |
-       |      |             |      |
+       |      |             |+     |
-       |      |  Containers |      |
+       |      |  Containers ||     |
-       |      |             |      |
+       |      |             ||     |
-       |      +-------------+      |
+       |      +-------------+|     |
-       |                           |
+       |       +-------------+     |
        |                           |
        +---------+-------+---------+
                  |       |
@@ -33,18 +64,40 @@ required configuration in Kayobe::
                      |
    +-----------------+------------------+ Internet
 
+The networking in particular is relatively simple. The main interface of the
+overcloud host, labelled NIC 1 in the above diagram, will be used only for
+connectivity to the host and Internet access. A single Kayobe network called
+``aio`` carries all control plane traffic, and is based on virtual networking
+that is local to the host.
 
-Prerequisites
+Later in this tutorial, we will create a dummy interface called ``dummy0``, and
-=============
+plug it into a bridge called ``br0``::
 
-This scenario requires:
+    +--------------+
+    |              |
+    |      OVS     |
+    |              |
+    +--------------+
+            |
+            |
+    +--------------+
+    |              |
+    |      br0     |
+    | 192.168.33.3 |
+    | 192.168.33.2 |
+    +--------------+
+       | dummy0 |
+       +--------+
 
-* a basic understanding of Linux, networking and OpenStack
+The use of a bridge here allows Kayobe to connect this network to the Open
-* a single host running a :ref:`supported operating system
+vSwitch network, while maintaining an IP address on the bridge. Ordinarily,
-  <support-matrix-supported-os>` (VM or bare metal)
+``dummy0`` would be a NIC providing connectivity to a physical network. We're
-* at least one network interface that has Internet access
+using a dummy interface here to keep things simple by using a fixed IP subnet,
-* an IP subnet with a free IP address for the OpenStack API virtual IP, and a
+``192.168.33.0/24``. The bridge will be assigned a static IP address of
-  range of free IP addresses for external network access
+``192.168.33.3``, and this address will by used for various things, including
+Ansible SSH access and OpenStack control plane traffic. Kolla Ansible will
+manage a Virtual IP (VIP) address of ``192.168.33.2`` on ``br0``, which will be
+used for OpenStack API endpoints.
 
 Contents
 ========

doc/source/configuration/scenarios/all-in-one/overcloud.rst

@@ -8,13 +8,35 @@ Overcloud
    for an all-in-one environment for test or development, see
    :ref:`contributor-automated`.
 
+Preparation
+===========
+
+Use the bootstrap user described in :ref:`prerequisites
+<configuration-scenario-aio-prerequisites>` to access the machine.
+
+As described in the :ref:`overview <configuration-scenario-aio-overview>`, we
+will use a bridge (``br0``) and a dummy interface (``dummy0``) for control
+plane networking. Use the following commands to create them and assign the
+bridge a static IP address of ``192.168.33.3``:
+
+.. code-block:: console
+
+   sudo ip l add br0 type bridge
+   sudo ip l set br0 up
+   sudo ip a add 192.168.33.3/24 dev br0
+   sudo ip l add dummy0 type dummy
+   sudo ip l set dummy0 up
+   sudo ip l set dummy0 master br0
+
+This configuration is not persistent, and must be recreated if the VM is
+rebooted.
+
 Installation
 ============
 
-SSH to the overcloud machine, then follow the instructions in
+Follow the instructions in :doc:`/installation` to set up an Ansible control
-:doc:`/installation` to set up an Ansible control host environment.
+host environment.  Typically this would be on a separate machine, but here we
-Typically this would be on a separate machine, but here we are keeping things
+are keeping things as simple as possible.
-as simple as possible.
 
 Configuration
 =============
@@ -56,21 +78,19 @@ compute nodes would be used.
 
 The ``inventory`` directory also contains group variables for network interface
 configuration. In this example we will assume that the machine has a single
-network interface called ``eth0``. We will create a bridge called ``breth0``
+network interface called ``dummy0``. We will create a bridge called ``br0``
-and plug ``eth0`` into it. This allows us to move the host's IP address to the
+and plug ``dummy0`` into it.  Replace the network interface configuration for
-bridge, and pass traffic through to an Open vSwitch bridge for Neutron. Replace
+the ``controllers`` group with the following:
-the network interface configuration for the ``controllers`` group with the
-following, replacing ``eth0`` with an appropriate interface:
 
 .. code-block:: yaml
    :caption: ``etc/kayobe/inventory/group_vars/controllers/network-interfaces``
 
    # Controller interface on all-in-one network.
-   aio_interface: breth0
+   aio_interface: br0
 
-   # Interface eth0 is plugged into the all-in-one network bridge.
+   # Interface dummy0 is plugged into the all-in-one network bridge.
    aio_bridge_ports:
-     - eth0
+     - dummy0
 
 In this scenario a single network called ``aio`` is used. We must therefore set
 the name of the default controller networks to ``aio``:
@@ -170,7 +190,6 @@ address of the OpenStack API.
 
    # All-in-one network.
    aio_cidr: 192.168.33.0/24
-   aio_gateway: 192.168.33.1
    aio_vip_address: 192.168.33.2
 
    ###############################################################################
@@ -196,9 +215,31 @@ the ``os_distribution`` variable in ``etc/kayobe/globals.yml`` to ``ubuntu``.
 .. code-block:: yaml
    :caption: ``etc/kayobe/globals.yml``
 
-   ---
    os_distribution: "ubuntu"
 
+Kayobe uses a bootstrap user to create a ``stack`` user account. By default,
+this user is ``centos`` on CentOS, and ``ubuntu`` on Ubuntu, in line with the
+default user in the official cloud images. If you are using a different
+bootstrap user, set the ``controller_bootstrap_user`` variable in
+``etc/kayobe/controllers.yml``. For example, to set it to ``cloud-user`` (as
+seen in MAAS):
+
+.. code-block:: yaml
+   :caption: ``etc/kayobe/controllers.yml``
+
+   controller_bootstrap_user: "cloud-user"
+
+By default, on systems with SELinux enabled, Kayobe will disable SELinux and
+reboot the system to apply the change. In a test or development environment
+this can be a bit disruptive, particularly when using ephemeral network
+configuration.  To avoid rebooting the system after disabling SELinux, set
+``disable_selinux_do_reboot`` to ``false`` in ``etc/kayobe/globals.yml``.
+
+.. code-block:: yaml
+   :caption: ``etc/kayobe/globals.yml``
+
+   disable_selinux_do_reboot: false
+
 In a development environment, we may wish to tune some Kolla Ansible variables.
 Using QEMU as the virtualisation type will be necessary if KVM is not
 available. Reducing the number of OpenStack service workers helps to avoid
@@ -207,7 +248,6 @@ using too much memory.
 .. code-block:: yaml
    :caption: ``etc/kayobe/kolla/globals.yml``
 
-   ---
    # Most development environments will use nested virtualisation, and we can't
    # guarantee that nested KVM support is available. Use QEMU as a lowest common
    # denominator.
@@ -217,10 +257,62 @@ using too much memory.
    # processes to one per-service.
    openstack_service_workers: "1"
 
+We can see the changes that have been made to the configuration.
+
+.. code-block:: console
+
+   cd <base path>/src/kayobe-config
+   git status
+
+   On branch master
+   Your branch is up to date with 'origin/master'.
+
+   Changes to be committed:
+     (use "git restore --staged <file>..." to unstage)
+       deleted:    etc/kayobe/inventory/hosts.example
+
+   Changes not staged for commit:
+     (use "git add <file>..." to update what will be committed)
+     (use "git restore <file>..." to discard changes in working directory)
+       modified:   etc/kayobe/globals.yml
+       modified:   etc/kayobe/inventory/group_vars/controllers/network-interfaces
+       modified:   etc/kayobe/kolla/globals.yml
+       modified:   etc/kayobe/networks.yml
+
+   Untracked files:
+     (use "git add <file>..." to include in what will be committed)
+       etc/kayobe/inventory/hosts
+       etc/kayobe/network-allocation.yml
+
+The ``git diff`` command is also helpful. Once all configuration changes have
+been made, they should be committed to the kayobe-config git repository.
+
+.. code-block:: console
+
+   cd <base path>/src/kayobe-config
+   git add etc/kayobe/inventory/hosts etc/kayobe/network-allocation.yml
+   git add --update
+   git commit -m "All in one scenario config"
+
+In a real environment these changes would be pushed to a central repository.
+
+Deployment
+==========
+
+We are now ready to perform a deployment.
+
+Activate the Kayobe virtual environment:
+
+.. code-block:: console
+
+   cd <base path>/venvs/kayobe
+   source bin/activate
+
 Activate the Kayobe configuration environment:
 
 .. code-block:: console
 
+   cd <base path>/src/kayobe-config
    source kayobe-env
 
 Bootstrap the control host:
@@ -235,13 +327,19 @@ Configure the overcloud host:
 
    kayobe overcloud host configure
 
-The previous command is likely to reboot the machine to disable SELinux. SSH
+After this command has run, some files in the kayobe-config repository will
-again when it has booted, activate the Kayobe environment and complete the host
+have changed. Kayobe performs static allocation of IP addresses, and tracks
-configuration:
+them in ``etc/kayobe/network-allocation.yml``. Normally there may be changes to
+this file, but in this case we manually added the IP address of ``controller0``
+earlier. Kayobe uses tools provided by Kolla Ansible to generate passwords, and
+stores them in ``etc/kayobe/kolla/passwords.yml``. It is important to track
+changes to this file.
 
 .. code-block:: console
 
-   kayobe overcloud host configure
+   cd <base path>/src/kayobe-config
+   git add etc/kayobe/kolla/passwords.yml
+   git commit -m "Add autogenerated passwords for Kolla Ansible"
 
 Pull overcloud container images:
 
@@ -255,13 +353,8 @@ Deploy overcloud services:
 
    kayobe overcloud service deploy
 
-There is an issue with Docker where it changes the default policy of the
+Testing
-``FORWARD`` chain to ``DROP``. This prevents traffic traversing the bridge.
+=======
-Revert this change:
-
-.. code-block:: console
-
-   sudo iptables -P FORWARD ACCEPT
 
 The ``init-runonce`` script provided by Kolla Ansible (not for production) can
 be used to setup some resources for testing. This includes:
@@ -281,18 +374,23 @@ pool range containing free IP addresses:
 
    pip install python-openstackclient
    export EXT_NET_CIDR=192.168.33.0/24
-   export EXT_NET_GATEWAY=192.168.33.1
+   export EXT_NET_GATEWAY=192.168.33.3
    export EXT_NET_RANGE="start=192.168.33.4,end=192.168.33.254"
    source "${KOLLA_CONFIG_PATH:-/etc/kolla}/admin-openrc.sh"
    ${KOLLA_SOURCE_PATH}/tools/init-runonce
 
 Create a server instance, assign a floating IP address, and check that it is
-accessible. The floating IP address is displayed after it is created, in this
+accessible.
-example it is ``192.168.33.4``:
 
 .. code-block:: console
 
    openstack server create --image cirros --flavor m1.tiny --key-name mykey --network demo-net demo1
    openstack floating ip create public1
+
+The floating IP address is displayed after it is created, in this example it is
+``192.168.33.4``:
+
+.. code-block:: console
+
    openstack server add floating ip demo1 192.168.33.4
    ssh cirros@192.168.33.4