openstack/ironic
Code Issues Proposed changes

Switch emphasis to hardware types in the installation guide

Browse Source 
This change updates the installation guide to talk in terms of hardware types
and hardware interfaces, only briefly mentioning classic drivers, when needed.

Also fixes incorrect information about instance_info fields in the standalone
guide.

Change-Id: I5e8a0de79c247535fd599318540fb8bbd2fc5df0
This commit is contained in:
Dmitry Tantsur 2017-11-02 13:06:15 +01:00
parent f02ef8ad7a
commit e824e490a3
10 changed files with 81 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/install/configdrive.rst
View File

@ -92,9 +92,9 @@ instead. ::
password = PASSWORD
auth_url = http://RADOSGW_IP:8000/auth/v1
Make sure that if an agent_* driver is being used, edit
``/etc/glance/glance-api.conf`` to store the instance images in respective
object store (radosgw or swift) as well::
If the :ref:`direct-deploy` is being used, edit ``/etc/glance/glance-api.conf``
to store the instance images in respective object store (radosgw or swift)
as well::
[glance_store]
...

7
doc/source/install/configure-glance-swift.rst
View File

@ -3,10 +3,9 @@
Configure the Image service for temporary URLs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some drivers of the Baremetal service (in particular, any ``agent_*`` drivers,
any new-style drivers using ``direct`` deploy interface,
and some virtual media drivers) require target user images to be available
over clean HTTP(S) URL with no authentication involved
Some drivers of the Baremetal service (in particular, any drivers using
:ref:`direct-deploy` and some virtual media drivers) require target user images
to be available over clean HTTP(S) URL with no authentication involved
(neither username/password-based, nor token-based).
When using the Baremetal service integrated in OpenStack,

14
doc/source/install/configure-ipmi.rst
View File

@ -5,10 +5,9 @@ Installing ipmitool command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable one of the drivers that use IPMI_ protocol for power and management
actions (for example, ``ipmi``, ``pxe_ipmitool`` and ``agent_ipmitool``), the
``ipmitool`` command must be present on the service node(s) where
``ironic-conductor`` is running. On most distros, it is provided as part
of the ``ipmitool`` package. Source code is available at
actions (for example, ``ipmi``), the ``ipmitool`` command must be present on
the service node(s) where ``ironic-conductor`` is running. On most distros, it
is provided as part of the ``ipmitool`` package. Source code is available at
http://ipmitool.sourceforge.net/.
.. warning::
@ -58,10 +57,9 @@ Collecting sensor data
~~~~~~~~~~~~~~~~~~~~~~
Bare Metal service supports sending IPMI sensor data to Telemetry with
certain drivers, such as drivers ending with ``ipmitool``, ``ilo`` and
``irmc``. By default, support for sending IPMI sensor data to Telemetry is
disabled. If you want to enable it, you should make the following two changes
in ``ironic.conf``:
certain hardware types, such as ``ipmi``, ``ilo`` and ``irmc``. By default,
support for sending IPMI sensor data to Telemetry is disabled. If you want
to enable it, you should make the following two changes in ``ironic.conf``:
.. code-block:: ini

8
doc/source/install/configure-pxe.rst
View File

@ -202,9 +202,11 @@ steps on the ironic conductor node to configure the PXE UEFI environment.
#. Make sure that bare metal node is configured to boot in UEFI boot mode and
boot device is set to network/pxe.
NOTE: ``pxe_ilo`` driver supports automatic setting of UEFI boot mode and
boot device on the bare metal node. So this step is not required for
``pxe_ilo`` driver.
.. note::
Some drivers, e.g. ``ilo`` and ``irmc``, support automatic setting of the
boot mode during deployment. This step is not required for them. Please
check :doc:`../admin/drivers` for information on whether your driver
requires manual UEFI configuration.
.. note::
For more information on configuring boot modes, see :ref:`boot_mode_support`.

8
doc/source/install/configure-tenant-networks.rst
View File

