Merge pull request #23 from stackhpc/dib-backports

Backport all overcloud DIB patches

ansible/overcloud-host-image-build.yml

@@ -1,19 +1,24 @@
 ---
-# Build and install a overcloud host disk image for the seed host's ironic
+# Build and install overcloud host disk images for the seed host's ironic
 # service.
 
-- name: Ensure overcloud host disk image is built and installed
+- name: Ensure overcloud host disk images are built and installed
   hosts: seed
   tags:
     - overcloud-host-image-build
   vars:
-    overcloud_host_image_name: "deployment_image"
-    overcloud_host_disk_images:
-      - "{{ overcloud_host_image_name }}.qcow2"
     overcloud_host_image_force_rebuild: False
   tasks:
     - block:
-        - name: Ensure overcloud host disk image is built
+        - name: Validate overcloud host disk image configuration
+          assert:
+            that:
+              - overcloud_dib_host_images is sequence
+              - overcloud_dib_host_images | selectattr('name', 'undefined') | list | length == 0
+              - overcloud_dib_host_images | selectattr('elements', 'undefined') | list | length == 0
+            msg: "overcloud_dib_host_images set to invalid value"
+
+        - name: Ensure overcloud host disk images are built
           include_role:
             name: stackhpc.os-images
           vars:
@@ -22,30 +27,18 @@
             os_images_upper_constraints_file: "{{ overcloud_dib_upper_constraints_file }}"
             os_images_cache: "{{ image_cache_path }}"
             os_images_common: ""
-            os_images_list:
-              - name: "{{ overcloud_host_image_name }}"
-                elements: "{{ overcloud_dib_elements }}"
-                env: "{{ overcloud_dib_env_vars }}"
-                packages: "{{ overcloud_dib_packages }}"
-                type: qcow2
+            os_images_list: "{{ overcloud_dib_host_images }}"
+            os_images_git_elements: "{{ overcloud_dib_git_elements }}"
             os_images_upload: False
             os_images_force_rebuild: "{{ overcloud_host_image_force_rebuild }}"
 
-        - name: Ensure overcloud host disk image is copied onto seed
+        - name: Copy overcloud host disk images into /httpboot
           copy:
-            src: "{{ image_cache_path }}/{{ overcloud_host_image_name }}/{{ item }}"
-            dest: "/etc/kolla/bifrost/{{ item }}"
+            src: "{{ image_cache_path }}/{{ image.name }}/{{ image.name }}.{{ image.type | default('qcow2') }}"
+            dest: "/var/lib/docker/volumes/bifrost_httpboot/_data/{{ image.name }}.{{ image.type | default('qcow2') }}"
             remote_src: True
-          with_items: "{{ overcloud_host_disk_images }}"
+          with_items: "{{ overcloud_dib_host_images }}"
+          loop_control:
+            loop_var: image
           become: True
-
-        - name: Copy overcloud host disk image into /httpboot
-          command: >
-            docker exec bifrost_deploy
-            bash -c 'ansible -vvvv target
-            -i /bifrost/playbooks/inventory/target
-            -m copy
-            -a "src=/etc/bifrost/{{ item }} dest=/httpboot/{{ item }}"
-            -e "ansible_python_interpreter=/var/lib/kolla/venv/bin/python"'
-          with_items: "{{ overcloud_host_disk_images }}"
       when: overcloud_dib_build_host_images | bool

doc/source/configuration/reference/bifrost.rst

@@ -39,6 +39,11 @@ For example, to install Bifrost from a custom git repository:
 Overcloud root disk image configuration
 =======================================
 
+.. note::
+
+   This configuration only applies when ``overcloud_dib_build_host_images``
+   (set in ``${KAYOBE_CONFIG_PATH}/overcloud-dib.yml``) is not changed to true.
+
 Bifrost uses Diskimage builder (DIB) to build a root disk image that is
 deployed to overcloud hosts when they are provisioned. The following options
 configure how this image is built.  Consult the
@@ -179,6 +184,8 @@ Rather than needing to write a custom DIB element, we can use the
    kolla_bifrost_dib_packages:
      - "biosdevname"
 
+.. _configuration-bifrost-image-deployment-config:
+
 Disk image deployment configuration
 ===================================
 
@@ -189,11 +196,10 @@ The name of the root disk image to deploy can be configured via the
 Kayobe inventory. This can be used to provision different images across the
 overcloud.
 
-.. note::
-
-   Support for building multiple disk images is not yet available. Images can
-   be manually renamed before changing the Kayobe configuration to build a
-   different image.
+While only a single disk image can be built with Bifrost, starting from the
+Yoga 12.0.0 release, Kayobe supports building multiple disk images directly
+through Diskimage builder. Consult the :ref:`overcloud host disk image build
+documentation <overcloud-dib>` for more details.
 
 Ironic configuration
 ====================

doc/source/configuration/reference/index.rst

@@ -18,6 +18,7 @@ options.
    kolla
    kolla-ansible
    bifrost
+   overcloud-dib
    ironic-python-agent
    docker-registry
    seed-custom-containers

doc/source/configuration/reference/os-distribution.rst

