Update kernel command line docs (SC-1457) (#2133)

- describe kernel command line override
- add OpenStack Ironic selection instructions
- describe datasource selection
- move datasource creation doc to dev section
- remove generator stage from boot stages
- document how to disable cloud-init in howtos
- fix missing kernel-cmdline.rst link
- update outdated security advice

Document the following commits:

 34e8c914df666c937e48f5d1c3add0bd47e4e7eb
 f146fe71733e72b94fad525b8cc9988b1405e760
 250280ada67995a8449b64027b879d01939d2729
 612b4de892d19333c33276d541fed99fd16d3998
 a60c0845806baff72c74603286d048efbafab664
 d1ffbea556a06105d1ade88b4143ad43f53692c4
 02202954c65a7a1cdb9b28703bd0af01edd0e091

14 files changed, 363 insertions, 157 deletions

diff --git a/doc/rtd/development/datasource_creation.rst b/doc/rtd/development/datasource_creation.rst
new file mode 100644
index 00000000..f55508fc
--- /dev/null
+++ b/doc/rtd/development/datasource_creation.rst
@@ -0,0 +1,89 @@
+.. _datasource_creation:
+
+Datasource creation
+*******************
+
+There are multiple ways to provide `user data`, `metadata`, and
+`vendor data`, and each cloud solution prefers its own way. A datasource
+abstract base class defines a single interface to interact with the different
+clouds. Each cloud implementation must inherit from this base class to use this
+shared functionality and interface. See :file:`cloud-init/sources/__init__.py`
+to see this class.
+
+If you are interested in adding a new datasource for your cloud platform you
+will need to do all of the following:
+
+Identify a mechanism for positive identification of the platform
+================================================================
+
+It is good practice for a cloud platform to positively identify itself to
+the guest. This allows the guest to make educated decisions based on the
+platform on which it is running. On the x86 and arm64 architectures, many
+clouds identify themselves through `DMI`_ data. For example, Oracle's public
+cloud provides the string ``'OracleCloud.com'`` in the DMI chassis-asset
+field.
+
+``Cloud-init``-enabled images produce a log file with details about the
+platform. Reading through this log in :file:`/run/cloud-init/ds-identify.log`
+may provide the information needed to uniquely identify the platform.
+If the log is not present, you can generate it by running from source
+:file:`./tools/ds-identify` or the installed location
+:file:`/usr/lib/cloud-init/ds-identify`.
+
+The mechanism used to identify the platform will be required for the
+``ds-identify`` and datasource module sections below.
+
+Add datasource module cloudinit/sources/DataSource<CloudPlatform>.py
+====================================================================
+
+We suggest you start by copying one of the simpler datasources
+such as ``DataSourceHetzner``.
+
+Add tests for datasource module
+===============================
+
+Add a new file with some tests for the module to
+:file:`cloudinit/sources/test_<yourplatform>.py`. For example, see
+:file:`cloudinit/sources/tests/test_oracle.py`
+
+Update ``ds-identify``
+======================
+
+In ``systemd`` systems, ``ds-identify`` is used to detect which datasource
+should be enabled, or if ``cloud-init`` should run at all. You'll need to
+make changes to :file:`tools/ds-identify`.
+
+Add tests for ``ds-identify``
+=============================
+
+Add relevant tests in a new class to
+:file:`tests/unittests/test_ds_identify.py`. You can use ``TestOracle`` as
+an example.
+
+Add your datasource name to the built-in list of datasources
+============================================================
+
+Add your datasource module name to the end of the ``datasource_list``
+entry in :file:`cloudinit/settings.py`.
+
+Add your cloud platform to apport collection prompts
+====================================================
+
+Update the list of cloud platforms in :file:`cloudinit/apport.py`. This list
+will be provided to the user who invokes :command:`ubuntu-bug cloud-init`.
+
+Enable datasource by default in Ubuntu packaging branches
+=========================================================
+
+Ubuntu packaging branches contain a template file,
+:file:`debian/cloud-init.templates`, which ultimately sets the default
+``datasource_list`` when installed via package. This file needs updating when
+the commit gets into a package.
+
+Add documentation for your datasource
+=====================================
+
+You should add a new file in :file:`doc/datasources/<cloudplatform>.rst`.
+
+.. _make-mime: https://cloudinit.readthedocs.io/en/latest/explanation/instancedata.html#storage-locations
+.. _DMI: https://www.dmtf.org/sites/default/files/standards/documents/DSP0005.pdf
diff --git a/doc/rtd/development/index.rst b/doc/rtd/development/index.rst
index 9768fab5..e85d29f1 100644
--- a/doc/rtd/development/index.rst
+++ b/doc/rtd/development/index.rst
@@ -16,6 +16,7 @@ Contributing
 
    contributing.rst
    module_creation.rst
+   datasource_creation.rst
    code_review.rst
    dir_layout.rst
 
diff --git a/doc/rtd/explanation/boot.rst b/doc/rtd/explanation/boot.rst
index 42ccbc87..02176a01 100644
--- a/doc/rtd/explanation/boot.rst
+++ b/doc/rtd/explanation/boot.rst
@@ -17,21 +17,9 @@ stages to boot:
 
 Generator
 =========
-
-When booting under ``systemd``, a `generator`_ will run that determines if
-``cloud-init.target`` should be included in the boot goals. By default, this
-generator will enable ``cloud-init``. It will not enable ``cloud-init``
-if either:
-
-- The file :file:`/etc/cloud/cloud-init.disabled` exists, or
-- The kernel command line as found in :file:`/proc/cmdline` contains
-  ``cloud-init=disabled``. When running in a container, the kernel command
-  line is not honored, but ``cloud-init`` will read an environment
-  variable named ``KERNEL_CMDLINE`` in its place.
-
-.. note::
-   These mechanisms for disabling ``cloud-init`` at runtime currently only
-   exist in ``systemd``.
+When booting under ``systemd``, a generator will run that determines if
+cloud-init.target should be included in the boot goals. ``ds-identify``
+runs at this stage.
 
 .. _boot-Local:
 
diff --git a/doc/rtd/explanation/format.rst b/doc/rtd/explanation/format.rst
index 1e9c9307..3de09c3e 100644
--- a/doc/rtd/explanation/format.rst
+++ b/doc/rtd/explanation/format.rst
@@ -6,6 +6,8 @@ User data formats
 User data that will be acted upon by ``cloud-init`` must be in one of the
 following types.
 
+.. _user_data_formats-cloud_config:
+
 Cloud config data
 =================
 
diff --git a/doc/rtd/explanation/index.rst b/doc/rtd/explanation/index.rst
index c6114096..2e2cec20 100644
--- a/doc/rtd/explanation/index.rst
+++ b/doc/rtd/explanation/index.rst
@@ -18,3 +18,4 @@ knowledge and become better at using and configuring ``cloud-init``.
    vendordata.rst
    security.rst
    analyze.rst
+   kernel-cmdline.rst
diff --git a/doc/rtd/explanation/kernel-cmdline.rst b/doc/rtd/explanation/kernel-cmdline.rst
index 94f646f5..2e88dc13 100644
--- a/doc/rtd/explanation/kernel-cmdline.rst
+++ b/doc/rtd/explanation/kernel-cmdline.rst
@@ -3,20 +3,45 @@
 Kernel command line
 *******************
 
+Providing configuration data via the kernel command line is somewhat of a last
+resort, since this method only supports
+:ref:`cloud config<user_data_formats-cloud_config>` starting with
+`#cloud-config`, and many datasources do not support injecting kernel
+command line arguments without modifying the bootloader.
+
+Despite the limitations of using the kernel command line, cloud-init supports
+some use-cases.
+
+Note that this page describes kernel command line behavior that applies
+to all clouds. To provide a local configuration with an image using kernel
+command line, see :ref:`datasource NoCloud<datasource_nocloud>` which provides
+more configuration options.
+
+.. _kernel_datasource_override:
+
+Datasource discovery override
+=============================
+
+During boot, cloud-init must identify which datasource it is running on
+(OpenStack, AWS, Azure, GCP, etc). This discovery step can be optionally
+overriden by specifying the datasource name, such as:
+
+.. code-block:: text
+
+   root=/dev/sda ro ds=openstack
+
+Kernel cloud-config-url configuration
+=====================================
+
 In order to allow an ephemeral, or otherwise pristine image to receive some
-configuration, ``cloud-init`` will read a URL directed by the kernel command
+configuration, ``cloud-init`` can read a URL directed by the kernel command
 line and proceed as if its data had previously existed.
 
 This allows for configuring a metadata service, or some other data.
 
-.. note::
-   Usage of the kernel command line is somewhat of a last resort,
-   as it requires knowing in advance the correct command line or modifying
-   the boot loader to append data.
-
-For example, when :command:`cloud-init init --local` runs, it will check to
-see if ``cloud-config-url`` appears in key/value fashion in the kernel command
-line, as in:
+When :ref:`the local stage<boot-Local>` runs, it will check to see if
+``cloud-config-url`` appears in key/value fashion in the kernel command line,
+such as:
 
 .. code-block:: text
 
@@ -27,13 +52,14 @@ starts with ``#cloud-config``, it will store that data to the local filesystem
 in a static filename :file:`/etc/cloud/cloud.cfg.d/91_kernel_cmdline_url.cfg`,
 and consider it as part of the config from that point forward.
 
-If that file exists already, it will not be overwritten, and the
-``cloud-config-url`` parameter is completely ignored.
+.. note::
+   If :file:`/etc/cloud/cloud.cfg.d/91_kernel_cmdline_url.cfg` already exists,
+   cloud-init will not overwrite the file, and the ``cloud-config-url``
+   parameter is completely ignored.
 
-Then, when the datasource runs, it will find that config already available.
 
-So, to be able to configure the MAAS datasource by controlling the
-kernel command line from outside the image, you can append:
+This is useful, for example, to be able to configure the MAAS datasource by
+controlling the kernel command line from outside the image, you can append:
 
 .. code-block:: text
 
@@ -59,11 +85,12 @@ Then, have the following content at that url:
 .. note::
 
    Since ``cloud-config-url=`` is so generic, in order to avoid false
-   positives, ``cloud-init`` requires the content to start with
-   ``#cloud-config`` for it to be considered.
+   positives, only :ref:`cloud config<user_data_formats-cloud_config>` user
+   data starting with ``#cloud-config`` is supported.
+
 
 .. note::
 
-   The ``cloud-config-url=`` is un-authed http GET, and contains credentials.
-   It could be set up to be randomly generated and also to check the source
-   address in order to be more secure.
+   The ``cloud-config-url=`` is unencrypted http GET, and may contain
+   credentials. Care must be taken to ensure this data is only
+   transferred via trusted channels (i.e., within a closed system).
diff --git a/doc/rtd/howto/disable_cloud_init.rst b/doc/rtd/howto/disable_cloud_init.rst
new file mode 100644
index 00000000..75e07001
--- /dev/null
+++ b/doc/rtd/howto/disable_cloud_init.rst
@@ -0,0 +1,39 @@
+.. _disable-Cloud_init:
+
+How to disable cloud-init
+*************************
+
+One may wish to disable cloud-init to ensure that it doesn't do anything on
+subsequent boots. Some parts of cloud-init may run once per boot otherwise.
+
+There are two cross-platform methods of disabling ``cloud-init``.
+
+Method 1: text file
+====================
+
+To disable cloud-init, create the empty file
+:file:`/etc/cloud/cloud-init.disabled`. During boot the operating system's init
+system will check for the existence of this file. If it exists, cloud-init will
+not be started.
+
+Example:
+
+.. code-block::
+
+    $ touch /etc/cloud/cloud-init.disabled
+
+Method 2: kernel commandline
+============================
+
+To disable cloud-init, add ``cloud-init=disabled`` to the kernel commandline.
+
+Example (using GRUB2 with Ubuntu):
+
+.. code-block::
+
+    $ echo 'GRUB_CMDLINE_LINUX=cloud-init.disabled' >> /etc/default/grub
+    $ grub-mkconfig -o /boot/efi/EFI/ubuntu/grub.cfg
+
+.. note::
+   When running in containers, ``cloud-init`` will read an environment
+   variable named ``KERNEL_CMDLINE`` in place of a kernel commandline.
diff --git a/doc/rtd/howto/index.rst b/doc/rtd/howto/index.rst
index 23936fa9..f542e9ba 100644
--- a/doc/rtd/howto/index.rst
+++ b/doc/rtd/howto/index.rst
@@ -20,4 +20,5 @@ How do I...?
 
    Test cloud-init locally before deploying <predeploy_testing.rst>
    Change how often a module runs <module_run_frequency.rst>
+   Disable cloud-init <disable_cloud_init.rst>
    Report a bug <bugs.rst>
diff --git a/doc/rtd/reference/base_config_reference.rst b/doc/rtd/reference/base_config_reference.rst
index 928efc55..cd106a72 100644
--- a/doc/rtd/reference/base_config_reference.rst
+++ b/doc/rtd/reference/base_config_reference.rst
@@ -215,6 +215,8 @@ instance.
 Prioritised list of python packages to search when finding a datasource.
 Automatically includes ``cloudinit.sources``.
 
+.. _base_config_datasource_list:
+
 ``datasource_list``
 ^^^^^^^^^^^^^^^^^^^
 
@@ -229,8 +231,8 @@ are two primary use cases for modifying the ``datasource_list``:
    type than would typically be prioritised.
 
 If ``datasource_list`` has only a single entry (or a single entry + ``None``),
-:ref:`cloud-init's generator script<boot-Generator>` will automatically assume
-and use this datasource without attempting detection.
+`cloud-init` will automatically assume and use this datasource without
+attempting detection.
 
 ``vendor_data``/``vendor_data2``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/doc/rtd/reference/datasource_dsname_map.rst b/doc/rtd/reference/datasource_dsname_map.rst
new file mode 100644
index 00000000..3abb55a3
--- /dev/null
+++ b/doc/rtd/reference/datasource_dsname_map.rst
@@ -0,0 +1,53 @@
+.. _datasource_dsname:
+
+Datasource dsname
+*****************
+
+Each datasource has an attribute called dsname. This may be used in the
+kernel commandline to
+:ref:`override datasource detection<kernel_datasource_override>`. The
+``dsname`` on the kernel command line may be a case-insensitive match. See the
+mapping between datasource module names and ``dsname`` in the table below.
+
+
+..
+    generate the following map with the following one-liner:
+
+    find cloudinit/sources -name 'DataSource*.py' \
+    |  xargs grep 'dsname =' \
+    | awk -F '[/:"]' 'BEGIN { print "**Datasource Module**, **dsname**" }\
+      {print $3 ", " $5}'
+
+
+.. csv-table::
+   :align: left
+
+    **Datasource Module**, **dsname**
+    DataSourceRbxCloud.py, RbxCloud
+    DataSourceConfigDrive.py, ConfigDrive
+    DataSourceNoCloud.py, NoCloud
+    DataSourceVultr.py, Vultr
+    DataSourceEc2.py, Ec2
+    DataSourceOracle.py, Oracle
+    DataSourceMAAS.py, MAAS
+    DataSourceDigitalOcean.py, DigitalOcean
+    DataSourceNone.py, None
+    DataSourceSmartOS.py, Joyent
+    DataSourceHetzner.py, Hetzner
+    DataSourceLXD.py, LXD
+    DataSourceOpenNebula.py, OpenNebula
+    DataSourceAzure.py, Azure
+    DataSourceGCE.py, GCE
+    DataSourceScaleway.py, Scaleway
+    DataSourceAltCloud.py, AltCloud
+    DataSourceCloudSigma.py, CloudSigma
+    DataSourceBigstep.py, Bigstep
+    DataSourceIBMCloud.py, IBMCloud
+    DataSourceOVF.py, OVF
+    DataSourceUpCloud.py, UpCloud
+    DataSourceOpenStack.py, OpenStack
+    DataSourceVMware.py, VMware
+    DataSourceCloudStack.py, CloudStack
+    DataSourceExoscale.py, Exoscale
+    DataSourceAliYun.py, AliYun
+    DataSourceNWCS.py, NWCS
diff --git a/doc/rtd/reference/datasources.rst b/doc/rtd/reference/datasources.rst
index 6db0053a..36f8372b 100644
--- a/doc/rtd/reference/datasources.rst
+++ b/doc/rtd/reference/datasources.rst
@@ -9,20 +9,29 @@ configuration drive (i.e., metadata). Typical user data includes files,
 YAML, and shell scripts whereas typical metadata includes server name,
 instance id, display name, and other cloud specific details.
 
-Since there are multiple ways to provide this data (each cloud solution seems
-to prefer its own way), a datasource abstract class was internally created to
-allow for a single way to access the different cloud systems methods, providing
-this data through the typical usage of subclasses.
-
 Any metadata processed by ``cloud-init``'s datasources is persisted as
 :file:`/run/cloud-init/instance-data.json`. ``Cloud-init`` provides tooling to
 quickly introspect some of that data. See :ref:`instance_metadata` for more
 information.
 
-Known sources
-=============
+How to configure which datasource to use
+========================================
+
+By default ``cloud-init`` should automatically determine which datasource it is
+running on. Therefore, in most cases, users of ``cloud-init`` should not
+have to configure ``cloud-init`` to specify which datasource cloud-init is
+running on; ``cloud-init`` should "figure it out".
+
+There are exceptions, however, when the :ref:`datasource does not
+identify<datasource_ironic>` itself to ``cloud-init``. For these
+exceptions, one can override datasource detection either by configuring a
+single datasource in the :ref:`datasource_list<base_config_datasource_list>`,
+or by using :ref:`kernel commandline arguments<kernel_datasource_override>`.
+
+Datasources:
+============
 
-The following is a list of documents for each supported datasource:
+The following is a list of documentation for each supported datasource:
 
 .. toctree::
    :titlesonly:
@@ -54,81 +63,3 @@ The following is a list of documents for each supported datasource:
    datasources/vultr.rst
    datasources/zstack.rst
 
-Datasource creation
-===================
-
-The datasource objects have a few touch points with ``cloud-init``. If you
-are interested in adding a new datasource for your cloud platform you will
-need to take care of the following items:
-
-Identify a mechanism for positive identification of the platform
-----------------------------------------------------------------
-
-It is good practice for a cloud platform to positively identify itself to
-the guest. This allows the guest to make educated decisions based on the
-platform on which it is running. On the x86 and arm64 architectures, many
-clouds identify themselves through DMI data. For example, Oracle's public
-cloud provides the string ``'OracleCloud.com'`` in the DMI chassis-asset
-field.
-
-``Cloud-init``-enabled images produce a log file with details about the
-platform. Reading through this log in :file:`/run/cloud-init/ds-identify.log`
-may provide the information needed to uniquely identify the platform.
-If the log is not present, you can generate it by running from source
-:file:`./tools/ds-identify` or the installed location
-:file:`/usr/lib/cloud-init/ds-identify`.
-
-The mechanism used to identify the platform will be required for the
-``ds-identify`` and datasource module sections below.
-
-Add datasource module :file:`cloudinit/sources/DataSource<CloudPlatform>.py`
-----------------------------------------------------------------------------
-
-It is suggested that you start by copying one of the simpler datasources
-such as ``DataSourceHetzner``.
-
-Add tests for datasource module
--------------------------------
-
-Add a new file with some tests for the module to
-:file:`cloudinit/sources/test_<yourplatform>.py`. For example, see
-:file:`cloudinit/sources/tests/test_oracle.py`
-
-Update ``ds-identify``
-----------------------
-
-In ``systemd`` systems, ``ds-identify`` is used to detect which datasource
-should be enabled, or if ``cloud-init`` should run at all. You'll need to
-make changes to :file:`tools/ds-identify`.
-
-Add tests for ``ds-identify``
------------------------------
-
-Add relevant tests in a new class to
-:file:`tests/unittests/test_ds_identify.py`. You can use ``TestOracle`` as
-an example.
-
-Add your datasource name to the built-in list of datasources
-------------------------------------------------------------
-
-Add your datasource module name to the end of the ``datasource_list``
-entry in :file:`cloudinit/settings.py`.
-
-Add your cloud platform to apport collection prompts
-----------------------------------------------------
-
-Update the list of cloud platforms in :file:`cloudinit/apport.py`. This list
-will be provided to the user who invokes :command:`ubuntu-bug cloud-init`.
-
-Enable datasource by default in Ubuntu packaging branches
----------------------------------------------------------
-
-Ubuntu packaging branches contain a template file,
-:file:`debian/cloud-init.templates`, which ultimately sets the default
-``datasource_list`` when installed via package. This file needs updating when
-the commit gets into a package.
-
-Add documentation for your datasource
--------------------------------------
-
-You should add a new file in :file:`doc/datasources/<cloudplatform>.rst`.
diff --git a/doc/rtd/reference/datasources/nocloud.rst b/doc/rtd/reference/datasources/nocloud.rst
index 682c8477..b1a868f2 100644
--- a/doc/rtd/reference/datasources/nocloud.rst
+++ b/doc/rtd/reference/datasources/nocloud.rst
@@ -3,22 +3,43 @@
 NoCloud
 *******
 
-The data source ``NoCloud`` allows the user to provide user data and metadata
-to the instance without running a network service (or even without having a
-network at all).
+The data source ``NoCloud`` is a flexible datasource that can be used in
+multiple different ways. With NoCloud, the user can provide user data and
+metadata to the instance without running a network service (or even without
+having a network at all). Alternatively, one may use a custom webserver to
+provide configurations.
 
-You can provide metadata and user data to a local VM boot via files on a
-`vfat`_ or `iso9660`_ filesystem. The filesystem volume label must be
-``cidata`` or ``CIDATA``.
+Configuration Methods:
+======================
 
-Alternatively, you can provide metadata via the kernel command line or SMBIOS
-"serial number" option. The data must be passed in the form of a string: ::
+Method 1: Local filesystem, labeled filesystem
+----------------------------------------------
 
-  ds=nocloud[;key=val;key=val]
+To provide cloud-init configurations from the local filesystem, a labeled
+`vfat`_ or `iso9660`_ filesystem containing user data and metadata may
+be used. For this method to work, the filesystem volume must be labelled
+``CIDATA``.
 
-or, ::
+Method 2: Local filesystem, kernel commandline or SMBIOS
+--------------------------------------------------------
 
-  ds=nocloud-net[;key=val;key=val]
+Configuration files can be provided on the local filesystem without a label
+using kernel commandline arguments or SMBIOS serial number to tell cloud-init
+where on the filesystem to look.
+
+Alternatively, one can provide metadata via the kernel command line or SMBIOS
+"serial number" option. This argument might look like: ::
+
+  ds=nocloud s=file://path/to/directory/;h=node-42
+
+Method 3: Custom webserver: kernel commandline or SMBIOS
+--------------------------------------------------------
+
+In a similar fashion, configuration files can be provided to cloud-init using a
+custom webserver at a URL dictated by kernel commandline arguments or SMBIOS
+serial number. This argument might look like: ::
+
+  ds=nocloud s=http://10.42.42.42/cloud-init/configs/
 
 Permitted keys
 ==============
@@ -29,9 +50,44 @@ The permitted keys are:
 * ``i`` or ``instance-id``
 * ``s`` or ``seedfrom``
 
-With ``ds=nocloud``, the ``seedfrom`` value must start with ``/`` or
-``file://``.  With ``ds=nocloud-net``, the ``seedfrom`` value must start
-with ``http://`` or ``https://`` and end with a trailing ``/``.
+A valid ``seedfrom`` value consists of:
+
+Filesystem
+----------
+
+A filesystem path starting with ``/`` or ``file://`` that points to a directory
+containing files: ``user-data``, ``meta-data``, and (optionally)
+``vendor-data``
+
+HTTP server
+-----------
+
+An ``http`` or ``https`` URL (a trailing ``/`` is required)
+
+
+File formats
+============
+
+These user data and metadata files are required as separate files at the
+same base URL: ::
+
+  /user-data
+  /meta-data
+
+Both files must be present for it to be considered a valid seed ISO.
+
+The ``user-data`` file uses :ref:`user data format<user_data_formats>` and
+``meta-data`` is a YAML-formatted file representing what you'd find in the EC2
+metadata service.
+
+You may also optionally provide a vendor data file adhering to
+:ref:`user data formats<user_data_formats>` at the same base URL: ::
+
+  /vendor-data
+
+
+DMI-specific kernel commandline
+===============================
 
 Cloud-init performs variable expansion of the ``seedfrom`` URL for any DMI
 kernel variables present in :file:`/sys/class/dmi/id` (kenv on FreeBSD).
@@ -69,28 +125,9 @@ YOUR_SERIAL_NUMBER as seen in :file:`/sys/class/dmi/id/chassis_serial_number`
 (kenv on FreeBSD) from http://10.10.0.1:8000/YOUR_SERIAL_NUMBER/meta-data after
 the network initialisation is complete.
 
-File formats
-============
-
-These user data and metadata files are required as separate files at the
-same base URL: ::
-
-  /user-data
-  /meta-data
-
-Both files must be present for it to be considered a valid seed ISO.
-
-Basically, ``user-data`` is simply :ref:`user data<user_data_formats>` and
-``meta-data`` is a YAML-formatted file representing what you'd find in the EC2
-metadata service.
-
-You may also optionally provide a vendor data file adhering to
-:ref:`user data formats<user_data_formats>` at the same base URL: ::
-
-  /vendor-data
 
-Creating a disk
-===============
+Example: Creating a disk
+========================
 
 Given a disk Ubuntu cloud image in :file:`disk.img`, you can create a
 sufficient disk by following the following example.
diff --git a/doc/rtd/reference/datasources/openstack.rst b/doc/rtd/reference/datasources/openstack.rst
index f8fd2eb4..7bb52e4a 100644
--- a/doc/rtd/reference/datasources/openstack.rst
+++ b/doc/rtd/reference/datasources/openstack.rst
@@ -125,4 +125,38 @@ path; if found, settings are applied after (and, hence, overriding) the
 settings from static vendor data. Both sets of vendor data can be overridden
 by user data.
 
+.. _datasource_ironic:
+
+OpenStack Ironic Bare Metal
+===========================
+
+During boot, cloud-init typically has to identify which platform it is running
+on. Since OpenStack Ironic Bare Metal doesn't provide a method for cloud-init
+to discover that it is running on Ironic, extra user configuration is required.
+
+Cloud-init provides two methods to do this:
+
+Method 1: Configuration file
+----------------------------
+
+Explicitly set ``datasource_list`` to only ``openstack``, such as:
+
+.. code-block:: yaml
+
+   datasource_list: ["openstack"]
+
+Method 2: Kernel command line
+-----------------------------
+
+Set the kernel commandline to configure
+:ref:`datasource override <kernel_datasource_override>`.
+
+Example using Ubuntu + GRUB2:
+
+.. code-block::
+
+    $ echo 'ds=openstack' >> /etc/default/grub
+    $ grub-mkconfig -o /boot/efi/EFI/ubuntu/grub.cfg
+
+
 .. _OpenStack Metadata Service: https://docs.openstack.org/nova/latest/admin/metadata-service.html
diff --git a/doc/rtd/reference/index.rst b/doc/rtd/reference/index.rst
index 5610490b..4d1dc6af 100644
--- a/doc/rtd/reference/index.rst
+++ b/doc/rtd/reference/index.rst
@@ -19,3 +19,4 @@ matrices and so on.
    datasources.rst
    network-config.rst
    base_config_reference.rst
+   datasource_dsname_map.rst