From 8d8d9de90cdc4e980126c541fd134b1e57bf453e Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Thu, 24 Sep 2020 14:25:25 +0200 Subject: [PATCH] Add documentation for ISO boot Split ramdisk deploy information away from other deploy interfaces, since it's so different from the other interfaces (and to highlight it in the top-level index). Change-Id: Id3a5d71141451a45e89ffdba903966bb7da84d55 --- doc/source/admin/index.rst | 1 + doc/source/admin/interfaces/deploy.rst | 44 +------------- doc/source/admin/ramdisk-boot.rst | 80 ++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 42 deletions(-) create mode 100644 doc/source/admin/ramdisk-boot.rst diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 5154aa39b4..6a3e97cd29 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -30,6 +30,7 @@ the services. Power Sync with the Compute Service Node Multi-Tenancy Fast-Track Deployment + Booting a Ramdisk or an ISO Advanced Topics --------------- diff --git a/doc/source/admin/interfaces/deploy.rst b/doc/source/admin/interfaces/deploy.rst index d8c0e1b09a..39c8eecb14 100644 --- a/doc/source/admin/interfaces/deploy.rst +++ b/doc/source/admin/interfaces/deploy.rst @@ -145,45 +145,5 @@ Ramdisk deploy ============== The ramdisk interface is intended to provide a mechanism to "deploy" an -instance where the item to be deployed is in reality a ramdisk. -Most commonly this is performed when an instance is booted via PXE, iPXE or -Virtual Media, with the only local storage contents being those in memory. -It is suported by ``pxe`` and ``ilo-virtual-media`` boot interfaces. - -As with most non-default interfaces, it must be enabled and set for a node -to be utilized: - -.. code-block:: ini - - [DEFAULT] - ... - enabled_deploy_interfaces = iscsi,direct,ramdisk - ... - -Once enabled and the conductor(s) have been restarted, the interface can -be set upon creation of a new node or update a pre-existing node: - -.. code-block:: shell - - openstack baremetal node create --driver ipmi \ - --deploy-interface ramdisk \ - --boot-interface pxe - openstack baremetal node set --deploy-interface ramdisk - -The intended use case is for advanced scientific and ephemeral workloads -where the step of writing an image to the local storage is not required -or desired. As such, this interface does come with several caveats: - -* Configuration drives are not supported. -* Disk image contents are not written to the bare metal node. -* Users and Operators who intend to leverage this interface should - expect to leverage a metadata service, custom ramdisk images, or the - ``instance_info/ramdisk_kernel_arguments`` parameter to add options to - the kernel boot command line. -* Bare metal nodes must continue to have network access to PXE and iPXE - network resources. This is contrary to most tenant networking enabled - configurations where this access is restricted to the provisioning and - cleaning networks -* As with all deployment interfaces, automatic cleaning of the node will - still occur with the contents of any local storage being wiped between - deployments. +instance where the item to be deployed is in reality a ramdisk. It is +documented separately, see :doc:`/admin/ramdisk-boot`. diff --git a/doc/source/admin/ramdisk-boot.rst b/doc/source/admin/ramdisk-boot.rst new file mode 100644 index 0000000000..cd6c2151ff --- /dev/null +++ b/doc/source/admin/ramdisk-boot.rst @@ -0,0 +1,80 @@ +Booting a Ramdisk or an ISO +=========================== + +Ironic supports booting a user provided ramdisk or an ISO image (starting with +the Victoria release) instead of deploying a node. +Most commonly this is performed when an instance is booted via PXE, iPXE or +Virtual Media, with the only local storage contents being those in memory. +It is suported by ``pxe``, ``ipxe``, ``redfish-virtual-media`` and +``ilo-virtual-media`` boot interfaces. + +Configuration +------------- + +Ramdisk/ISO boot requires using the ``ramdisk`` deploy interface. As with most +non-default interfaces, it must be enabled and set for a node to be utilized: + +.. code-block:: ini + + [DEFAULT] + ... + enabled_deploy_interfaces = iscsi,direct,ramdisk + ... + +Once enabled and the conductor(s) have been restarted, the interface can +be set upon creation of a new node: + +.. code-block:: shell + + openstack baremetal node create --driver ipmi \ + --deploy-interface ramdisk \ + --boot-interface ipxe + +or update an existing node: + +.. code-block:: shell + + openstack baremetal node set --deploy-interface ramdisk + +Using virtual media: + +.. code-block:: shell + + openstack baremetal node create --driver redfish \ + --deploy-interface ramdisk \ + --boot-interface redfish-virtual-media + +.. TODO(dtantsur): document how exactly to create and boot a ramdisk + +Booting an ISO +-------------- + +The ``ramdisk`` deploy interface can also be used to boot an ISO image. +For example, + +.. code-block:: shell + + openstack baremetal node set \ + --instance-info boot_iso=http://path/to/boot.iso + openstack baremetal node deploy + +Limitations +----------- + +The intended use case is for advanced scientific and ephemeral workloads +where the step of writing an image to the local storage is not required +or desired. As such, this interface does come with several caveats: + +* Configuration drives are not supported. +* Disk image contents are not written to the bare metal node. +* Users and Operators who intend to leverage this interface should + expect to leverage a metadata service, custom ramdisk images, or the + ``instance_info/ramdisk_kernel_arguments`` parameter to add options to + the kernel boot command line. +* When using PXE/iPXE boot, bare metal nodes must continue to have network + access to PXE and iPXE network resources. This is contrary to most tenant + networking enabled configurations where this access is restricted to + the provisioning and cleaning networks +* As with all deployment interfaces, automatic cleaning of the node will + still occur with the contents of any local storage being wiped between + deployments.