diff --git a/doc/source/admin/drivers/ipmitool.rst b/doc/source/admin/drivers/ipmitool.rst index 6aee2a2ab5..56f14f10cb 100644 --- a/doc/source/admin/drivers/ipmitool.rst +++ b/doc/source/admin/drivers/ipmitool.rst @@ -32,10 +32,10 @@ Glossary * BMC_ - Baseboard Management Controller. * RMCP - Remote Management Control Protocol. -Enabling the IPMITool driver(s) +Enabling the IPMItool driver(s) =============================== -Please see `IPMI configuration guide`_ for the required dependencies. +Please see :doc:`/install/configure-ipmi` for the required dependencies. #. The ``ipmi`` hardware type is enabled by default starting with the Ocata release. To enable it explicitly, add the following to your ``ironic.conf``: @@ -46,7 +46,7 @@ Please see `IPMI configuration guide`_ for the required dependencies. enabled_hardware_types = ipmi #. The ``pxe_ipmitool`` classic driver is enabled by default. To enable one or - more of the other ipmitool classic drivers, add them to the + more of the other IPMI classic drivers, add them to the ``enabled_drivers`` configuration option in your ``ironic.conf``. The following enables ``pxe_ipmitool`` and ``agent_ipmitool`` drivers: @@ -57,14 +57,14 @@ Please see `IPMI configuration guide`_ for the required dependencies. #. Restart the Ironic conductor service. -Please see `documentation on enabling drivers`_ for more details. +Please see :doc:`/install/enabling-drivers` for more details. Registering a node with the IPMItool driver =========================================== -Nodes configured to use the IPMItool drivers should have the driver field set -to ``ipmi`` (hardware type) or to the name of one of the classic drivers -that support ipmitool. +Nodes configured to use the IPMItool drivers should have the ``driver`` field +set to ``ipmi`` (hardware type) or to the name of one of the classic drivers +that support IPMItool. The following configuration value is required and has to be added to the node's ``driver_info`` field: @@ -85,7 +85,7 @@ good practice to have them set: your BMC. The ``ironic node-create`` command can be used to enroll a node with -an IPMITool-based driver. For example:: +an IPMItool-based driver. For example:: ironic node-create -d ipmi -i ipmi_address=
\ -i ipmi_username= -i ipmi_password= @@ -105,7 +105,7 @@ Single/Double bridging functionality the bridging functionality. There are two different bridging functionalities supported by the -IPMITool-based drivers: *single* bridge and *dual* bridge. +IPMItool-based drivers: *single* bridge and *dual* bridge. The following configuration values need to be added to the node's ``driver_info`` field so bridging can be used: @@ -177,5 +177,3 @@ protocol version:: .. _IPMItool: https://sourceforge.net/projects/ipmitool/ .. _IPMI: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface .. _BMC: https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface#Baseboard_management_controller -.. _IPMI configuration guide: https://docs.openstack.org/project-install-guide/baremetal/draft/configure-ipmi.html -.. _documentation on enabling drivers: https://docs.openstack.org/project-install-guide/baremetal/draft/enabling-drivers.html diff --git a/doc/source/install/configure-pxe.rst b/doc/source/install/configure-pxe.rst index a207f35c93..74f6086389 100644 --- a/doc/source/install/configure-pxe.rst +++ b/doc/source/install/configure-pxe.rst @@ -188,7 +188,7 @@ steps on the ironic conductor node to configure the PXE UEFI environment. It redirects it to specific grub config file based on DHCP IP assigned to baremetal node. - .. literalinclude:: ../../ironic/drivers/modules/master_grub_cfg.txt + .. literalinclude:: ../../../ironic/drivers/modules/master_grub_cfg.txt Change the permission of grub.cfg:: diff --git a/doc/source/install/enabling-drivers.rst b/doc/source/install/enabling-drivers.rst index 5b5e20fc24..f698324fea 100644 --- a/doc/source/install/enabling-drivers.rst +++ b/doc/source/install/enabling-drivers.rst @@ -37,7 +37,7 @@ configuration option, for example: [DEFAULT] enabled_hardware_types = ipmi,redfish -However, due to their dynamic nature, they also require configuring enabled +Due to the driver's dynamic nature, they also require configuring enabled hardware interfaces. .. note:: @@ -61,9 +61,11 @@ boot enabled_boot_interfaces = pxe,ilo-virtual-media Boot interfaces with ``pxe`` in their name require :doc:`configure-pxe`. + There are also a few hardware-specific boot interfaces - see + :doc:`/admin/drivers` for their required configuration. console manages access to the serial console of a bare metal node. - See `Configuring Web or Serial Console`_ for details. + See :doc:`/admin/console` for details. deploy defines how the image gets transferred to the target disk. @@ -92,7 +94,7 @@ inspect enabled_hardware_types = ipmi,ilo,irmc enabled_inspect_interfaces = ilo,irmc,inspector - See `inspection documentation`_ for more details. + See :doc:`/admin/inspection` for more details. management provides additional hardware management actions, like getting or setting boot devices. This interface is usually vendor-specific, and its name @@ -106,7 +108,7 @@ management enabled_management_interfaces = ipmitool,redfish,ilo,irmc Using ``ipmitool`` requires :doc:`configure-ipmi`. See - `driver-specific documentation`_ for required configuration of each driver. + :doc:`/admin/drivers` for the required configuration of each driver. network connects/disconnects bare metal nodes to/from virtual networks. This is the only interface that is also pluggable for classic drivers. See @@ -123,11 +125,11 @@ power enabled_power_interfaces = ipmitool,redfish,ilo,irmc Using ``ipmitool`` requires :doc:`configure-ipmi`. See - `driver-specific documentation`_ for required configuration of each driver. + :doc:`/admin/drivers` for the required configuration of each driver. raid manages building and tearing down RAID on nodes. Similar to inspection, it can be implemented either out-of-band or in-band (via ``agent`` - implementation). See `RAID documentation`_ for details. + implementation). See :doc:`/admin/raid` for details. For example: .. code-block:: ini @@ -135,8 +137,8 @@ raid enabled_hardware_types = ipmi,redfish,ilo,irmc enabled_raid_interfaces = agent,no-raid vendor - is a place for vendor extensions to be exposed in API. See `vendor - methods documentation`_ for details. + is a place for vendor extensions to be exposed in API. See + :doc:`/contributor/vendor-passthru` for details. .. code-block:: ini @@ -213,23 +215,23 @@ respectively: This is because the ``redfish`` hardware type will have different enabled *deploy* interfaces on these conductors. It would have been fine, if the second -conductor had ``enabled_deploy_interface=direct`` instead of ``iscsi``. +conductor had ``enabled_deploy_interfaces = direct`` instead of ``iscsi``. This situation is not detected by the Bare Metal service, but it can cause inconsistent behavior in the API, when node functionality will depend on which conductor it gets assigned to. .. note:: - We don't treat it as an error, because such *temporary* inconsistency is + We don't treat this as an error, because such *temporary* inconsistency is inevitable during a rolling upgrade or a configuration update. Configuring interface defaults ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a user does not provide an explicit value for one of interfaces (when -creating a node or updating its driver), the default value is calculated -as described in :ref:`hardware_interfaces_defaults`. An operator can override -the defaults for any interfaces by setting one of options named +When an operator does not provide an explicit value for one of the interfaces +(when creating a node or updating its driver), the default value is calculated +as described in :ref:`hardware_interfaces_defaults`. It is also possible +to override the defaults for any interfaces by setting one of the options named ``default__interface``, where ```` is the interface name. For example: @@ -247,9 +249,11 @@ its hardware type. Thus, changing these configuration options has no effect on existing nodes. .. warning:: - The default interface implementation has to be configured the same way + The default interface implementation must be configured the same way across all conductors in the cloud, except maybe for a short period of time - during an upgrade or configuration update. + during an upgrade or configuration update. Otherwise the default + implementation will depend on which conductor handles which node, and this + mapping is not predictable or even persistent. .. warning:: These options should be used with care. If a hardware type does not @@ -280,14 +284,9 @@ be installed locally. For example, * drivers ending with ``ipmitool`` require :doc:`configure-ipmi`. -See `driver-specific documentation`_ for required configuration of each driver. +See :doc:`/admin/drivers` for the required configuration of each driver. .. _driver composition reform specification: http://specs.openstack.org/openstack/ironic-specs/specs/approved/driver-composition-reform.html -.. _driver-specific documentation: https://docs.openstack.org/ironic/latest/admin/drivers.html .. _setup.cfg: https://git.openstack.org/cgit/openstack/ironic/tree/setup.cfg -.. _`Configuring Web or Serial Console`: http://docs.openstack.org/ironic/latest/admin/console.html .. _iSCSI: https://en.wikipedia.org/wiki/ISCSI -.. _ironic-inspector: https://docs.openstack.org/developer/ironic-inspector/ -.. _inspection documentation: https://docs.openstack.org/ironic/latest/admin/inspection.html -.. _RAID documentation: https://docs.openstack.org/ironic/latest/admin/raid.html -.. _vendor methods documentation: https://docs.openstack.org/ironic/latest/contributor/vendor-passthru.html +.. _ironic-inspector: https://docs.openstack.org/ironic-inspector/latest/ diff --git a/doc/source/install/enrollment.rst b/doc/source/install/enrollment.rst index d9bfbb6047..6fc6d54d3f 100644 --- a/doc/source/install/enrollment.rst +++ b/doc/source/install/enrollment.rst @@ -56,8 +56,8 @@ also list only classic or only dynamic drivers: +---------------------+-----------------------+ The specific driver to use should be picked based on actual hardware -capabilities and expected features. See `driver-specific documentation`_ -for more hints on that. +capabilities and expected features. See :doc:`/admin/drivers` for more hints +on that. Each driver has a list of *driver properties* that need to be specified via the node's ``driver_info`` field, in order for the driver to operate on node. @@ -82,8 +82,6 @@ command: The properties marked as required must be supplied either during node creation or shortly after. Some properties may only be required for certain features. -.. _driver-specific documentation: https://docs.openstack.org/ironic/latest/admin/drivers.html - Note on API versions -------------------- @@ -172,7 +170,7 @@ and may be combined if desired. +------------------------+--------------------------------------+ A node may also be referred to by a logical name as well as its UUID. - A name can be assigned to the node during creating by adding the ``-n`` + A name can be assigned to the node during its creation by adding the ``-n`` option to the ``node-create`` command or by updating an existing node with the ``node-update`` command. See `Logical Names`_ for examples. @@ -198,7 +196,7 @@ and may be combined if desired. --deploy-interface direct \ --raid-interface agent - If no value is provided for certain interfaces, `Defaults for hardware + If no value is provided for some interfaces, `Defaults for hardware interfaces`_ are used instead. It's an error to try changing this field for a node with a *classic driver*, @@ -449,10 +447,9 @@ To move a node from ``manageable`` to ``available`` provision state: +------------------------+--------------------------------------------------------------------+ For more details on the Bare Metal service's state machine, see the -`state machine `_ -documentation. +:doc:`/contributor/states` documentation. -.. _ComputeCapabilitiesFilter: http://docs.openstack.org/developer/nova/devref/filter_scheduler.html?highlight=computecapabilitiesfilter +.. _ComputeCapabilitiesFilter: https://docs.openstack.org/nova/latest/user/filter-scheduler.html Logical names ------------- @@ -642,15 +639,9 @@ Hardware Inspection ------------------- The Bare Metal service supports hardware inspection that simplifies enrolling -nodes - please see `inspection`_ for details. - -.. _`inspection`: http://docs.openstack.org/ironic/latest/admin/inspection.html +nodes - please see :doc:`/admin/inspection` for details. Tenant Networks and Port Groups ------------------------------- -See `Multitenancy in Bare Metal service`_ and -`Port groups configuration in Bare Metal service`_. - -.. _`Multitenancy in Bare Metal service`: http://docs.openstack.org/ironic/latest/admin/multitenancy.html -.. _`Port groups configuration in Bare Metal service`: http://docs.openstack.org/ironic/latest/admin/portgroups.html +See :doc:`/admin/multitenancy` and :doc:`/admin/portgroups`. diff --git a/doc/source/install/include/configure-ironic-conductor.rst b/doc/source/install/include/configure-ironic-conductor.rst index 14db5edca0..7681a1197d 100644 --- a/doc/source/install/include/configure-ironic-conductor.rst +++ b/doc/source/install/include/configure-ironic-conductor.rst @@ -66,7 +66,7 @@ Configuring ironic-conductor service glance_host=GLANCE_IP .. note:: - Swift backend for the Image service should be installed and configured + Swift backend for the Image service must be installed and configured for ``agent_*`` drivers. Ceph Object Gateway (RADOS Gateway) is also supported as the Image service's backend (`radosgw support `_). diff --git a/doc/source/install/standalone.rst b/doc/source/install/standalone.rst index a18a786065..16c6bbc22e 100644 --- a/doc/source/install/standalone.rst +++ b/doc/source/install/standalone.rst @@ -2,7 +2,7 @@ Using Bare Metal service as a standalone service ================================================ -It's possible to use the Bare Metal service without other OpenStack services. +It is possible to use the Bare Metal service without other OpenStack services. You should make the following changes to ``/etc/ironic/ironic.conf``: #. To disable usage of Identity service tokens:: @@ -151,7 +151,7 @@ For iLO drivers, fields that should be provided are: * ``ilo_boot_iso``, ``image_source``, ``root_gb`` under ``instance_info``. .. note:: - The Bare metal service tracks content changes for non-Glance images by + The Bare Metal service tracks content changes for non-Glance images by checking their modification date and time. For example, for HTTP image, if 'Last-Modified' header value from response to a HEAD request to "http://my.server.net/images/deploy.ramdisk" is greater than cached image