Skip to content
Snippets Groups Projects
overcloud-dib.rst 8.1 KiB
Newer Older
  • Learn to ignore specific revisions
  • .. _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_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: 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.