From cb395e672b9da1d8fa78ada10074d66c1e5d81d1 Mon Sep 17 00:00:00 2001 From: Steve Baker Date: Tue, 7 Mar 2023 09:25:53 +1300 Subject: [PATCH] Document diskimage-builder command Change-Id: I607ecb4adee9cf2e2db98142fe5274f4c12f5ab0 --- doc/source/developer/components.rst | 54 +++++++++++++++++++++ doc/source/user_guide/building_an_image.rst | 25 ++++++++++ doc/source/user_guide/installation.rst | 4 +- 3 files changed, 81 insertions(+), 2 deletions(-) diff --git a/doc/source/developer/components.rst b/doc/source/developer/components.rst index df9b675d..4f213b83 100644 --- a/doc/source/developer/components.rst +++ b/doc/source/developer/components.rst @@ -24,6 +24,60 @@ Components Ironic no longer supports images created like this. +`diskimage-builder [--dry-run] [--stop-on-failure] [--help] filename.yaml [filename2.yaml...]` + + A YAML defined wrapper over `disk-image-create` and `ramdisk-image-create`. + + To generate kernel+ramdisk pair for use with nova-baremetal, specify the YAML: + + .. code-block:: yaml + + - imagename: deploy.ramdisk + ramdisk: true + elements: + - deploy-baremetal + + Duplicate `imagename` entries are merged into a single entry, allowing customizations over + a base image definition. If an `imagename` is missing, the `imagename` from the previous + entry is implied: + + .. code-block:: yaml + + # base image definition + - imagename: output.qcow + elements: + - vm + - block-device-gpt + - ubuntu-minimal + debug-trace: 1 + environment: + DIB_IMAGE_SIZE: '10' + + # debug logging customization + - imagename: output.qcow + debug-trace: 2 + + # adding element customization + - elements: + - devuser + environment: + DIB_DEV_USER_USERNAME: 'myuser' + DIB_DEV_USER_PWDLESS_SUDO: 'Yes' + DIB_DEV_USER_AUTHORIZED_KEYS: '/home/myuser/.ssh/id_rsa.pub' + + # resulting image entry which will be built + - imagename: output.qcow + elements: + - vm + - block-device-gpt + - ubuntu-minimal + - devuser + debug-trace: 2 + environment: + DIB_DEV_USER_USERNAME: 'myuser' + DIB_DEV_USER_PWDLESS_SUDO: 'Yes' + DIB_DEV_USER_AUTHORIZED_KEYS: '/home/myuser/.ssh/id_rsa.pub' + DIB_IMAGE_SIZE: '10' `element-info` diff --git a/doc/source/user_guide/building_an_image.rst b/doc/source/user_guide/building_an_image.rst index 97c9d2fb..fbdb1079 100644 --- a/doc/source/user_guide/building_an_image.rst +++ b/doc/source/user_guide/building_an_image.rst @@ -19,6 +19,24 @@ The following command will start our image build (distro must be either This will create a qcow2 file 'image.qcow2' which can then be booted. +Images can also be defined with YAML and built with the `diskimage-builder`. + +With an `image.yaml` file containing: + +.. code-block:: yaml + + - elements: + - + - vm + +An image is built with: + +:: + + diskimage-builder image.yaml + +Run `diskimage-builder --help` full description of the YAML attributes supported. + Elements -------- @@ -79,6 +97,13 @@ There are currently two defaults: disk-image-create -o output.qcow vm block-device-gpt ubuntu-minimal + Or with `diskimage-builder` YAML + + .. code-block:: yaml + + - imagename: output.qcow + elements: [vm, block-device-gpt, ubuntu-minimal] + * When not using the ``vm`` element a plain filesystem image, without any partitioning, is created. diff --git a/doc/source/user_guide/installation.rst b/doc/source/user_guide/installation.rst index 2ffe2c79..80a1671a 100644 --- a/doc/source/user_guide/installation.rst +++ b/doc/source/user_guide/installation.rst @@ -7,8 +7,8 @@ to keep it separate. For details, see the installation section in the :ref:`dev_install`. Once installed, you will be able to :doc:`build images -` using ``disk-image-create`` and the elements -included in the main ``diskimage-builder`` repository. +` using ``disk-image-create`` or ``diskimage-builder`` +and the elements included in the main ``diskimage-builder`` repository. Requirements