From c1b4722036a1ad3f683b7942db4d07639f88dcd2 Mon Sep 17 00:00:00 2001 From: Brett Holman Date: Tue, 25 Apr 2023 12:09:45 -0600 Subject: 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 --- doc/rtd/development/datasource_creation.rst | 89 +++++++++++++++++++++++ doc/rtd/development/index.rst | 1 + doc/rtd/explanation/boot.rst | 18 +---- doc/rtd/explanation/format.rst | 2 + doc/rtd/explanation/index.rst | 1 + doc/rtd/explanation/kernel-cmdline.rst | 65 ++++++++++++----- doc/rtd/howto/disable_cloud_init.rst | 39 ++++++++++ doc/rtd/howto/index.rst | 1 + doc/rtd/reference/base_config_reference.rst | 6 +- doc/rtd/reference/datasource_dsname_map.rst | 53 ++++++++++++++ doc/rtd/reference/datasources.rst | 103 +++++--------------------- doc/rtd/reference/datasources/nocloud.rst | 107 +++++++++++++++++++--------- doc/rtd/reference/datasources/openstack.rst | 34 +++++++++ doc/rtd/reference/index.rst | 1 + 14 files changed, 363 insertions(+), 157 deletions(-) create mode 100644 doc/rtd/development/datasource_creation.rst create mode 100644 doc/rtd/howto/disable_cloud_init.rst create mode 100644 doc/rtd/reference/datasource_dsname_map.rst 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.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_.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/.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` 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` 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` 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 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 Change how often a module runs + Disable cloud-init Report a bug 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` 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`. 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` itself to ``cloud-init``. For these +exceptions, one can override datasource detection either by configuring a +single datasource in the :ref:`datasource_list`, +or by using :ref:`kernel commandline arguments`. + +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.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_.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/.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` 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` 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` 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` 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 `. + +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 -- cgit v1.2.1