openstack/ironic
Code Issues Proposed changes

docs: remove backwards looking notes

Browse Source 
A recent ?Linked-In? or ?Reddit? thread I saw bemoned Ironic's
documentation as stale. This perception largely seems to be due
to backwards looking notes in the text.

For example, it doesn't make sense for current docs to talk about
Juno, Kilo, or upgrade to Queens.

And so, after getting some context loaded into Claude, I was able
to ask it to cleanup the docs for versions older than 2023.1.

Mostly, it looks like just cleaning up some sentences of our prior
context so it seems more up to date.

Assisted-By: Claude Code - Claude Sonnet 4
Change-Id: Ic86db90db441909848f7ec566c94e4018e322faf
Signed-off-by: Julia Kreger <juliaashleykreger@gmail.com>
This commit is contained in:
Julia Kreger
2025-09-24 10:01:42 -07:00
parent a483e6aaa2
commit c539943c01
8 changed files with 53 additions and 314 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
doc/source/admin/adoption.rst
View File

@@ -165,10 +165,9 @@ from the ``manageable`` state to ``active`` state::
baremetal node set <node name or uuid> --instance-uuid <uuid>
.. NOTE::
In Newton, coupled with API version 1.20, the concept of a
network_interface was introduced. A user of this feature may wish to
add new nodes with a network_interface of ``noop`` and then change
the interface at a later point and time.
A user of this feature may wish to add new nodes with a
``network_interface`` value of ``noop`` and then change the interface
at a later point and time.
Troubleshooting
===============

4
doc/source/admin/drivers/ilo.rst
View File

@@ -8,8 +8,8 @@ Overview
========
iLO driver enables to take advantage of features of iLO management engine in
HPE ProLiant servers. The ``ilo`` hardware type is targeted for HPE ProLiant
Gen8 and Gen9 systems which have `iLO 4 management engine`_. From **Pike**
release ``ilo`` hardware type supports ProLiant Gen10 systems which have
Gen8 and Gen9 systems which have `iLO 4 management engine`_. The ``ilo``
hardware type supports ProLiant Gen10 systems which have
`iLO 5 management engine`_. iLO5 conforms to `Redfish`_ API and hence hardware
type ``redfish`` (see :doc:`redfish`) is also an option for this kind of
hardware but it lacks the iLO specific features.

3
doc/source/admin/drivers/irmc.rst
View File

@@ -46,8 +46,7 @@ hardware interfaces:
.. warning::
We deprecated the ``pxe`` boot interface when used with ``irmc``
hardware type. Support for this interface will be removed in the
future. Instead, use ``irmc-pxe``. ``irmc-pxe`` boot interface
was introduced in Pike.
future. Instead, use ``irmc-pxe``.
* console
Supports ``ipmitool-socat``, ``ipmitool-shellinabox``, and ``no-console``.

25
doc/source/admin/troubleshooting.rst
View File

@@ -629,15 +629,19 @@ Originally this was a fairly easy issue to encounter. The retry logic path
which resulted between the Orchestration (heat) and Compute (nova) services,
could sometimes result in additional un-necessary ports being created.
Bugs of this class have been largely resolved since the Rocky development
cycle. Since then, the way this can become encountered is due to Networking
(neutron) VIF attachments not being removed or deleted prior to deleting a
port in the Bare Metal service.
Most users of modern Ironic are unlikely to experience this except in
situations where a Networking (neutron) VIF attachment was not removed
or deleted prior to deleting and re-creating a port in the Bare Metal
service. Users utilizing custom tooling may also experience a similar
issue due to incorrect usage patterns, i.e. a port being pre-assigned
a physical machine's MAC address.
Ultimately, the key of this is that the port is being deleted. Under most
operating circumstances, there really is no need to delete the port, and
VIF attachments are stored on the port object, so deleting the port
*CAN* result in the VIF not being cleaned up from Neutron.
Ultimately, the key of this is that the port is being deleted,
or a separate port was added outside of Ironic's workflow. Under most
operating circumstances, there really is no need to delete the port
on a node, and VIF attachments are stored on the port object,
so deleting the port *CAN* result in the VIF not being cleaned
up from Neutron which ends up creating this sort of situation.
Under normal circumstances, when deleting ports, a node should be in a
stable state, and the node should not be provisioned. If the
@@ -680,7 +684,10 @@ Using that, you can delete the port. Example:
use or no longer seems applicable/operable. If multiple deployments of
the Bare Metal service with a single Neutron, the possibility that a
inventory typo, or possibly even a duplicate MAC address exists, which
could also produce the same basic error message.
could also produce the same basic error message. A final root cause
is where users might pre-create a port in Neutron with a Bare Metal
port's MAC address, which is an incorrect practice as Ironic attempts
to assert the MAC address based upon the Node.
My test VM image does not deploy -- mount point does not exist
==============================================================

