openstack/ironic
Code Issues Proposed changes

doc/source/admin fixes part-2

Browse Source 
This a continuation to the efforts to ensure that the documentation is free from typos and grammatical mistakes so that the reader is not confused. Includes fixes for some of the documentation in doc/source/admin/*

Change-Id: Ibbce369ff5fcccaf0f3aea90f2780a7a700698a1
This commit is contained in:
Muhammad Ahmad 2024-12-07 17:48:22 +05:00
parent afd59e3da9
commit 5c0869bfb6
4 changed files with 43 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/source/admin/building-windows-images.rst
View File

@ -4,7 +4,7 @@ Building images for Windows
---------------------------
We can use ``New-WindowsOnlineImage`` in `windows-openstack-imaging-tools`_
tool as an option to create Windows images (whole disk images) corresponding
boot modes which will support for Windows NIC Teaming. And allow the
boot modes which will support Windows NIC Teaming. And allow the
utilization of link aggregation when the instance is spawned on hardware
servers (Bare metals).
@ -16,26 +16,25 @@ Requirements:
``PowerShell`` version >=4 supported,
``Windows Assessment and Deployment Kit``,
in short ``Windows ADK``.
* The windows Server compatible drivers.
* The Windows Server compatible drivers.
* Working git environment.
Preparation:
~~~~~~~~~~~~
* Download a Windows Server 2012R2/ 2016 installation ISO.
* Install Windows Server 2012R2/ 2016 OS on workstation PC along with
* Install Windows Server 2012R2/ 2016 OS on the workstation PC along with
following feature:
- Enable Hyper-V virtualization.
- Install PowerShell 4.0.
- Install Git environment & import git proxy (if have).
- Create new ``Path`` in Microsoft Windows Server Operating System which
- Install Git environment & import git proxy (if you have).
- Create a new ``Path`` in the Microsoft Windows Server Operating System which
support for submodule update via ``git submodule update –init`` command::
- Variable name: Path
- Variable value: C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Program Files\Git\bin
- Rename virtual switch name in Windows Server 2012R2/ 2016 in
- Rename the virtual switch name in Windows Server 2012R2/ 2016 in
``Virtual Switch Manager`` into ``external``.
Implementation:
@ -85,7 +84,7 @@ Implementation:
.. note::
We can change ``SizeBytes``, ``CpuCores`` and ``Memory`` depending on requirements.
We can change ``SizeBytes``, ``CpuCores``, and ``Memory`` depending on requirements.
.. _`example_windows_images`: https://github.com/cloudbase/windows-openstack-imaging-tools/blob/master/Examples
.. _`windows-openstack-imaging-tools`: https://github.com/cloudbase/windows-openstack-imaging-tools

36
doc/source/admin/cleaning.rst
View File

@ -84,8 +84,8 @@ Clean steps specific to storage are ``erase_devices``,
``erase_devices_metadata`` and (added in Yoga) ``erase_devices_express``.
``erase_devices`` aims to ensure that the data is removed in the most secure
way available. On devices that support hardware assisted secure erasure
(many NVMe and some ATA drives) this is the preferred option. If
way available. On devices that support hardware-assisted secure erasure
(many NVMe and some ATA drives), this is the preferred option. If
hardware-assisted secure erasure is not available and if
:oslo.config:option:`deploy.continue_if_disk_secure_erase_fails` is set to
``True``, cleaning will fall back to using ``shred`` to overwrite the
@ -95,24 +95,24 @@ data security.
.. note::
``erase_devices`` may take a very long time (hours or even days) to
complete, unless fast, hardware assisted data erasure is supported by
complete, unless fast, hardware-assisted data erasure is supported by
all the devices in a system.
``erase_devices_metadata`` clean step doesn't provide as strong assurance
of irreversible destruction of data as ``erase_devices``. However, it has the
advantage of a reasonably quick runtime (seconds to minutes). It operates by
destroying metadata of the storage device without erasing every bit of the
data itself. Attempts of restoring data after running
destroying the metadata of the storage device without erasing every bit of the
data itself. Attempts to restore data after running
``erase_devices_metadata`` may be successful but would certainly require
relevant expertise and specialized tools.
Lastly, ``erase_devices_express`` combines some of the perks of both
``erase_devices`` and ``erase_devices_metadata``. It attempts to utilize
hardware assisted data erasure features if available (currently only NVMe
devices are supported). In case hardware-asssisted data erasure is not
hardware-assisted data erasure features if available (currently only NVMe
devices are supported). In case hardware-assisted data erasure is not
available, it falls back to metadata erasure for the device (which is
identical to ``erase_devices_metadata``). It can be considered a
time optimized mode of storage cleaning, aiming to perform as thorough
time-optimized mode of storage cleaning, aiming to perform as thorough
data erasure as it is possible within a short period of time.
This clean step is particularly well suited for environments with hybrid
NVMe-HDD storage configuration as it allows fast and secure erasure of data
@ -120,7 +120,7 @@ stored on NVMes combined with equally fast but more basic metadata-based
erasure of data on commodity HDDs.
By default, Ironic will use ``erase_devices_metadata`` early in cleaning
for reliability (ensuring a node cannot reboot into it's old workload) and
for reliability (ensuring a node cannot reboot into its old workload) and
``erase_devices`` later in cleaning to securely erase the drive;
``erase_devices_express`` is disabled.
@ -161,7 +161,7 @@ This list may not be comprehensive. Please review ironic.conf.sample
.. warning::
Ironic automated cleaning is defaulted to a secure configuration. You should
not modify settings related to it unless you are have special hardware needs,
not modify settings related to it unless you have special hardware needs
or a unique use case. Misconfigurations can lead to data exposure
vulnerabilities.
@ -173,7 +173,7 @@ This list may not be comprehensive. Please review ironic.conf.sample
Manual cleaning
===============
``Manual cleaning`` is typically used to handle long running, manual, or
``Manual cleaning`` is typically used to handle long-running, manual, or
destructive tasks that an operator wishes to perform either before the first
workload has been assigned to a node or between workloads. When initiating a
manual clean, the operator specifies the cleaning steps to be performed.
@ -381,7 +381,7 @@ priority.
Changing the priority of an in-band (ironic-python-agent) cleaning step
requires use of :oslo.config:option:`conductor.clean_step_priority_override`,
a configuration option which allows specifying priority of each step using
a configuration option that allows specifying the priority of each step using
multiple configuration values:
.. code-block:: ini
@ -421,7 +421,7 @@ Why can't I power on/off a node while it's cleaning?
----------------------------------------------------
During cleaning, nodes may be performing actions that shouldn't be
interrupted, such as BIOS or Firmware updates. As a result, operators are
forbidden from changing power state via the ironic API while a node is
forbidden from changing the power state via the ironic API while a node is
cleaning.
Advanced topics
@ -436,7 +436,7 @@ account child nodes. Mainly, the concept of executing clean steps in relation
to child nodes.
In this context, a child node is primarily intended to be an embedded device
with it's own management controller. For example "SmartNIC's" or Data
with its own management controller. For example "SmartNIC's" or Data
Processing Units (DPUs) which may have their own management controller and
power control.
@ -447,9 +447,9 @@ The relationship between a parent node and a child node is established on the ch
Child Node Clean Step Execution
-------------------------------
You can execute steps which perform actions on child nodes. For example,
You can execute steps that perform actions on child nodes. For example,
turn them on (via step ``power_on``), off (via step ``power_off``), or to
signal a BMC controlled reboot (via step ``reboot``).
signal a BMC-controlled reboot (via step ``reboot``).
For example, if you need to explicitly power off child node power, before
performing another step, you can articulate it with a step such as::
@ -484,8 +484,8 @@ If cleaning fails on a node, the node will be put into ``clean failed`` state.
If the failure happens while running a clean step, the node is also placed in
maintenance mode to prevent ironic from taking actions on the node. The
operator should validate that no permanent damage has been done to the
node and no processes are still running on it before removing the maintenance
mode.
node and that no processes are still running on it before removing the
maintenance mode.
.. note:: Older versions of ironic may put the node to maintenance even when
no clean step has been running.

14
doc/source/admin/conductor-groups.rst
View File

@ -7,13 +7,13 @@ Conductor Groups
Overview
========
Large scale operators tend to have needs that involve creating
well defined and delinated resources. In some cases, these systems
may reside close by or in far away locations. Reasoning may be simple
Large-scale operators tend to have needs that involve creating
well-defined and delineated resources. In some cases, these systems
may reside close by or in faraway locations. The reasoning may be simple
or complex, and yet is only known to the deployer and operator of the
infrastructure.
A common case is the need for delineated high availability domains
A common case is the need for delineated high-availability domains
where it would be much more efficient to manage a datacenter in Antarctica
with a conductor in Antarctica, as opposed to a conductor in New York City.
@ -44,7 +44,7 @@ only managing nodes with a matching ``conductor_group`` string.
How to use
==========
A conductor group value may be any case insensitive string up to 255
A conductor group value may be any case-insensitive string up to 255
characters long which matches the ``^[a-zA-Z0-9_\-\.]*$`` regular
expression.
@ -61,6 +61,6 @@ expression.
baremetal node set \
--conductor-group "OperatorDefinedString" <uuid>
#. As desired and as needed, remaining conductors can be updated with
#. As desired and as needed, the remaining conductors can be updated with
the first two steps. Please be mindful of the constraints covered
earlier in the document related to ability to manage nodes.
earlier in the document related to the ability to manage nodes.

22
doc/source/admin/console.rst
View File

@ -7,9 +7,9 @@ Configuring Web or Serial Console
Overview
--------
There are two types of console which are available in Bare Metal service,
There are two types of consoles which are available in Bare Metal service,
one is web console (`Node web console`_) which is available directly from web
browser, another is serial console (`Node serial console`_).
browser, and another is serial console (`Node serial console`_).
Node web console
----------------
@ -17,14 +17,14 @@ Node web console
The web console can be configured in Bare Metal service in the following way:
* Install shellinabox in ironic conductor node. For RHEL/CentOS, shellinabox package
is not present in base repositories, user must enable EPEL repository, you can find
more from `FedoraProject page`_.
is not present in base repositories, the user must enable EPEL repository, you can
find more from `FedoraProject page`_.
.. note::
shellinabox is no longer maintained by the authorized author.
`This <https://github.com/shellinabox/shellinabox>`_ is a fork of the
project on GitHub that aims to continue with maintenance of the
project on GitHub that aims to continue with the maintenance of the
shellinabox project.
Installation example:
@ -66,7 +66,7 @@ The web console can be configured in Bare Metal service in the following way:
* Customize the console section in the Bare Metal service configuration
file (/etc/ironic/ironic.conf), if you want to use SSL certificate in
shellinabox, you should specify ``terminal_cert_dir``.
for example::
For example::
[console]
@ -147,9 +147,9 @@ The web console can be configured in Bare Metal service in the following way:
| console_info | {u'url': u'http://<url>:<customized_port>', u'type': u'shellinabox'} |
+-----------------+----------------------------------------------------------------------+
You can open web console using above ``url`` through web browser. If ``console_enabled`` is
``false``, ``console_info`` is ``None``, web console is disabled. If you want to launch web
console, see the ``Configure node web console`` part.
You can open the web console using the above ``url`` through web browser. If
``console_enabled`` is ``false``, ``console_info`` is ``None``, web console is disabled.
If you want to launch the web console, see the ``Configure node web console`` part.
.. note::
@ -235,7 +235,7 @@ If ``console_enabled`` is ``false`` or ``console_info`` is ``None`` then
the serial console is disabled. If you want to launch serial console, see the
``Configure node console``.
Node serial console of the Bare Metal service is compatible with the
The node serial console of the Bare Metal service is compatible with the
serial console of the Compute service. Hence, serial consoles to
Bare Metal nodes can be seen and interacted with via the Dashboard service.
In order to achieve that, you need to follow the documentation for
@ -269,7 +269,7 @@ configuration, you may consider some settings below.
* The Compute service's caching feature may need to be enabled in order
to make the Bare Metal serial console work under a HA configuration.
Here is an example of caching configuration in ``nova.conf``.
Here is an example of a caching configuration in ``nova.conf``.
.. code-block:: ini