From f02ef8ad7a8d993bbd62780a8da6e66a6a0a1cf6 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Fri, 3 Nov 2017 15:33:59 +0100 Subject: [PATCH] Rework drivers page in the admin documentation First, "Enabling Drivers" is a really confusing title, since this page links to complete driver documentation. It also links to IPA docs and the PXE driver interface. Next, our documentation is full of remarks about e.g. "pxe_* family of drivers", which are misleading in the presence of hardware types and the pxe_agent_cimc driver. We also have mentions of "iscsi deploy method" without detailed explanation of how this method relates to hardware types and classic drivers. This change consolidates drivers and interfaces documentation under the more clearly named root page. A new page is created with sections for both deploy interfaces to use for linking from wherever a link to a particular deploy interface is required. Change-Id: Ifb8328ccaaac443fac276873e2c375ebcf983f03 --- doc/source/admin/drivers.rst | 106 +++++----------------- doc/source/admin/drivers/ipa.rst | 12 +-- doc/source/admin/drivers/pxe.rst | 27 +----- doc/source/admin/index.rst | 2 +- doc/source/admin/interfaces/boot.rst | 70 ++++++++++++++ doc/source/admin/interfaces/deploy.rst | 57 ++++++++++++ doc/source/contributor/dev-quickstart.rst | 7 +- doc/source/install/enabling-drivers.rst | 24 +++-- doc/source/install/refarch/common.rst | 27 ++---- doc/source/user/index.rst | 14 +-- 10 files changed, 188 insertions(+), 158 deletions(-) create mode 100644 doc/source/admin/interfaces/boot.rst create mode 100644 doc/source/admin/interfaces/deploy.rst diff --git a/doc/source/admin/drivers.rst b/doc/source/admin/drivers.rst index a7ef80d633..a5ed938693 100644 --- a/doc/source/admin/drivers.rst +++ b/doc/source/admin/drivers.rst @@ -1,107 +1,38 @@ -.. _enabling_drivers: +=============================================== +Drivers, Hardware Types and Hardware Interfaces +=============================================== -================ -Enabling drivers -================ - -Ironic-Python-Agent (agent) ---------------------------- - -Ironic-Python-Agent is an agent that handles *ironic* bare metal -nodes in various actions such as inspection and deployment of such -nodes, and runs processes inside of a ramdisk. - -For more information on this, see :ref:`IPA`. - -PXE Boot Interface +Generic Interfaces ------------------ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - drivers/pxe + interfaces/boot + interfaces/deploy -IPMITool driver ---------------- - -.. toctree:: - :maxdepth: 1 - - drivers/ipmitool - -iDRAC driver ------------- - -.. toctree:: - :maxdepth: 1 - - drivers/idrac - -SNMP driver ------------ - -.. toctree:: - :maxdepth: 1 - - drivers/snmp - -iLO driver ----------- - -.. toctree:: - :maxdepth: 1 - - drivers/ilo - -iRMC driver ------------ - -.. toctree:: - :maxdepth: 1 - - drivers/irmc - -Cisco UCS driver ----------------- - -.. toctree:: - :maxdepth: 1 - - drivers/ucs - - -CIMC driver ------------ +Hardware Types +-------------- .. toctree:: :maxdepth: 1 drivers/cimc - - -OneView driver --------------- - -.. toctree:: - :maxdepth: 1 - + drivers/idrac + drivers/ilo + drivers/ipmitool + drivers/irmc drivers/oneview - - -Redfish driver --------------- - -.. toctree:: - :maxdepth: 1 - drivers/redfish + drivers/snmp + drivers/ucs Unsupported drivers ------------------- The following drivers were declared as unsupported in ironic Newton release -and as of Ocata release they are removed form ironic: +and as of Ocata release they are removed from ironic: - AMT driver - available as part of ironic-staging-drivers_ - iBoot driver - available as part of ironic-staging-drivers_ @@ -110,4 +41,9 @@ and as of Ocata release they are removed form ironic: - SeaMicro drivers - MSFT OCS drivers +The SSH drivers were removed in the Pike release. Similar functionality can be +achieved either with VirtualBMC_ or using libvirt drivers from +ironic-staging-drivers_. + .. _ironic-staging-drivers: http://ironic-staging-drivers.readthedocs.io +.. _VirtualBMC: https://git.openstack.org/cgit/openstack/virtualbmc diff --git a/doc/source/admin/drivers/ipa.rst b/doc/source/admin/drivers/ipa.rst index 500a7b05db..19f751da1e 100644 --- a/doc/source/admin/drivers/ipa.rst +++ b/doc/source/admin/drivers/ipa.rst @@ -1,5 +1,3 @@ -.. _IPA: - =================== Ironic Python Agent =================== @@ -23,16 +21,16 @@ Starting with the Kilo release all drivers (except for fake ones) are using IPA for deployment. There are two types of them, which can be distinguished by prefix: -* For drivers with ``pxe_`` or ``iscsi_`` prefix IPA exposes the root hard +* For nodes using the :ref:`iscsi-deploy` interface, IPA exposes the root hard drive as an iSCSI share and calls back to the ironic conductor. The conductor mounts the share and copies an image there. It then signals back to IPA for post-installation actions like setting up a bootloader for local boot support. -* For drivers with ``agent_`` prefix the conductor prepares a swift temporary - URL for an image. IPA then handles the whole deployment process: - downloading an image from swift, putting it on the machine and doing any - post-deploy actions. +* For nodes using the :ref:`direct-deploy` interface, the conductor prepares + a swift temporary URL for an image. IPA then handles the whole deployment + process: downloading an image from swift, putting it on the machine and doing + any post-deploy actions. Which one to choose depends on your environment. iSCSI-based drivers put higher load on conductors, agent-based drivers currently require the whole diff --git a/doc/source/admin/drivers/pxe.rst b/doc/source/admin/drivers/pxe.rst index 4718d92e4a..53381c7bee 100644 --- a/doc/source/admin/drivers/pxe.rst +++ b/doc/source/admin/drivers/pxe.rst @@ -1,26 +1 @@ -.. pxe: - -============================== -Configuring PXE boot interface -============================== - -Enable persistent boot device for deploy/clean operation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Ironic uses non-persistent boot for cleaning/deploying phases as default, -in PXE interface. For some drivers, a persistent change is far more -costly than a non-persistent one, so this can bring performance improvements. - -Enable persistent boot device on node -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Set the flag ``force_persistent_boot_device`` to ``True`` in the node's ``driver_info``:: - - $ openstack baremetal node set --driver-info force_persistent_boot_device=True - - .. note:: - It's recommended to check if the node's state has not changed as there - is no way of locking the node between these commands. - -Once the flag is present, the next cleaning and deploy steps will be done -with persistent boot for that node. +See :ref:`pxe-boot`. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index fe9b39f5f6..79bfb99efa 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -8,7 +8,7 @@ the services. .. toctree:: :maxdepth: 1 - Enabling Drivers + Drivers, Hardware Types and Hardware Interfaces Ironic Python Agent Node Hardware Inspection Node Cleaning diff --git a/doc/source/admin/interfaces/boot.rst b/doc/source/admin/interfaces/boot.rst new file mode 100644 index 0000000000..f6c27736f3 --- /dev/null +++ b/doc/source/admin/interfaces/boot.rst @@ -0,0 +1,70 @@ +=============== +Boot interfaces +=============== + +The boot interface manages booting of both the deploy ramdisk and the user +instances on the bare metal node. + +The `PXE boot`_ interface is generic and works with all hardware that supports +booting from network. Alternatively, several vendors provide *virtual media* +implementations of the boot interface. They work by pushing an ISO image to +the node's `management controller`_, and do not require either PXE or iPXE. +Check your driver documentation at :doc:`../drivers` for details. + +.. _pxe-boot: + +PXE boot +-------- + +The ``pxe`` boot interface uses PXE_ or iPXE_ to deliver the target +kernel/ramdisk pair. PXE uses relatively slow and unreliable TFTP protocol +for transfer, while iPXE uses HTTP. The downside of iPXE is that it's less +common, and usually requires bootstrapping using PXE first. + +The ``pxe`` boot interface works by preparing a PXE/iPXE environment for a +node on the file system, then instructing the DHCP provider (for example, +the Networking service) to boot the node from it. See +:ref:`iscsi-deploy-example` and :ref:`direct-deploy-example` for a better +understanding of the whole deployment process. + +.. note:: + Both PXE and iPXE are configured differently, when UEFI boot is used + instead of conventional BIOS boot. This is particularly important for CPU + architectures that do not have BIOS support at all. + +The ``pxe`` boot interface is used by default for many hardware types, +including ``ipmi``, and for all classic drivers with names starting with +``pxe_``. Some hardware types, notably ``ilo`` and ``irmc`` have their +specific implementations of the PXE boot interface. + +Additional configuration is required for this boot interface - see +:doc:`/install/configure-pxe` for details. + +Enable persistent boot device for deploy/clean operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ironic uses non-persistent boot for cleaning/deploying phases as default, +in PXE interface. For some drivers, a persistent change is far more +costly than a non-persistent one, so this can bring performance improvements. + +Set the flag ``force_persistent_boot_device`` to ``True`` in the node's +``driver_info``:: + + $ openstack baremetal node set --driver-info force_persistent_boot_device=True + +.. note:: + It's recommended to check if the node's state has not changed as there + is no way of locking the node between these commands. + +Once the flag is present, the next cleaning and deploy steps will be done +with persistent boot for that node. + + +.. _PXE: https://en.wikipedia.org/wiki/Preboot_Execution_Environment +.. _iPXE: https://en.wikipedia.org/wiki/IPXE +.. _management controller: https://en.wikipedia.org/wiki/Out-of-band_management + +.. toctree:: + :hidden: + + ../drivers/pxe diff --git a/doc/source/admin/interfaces/deploy.rst b/doc/source/admin/interfaces/deploy.rst new file mode 100644 index 0000000000..a76cc01026 --- /dev/null +++ b/doc/source/admin/interfaces/deploy.rst @@ -0,0 +1,57 @@ +================= +Deploy Interfaces +================= + +A *deploy* interface plays a critical role in the provisioning process. It +orchestrates the whole deployment and defines how the image gets transferred +to the target disk. + +.. _iscsi-deploy: + +iSCSI deploy +============ + +With ``iscsi`` deploy interface (and also ``oneview-iscsi``, specific to the +``oneview`` hardware type) the deploy ramdisk publishes the node's hard drive +as an iSCSI_ share. The ironic-conductor then copies the image to this share. +See :ref:`iSCSI deploy diagram ` for a detailed +explanation of how this deploy interface works. + +This interface is used by default, if enabled (see +:ref:`enable-hardware-interfaces`). You can specify it explicitly +when creating or updating a node:: + + openstack baremetal node create --driver ipmi --deploy-interface iscsi + openstack baremetal node set --deploy-interface iscsi + +The ``iscsi`` deploy interface is also used in all of the *classic drivers* +with names starting with ``pxe_`` (except for ``pxe_agent_cimc``) +and ``iscsi_``. + +.. _iSCSI: https://en.wikipedia.org/wiki/ISCSI + +.. _direct-deploy: + +Direct deploy +============= + +With ``direct`` deploy interface (and also ``oneview-direct``, specific to the +``oneview`` hardware type), the deploy ramdisk fetches the image from an +HTTP location. It can be an object storage (swift or RadosGW) temporary URL or +a user-provided HTTP URL. The deploy ramdisk then copies the image to the +target disk. See :ref:`direct deploy diagram ` for +a detailed explanation of how this deploy interface works. + +You can specify this deploy interface when creating or updating a node:: + + openstack baremetal node create --driver ipmi --deploy-interface direct + openstack baremetal node set --deploy-interface direct + +The ``direct`` deploy interface is also used in all *classic drivers* +whose names include ``agent``. + +.. note:: + For historical reasons the ``direct`` deploy interface is sometimes called + ``agent``, and some *classic drivers* using it are called ``agent_*``. + This is because before the Kilo release **ironic-python-agent** used to + only support this deploy interface. diff --git a/doc/source/contributor/dev-quickstart.rst b/doc/source/contributor/dev-quickstart.rst index 04e4dd12fb..4b0f0e3d0c 100644 --- a/doc/source/contributor/dev-quickstart.rst +++ b/doc/source/contributor/dev-quickstart.rst @@ -429,9 +429,10 @@ Switch to the stack user and clone DevStack:: git clone https://git.openstack.org/openstack-dev/devstack.git devstack Create devstack/local.conf with minimal settings required to enable Ironic. -You can use either of two drivers for deploy: agent\_\* or pxe\_\*, see :ref:`IPA` -for explanation. An example local.conf that enables both types of drivers -and uses the ``agent_ipmitool`` driver by default:: +You can use either of two drivers for deploy: agent\_\* or pxe\_\*, see +:doc:`/admin/interfaces/deploy` for explanation. An example local.conf that +enables both types of drivers and uses the ``agent_ipmitool`` driver +by default:: cd devstack cat >local.conf <