From e824e490a3e2cf845b2ca5069250048da633376b Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Thu, 2 Nov 2017 13:06:15 +0100 Subject: [PATCH] Switch emphasis to hardware types in the installation guide 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 --- doc/source/install/configdrive.rst | 6 +- doc/source/install/configure-glance-swift.rst | 7 +- doc/source/install/configure-ipmi.rst | 14 ++-- doc/source/install/configure-pxe.rst | 8 ++- .../install/configure-tenant-networks.rst | 8 +-- doc/source/install/enrollment.rst | 32 +++++---- doc/source/install/include/boot-mode.rst | 8 +-- doc/source/install/include/trusted-boot.rst | 2 +- doc/source/install/standalone.rst | 70 ++++++++++--------- doc/source/install/troubleshooting.rst | 2 +- 10 files changed, 81 insertions(+), 76 deletions(-) diff --git a/doc/source/install/configdrive.rst b/doc/source/install/configdrive.rst index eef55f9994..55fd7897df 100644 --- a/doc/source/install/configdrive.rst +++ b/doc/source/install/configdrive.rst @@ -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] ... diff --git a/doc/source/install/configure-glance-swift.rst b/doc/source/install/configure-glance-swift.rst index 13e67f435d..b11d9e8162 100644 --- a/doc/source/install/configure-glance-swift.rst +++ b/doc/source/install/configure-glance-swift.rst @@ -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, diff --git a/doc/source/install/configure-ipmi.rst b/doc/source/install/configure-ipmi.rst index 5e55a1f333..d95ac851e3 100644 --- a/doc/source/install/configure-ipmi.rst +++ b/doc/source/install/configure-ipmi.rst @@ -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 diff --git a/doc/source/install/configure-pxe.rst b/doc/source/install/configure-pxe.rst index 3ee1a9814a..bde1d7968e 100644 --- a/doc/source/install/configure-pxe.rst +++ b/doc/source/install/configure-pxe.rst @@ -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`. diff --git a/doc/source/install/configure-tenant-networks.rst b/doc/source/install/configure-tenant-networks.rst index 31479b8015..7bc80108c1 100644 --- a/doc/source/install/configure-tenant-networks.rst +++ b/doc/source/install/configure-tenant-networks.rst @@ -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). diff --git a/doc/source/install/enrollment.rst b/doc/source/install/enrollment.rst index 25104be7da..ce084551a9 100644 --- a/doc/source/install/enrollment.rst +++ b/doc/source/install/enrollment.rst @@ -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 | diff --git a/doc/source/install/include/boot-mode.rst b/doc/source/install/include/boot-mode.rst index 3ac0f23bdc..7895beba6a 100644 --- a/doc/source/install/include/boot-mode.rst +++ b/doc/source/install/include/boot-mode.rst @@ -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. diff --git a/doc/source/install/include/trusted-boot.rst b/doc/source/install/include/trusted-boot.rst index 82de31c5dd..ac3a75d885 100644 --- a/doc/source/install/include/trusted-boot.rst +++ b/doc/source/install/include/trusted-boot.rst @@ -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} diff --git a/doc/source/install/standalone.rst b/doc/source/install/standalone.rst index bcb7d702a2..db4f8ea9d6 100644 --- a/doc/source/install/standalone.rst +++ b/doc/source/install/standalone.rst @@ -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 ` (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 diff --git a/doc/source/install/troubleshooting.rst b/doc/source/install/troubleshooting.rst index b2dc16e0bc..a4e5f3e910 100644 --- a/doc/source/install/troubleshooting.rst +++ b/doc/source/install/troubleshooting.rst @@ -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 |