From cb395e672b9da1d8fa78ada10074d66c1e5d81d1 Mon Sep 17 00:00:00 2001
From: Steve Baker <sbaker@redhat.com>
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:
+     - <distro>
+     - 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
-<building_an_image>` using ``disk-image-create`` and the elements
-included in the main ``diskimage-builder`` repository.
+<building_an_image>` using ``disk-image-create`` or ``diskimage-builder``
+and the elements included in the main ``diskimage-builder`` repository.
 
 
 Requirements