openstack/tripleo-docs
Code Issues Proposed changes

Update the driver documentation for the undercloud

Browse Source 
This change updates the wording to use "hardware types", which is our
primary notion right now. A difference between hardware types and classic
drivers is mentioned, and a few helpful links are added.

Add the full list of (techinically) supported drivers, and link to their
documentation pages. Stop "recommeding" vendor drivers, as they often have
problems that the IPMI driver does not have, and make it clear that these
drivers are not supported by the TripleO team (incl. its ironic part).

Change-Id: I8b2b307c9dd0d3d53e2ab791184128628c72c43c
Related-Bug: #1690185
This commit is contained in:
Dmitry Tantsur 2017-12-01 17:33:11 +01:00
parent 98c2d4cb6d
commit 7299c84eeb
1 changed files with 110 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
doc/source/install/environments/baremetal.rst
View File

@ -172,7 +172,8 @@ descriptions.
Each node description should contains required fields: Each node description should contains required fields:
* ``pm_type`` - driver for Ironic nodes, see `Ironic Drivers`_ for details * ``pm_type`` - driver for Ironic nodes, see `Ironic Hardware Types`_
for details
* ``pm_addr`` - node BMC IP address (hypervisor address in case of virtual * ``pm_addr`` - node BMC IP address (hypervisor address in case of virtual
environment) environment)
@ -265,75 +266,131 @@ For example::
You don't need to create this file, if you plan on using You don't need to create this file, if you plan on using
:doc:`../advanced_deployment/node_discovery`. :doc:`../advanced_deployment/node_discovery`.
Ironic Drivers Ironic Hardware Types
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
Ironic drivers provide various level of support for different hardware. Ironic *hardware types* provide various level of support for different
The most up-to-date information about Ironic drivers is at hardware. Hardware types, introduced in the Ocata cycle, are a new generation
http://docs.openstack.org/developer/ironic/deploy/drivers.html, but note that of Ironic *drivers*. Previously, the word *drivers* was used to refer to what
this page always targets Ironic git master, not the release we use. is now called *classic drivers*. See `Ironic drivers documentation`_ for a full
explanation of similarities and differences between the two types.
This most generic driver is ``ipmi``. It uses `ipmitool`_ utility Hardware types are enabled in the ``undercloud.conf`` using the
to manage a bare metal node, and supports a vast variety of hardware. ``enabled_hardware_types`` configuration option. Classic drivers are enabled
using the ``enabled_drivers`` option. It is deprecated in the Queens release
cycle and should no longer be used. See the `hardware types migration guide`_
for information on how to migrate existing nodes.
.. admonition:: Stable Branch Both hardware types and classic drivers can be equially used in the
:class: stable ``pm_addr`` field of the ``instackenv.json``.
This driver is supported starting with the Pike release. For older releases See https://docs.openstack.org/ironic/latest/admin/drivers.html for the most
use functionally equivalent ``pxe_ipmitool`` driver. up-to-date information about Ironic hardware types and hardware
interfaces, but note that this page always targets Ironic git master, not the
release we use.
.. admonition:: Virtual Generic Hardware Types
:class: virtual ~~~~~~~~~~~~~~~~~~~~~~~
When combined with :doc:`virtualbmc` this driver can be used for developing * This most generic hardware type is ipmi_. It uses the `ipmitool`_ utility
and testing TripleO in a virtual environment as well. to manage a bare metal node, and supports a vast variety of hardware.
.. admonition:: Stable Branch .. admonition:: Stable Branch
:class: stable :class: stable
Prior to the Ocata release, a special ``pxe_ssh`` driver was used for This hardware type is supported starting with the Pike release. For older
testing Ironic in the virtual environment. This driver connects to the releases use the functionally equivalent ``pxe_ipmitool`` driver.
hypervisor to conduct management operations on virtual nodes. In case of
this driver, ``pm_addr`` is a hypervisor address, ``pm_user`` is a SSH
user name for accessing hypervisor, ``pm_password`` is a private SSH
key for accessing hypervisor. Note that private key must not be
encrypted.
.. warning:: .. admonition:: Virtual
The ``pxe_ssh`` driver is deprecated and ``pxe_ipmitool`` + :class: virtual
:doc:`virtualbmc` should be used instead.
Another generic driver is ``redfish``. It provides support for the quite new When combined with :doc:`virtualbmc`, this hardware type can be used for
Redfish_ protocol, which aims to replace IPMI eventually as a generic developing and testing TripleO in a virtual environment as well.
protocol for managing hardware. In addition to the ``pm_*`` fields mentioned
above, this driver also requires setting ``pm_system_id`` to the full
identifier of the node in the controller (e.g. ``/redfish/v1/Systems/42``).
.. admonition:: Stable Branch .. admonition:: Stable Branch
:class: stable :class: stable
Redfish support was introduced in the Pike release. Prior to the Ocata release, a special ``pxe_ssh`` driver was used for
testing Ironic in the virtual environment. This driver connects to the
hypervisor to conduct management operations on virtual nodes. In case
of this driver, ``pm_addr`` is a hypervisor address, ``pm_user`` is
a SSH user name for accessing hypervisor, ``pm_password`` is a private
SSH key for accessing hypervisor. Note that private key must not be
encrypted.
Ironic also provides specific drivers for some types of hardware: .. warning::
The ``pxe_ssh`` driver is deprecated and ``pxe_ipmitool`` +
:doc:`virtualbmc` should be used instead.
* ``pxe_ilo`` targets HP Proliant Gen 8 and Gen 9 systems, and is recommended * Another generic hardware type is redfish_. It provides support for the
for these systems instead of ``ipmi`` or ``pxe_ipmitool``. Please refer quite new `Redfish standard`_, which aims to replace IPMI eventually as
to the `current iLO driver documentation`_ or `detailed iLO documentation a generic protocol for managing hardware. In addition to the ``pm_*`` fields
for Kilo version`_. mentioned above, this hardware type also requires setting ``pm_system_id``
to the full identifier of the node in the controller (e.g.
``/redfish/v1/Systems/42``).
* ``pxe_drac`` targets DELL 11G and newer systems, and is recommended for these .. admonition:: Stable Branch
systems instead of ``ipmi`` or ``pxe_ipmitool``. :class: stable
There are also 2 testing drivers: Redfish support was introduced in the Pike release.
* ``fake_pxe`` provides stubs instead of real power and management operations. The following generic hardware types are not enabled by default:
When using this driver, you have to conduct power on and off operations,
and set the current boot device, yourself.
* ``fake`` provides stubs for every operation, so that Ironic does not touch * The snmp_ hardware type supports controlling PDUs for power management.
hardware at all. It requires boot device to be manually configured on the nodes.
* Finally, the ``manual-management`` hardware type (not enabled by default)
skips power and boot device management completely. It requires manual power
and boot operations to be done at the right moments, so it's not recommended
for a generic production.
.. admonition:: Stable Branch
:class: stable
The functional analog of this hardware type before the Queens release
was the ``fake_pxe`` driver.
Vendor Hardware Types
~~~~~~~~~~~~~~~~~~~~~
TripleO also supports vendor-specific hardware types for some types
of hardware:
* ilo_ targets HPE Proliant Gen 8 and Gen 9 systems.
.. admonition:: Stable Branch
:class: stable
Use the ``pxe_ilo`` classic driver before the Queens release.
* idrac_ targets DELL 12G and newer systems.
.. admonition:: Stable Branch
:class: stable
Use the ``pxe_drac`` classic driver before the Queens release.
The following hardware types are supported but not enabled by default:
* irmc_ targets FUJITSU PRIMERGY servers.
* cisco-ucs-managed_ targets UCS Manager managed Cisco UCS B/C series servers.
* cisco-ucs-standalone_ targets standalone Cisco UCS C series servers.
.. note::
Contact a specific vendor team if you have problems with any of these
drivers, as the TripleO team often cannot assist with them.
.. _Ironic drivers documentation: https://docs.openstack.org/ironic/latest/install/enabling-drivers.html
.. _hardware types migration guide: https://docs.openstack.org/ironic/latest/admin/upgrade-to-hardware-types.html
.. _ipmitool: http://sourceforge.net/projects/ipmitool/ .. _ipmitool: http://sourceforge.net/projects/ipmitool/
.. _Redfish: https://www.dmtf.org/standards/redfish .. _Redfish standard: https://www.dmtf.org/standards/redfish
.. _current iLO driver documentation: http://docs.openstack.org/developer/ironic/drivers/ilo.html .. _ipmi: https://docs.openstack.org/ironic/latest/admin/drivers/ipmitool.html
.. _detailed iLO documentation for Kilo version: https://wiki.openstack.org/wiki/Ironic/Drivers/iLODrivers/Kilo .. _redfish: https://docs.openstack.org/ironic/latest/admin/drivers/redfish.html
.. _snmp: https://docs.openstack.org/ironic/latest/admin/drivers/snmp.html
.. _ilo: https://docs.openstack.org/ironic/latest/admin/drivers/ilo.html
.. _idrac: https://docs.openstack.org/ironic/latest/admin/drivers/idrac.html
.. _irmc: https://docs.openstack.org/ironic/latest/admin/drivers/irmc.html
.. _cisco-ucs-managed: https://docs.openstack.org/ironic/latest/admin/drivers/ucs.html
.. _cisco-ucs-standalone: https://docs.openstack.org/ironic/latest/admin/drivers/cimc.html