42
doc/source/admin/upgrade-guide.rst
View File

@@ -16,13 +16,11 @@ Both offline and rolling upgrades are supported.
Plan your upgrade
=================
* Rolling upgrades are available starting with the Pike release; that is, when
upgrading from Ocata. This means that it is possible to do an upgrade with
minimal to no downtime of the Bare Metal API.
* Rolling upgrades are supported for the Bare Metal service, allowing upgrades
with minimal to no downtime of the Bare Metal API.
* Upgrades are only supported between two consecutive named releases.
This means that you cannot upgrade Ocata directly into Queens; you need to
upgrade into Pike first.
* Upgrades are supported between named releases in the framing of
`SLURP <https://docs.openstack.org/project-team-guide/release-cadence-adjustment.html>`_.
* The `release notes <https://docs.openstack.org/releasenotes/ironic/>`_
should always be read carefully when upgrading the Bare Metal service.
@@ -85,10 +83,10 @@ Once the above is done, do the following:
.. warning::
You will not be able to start an upgrade to the release
after this one, until this has been completed for the current
release. For example, as part of upgrading from Ocata to Pike,
you need to complete Pike's data migrations. If this not done,
you will not be able to upgrade to Queens -- it will not be
possible to execute Queens' database schema updates.
release. You need to complete the current release's data migrations
before upgrading to the next release. If this is not done,
you will not be able to upgrade to the next release -- it will not be
possible to execute the next release's database schema updates.
Rolling upgrades
@@ -97,8 +95,8 @@ Rolling upgrades
To Reduce downtime, the services can be upgraded in a rolling fashion, meaning
to upgrade one or a few services at a time to minimize impact.
Rolling upgrades are available starting with the Pike release. This feature
makes it possible to upgrade between releases, such as Ocata to Pike, with
Rolling upgrades are supported for the Bare Metal service. This feature
makes it possible to upgrade between consecutive releases with
minimal to no downtime of the Bare Metal API.
Requirements
@@ -163,9 +161,10 @@ is to make use of new features immediately.
you are doing a cold upgrade).
This data migration must be completed. If not, you will not be able to
upgrade to future releases. For example, if you had upgraded from Ocata to
Pike but did not do the data migrations, you will not be able to upgrade from
Pike to Queens. (More precisely, you will not be able to apply Queens' schema
upgrade to future releases. For example, if you upgraded between releases
but did not do the data migrations, you will not be able to upgrade to
the next release. (More precisely, you will not be able to apply the next
release's schema
migrations.)
Graceful conductor service shutdown
@@ -254,7 +253,7 @@ During maintenance window
the version you are upgrading from (that is, the old version). Based on
this setting, the new ironic-conductor services will downgrade any
RPC communication and data objects to conform to the old service.
For example, if you are upgrading from Ocata to Pike, set this value to
For example, when upgrading between consecutive releases, set this value to
``ocata``.
* start the service
@@ -277,7 +276,7 @@ During maintenance window
newer API versions that the old services did not support. This prevents
new features (available in new API versions) from being used until after
the upgrade has been completed.
For example, if you are upgrading from Ocata to Pike, set this value to
For example, when upgrading between consecutive releases, set this value to
``ocata``.
* restart the service
* add it back into the load balancer
@@ -331,11 +330,10 @@ release.
.. warning::
Note that you will not be able to start an upgrade to the next release after
this one, until this has been completed for the current release. For example,
as part of upgrading from Ocata to Pike, you need to complete Pike's data
migrations. If this not done, you will not be able to upgrade to Queens --
it will not be possible to execute Queens' database schema updates.
as part of upgrading between releases, you need to complete the current
release's data migrations. If this not done, you will not be able to
upgrade to the next release -- it will not be possible to execute the
next release's database schema updates.
.. toctree::
:hidden:
upgrade-to-hardware-types.rst

266
doc/source/admin/upgrade-to-hardware-types.rst
View File

@@ -1,266 +0,0 @@
Upgrading to Hardware Types
===========================
Starting with the Rocky release, the Bare Metal service does not support
*classic drivers* any more. If you still use *classic drivers*, please
upgrade to *hardware types* immediately. Please see
:doc:`/install/enabling-drivers` for details on
*hardware types* and *hardware interfaces*.
Planning the upgrade
--------------------
It is necessary to figure out which hardware types and hardware interfaces
correspond to which classic drivers used in your deployment. The following
table lists the classic drivers with their corresponding hardware types and
the boot, deploy, inspect, management, and power hardware interfaces:
===================== ==================== ==================== ============== ========== ========== =========
Classic Driver Hardware Type Boot Deploy Inspect Management Power
===================== ==================== ==================== ============== ========== ========== =========
agent_ilo ilo ilo-virtual-media direct ilo ilo ilo
agent_ipmitool ipmi pxe direct inspector ipmitool ipmitool
agent_ipmitool_socat ipmi pxe direct inspector ipmitool ipmitool
agent_irmc irmc irmc-virtual-media direct irmc irmc irmc
iscsi_ilo ilo ilo-virtual-media iscsi ilo ilo ilo
iscsi_irmc irmc irmc-virtual-media iscsi irmc irmc irmc
pxe_drac idrac pxe iscsi idrac idrac idrac
pxe_drac_inspector idrac pxe iscsi inspector idrac idrac
pxe_ilo ilo ilo-pxe iscsi ilo ilo ilo
pxe_ipmitool ipmi pxe iscsi inspector ipmitool ipmitool
pxe_ipmitool_socat ipmi pxe iscsi inspector ipmitool ipmitool
pxe_irmc irmc irmc-pxe iscsi irmc irmc irmc
pxe_snmp snmp pxe iscsi no-inspect fake snmp
===================== ==================== ==================== ============== ========== ========== =========
.. note::
The ``inspector`` *inspect* interface was only used if
explicitly enabled in the configuration. Otherwise, ``no-inspect``
was used.
.. note::
``pxe_ipmitool_socat`` and ``agent_ipmitool_socat`` use
``ipmitool-socat`` *console* interface (the default for the ``ipmi``
hardware type), while ``pxe_ipmitool`` and ``agent_ipmitool`` use
``ipmitool-shellinabox``. See Console_ for details.
For out-of-tree drivers you may need to reach out to their maintainers or
figure out the appropriate interfaces by researching the source code.
Configuration
-------------
You will need to enable hardware types and interfaces that correspond to your
currently enabled classic drivers. For example, if you have the following
configuration in your ``ironic.conf``:
.. code-block:: ini
[DEFAULT]
enabled_drivers = pxe_ipmitool,agent_ipmitool
You will have to add this configuration as well:
.. code-block:: ini
[DEFAULT]
enabled_hardware_types = ipmi
enabled_boot_interfaces = pxe
enabled_deploy_interfaces = iscsi,direct
enabled_management_interfaces = ipmitool
enabled_power_interfaces = ipmitool
.. note::
For every interface type there is an option
``default_<INTERFACE>_interface``, where ``<INTERFACE>`` is the interface
type name. For example, one can make all nodes use the ``direct`` deploy
method by default by setting:
.. code-block:: ini
[DEFAULT]
default_deploy_interface = direct
Migrating nodes
---------------
After the required items are enabled in the configuration, each node's
``driver`` field has to be updated to a new value. You may need to also
set new values for some or all interfaces:
.. code-block:: console
export OS_BAREMETAL_API_VERSION=1.31
for uuid in $(baremetal node list --driver pxe_ipmitool -f value -c UUID); do
baremetal node set <node> --driver ipmi --deploy-interface iscsi
done
for uuid in $(baremetal node list --driver agent_ipmitool -f value -c UUID); do
baremetal node set <node> --driver ipmi --deploy-interface direct
done
See :doc:`/install/enrollment` for more details on setting hardware types and
interfaces.
.. warning::
It is not recommended to change the interfaces for ``active`` nodes. If
absolutely needed, the nodes have to be put in the maintenance mode first:
.. code-block:: console
baremetal node maintenance set $UUID \
--reason "Changing driver and/or hardware interfaces"
# do the update, validate its correctness
baremetal node maintenance unset $UUID
Other interfaces
----------------
Care has to be taken to migrate from classic drivers using non-default
interfaces. This chapter covers a few of the most commonly used.
Ironic Inspector
~~~~~~~~~~~~~~~~
Some classic drivers, notably ``pxe_ipmitool``, ``agent_ipmitool`` and
``pxe_drac_inspector``, use ironic-inspector_ for their *inspect* interface.
The same functionality is available for all hardware types, but the appropriate
``inspect`` interface has to be enabled in the Bare Metal service configuration
file, for example:
.. code-block:: ini
[DEFAULT]
enabled_inspect_interfaces = inspector,no-inspect
See :doc:`/install/enabling-drivers` for more details.
Then you can tell your nodes to use this interface, for example:
.. code-block:: console
export OS_BAREMETAL_API_VERSION=1.31
for uuid in $(baremetal node list --driver ipmi -f value -c UUID); do
baremetal node set <node> --inspect-interface inspector
done
.. note::
A node configured with the IPMI hardware type, will use the inspector
inspection implementation automatically if it is enabled. This is not
the case for the most of the vendor drivers.
.. _ironic-inspector: https://docs.openstack.org/ironic-inspector/
Console
~~~~~~~
Several classic drivers, notably ``pxe_ipmitool_socat`` and
``agent_ipmitool_socat``, use socat-based serial console implementation.
For the ``ipmi`` hardware type it is used by default, if enabled in the
configuration file:
.. code-block:: ini
[DEFAULT]
enabled_console_interfaces = ipmitool-socat,no-console
If you want to use the ``shellinabox`` implementation instead, it has to be
enabled as well:
.. code-block:: ini
[DEFAULT]
enabled_console_interfaces = ipmitool-shellinabox,no-console
Then you need to update some or all nodes to use it explicitly. For example,
to update all nodes use:
.. code-block:: console
export OS_BAREMETAL_API_VERSION=1.31
for uuid in $(baremetal node list --driver ipmi -f value -c UUID); do
baremetal node set <node> --console-interface ipmitool-shellinabox
done
RAID
~~~~
Many classic drivers, including ``pxe_ipmitool`` and ``agent_ipmitool`` use
the IPA-based in-band RAID implementation by default.
For the hardware types it is not used by default. To use it, you need to
enable it in the configuration first:
.. code-block:: ini
[DEFAULT]
enabled_raid_interfaces = agent,no-raid
Then you can update those nodes that support in-band RAID to use the ``agent``
RAID interface. For example, to update all nodes use:
.. code-block:: console
export OS_BAREMETAL_API_VERSION=1.31
for uuid in $(baremetal node list --driver ipmi -f value -c UUID); do
baremetal node set <node> --raid-interface agent
done
.. note::
The ability of a node to use the ``agent`` RAID interface depends on
the ramdisk (more specifically, a
:ironic-python-agent-doc:`hardware manager <contributor/hardware_managers.html>`
used in it), not on the driver.
Network and storage
~~~~~~~~~~~~~~~~~~~
The network and storage interfaces have always been dynamic, and thus do not
require any special treatment during upgrade.
Vendor
~~~~~~
Classic drivers are allowed to use the ``VendorMixin`` functionality
to combine and expose several node or driver vendor passthru methods
from different vendor interface implementations in one driver.
**This is no longer possible with hardware types.**
With hardware types, a vendor interface can only have a single active
implementation from the list of vendor interfaces supported by a given
hardware type.
Ironic no longer has in-tree drivers (both classic and hardware types) that
rely on this ``VendorMixin`` functionality support.
However if you are using an out-of-tree classic driver that depends on it,
you'll need to do the following in order to use vendor
passthru methods from different vendor passthru implementations:
#. While creating a new hardware type to replace your classic driver,
specify all vendor interface implementations your classic driver
was using to build its ``VendorMixin`` as supported vendor interfaces
(property ``supported_vendor_interfaces`` of the Python class
that defines your hardware type).
#. Ensure all required vendor interfaces are enabled in the ironic
configuration file under the :oslo.config:option:`DEFAULT.enabled_vendor_interfaces`
option.
You should also consider setting the :oslo.config:option:`DEFAULT.default_vendor_interface`
option to specify the vendor interface for nodes that do not have one set
explicitly.
#. Before invoking a specific vendor passthru method,
make sure that the node's vendor interface is set to the interface
with the desired vendor passthru method.
For example, if you want to invoke the vendor passthru method
``vendor_method_foo()`` from ``vendor_foo`` vendor interface:
.. code-block:: shell
# set the vendor interface to 'vendor_foo`
baremetal node set <node> --vendor-interface vendor_foo
# invoke the vendor passthru method
baremetal node passthru call <node> vendor_method_foo

11
doc/source/contributor/rolling-upgrades.rst
View File

@@ -4,8 +4,8 @@
Rolling Upgrades
================
The ironic (ironic-api and ironic-conductor) services support rolling upgrades,
starting with a rolling upgrade from the Ocata to the Pike release. This
The ironic (ironic-api and ironic-conductor) services support rolling upgrades.
This
describes the design of rolling upgrades, followed by notes for developing new
features or modifying an IronicObject.
@@ -19,7 +19,10 @@ Ironic follows the `release-cycle-with-intermediary release model
The releases are `semantic-versioned <http://semver.org/>`_, in the form
<major>.<minor>.<patch>.
We refer to a ``named release`` of ironic as the release associated with a
development cycle like Pike.
time based integrated release of OpenStack, for example 2025.1 which was
named Epoxy. Please review
`OpenStack releases <https://releases.openstack.org/>`_ for the high level
release version to name mappings.
In addition, ironic follows the `standard deprecation policy
<https://governance.openstack.org/tc/reference/tags/assert_follows-standard-deprecation.html>`_,
@@ -29,7 +32,7 @@ is both deprecated *and* removed between two named releases.
Rolling upgrades will be supported between:
* named release N to N+1 (starting with N == Ocata)
* named release N to N+1
* any named release to its latest revision, containing backported bug fixes.
Because those bug fixes can contain improvements to the upgrade process, the
operator should patch the system before upgrading between named releases.

9
doc/source/user/deploy.rst
View File

@@ -187,11 +187,10 @@ Capabilities
The two settings must not contradict each other.
.. note::
This capability was introduced in the Wallaby release series,
previously ironic used a separate ``instance_info/deploy_boot_mode``
Previously ironic used a separate ``instance_info/deploy_boot_mode``
field instead.
* Starting with the Ussuri release, you can set :ref:`root device hints
* You can set :ref:`root device hints
<root-device-hints>` per instance:
.. code-block:: shell
@@ -221,7 +220,7 @@ override a node's storage interface, run the following:
``instance_info`` values persist until after a node is cleaned.
.. note::
This feature is available starting with the Wallaby release.
This feature is available.
Attaching virtual interfaces
----------------------------
@@ -266,7 +265,7 @@ Deployment
baremetal node deploy $NODE_UUID
#. Starting with the Wallaby release you can also request custom deploy steps,
#. You can also request custom deploy steps,
see :ref:`standalone-deploy-steps` for details.
.. _deploy-configdrive: