From 582b2e991c15cccfe8fcca4443b12b21bd520e9b Mon Sep 17 00:00:00 2001 From: cid Date: Tue, 6 Aug 2024 10:35:57 +0100 Subject: [PATCH] Link to configuration options Implement cross-referencing to configuration options through out the Ironic documentation. Closes-Bug: #2076111 Change-Id: I28712a3a92eb7e7d9875e49ea3ed8800168262fe --- doc/source/admin/agent-token.rst | 4 +-- .../admin/anaconda-deploy-interface.rst | 6 ++-- doc/source/admin/boot-from-volume.rst | 4 +-- doc/source/admin/cleaning.rst | 2 +- doc/source/admin/conductor-groups.rst | 8 ++--- doc/source/admin/dhcp-less.rst | 2 +- doc/source/admin/drivers/ansible.rst | 10 +++--- doc/source/admin/drivers/idrac.rst | 6 ++-- doc/source/admin/drivers/ilo.rst | 32 +++++++++---------- doc/source/admin/drivers/ipa.rst | 10 +++--- doc/source/admin/drivers/redfish.rst | 8 ++--- .../admin/drivers/redfish/session-cache.rst | 2 +- doc/source/admin/firmware-updates.rst | 2 +- doc/source/admin/metrics.rst | 2 +- doc/source/admin/portgroups.rst | 2 +- doc/source/admin/retirement.rst | 6 ++-- doc/source/admin/secure-rbac.rst | 4 +-- doc/source/admin/security.rst | 10 +++--- doc/source/admin/servicing.rst | 2 +- doc/source/admin/troubleshooting.rst | 14 ++++---- doc/source/admin/upgrade-guide.rst | 6 ++-- .../admin/upgrade-to-hardware-types.rst | 8 ++--- .../install/configure-ipv6-networking.rst | 2 +- doc/source/install/configure-pxe.rst | 27 ++++++++-------- .../install/configure-tenant-networks.rst | 2 +- doc/source/install/refarch/common.rst | 4 +-- 26 files changed, 91 insertions(+), 94 deletions(-) diff --git a/doc/source/admin/agent-token.rst b/doc/source/admin/agent-token.rst index 94c25cdedb..2a28d09bf8 100644 --- a/doc/source/admin/agent-token.rst +++ b/doc/source/admin/agent-token.rst @@ -46,8 +46,8 @@ With the token is available in memory in the agent, the token is embedded with authenticate the heartbeat request, and refuse "heartbeat" requests from the ``ironic-python-agent``. As of the Victoria release, use of Agent Token is required for all agents and the previously available setting to force this -functionality to be mandatory, ``[DEFAULT]require_agent_token`` no longer has -any effect. +functionality to be mandatory, ``[DEFAULT]require_agent_token`` has been removed +and no longer has any effect. .. warning:: If the Bare Metal Service is updated, and the version of diff --git a/doc/source/admin/anaconda-deploy-interface.rst b/doc/source/admin/anaconda-deploy-interface.rst index 4e7be8c8e4..f6d606ce1c 100644 --- a/doc/source/admin/anaconda-deploy-interface.rst +++ b/doc/source/admin/anaconda-deploy-interface.rst @@ -22,7 +22,7 @@ This change takes effect after all the ironic conductors have been restarted. The default kickstart template is specified via the configuration option -``[anaconda]default_ks_template``. It is set to this `ks.cfg.template`_ +:oslo.config:option:`anaconda.default_ks_template`. It is set to this `ks.cfg.template`_ but can be modified to be some other template. .. code-block:: ini @@ -280,14 +280,14 @@ part due to the general defaults being set to much lower values for image based deployments, but the way the anaconda deployment interface works, you may need to make some adjustments. -* ``[conductor]deploy_callback_timeout`` likely needs to be adjusted +* :oslo.config:option:`conductor.deploy_callback_timeout` likely needs to be adjusted for most ``anaconda`` deployment interface users. By default this is a timer which looks for "agents" which have not checked in with Ironic, or agents which may have crashed or failed after they started. If the value is reached, then the current operation is failed. This value should be set to a number of seconds which exceeds your average anaconda deployment time. -* ``[pxe]boot_retry_timeout`` can also be triggered and result in +* :oslo.config:option:`pxe.boot_retry_timeout` can also be triggered and result in an anaconda deployment in progress getting reset as it is intended to reboot nodes which might have failed their initial PXE operation. Depending on sizes of images, and the exact nature of what was deployed, diff --git a/doc/source/admin/boot-from-volume.rst b/doc/source/admin/boot-from-volume.rst index 1f4ff1bef4..becc7e9799 100644 --- a/doc/source/admin/boot-from-volume.rst +++ b/doc/source/admin/boot-from-volume.rst @@ -69,7 +69,7 @@ Currently booting from a volume requires: Conductor Configuration ======================= In ironic.conf, you can specify a list of enabled storage interfaces. Check -``[DEFAULT]enabled_storage_interfaces`` in your ironic.conf to ensure that +:oslo.config:option:`DEFAULT.enabled_storage_interfaces` in your ironic.conf to ensure that your desired interface is enabled. For example, to enable the ``cinder`` and ``noop`` storage interfaces:: @@ -77,7 +77,7 @@ your desired interface is enabled. For example, to enable the ``cinder`` and enabled_storage_interfaces = cinder,noop If you want to specify a default storage interface rather than setting the -storage interface on a per node basis, set ``[DEFAULT]default_storage_interface`` +storage interface on a per node basis, set :oslo.config:option:`DEFAULT.default_storage_interface` in ironic.conf. The ``default_storage_interface`` will be used for any node that doesn't have a storage interface defined. diff --git a/doc/source/admin/cleaning.rst b/doc/source/admin/cleaning.rst index 16030bda78..a3d8e9e83c 100644 --- a/doc/source/admin/cleaning.rst +++ b/doc/source/admin/cleaning.rst @@ -379,7 +379,7 @@ iterations, use the following configuration option:: Overriding step priority ------------------------ -``[conductor]clean_step_priority_override`` is a new configuration option +:oslo.config:option:`conductor.clean_step_priority_override` is a new configuration option which allows specifying priority of each step using multiple configuration values: diff --git a/doc/source/admin/conductor-groups.rst b/doc/source/admin/conductor-groups.rst index 941d024c37..b2444ad876 100644 --- a/doc/source/admin/conductor-groups.rst +++ b/doc/source/admin/conductor-groups.rst @@ -24,12 +24,12 @@ Starting in ironic 11.1, each node has a ``conductor_group`` field which influences how the ironic conductor calculates (and thus allocates) baremetal nodes under ironic's management. This calculation is performed independently by each operating conductor and as such if a conductor has -a ``[conductor]conductor_group`` configuration option defined in its +a :oslo.config:option:`conductor.conductor_group` configuration option defined in its `ironic.conf` configuration file, the conductor will then be limited to only managing nodes with a matching ``conductor_group`` string. .. note:: - Any conductor without a ``[conductor]conductor_group`` setting will + Any conductor without a :oslo.config:option:`conductor.conductor_group` setting will only manage baremetal nodes without a ``conductor_group`` value set upon node creation. If no such conductor is present when conductor groups are configured, node creation will fail unless a ``conductor_group`` is @@ -37,7 +37,7 @@ only managing nodes with a matching ``conductor_group`` string. .. warning:: Nodes without a ``conductor_group`` setting can only be managed when a - conductor exists that does not have a ``[conductor]conductor_group`` + conductor exists that does not have a :oslo.config:option:`conductor.conductor_group` defined. If all conductors have been migrated to use a conductor group, such nodes are effectively "orphaned". @@ -48,7 +48,7 @@ A conductor group value may be any case insensitive string up to 255 characters long which matches the ``^[a-zA-Z0-9_\-\.]*$`` regular expression. -#. Set the ``[conductor]conductor_group`` option in ironic.conf +#. Set the :oslo.config:option:`conductor.conductor_group` option in ironic.conf on one or more, but not all conductors:: [conductor] diff --git a/doc/source/admin/dhcp-less.rst b/doc/source/admin/dhcp-less.rst index a14c2499dd..3853f1bdbb 100644 --- a/doc/source/admin/dhcp-less.rst +++ b/doc/source/admin/dhcp-less.rst @@ -131,7 +131,7 @@ the service catalog or configured in the ``[service_catalog]`` section: In case you need specific URLs for each node, you can use the ``driver_info[external_http_url]`` node property. When used it overrides the -``[deploy]http_url`` and ``[deploy]external_http_url`` settings in the +:oslo.config:option:`deploy.http_url` and :oslo.config:option:`deploy.external_http_url` settings in the configuration file. .. code-block:: bash diff --git a/doc/source/admin/drivers/ansible.rst b/doc/source/admin/drivers/ansible.rst index f127c4aee8..9c762b1b6a 100644 --- a/doc/source/admin/drivers/ansible.rst +++ b/doc/source/admin/drivers/ansible.rst @@ -378,26 +378,26 @@ Those values are then accessible in your plays as well passed inside this variable. Some extra notes and fields: - ``mem_req`` is calculated from image size (if available) and config - option ``[ansible]extra_memory``. + option :oslo.config:option:`ansible.extra_memory`. - if ``checksum`` is not in the form ``:``, hashing algorithm is assumed to be ``md5`` (default in Glance). - ``validate_certs`` - boolean (``yes/no``) flag that turns validating image store SSL certificate on or off (default is 'yes'). - Governed by ``[ansible]image_store_insecure`` option + Governed by :oslo.config:option:`ansible.image_store_insecure` option in ironic configuration file. - ``cafile`` - custom CA bundle to use for validating image store SSL certificate. - Takes value of ``[ansible]image_store_cafile`` if that is defined. + Takes value of :oslo.config:option:`ansible.image_store_cafile` if that is defined. Currently is not used by default playbooks, as Ansible has no way to specify the custom CA bundle to use for single HTTPS actions, however you can use this value in your custom playbooks to for example upload and register this CA in the ramdisk at deploy time. - ``client_cert`` - cert file for client-side SSL authentication. - Takes value of ``[ansible]image_store_certfile`` option if defined. + Takes value of :oslo.config:option:`ansible.image_store_certfile` option if defined. Currently is not used by default playbooks, however you can use this value in your custom playbooks. - ``client_key`` - private key file for client-side SSL authentication. - Takes value of ``[ansible]image_store_keyfile`` option if defined. + Takes value of :oslo.config:option:`ansible.image_store_keyfile` option if defined. Currently is not used by default playbooks, however you can use this value in your custom playbooks. diff --git a/doc/source/admin/drivers/idrac.rst b/doc/source/admin/drivers/idrac.rst index a3e588bd57..03277d29fd 100644 --- a/doc/source/admin/drivers/idrac.rst +++ b/doc/source/admin/drivers/idrac.rst @@ -366,7 +366,7 @@ Storage setup To start using these steps, configure the storage location. The settings can be found in the ``[molds]`` section. Configure the storage type from the -``[molds]storage`` setting. Currently, ``swift``, which is enabled by default, +:oslo.config:option:`molds.storage` setting. Currently, ``swift``, which is enabled by default, and ``http`` are supported. In the setup input parameters, the complete HTTP URL is used. This requires @@ -398,7 +398,7 @@ To use HTTP server with configuration molds, #. Enable HTTP PUT support. #. Create the directory to be used for the configuration mold storage. #. Configure read/write access for HTTP Basic access authentication and provide - user credentials in ``[molds]user`` and ``[molds]password`` fields. + user credentials in :oslo.config:option:`molds.user` and :oslo.config:option:`molds.password` fields. The HTTP web server does not support multitenancy and is intended to be used in a stand-alone Ironic, or single-tenant OpenStack environment. @@ -588,7 +588,7 @@ Nodes go into maintenance mode After some period of time, nodes managed by the ``idrac`` hardware type may go into maintenance mode in Ironic. This issue can be worked around by changing the Ironic power state poll interval to 70 seconds. See -``[conductor]sync_power_state_interval`` in ``/etc/ironic/ironic.conf``. +:oslo.config:option:`conductor.sync_power_state_interval` in ``/etc/ironic/ironic.conf``. PXE reset with "factory_reset" BIOS clean step ---------------------------------------------- diff --git a/doc/source/admin/drivers/ilo.rst b/doc/source/admin/drivers/ilo.rst index deed7c15bd..9d9af60625 100644 --- a/doc/source/admin/drivers/ilo.rst +++ b/doc/source/admin/drivers/ilo.rst @@ -94,7 +94,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * bios Supports ``ilo`` and ``no-bios``. The default is ``ilo``. - They can be enabled by using the ``[DEFAULT]enabled_bios_interfaces`` + They can be enabled by using the :oslo.config:option:`DEFAULT.enabled_bios_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -110,7 +110,7 @@ The ``ilo`` hardware type supports following hardware interfaces: media to boot up the bare metal node. The ``ilo-pxe`` and ``ilo-ipxe`` interfaces use PXE and iPXE respectively for deployment(just like :ref:`pxe-boot`). These interfaces do not require iLO Advanced license. - They can be enabled by using the ``[DEFAULT]enabled_boot_interfaces`` + They can be enabled by using the :oslo.config:option:`DEFAULT.enabled_boot_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -121,7 +121,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * console Supports ``ilo`` and ``no-console``. The default is ``ilo``. - They can be enabled by using the ``[DEFAULT]enabled_console_interfaces`` + They can be enabled by using the :oslo.config:option:`DEFAULT.enabled_console_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -139,7 +139,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * inspect Supports ``ilo`` and ``inspector``. The default is ``ilo``. They - can be enabled by using the ``[DEFAULT]enabled_inspect_interfaces`` option + can be enabled by using the :oslo.config:option:`DEFAULT.enabled_inspect_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -154,7 +154,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * management Supports only ``ilo``. It can be enabled by using the - ``[DEFAULT]enabled_management_interfaces`` option in ``ironic.conf`` as + :oslo.config:option:`DEFAULT.enabled_management_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -165,7 +165,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * power Supports only ``ilo``. It can be enabled by using the - ``[DEFAULT]enabled_power_interfaces`` option in ``ironic.conf`` as given + :oslo.config:option:`DEFAULT.enabled_power_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -176,7 +176,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * raid Supports ``agent`` and ``no-raid``. The default is ``no-raid``. - They can be enabled by using the ``[DEFAULT]enabled_raid_interfaces`` + They can be enabled by using the :oslo.config:option:`DEFAULT.enabled_raid_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -187,7 +187,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * storage Supports ``cinder`` and ``noop``. The default is ``noop``. - They can be enabled by using the ``[DEFAULT]enabled_storage_interfaces`` + They can be enabled by using the :oslo.config:option:`DEFAULT.enabled_storage_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -204,7 +204,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * rescue Supports ``agent`` and ``no-rescue``. The default is ``no-rescue``. - They can be enabled by using the ``[DEFAULT]enabled_rescue_interfaces`` + They can be enabled by using the :oslo.config:option:`DEFAULT.enabled_rescue_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -216,7 +216,7 @@ The ``ilo`` hardware type supports following hardware interfaces: * vendor Supports ``ilo``, ``ilo-redfish`` and ``no-vendor``. The default is ``ilo``. They can be enabled by using the - ``[DEFAULT]enabled_vendor_interfaces`` option in ``ironic.conf`` as given + :oslo.config:option:`DEFAULT.enabled_vendor_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -232,7 +232,7 @@ except for ``boot`` and ``raid`` interfaces. The details of ``boot`` and * raid Supports ``ilo5`` and ``no-raid``. The default is ``ilo5``. - They can be enabled by using the ``[DEFAULT]enabled_raid_interfaces`` + They can be enabled by using the :oslo.config:option:`DEFAULT.enabled_raid_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -244,7 +244,7 @@ except for ``boot`` and ``raid`` interfaces. The details of ``boot`` and * boot Supports ``ilo-uefi-https`` apart from the other boot interfaces supported by ``ilo`` hardware type. - This can be enabled by using the ``[DEFAULT]enabled_boot_interfaces`` + This can be enabled by using the :oslo.config:option:`DEFAULT.enabled_boot_interfaces` option in ``ironic.conf`` as given below: .. code-block:: ini @@ -1532,9 +1532,9 @@ An example of a manual clean step with ``create_csr`` as the only clean step cou } }] -The ``[ilo]cert_path`` option in ``ironic.conf`` is used as the directory path for +The :oslo.config:option:`ilo.cert_path` option in ``ironic.conf`` is used as the directory path for creating the CSR, which defaults to ``/var/lib/ironic/ilo``. The CSR is created in the directory location -given in ``[ilo]cert_path`` in ``node_uuid`` directory as .csr. +given in :oslo.config:option:`ilo.cert_path` in ``node_uuid`` directory as .csr. Add HTTPS Certificate as manual clean step @@ -1556,7 +1556,7 @@ An example of a manual clean step with ``add_https_certificate`` as the only cle Argument ``cert_file`` is mandatory. The ``cert_file`` takes the path or url of the certificate file. The url schemes supported are: ``file``, ``http`` and ``https``. The CSR generated in step ``create_csr`` needs to be signed by a valid CA and the resultant HTTPS certificate should -be provided in ``cert_file``. It copies the ``cert_file`` to ``[ilo]cert_path`` under ``node.uuid`` as .crt +be provided in ``cert_file``. It copies the ``cert_file`` to :oslo.config:option:`ilo.cert_path` under ``node.uuid`` as .crt before adding it to iLO. RAID Support @@ -1881,7 +1881,7 @@ soft power operations on a server: [--power-timeout ] .. note:: - The configuration ``[conductor]soft_power_off_timeout`` is used as a + The configuration :oslo.config:option:`conductor.soft_power_off_timeout` is used as a default timeout value when no timeout is provided while invoking hard or soft power operations. diff --git a/doc/source/admin/drivers/ipa.rst b/doc/source/admin/drivers/ipa.rst index ecafa081f6..e9eba878eb 100644 --- a/doc/source/admin/drivers/ipa.rst +++ b/doc/source/admin/drivers/ipa.rst @@ -58,14 +58,14 @@ Steps to enable proxies sensitive information. Refer to your proxy server's documentation to complete this step. -#. Set ``[glance]swift_temp_url_cache_enabled`` in the ironic conductor config +#. Set :oslo.config:option:`glance.swift_temp_url_cache_enabled` in the ironic conductor config file to ``True``. The conductor will reuse the cached swift temporary URLs instead of generating new ones each time an image is requested, so that the proxy server does not create new cache entries for the same image, based on the query part of the URL (as it contains some query parameters that change each time it is regenerated). -#. Set ``[glance]swift_temp_url_expected_download_start_delay`` option in the +#. Set :oslo.config:option:`glance.swift_temp_url_expected_download_start_delay` option in the ironic conductor config file to the value appropriate for your hardware. This is the delay (in seconds) from the time of the deploy request (when the swift temporary URL is generated) to when the URL is used for the image @@ -74,15 +74,15 @@ Steps to enable proxies temporary URL duration is large enough to let the image download begin. Also if temporary URL caching is enabled, this will determine if a cached entry will still be valid when the download starts. It is used only if - ``[glance]swift_temp_url_cache_enabled`` is ``True``. + :oslo.config:option:`glance.swift_temp_url_cache_enabled` is ``True``. -#. Increase ``[glance]swift_temp_url_duration`` option in the ironic conductor +#. Increase :oslo.config:option:`glance.swift_temp_url_duration` option in the ironic conductor config file, as only non-expired links to images will be returned from the swift temporary URLs cache. This means that if ``swift_temp_url_duration=1200`` then after 20 minutes a new image will be cached by the proxy server as the query in its URL will change. The value of this option must be greater than or equal to - ``[glance]swift_temp_url_expected_download_start_delay``. + :oslo.config:option:`glance.swift_temp_url_expected_download_start_delay`. #. Add one or more of ``image_http_proxy``, ``image_https_proxy``, ``image_no_proxy`` to driver_info properties in each node that will use the diff --git a/doc/source/admin/drivers/redfish.rst b/doc/source/admin/drivers/redfish.rst index 6f5b7ec75b..8cf92df1bf 100644 --- a/doc/source/admin/drivers/redfish.rst +++ b/doc/source/admin/drivers/redfish.rst @@ -355,16 +355,16 @@ Limitations & Issues ~~~~~~~~~~~~~~~~~~~~ Ironic contains two different ways of providing an HTTP(S) URL -to a remote BMC. The first is Swift, enabled when ``[redfish]use_swift`` +to a remote BMC. The first is Swift, enabled when :oslo.config:option:`redfish.use_swift` is set to ``true``. Ironic uploads files to Swift, which are then shared as Temporary Swift URLs. While highly scalable, this method does suffer from issues where some vendors BMCs reject URLs with **&** or **?** characters. There is no available workaround to leverage Swift in this state. -When the ``[redfish]use_swift`` setting is set to ``false``, Ironic will house -the files locally in the ``[deploy]http_root`` folder structure, and then +When the :oslo.config:option:`redfish.use_swift` setting is set to ``false``, Ironic will house +the files locally in the :oslo.config:option:`deploy.http_root` folder structure, and then generate a URL pointing the BMC to connect to the HTTP service configured -via ``[deploy]http_url``. +via :oslo.config:option:`deploy.http_url`. Out-Of-Band inspection ====================== diff --git a/doc/source/admin/drivers/redfish/session-cache.rst b/doc/source/admin/drivers/redfish/session-cache.rst index 9f83c8db3c..f25b94a06d 100644 --- a/doc/source/admin/drivers/redfish/session-cache.rst +++ b/doc/source/admin/drivers/redfish/session-cache.rst @@ -17,7 +17,7 @@ The session cache default size is ``1000`` sessions per conductor. If you are operating a deployment with a larger number of Redfish BMCs, it is advised that you do appropriately tune that number. This can be tuned via the API service configuration file, -``[redfish]connection_cache_size``. +:oslo.config:option:`redfish.connection_cache_size`. Session Cache Expiration ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/admin/firmware-updates.rst b/doc/source/admin/firmware-updates.rst index b0752edeaa..2c849c3014 100644 --- a/doc/source/admin/firmware-updates.rst +++ b/doc/source/admin/firmware-updates.rst @@ -101,7 +101,7 @@ Next, construct the JSON for the firmware update cleaning step to be executed. When launching the firmware update, the JSON may be specified on the command line directly or in a file. The following example shows one cleaning step that installs four firmware updates. All except 3rd entry that has explicit -``source`` added, uses setting from ``[redfish]firmware_source`` to determine +``source`` added, uses setting from :oslo.config:option:`redfish.firmware_source` to determine if and where to stage the files: .. code-block:: json diff --git a/doc/source/admin/metrics.rst b/doc/source/admin/metrics.rst index 733c6569b3..17d6b44927 100644 --- a/doc/source/admin/metrics.rst +++ b/doc/source/admin/metrics.rst @@ -76,7 +76,7 @@ Regardless if you're using Ceilometer, `ironic-prometheus-exporter `_, or some scripting you wrote to consume the message bus notifications, metrics data can be sent to the message bus notifier from the timer methods -*and* additional gauge counters by utilizing the ``[metrics]backend`` +*and* additional gauge counters by utilizing the :oslo.config:option:`metrics.backend` configuration option and setting it to ``collector``. When this is the case, Information is cached locally and periodically sent along with the general sensor data update to the messaging notifier, which can consumed off of the message bus, diff --git a/doc/source/admin/portgroups.rst b/doc/source/admin/portgroups.rst index e43066f62b..fb40cfc6ba 100644 --- a/doc/source/admin/portgroups.rst +++ b/doc/source/admin/portgroups.rst @@ -114,7 +114,7 @@ CLI commands below specify it for completeness. The mode and properties values are described in the `kernel documentation on bonding`_. The default port group mode is ``active-backup``, and this default can be changed by setting the - ``[DEFAULT]default_portgroup_mode`` configuration option in the ironic API + :oslo.config:option:`DEFAULT.default_portgroup_mode` configuration option in the ironic API service configuration file. #. Associate ports with the created port group. diff --git a/doc/source/admin/retirement.rst b/doc/source/admin/retirement.rst index e5288869ca..d2ab3b05e6 100644 --- a/doc/source/admin/retirement.rst +++ b/doc/source/admin/retirement.rst @@ -27,7 +27,7 @@ Requirements ============ The use of the retirement feature requires that automated cleaning -be enabled. The default ``[conductor]automated_clean`` setting must +be enabled. The default :oslo.config:option:`conductor.automated_clean` setting must not be disabled as the retirement feature is only engaged upon the completion of cleaning as it sets forth the expectation of removing sensitive data from a node. @@ -36,8 +36,8 @@ If you're uncomfortable with full cleaning, but want to make use of the the retirement feature, a compromise may be to explore use of metadata erasure, however this will leave additional data on disk which you may wish to erase completely. Please consult the configuration for the -``[deploy]erase_devices_metadata_priority`` and -``[deploy]erase_devices_priority`` settings, and do note that +:oslo.config:option:`deploy.erase_devices_metadata_priority` and +:oslo.config:option:`deploy.erase_devices_priority` settings, and do note that clean steps can be manually invoked through manual cleaning should you wish to trigger the ``erase_devices`` clean step to completely wipe all data from storage devices. Alternatively, automated cleaning can diff --git a/doc/source/admin/secure-rbac.rst b/doc/source/admin/secure-rbac.rst index 2c0041927e..3e431e4eb5 100644 --- a/doc/source/admin/secure-rbac.rst +++ b/doc/source/admin/secure-rbac.rst @@ -279,7 +279,7 @@ This functionality is enabled by default, and automatically imparts ``owner`` privileges to the created Bare Metal node. This functionality can be disabled by setting -``[api]project_admin_can_manage_own_nodes`` to ``False``. +:oslo.config:option:`api.project_admin_can_manage_own_nodes` to ``False``. Can I use a service role? ------------------------- @@ -297,7 +297,7 @@ usage of the service via a service account. A project scoped user with the ``service`` role is able to create baremetal nodes, but is not able to delete them. To disable the ability to create nodes, set the -``[api]project_admin_can_manage_own_nodes`` setting to ``False``. +:oslo.config:option:`api.project_admin_can_manage_own_nodes` setting to ``False``. The nodes which can be accessed/managed in the project scope also align with the ``owner`` and ``lessee`` access model, and thus if nodes are not matching the user's ``project_id``, then Ironic's API will appear not to diff --git a/doc/source/admin/security.rst b/doc/source/admin/security.rst index 6f75a3c659..6fb160e57c 100644 --- a/doc/source/admin/security.rst +++ b/doc/source/admin/security.rst @@ -185,7 +185,7 @@ For extra context, unmanaged introspection is when you ask ironic-inspector to inspect a machine *instead* of asking ironic. In other words, using ``openstack baremetal introspection start `` versus ``baremetal node inspect `` commands. This does require the -``[inspector]require_managed_boot`` setting be set to ``true``. +:oslo.config:option:`inspector.require_managed_boot` setting be set to ``true``. Driver support for Deployment with Secure Boot ---------------------------------------------- @@ -242,7 +242,7 @@ is required in ironic.conf.:: loader_file_paths = bootx64.efi:/usr/lib/shimx64.efi.signed,grubx64.efi:/usr/lib/grub/x86_64-efi-signed/grubnetx64.efi.signed .. NOTE:: - You may want to leverage the ``[pxe]loader_file_paths`` feature, which + You may want to leverage the :oslo.config:option:`pxe.loader_file_paths` feature, which automatically copies boot loaders into the ``tftp_root`` folder, but this functionality is not required if you manually copy the named files into the Preboot eXecution Environment folder(s), by default the [pxe]tftp_root, @@ -385,8 +385,8 @@ operators to restrict concurrent, long running, destructive actions. The overall use case this was implemented for was to help provide backstop for runaway processes and actions which one may apply to an environment, such as batch deletes of nodes. The appropriate -settings for these settings are the ``[conductor]max_concurrent_deploy`` -with a default value of 250, and ``[conductor]max_concurrent_clean`` +settings for these settings are the :oslo.config:option:`conductor.max_concurrent_deploy` +with a default value of 250, and :oslo.config:option:`conductor.max_concurrent_clean` with a default value of 50. These settings are reasonable defaults for medium to large deployments, but depending on load and usage patterns and can be safely tuned to be in line with an operator's @@ -400,7 +400,7 @@ can consume large amounts of memory, for example, disk image format conversions as part of a deployment operations. The Ironic conductor service has a minimum memory available check which is executed before launching these operations. It defaults to ``1024`` Megabytes, and can -be tuned using the ``[DEFAULT]minimum_required_memory`` setting. +be tuned using the :oslo.config:option:`DEFAULT.minimum_required_memory` setting. Operators with a higher level of concurrency may wish to increase the default value. diff --git a/doc/source/admin/servicing.rst b/doc/source/admin/servicing.rst index 69c2c17070..93bf0eceae 100644 --- a/doc/source/admin/servicing.rst +++ b/doc/source/admin/servicing.rst @@ -225,4 +225,4 @@ Servicing Network If you are using the Neutron DHCP provider (the default) you will also need to ensure you have configured a servicing network. This network will be used to boot the ramdisk for in-band service operations. This setting is configured -utilizing the ``[neutron]servicing_network`` configuration parameter. +utilizing the :oslo.config:option:`neutron.servicing_network` configuration parameter. diff --git a/doc/source/admin/troubleshooting.rst b/doc/source/admin/troubleshooting.rst index 9bccd7efb8..e3e47add6a 100644 --- a/doc/source/admin/troubleshooting.rst +++ b/doc/source/admin/troubleshooting.rst @@ -521,9 +521,9 @@ Again, these sorts of cases will depend upon the exact configuration of the deployment, but hopefully these are areas where these actions can occur. * Conversion to raw image files upon download to the conductor, from the - ``[DEFAULT]force_raw_images`` option. Users using Glance may also experience + :oslo.config:option:`DEFAULT.force_raw_images` option. Users using Glance may also experience issues here as the conductor will cache the image to be written which takes - place when the ``[agent]image_download_source`` is set to ``http`` instead of + place when the :oslo.config:option:`agent.image_download_source` is set to ``http`` instead of ``swift``. .. note:: @@ -867,11 +867,11 @@ This can be addressed a few different ways: * Add swap space. * Reduce concurrency, possibly via another conductor or changing the nova-compute.conf ``max_concurrent_builds`` parameter. -* Or finally, adjust the ``[DEFAULT]minimum_required_memory`` parameter +* Or finally, adjust the :oslo.config:option:`DEFAULT.minimum_required_memory` parameter in your ironic.conf file. The default should be considered a "default of last resort" and you may need to reserve additional memory. You may - also wish to adjust the ``[DEFAULT]minimum_memory_wait_retries`` and - ``[DEFAULT]minimum_memory_wait_time`` parameters. + also wish to adjust the :oslo.config:option:`DEFAULT.minimum_memory_wait_retries` and + :oslo.config:option:`DEFAULT.minimum_memory_wait_time` parameters. Why does API return "Node is locked by host"? ============================================= @@ -984,7 +984,7 @@ for cleaning operations is *50* and should be suitable for the majority of baremetal operators. These settings can be modified by using the -``[conductor]max_concurrent_deploy`` and ``[conductor]max_concurrent_clean`` +:oslo.config:option:`conductor.max_concurrent_deploy` and :oslo.config:option:`conductor.max_concurrent_clean` settings from the ironic.conf file supporting the ``ironic-conductor`` service. Neither setting can be explicitly disabled, however there is also no upper limit to the setting. @@ -1258,4 +1258,4 @@ longer accessible and no new configuration drive has been supplied to Ironic. To resolve this case, you can either supply new configuration drive contents with your request, or disable configuration from being stored in Swift for new baremetal node deployments by changing setting -``[conductor]configdrive_use_object_store`` to ``false``. +:oslo.config:option:`deploy.configdrive_use_object_store` to ``false``. diff --git a/doc/source/admin/upgrade-guide.rst b/doc/source/admin/upgrade-guide.rst index 6ed5e67631..8e94976f24 100644 --- a/doc/source/admin/upgrade-guide.rst +++ b/doc/source/admin/upgrade-guide.rst @@ -185,7 +185,7 @@ older code, and start up a service using newer code with minimal impact. Nodes that are being acted upon by an ironic-conductor process, which are not in a stable state, will be put into a failed state when -``[DEFAULT]graceful_shutdown_timeout`` is reached. Node failures that occur +:oslo.config:option:`DEFAULT.graceful_shutdown_timeout` is reached. Node failures that occur during an upgrade are likely due to timeouts, resulting from delays involving messages being processed and acted upon by a conductor during long running, multi-step processes such as deployment or cleaning. @@ -197,9 +197,9 @@ A drain shutdown is similar to graceful shutdown, differing in the following way * Triggered by sending signal ``SIGUSR2`` to the process instead of ``SIGTERM`` * The timeout for process termination is determined by - ``[DEFAULT]drain_shutdown_timeout`` instead of ``[DEFAULT]graceful_shutdown_timeout`` + :oslo.config:option:`DEFAULT.drain_shutdown_timeout` instead of :oslo.config:option:`DEFAULT.graceful_shutdown_timeout` -``[DEFAULT]drain_shutdown_timeout`` is set long enough so that any node in a not +:oslo.config:option:`DEFAULT.drain_shutdown_timeout` is set long enough so that any node in a not stable state will have time to reach a stable state (complete or failed) before the ironic-conductor process terminates. diff --git a/doc/source/admin/upgrade-to-hardware-types.rst b/doc/source/admin/upgrade-to-hardware-types.rst index ee114aea42..1dce310c13 100644 --- a/doc/source/admin/upgrade-to-hardware-types.rst +++ b/doc/source/admin/upgrade-to-hardware-types.rst @@ -137,10 +137,6 @@ file, for example: See :doc:`/install/enabling-drivers` for more details. -.. note:: - The configuration option ``[inspector]enabled`` does not affect hardware - types. - Then you can tell your nodes to use this interface, for example: .. code-block:: console @@ -250,9 +246,9 @@ passthru methods from different vendor passthru implementations: (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 ``[DEFAULT]enabled_vendor_interfaces`` + configuration file under the :oslo.config:option:`DEFAULT.enabled_vendor_interfaces` option. - You should also consider setting the ``[DEFAULT]default_vendor_interface`` + 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, diff --git a/doc/source/install/configure-ipv6-networking.rst b/doc/source/install/configure-ipv6-networking.rst index ddff898a46..25831e1f53 100644 --- a/doc/source/install/configure-ipv6-networking.rst +++ b/doc/source/install/configure-ipv6-networking.rst @@ -14,7 +14,7 @@ The PXE drivers operate in such a way that they are able to utilize both IPv4 and IPv6 addresses based upon the deployment's operating state and configuration. Internally, the drivers attempt to prepare configuration options for both formats, which allows ports which are IPv6 only to automatically receive boot parameters. As a result of this, it is critical that the -``[DEFAULT]my_ipv6`` configuration parameter is set to the conductor's +:oslo.config:option:`DEFAULT.my_ipv6` configuration parameter is set to the conductor's IPv6 address. This option is unique per conductor, and due to the nature of automatic address assignment, it cannot be "guessed" by the software. diff --git a/doc/source/install/configure-pxe.rst b/doc/source/install/configure-pxe.rst index 766f11f86a..fa857b092a 100644 --- a/doc/source/install/configure-pxe.rst +++ b/doc/source/install/configure-pxe.rst @@ -301,7 +301,7 @@ on the Bare Metal service node(s) where ``ironic-conductor`` is running. .. note:: Most UEFI systems have integrated networking which means the - ``[pxe]uefi_ipxe_bootfile_name`` setting should be set to + :oslo.config:option:`pxe.uefi_ipxe_bootfile_name` setting should be set to ``snponly.efi`` or ``ipxe-snponly-x86_64.efi`` if it's available for your distribution. @@ -313,12 +313,13 @@ on the Bare Metal service node(s) where ``ironic-conductor`` is running. #. Ensure iPXE is the default PXE, if applicable. - In earlier versions of ironic, a ``[pxe]ipxe_enabled`` setting allowing - operators to declare the behavior of the conductor to exclusively operate - as if only iPXE was to be used. As time moved on, iPXE functionality was - moved to it's own ``ipxe`` boot interface. + In earlier versions of ironic, a now deprecated and removed + ``[pxe]ipxe_enabled`` setting allowed operators to declare the behavior of + the conductor to exclusively operate as if only iPXE was to be used. + As time moved on, iPXE functionality was moved to it's own ``ipxe`` + boot interface. - If you want to emulate that same hehavior, set the following in the + If you want to emulate that same behavior, set the following in the configuration file (/etc/ironic/ironic.conf): .. code-block:: ini @@ -328,7 +329,7 @@ on the Bare Metal service node(s) where ``ironic-conductor`` is running. enabled_boot_interfaces=ipxe,pxe .. note:: - The ``[DEFAULT]enabled_boot_interfaces`` setting may be exclusively set + The :oslo.config:option:`DEFAULT.enabled_boot_interfaces` setting may be exclusively set to ``ipxe``, however ironic has multiple interfaces available depending on the hardware types available for use. @@ -387,7 +388,7 @@ PXE multi-architecture setup It is possible to deploy servers of different architecture by one conductor. To use this feature, architecture-specific boot and template files must be configured using the configuration options -``[pxe]pxe_bootfile_name_by_arch`` and ``[pxe]pxe_config_template_by_arch`` +:oslo.config:option:`pxe.pxe_bootfile_name_by_arch` and :oslo.config:option:`pxe.pxe_config_template_by_arch` respectively, in the Bare Metal service's configuration file (/etc/ironic/ironic.conf). @@ -437,9 +438,9 @@ nodes will be deployed by 'grubaa64.efi', and ppc64 nodes by 'bootppc64':: instead. .. note:: - A ``[pxe]ipxe_bootfile_name_by_arch`` setting is available for multi-arch + A :oslo.config:option:`pxe.ipxe_bootfile_name_by_arch` setting is available for multi-arch iPXE based deployment, and defaults to the same behavior as the comperable - ``[pxe]pxe_bootfile_name_by_arch`` setting for standard PXE. + :oslo.config:option:`pxe.pxe_bootfile_name_by_arch` setting for standard PXE. .. note:: When booting PowerPC based machines, the firmware loader directly boots @@ -493,8 +494,8 @@ a configuration similar to this example. If you choose to use relative paths as part of your destination, those paths will be created using configuration parameter -``[pxe]dir_permission`` where as actual files copied are set with -the configuration parameter ``[pxe]file_permission``. Absolute destination +:oslo.config:option:`pxe.dir_permission` where as actual files copied are set with +the configuration parameter :oslo.config:option:`pxe.file_permission`. Absolute destination paths are not supported and will result in ironic failing to start up as it is a misconfiguration of the deployment. @@ -654,7 +655,7 @@ and overall mechanism style. capabilities of iPXE. To enable the boot interfaces, you will need to add them to your -``[DEFAULT]enabled_boot_interfaces`` configuration entry. +:oslo.config:option:`DEFAULT.enabled_boot_interfaces` configuration entry. .. code-block:: ini diff --git a/doc/source/install/configure-tenant-networks.rst b/doc/source/install/configure-tenant-networks.rst index 7553d57ff8..e41499bb75 100644 --- a/doc/source/install/configure-tenant-networks.rst +++ b/doc/source/install/configure-tenant-networks.rst @@ -35,7 +35,7 @@ provisioning will happen in a multi-tenant environment (which means using the interface explicitly specified in the creation request. If this configuration option is not set, the default network interface is - determined by looking at the ``[dhcp]dhcp_provider`` configuration option + determined by looking at the :oslo.config:option:`dhcp.dhcp_provider` configuration option value. If it is ``neutron``, then ``flat`` network interface becomes the default, otherwise ``noop`` is the default. diff --git a/doc/source/install/refarch/common.rst b/doc/source/install/refarch/common.rst index 0fd5660411..a2f14ae2d2 100644 --- a/doc/source/install/refarch/common.rst +++ b/doc/source/install/refarch/common.rst @@ -265,12 +265,12 @@ the space requirements are different: * The deployment kernel and ramdisk are always cached during the deployment. -* When ``[agent]image_download_source`` is set to ``http`` and Glance is used, +* When :oslo.config:option:`agent.image_download_source` is set to ``http`` and Glance is used, the conductor will download instances images locally to serve them from its HTTP server. Use ``swift`` to publish images using temporary URLs and convert them on the node's side. - When ``[agent]image_download_source`` is set to ``local``, it will happen + When :oslo.config:option:`agent.image_download_source` is set to ``local``, it will happen even for HTTP(s) URLs. For standalone case use ``http`` to avoid unnecessary caching of images.