@ -81,10 +81,10 @@ provisioning will happen in a multi-tenant environment (which means using the
* TFTP
* egress port used for the Bare Metal service (6385 by default)
* ingress port used for ironic-python-agent (9999 by default)
* if using the iSCSI deploy method (``pxe_*`` and ``iscsi_*`` drivers),
the ingress port used for iSCSI (3260 by default)
* if using the direct deploy method (``agent_*`` drivers), the egress
port used for the Object Storage service (typically 80 or 443)
* if using :ref:`iscsi-deploy`, the ingress port used for iSCSI
(3260 by default)
* if using :ref:`direct-deploy`, the egress port used for the Object
Storage service (typically 80 or 443)
* if using iPXE, the egress port used for the HTTP server running
on the ironic-conductor nodes (typically 80).

32
doc/source/install/enrollment.rst
View File

@ -29,9 +29,11 @@ Choosing a driver
-----------------
When enrolling a node, the most important information to supply is *driver*.
This can be either a *classic driver* or a *hardware type* - see
:doc:`enabling-drivers` for the difference. The ``driver list`` command can
be used to list all drivers (of both types) enabled on all hosts:
See :doc:`enabling-drivers` for a detailed explanation of bare metal drivers,
hardware types and interfaces. Starting with the Pike release, we recommend
the use of *hardware types* instead of *classic drivers*, since classic drivers
may be deprecated in the near future. The ``driver list`` command can be used
to list all drivers enabled on all hosts:
.. code-block:: console
@ -44,7 +46,8 @@ be used to list all drivers (of both types) enabled on all hosts:
+---------------------+-----------------------+
Starting with API version 1.31 (and ``python-ironicclient`` 1.13), you can
also list only classic or only dynamic drivers:
also list only classic drivers or only hardware types via the ``--type``
argument:
.. code-block:: console
@ -67,7 +70,7 @@ command:
.. code-block:: console
$ openstack baremetal driver property list pxe_ipmitool
$ openstack baremetal driver property list ipmi
+----------------------+-------------------------------------------------------------------------------------------------------------+
| Property | Description |
+----------------------+-------------------------------------------------------------------------------------------------------------+
@ -124,8 +127,7 @@ for provisioning. Some steps are shown separately for illustration purposes,
and may be combined if desired.
#. Create a node in the Bare Metal service with the ``node create`` command.
At a minimum, you must specify the driver name (for example,
``pxe_ipmitool``, ``agent_ipmitool`` or ``ipmi``).
At a minimum, you must specify the driver name (for example, ``ipmi``).
This command returns the node UUID along with other information
about the node. The node's provision state will be ``enroll``:
@ -133,14 +135,14 @@ and may be combined if desired.
.. code-block:: console
$ export OS_BAREMETAL_API_VERSION=1.11
$ openstack baremetal node create --driver pxe_ipmitool
$ openstack baremetal node create --driver ipmi
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| uuid | dfc6189f-ad83-4261-9bda-b27258eb1987 |
| driver_info | {} |
| extra | {} |
| driver | pxe_ipmitool |
| driver | ipmi |
| chassis_uuid | |
| properties | {} |
| name | None |
@ -161,7 +163,7 @@ and may be combined if desired.
| provision_updated_at | None |
| maintenance | False |
| power_state | None |
| driver | pxe_ipmitool |
| driver | ipmi |
| properties | {} |
| instance_uuid | None |
| name | None |
@ -229,7 +231,7 @@ and may be combined if desired.
.. code-block:: console
$ openstack baremetal node create --driver pxe_ipmitool \
$ openstack baremetal node create --driver ipmi \
--driver-info ipmi_username=$USER \
--driver-info ipmi_password=$PASS \
--driver-info ipmi_address=$ADDRESS
@ -314,7 +316,7 @@ Adding scheduling information
.. code-block:: console
$ openstack baremetal node create --driver pxe_ipmitool \
$ openstack baremetal node create --driver ipmi \
--driver-info ipmi_username=$USER \
--driver-info ipmi_password=$PASS \
--driver-info ipmi_address=$ADDRESS \
@ -510,7 +512,7 @@ The node is named 'example' in the following examples:
.. code-block:: console
$ openstack baremetal node create --driver agent_ipmitool --name example
$ openstack baremetal node create --driver ipmi --name example
or
@ -524,14 +526,14 @@ UUID interchangeably:
.. code-block:: console
$ openstack baremetal node create --driver agent_ipmitool --name example
$ openstack baremetal node create --driver ipmi --name example
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
| uuid | 71e01002-8662-434d-aafd-f068f69bb85e |
| driver_info | {} |
| extra | {} |
| driver | agent_ipmitool |
| driver | ipmi |
| chassis_uuid | |
| properties | {} |
| name | example |

8
doc/source/install/include/boot-mode.rst
View File

@ -3,11 +3,9 @@
Boot mode support
-----------------
The following drivers support setting of boot mode (Legacy BIOS or UEFI).
* ``pxe_ipmitool``
The boot modes can be configured in Bare Metal service in the following way:
Most of the bare metal drivers (including the generic ``ipmi`` hardware type)
support setting of boot mode (Legacy BIOS or UEFI). The boot modes can be
configured in the Bare Metal service in the following way:
* When no boot mode setting is provided, these drivers default the boot_mode
to Legacy BIOS.

2
doc/source/install/include/trusted-boot.rst
View File

@ -27,7 +27,7 @@ with PXE and Nova:
#. Enroll the node and update the node capability value::
openstack baremetal node create --driver pxe_ipmitool
openstack baremetal node create --driver ipmi
openstack baremetal node set $NODE_UUID --property capabilities={'trusted_boot':true}

70
doc/source/install/standalone.rst
View File

@ -31,34 +31,30 @@ You should make the following changes to ``/etc/ironic/ironic.conf``:
for you.
If you don't use Image service, it's possible to provide images to Bare Metal
service via hrefs.
service via a URL.
.. note::
At the moment, only two types of hrefs are acceptable instead of Image
service UUIDs: HTTP(S) hrefs (for example, "http://my.server.net/images/img")
and file hrefs (file:///images/img).
At the moment, only two types of URLs are acceptable instead of Image
service UUIDs: HTTP(S) URLs (for example, "http://my.server.net/images/img")
and file URLs (file:///images/img).
There are however some limitations for different drivers:
There are however some limitations for different hardware interfaces:
* If you're using one of the drivers that use agent deploy method (namely,
``agent_ilo`` or ``agent_ipmitool``)
you have to know MD5 checksum for your instance image. To
compute it, you can use the following command::
* If you're using :ref:`direct-deploy`, you have to provide the Bare Metal
service with the MD5 checksum of your instance image. To compute it, you can
use the following command::
md5sum image.qcow2
ed82def8730f394fb85aef8a208635f6 image.qcow2
Apart from that, because of the way the agent deploy method works, image
hrefs can use only HTTP(S) protocol.
* :ref:`direct-deploy` requires the instance image be accessible through a
HTTP(s) URL.
* If you're using ``iscsi_ilo`` or ``agent_ilo`` driver, Object Storage service
is required, as these drivers need to store floppy image that is used to pass
parameters to deployment iso. For this method also only HTTP(S) hrefs are
acceptable, as HP iLO servers cannot attach other types of hrefs as virtual
media.
* Other drivers use PXE deploy method and there are no special requirements
in this case.
* Some :doc:`boot interfaces </admin/interfaces/boot>` (for example,
``ilo-virtual-media``) require the Object Storage service, as these
drivers need to store floppy image that is used to pass parameters
to deployment iso. For this method also only HTTP(S) URLs are acceptable,
as HP iLO servers cannot attach other types of URLs as virtual media.
Steps to start a deployment are pretty similar to those when using Compute:
@ -73,10 +69,10 @@ Steps to start a deployment are pretty similar to those when using Compute:
export OS_URL=http://localhost:6385/
#. Create a node in Bare Metal service. At minimum, you must specify the driver
name (for example, "pxe_ipmitool"). You can also specify all the required
name (for example, ``ipmi``). You can also specify all the required
driver parameters in one command. This will return the node UUID::
openstack node create --driver pxe_ipmitool \
openstack node create --driver ipmi \
--driver-info ipmi_address=ipmi.server.net \
--driver-info ipmi_username=user \
--driver-info ipmi_password=pass \
@ -92,7 +88,7 @@ Steps to start a deployment are pretty similar to those when using Compute:
| | u'ipmi.server.net', u'ipmi_username': u'user', u'ipmi_password': |
| | u'******'} |
| extra | {} |
| driver | pxe_ipmitool |
| driver | ipmi |
| chassis_uuid | |
| properties | {} |
+--------------+--------------------------------------------------------------------------+
@ -112,23 +108,33 @@ Steps to start a deployment are pretty similar to those when using Compute:
openstack baremetal port create $MAC_ADDRESS --node $NODE_UUID
#. As there is no Compute service flavor and instance image is not provided with
nova boot command, you also need to specify some fields in ``instance_info``.
For PXE deployment, they are ``image_source``, ``kernel``, ``ramdisk``,
``root_gb``::
#. You also need to specify some fields in the node's ``instance_info``:
* ``image_source`` - URL of the whole disk or root partition image,
mandatory. For :ref:`direct-deploy` only HTTP(s) links are accepted,
while :ref:`iscsi-deploy` also accepts links to local files (prefixed
with ``file://``).
* ``root_gb`` - size of the root partition, mandatory.
.. TODO(dtantsur): root_gb should not be mandatory for whole disk images,
but it seems to be.
* ``image_checksum`` - MD5 checksum of the image specified by
``image_source``, only required for :ref:`direct-deploy`.
* ``kernel``, ``ramdisk`` - HTTP(s) or file URLs of the kernel and
initramfs of the target OS, only required for partition images.
For example::
openstack baremetal node set $NODE_UUID \
--instance-info image_source=$IMG \
--instance-info image_checksum=$MD5HASH \
--instance-info kernel=$KERNEL \
--instance-info ramdisk=$RAMDISK \
--instance-info root_gb=10
Here $IMG, $KERNEL, $RAMDISK can also be HTTP(S) or file hrefs. For agent
drivers, you don't need to specify kernel and ramdisk, but MD5 checksum of
instance image is required::
openstack baremetal node set $NODE_UUID --instance-info image_checksum=$MD5HASH
#. Validate that all parameters are correct::
openstack baremetal node validate $NODE_UUID

2
doc/source/install/troubleshooting.rst
View File

@ -41,7 +41,7 @@ service and Bare Metal service::
| last_error | None |
| created_at | 2014-11-20T23:57:03+00:00 |
| target_provision_state | None |
| driver | pxe_ipmitool |
| driver | ipmi |
| updated_at | 2014-11-21T00:47:34+00:00 |
| instance_info | {} |
| chassis_uuid | 7b49bbc5-2eb7-4269-b6ea-3f1a51448a59 |