@@ -1,3 +1,5 @@
+.. _os-distribution:
+
 ===============
 OS Distribution
 ===============

doc/source/configuration/reference/overcloud-dib.rst

@@ -0,0 +1,242 @@
+.. _overcloud-dib:
+
+===============================
+Overcloud host disk image build
+===============================
+
+This section covers configuration for building overcloud host disk images with
+Diskimage builder (DIB), which is available from the Yoga 12.0.0 release. This
+configuration is applied in ``${KAYOBE_CONFIG_PATH}/overcloud-dib.yml``.
+
+Enabling host disk image build
+==============================
+
+From the Yoga release, disk images for overcloud hosts can be built directly
+using Diskimage builder rather than through Bifrost. This is enabled with the
+following option:
+
+``overcloud_dib_build_host_images``
+    Whether to build host disk images with DIB directly instead of through
+    Bifrost. Setting it to true disables Bifrost image build and allows images
+    to be built with the ``kayobe overcloud host image build`` command. Default
+    value is false. This will change in a future release.
+
+With this option enabled, Bifrost will be configured to stop building a root
+disk image. This will become the default behaviour in a future release.
+
+Overcloud root disk image configuration
+=======================================
+
+Kayobe uses Diskimage builder (DIB) to build root disk images that are deployed
+to overcloud hosts when they are provisioned. The following options configure
+how these images are built. Consult the
+:diskimage-builder-doc:`Diskimage-builder documentation <>` for further
+information on building disk images.
+
+The default configuration builds a whole disk (partitioned) image using the
+selected :ref:`OS distribution <os-distribution>` (CentOS Stream 8 by default)
+with serial console enabled, and SELinux disabled if CentOS Stream is used.
+`Cloud-init <https://cloudinit.readthedocs.io/en/latest/>`__ is used to process
+the configuration drive built by Bifrost during provisioning.
+
+``overcloud_dib_host_images``
+    List of overcloud host disk images to build. Each element is a dict
+    defining an image in a format accepted by the `stackhpc.os-images
+    <https://galaxy.ansible.com/stackhpc/os-images>`__ role. Default is to
+    build an image named ``deployment_image`` configured with the
+    ``overcloud_dib_*`` variables defined below: ``{"name": "deployment_image",
+    "elements": "{{ overcloud_dib_elements }}", "env": "{{
+    overcloud_dib_env_vars }}", "packages": "{{ overcloud_dib_packages }}"}``.
+``overcloud_dib_os_element``
+    DIB base OS element. Default is ``{{ os_distribution }}``.
+``overcloud_dib_os_release``
+    DIB image OS release. Default is ``{{ os_release }}``.
+``overcloud_dib_elements_default``
+    List of default DIB elements. Default is ``["centos",
+    "cloud-init-datasources", "disable-selinux", "enable-serial-console",
+    "vm"]`` when ``overcloud_dib_os_element`` is ``centos``, or ``["ubuntu",
+    "cloud-init-datasources", "enable-serial-console", "vm"]`` when
+    ``overcloud_dib_os_element`` is ``ubuntu``. The ``vm`` element is poorly
+    named, and causes DIB to build a whole disk image rather than a single
+    partition.
+``overcloud_dib_elements_extra``
+    List of additional DIB elements. Default is none.
+``overcloud_dib_elements``
+    List of DIB elements. Default is a combination of ``overcloud_dib_elements_default``
+    and ``overcloud_dib_elements_extra``.
+``overcloud_dib_env_vars_default``
+    DIB default environment variables. Default is
+    ``{"DIB_BOOTLOADER_DEFAULT_CMDLINE": "nofb nomodeset gfxpayload=text
+    net.ifnames=1", "DIB_CLOUD_INIT_DATASOURCES": "ConfigDrive", "DIB_RELEASE":
+    "{{ overcloud_dib_os_release }}"}``.
+``overcloud_dib_env_vars_extra``
+    DIB additional environment variables. Default is none.
+``overcloud_dib_env_vars``
+    DIB environment variables. Default is combination of
+    ``overcloud_dib_env_vars_default`` and
+    ``overcloud_dib_env_vars_extra``.
+``overcloud_dib_packages``
+    List of DIB packages to install. Default is to install no extra packages.
+``overcloud_dib_git_elements_default``
+    List of default git repositories containing Diskimage Builder (DIB)
+    elements. See stackhpc.os-images role for usage. Default is empty.
+``overcloud_dib_git_elements_extra``
+    List of additional git repositories containing Diskimage Builder (DIB)
+    elements. See stackhpc.os-images role for usage. Default is empty.
+``overcloud_dib_git_elements``
+    List of git repositories containing Diskimage Builder (DIB) elements. See
+    stackhpc.os-images role for usage. Default is a combination of
+    ``overcloud_dib_git_elements_default`` and
+    ``overcloud_dib_git_elements_extra``.
+``overcloud_dib_upper_constraints_file``
+    Upper constraints file for installing packages in the virtual environment
+    used for building overcloud host disk images. Default is ``{{
+    pip_upper_constraints_file }}``.
+
+Disk images are built with the following command:
+
+.. code-block:: console
+
+   (kayobe) $ kayobe overcloud host image build
+
+It is worth noting that images will not be rebuilt if they already exist. To
+force rebuilding images, it is necessary to use the ``--force-rebuild``
+argument.
+
+.. code-block:: console
+
+   (kayobe) $ kayobe overcloud host image build --force-rebuild
+
+Example: Adding an element
+--------------------------
+
+In the following, we extend the list of DIB elements to add the ``growpart``
+element:
+
+.. code-block:: yaml
+   :caption: ``dib.yml``
+
+   overcloud_dib_elements_extra:
+     - "growpart"
+
+Example: Building an XFS root filesystem image
+----------------------------------------------
+
+By default, DIB will format the image as ``ext4``. In some cases it might be
+useful to use XFS, for example when using the ``overlay`` Docker storage driver
+which can reach the maximum number of hardlinks allowed by ``ext4``.
+
+In DIB, we achieve this by setting the ``FS_TYPE`` environment variable to
+``xfs``.
+
+.. code-block:: yaml
+   :caption: ``dib.yml``
+
+   overcloud_dib_env_vars_extra:
+     FS_TYPE: "xfs"
+
+Example: Configuring a development user account
+-----------------------------------------------
+
+.. warning::
+
+   A development user account should not be used in production.
+
+When debugging a failed deployment, it can sometimes be necessary to allow
+access to the image via a preconfigured user account with a known password.
+This can be achieved via the :diskimage-builder-doc:`devuser
+<elements/devuser/README>` element.
+
+This example shows how to add the ``devuser`` element, and configure a username
+and password for an account that has passwordless sudo:
+
+.. code-block:: yaml
+   :caption: ``dib.yml``
+
+   overcloud_dib_elements_extra:
+     - "devuser"
+
+   overcloud_dib_env_vars_extra:
+     DIB_DEV_USER_USERNAME: "devuser"
+     DIB_DEV_USER_PASSWORD: "correct horse battery staple"
+     DIB_DEV_USER_PWDLESS_SUDO: "yes"
+
+Alternatively, the :diskimage-builder-doc:`dynamic-login element
+<elements/dynamic-login/README>` can be used to authorize SSH keys by appending
+them to the kernel arguments.
+
+Example: Configuring custom DIB elements
+----------------------------------------
+
+Sometimes it is useful to use custom DIB elements that are not shipped with DIB
+itself. This can be done by sharing them in a git repository.
+
+.. code-block:: yaml
+   :caption: ``overcloud-dib.yml``
+
+   overcloud_dib_elements_extra:
+     - "my-element"
+
+   overcloud_dib_git_elements:
+     - repo: "https://git.example.com/custom-dib-elements"
+       local: "{{ source_checkout_path }}/custom-dib-elements"
+       version: "master"
+       elements_path: "elements"
+
+In this example the ``master`` branch of
+https://git.example.com/custom-dib-elements would have a top level ``elements``
+directory, containing a ``my-element`` directory for the element.
+
+Example: Installing a package
+-----------------------------
+
+It can be necessary to install additional packages in the root disk image.
+Rather than needing to write a custom DIB element, we can use the
+``overcloud_dib_packages`` variable. For example, to install the
+``biosdevname`` package:
+
+.. code-block:: yaml
+   :caption: ``dib.yml``
+
+   overcloud_dib_packages:
+     - "biosdevname"
+
+Example: Building multiple images
+---------------------------------
+
+It can be necessary to build multiple images to support the various types of
+hardware present in a deployment or the different functions performed by
+overcloud hosts. This can be configured with the ``overcloud_dib_host_images``
+variable, using a format accepted by the `stackhpc.os-images
+<https://galaxy.ansible.com/stackhpc/os-images>`__ role. Note that image names
+should not include the file extension.  For example, to build a second image
+with a development user account and the ``biosdevname`` package:
+
+.. code-block:: yaml
+   :caption: ``dib.yml``
+
+   overcloud_dib_host_images:
+     - name: "deployment_image"
+       elements: "{{ overcloud_dib_elements }}"
+       env: "{{ overcloud_dib_env_vars }}"
+       packages: "{{ overcloud_dib_packages }}"
+     - name: "debug_deployment_image"
+       elements: "{{ overcloud_dib_elements + ['devuser'] }}"
+       env: "{{ overcloud_dib_env_vars | combine(devuser_env_vars) }}"
+       packages: "{{ overcloud_dib_packages + ['biosdevname'] }}"
+
+   devuser_env_vars:
+     DIB_DEV_USER_USERNAME: "devuser"
+     DIB_DEV_USER_PASSWORD: "correct horse battery staple"
+     DIB_DEV_USER_PWDLESS_SUDO: "yes"
+
+Running the ``kayobe overcloud host image build`` command with this
+configuration will create two images: ``deployment_image.qcow2`` and
+``debug_deployment_image.qcow2``.
+
+Disk image deployment configuration
+===================================
+
+See :ref:`disk image deployment configuration in
+Bifrost<configuration-bifrost-image-deployment-config>` for how to configure
+the root disk image to be used to provision each host.