From 1aa780377ed52d187764322c5b731e63ce94c052 Mon Sep 17 00:00:00 2001 From: Jay Faulkner Date: Wed, 15 May 2024 15:18:57 -0700 Subject: [PATCH] Deduplicate and remove invalid information for steps Lots of references to deprecated ways of doing things, as well as two entire separate sections dedicated to how disk erasure works. Also ensured we reference new valid config options surrounding disk erasure. Additional improvments could include adding documentation around how to skip disks per node (or linking to any preexisting docs around it). Change-Id: Ifa029e26eff0637b443d094d85e773b885d0979b --- doc/source/admin/cleaning.rst | 115 +++++++++++++++++----------------- 1 file changed, 58 insertions(+), 57 deletions(-) diff --git a/doc/source/admin/cleaning.rst b/doc/source/admin/cleaning.rst index a3d8e9e83c..04e84617d1 100644 --- a/doc/source/admin/cleaning.rst +++ b/doc/source/admin/cleaning.rst @@ -76,6 +76,10 @@ See `How do I change the priority of a cleaning step?`_ for more information. Storage cleaning options ------------------------ +.. warning:: + Ironic's storage cleaning options by default will remove data from the disk + permanently during automated cleaning. + Clean steps specific to storage are ``erase_devices``, ``erase_devices_metadata`` and (added in Yoga) ``erase_devices_express``. @@ -83,13 +87,16 @@ Clean steps specific to storage are ``erase_devices``, 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 -``[deploy]/continue_if_disk_secure_erase_fails`` is set to ``True``, cleaning -will fall back to using ``shred`` to overwrite the contents of the device. -Otherwise cleaning will fail. It is important to note that ``erase_devices`` -may take a very long time (hours or even days) to complete, unless fast, -hardware assisted data erasure is supported by all the devices in a system. -Generally, it is very difficult (if possible at all) to recover data after -performing cleaning with ``erase_devices``. +:oslo.config:option:`deploy.continue_if_disk_secure_erase_fails` is set to +``True``, cleaning will fall back to using ``shred`` to overwrite the +contents of the device. By default, if ``erase_devices`` is enabled +and Ironic is unable to erase the device, cleaning will fail to ensure +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 + 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 @@ -110,23 +117,53 @@ 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 stored on NVMes combined with equally fast but more basic metadata-based -erasure of data on HDDs. -``erase_devices_express`` is disabled by default. In order to use it, the -following configuration is recommended. +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 +``erase_devices`` later in cleaning to securely erase the drive; +``erase_devices_express`` is disabled. + +Operators can use :oslo.config:option:`deploy.erase_devices_priority` and +:oslo.config:option:`deploy.erase_devices_metadata_priority` to change the +priorities of the default device erase methods or disable them entirely +by setting ``0``. Other cleaning steps can have their priority modified +via the :oslo.config:option:`conductor.clean_step_priority_override` option. +For example, the configuration snippet below disables +``erase_devices_metadata`` and ``erase_devices`` and instead performs an +``erase_devices_express`` erase step. .. code-block:: ini - [deploy]/erase_devices_priority=0 - [deploy]/erase_devices_metadata_priority=0 - [conductor]/clean_step_priority_override=deploy.erase_devices_express:5 + [deploy] + erase_devices_priority=0 + erase_devices_metadata_priority=0 + + [conductor] + clean_step_priority_override=deploy.erase_devices_express:95 This ensures that ``erase_devices`` and ``erase_devices_metadata`` are disabled so that storage is not cleaned twice and then assigns a non-zero priority to ``erase_devices_express``, hence enabling it. Any non-zero -priority specified in the priority override will work. +priority specified in the priority override will work; larger values will +cause the disk erasure to run earlier in the cleaning process if multiple +steps are enabled. -Also ``[deploy]/enable_nvme_secure_erase`` should not be disabled (it is on by -default). +Other configurations that can modify how Ironic erases disks are below. +This list may not be comprehensive. Please review ironic.conf.sample +(linked) for more details: + +* :oslo.config:option:`deploy.enable_ata_secure_erase`, default ``True`` +* :oslo.config:option:`deploy.enable_nvme_secure_erase`, default ``True`` +* :oslo.config:option:`deploy.shred_random_overwrite_iterations`, default ``1`` +* :oslo.config:option:`deploy.shred_final_overwrite_with_zeros`, default ``True`` +* :oslo.config:option:`deploy.disk_erasure_concurrency`, default ``4`` + +.. 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, + or a unique use case. Misconfigurations can lead to data exposure + vulnerabilities. .. show-steps:: :phase: cleaning @@ -218,7 +255,7 @@ Alternatively, you can specify a runbook instead of clean_steps:: The specified runbook must match one of the node's traits to be used. -Starting manual cleaning via "openstack metal" CLI +Starting manual cleaning via "openstack baremetal" CLI ------------------------------------------------------ Manual cleaning is available via the ``baremetal node clean`` @@ -330,6 +367,7 @@ How do I skip a cleaning step? ------------------------------ For automated cleaning, cleaning steps with a priority of 0 or None are skipped. +.. _clean_step_priority: How do I change the priority of a cleaning step? ------------------------------------------------ @@ -342,46 +380,9 @@ Most out-of-band cleaning steps have an explicit configuration option for priority. Changing the priority of an in-band (ironic-python-agent) cleaning step -requires use of a custom HardwareManager. The only exception is -``erase_devices``, which can have its priority set in ironic.conf. For instance, -to disable erase_devices, you'd set the following configuration option:: - - [deploy] - erase_devices_priority=0 - -To enable/disable the in-band disk erase using ``ilo`` hardware type, use the -following configuration option:: - - [ilo] - clean_priority_erase_devices=0 - -The generic hardware manager first identifies whether a device is an NVMe -drive or an ATA drive so that it can attempt a platform-specific secure erase -method. In case of NVMe drives, it tries to perform a secure format operation -by using the ``nvme-cli`` utility. This behavior can be controlled using -the following configuration option (by default it is set to True):: - - [deploy] - enable_nvme_secure_erase=True - - -In case of ATA drives, it tries to perform ATA disk erase by using the -``hdparm`` utility. - -If neither method is supported, it performs software based disk erase using -the ``shred`` utility. By default, the number of iterations performed -by ``shred`` for software based disk erase is 1. To configure the number of -iterations, use the following configuration option:: - - [deploy] - erase_devices_iterations=1 - -Overriding step priority ------------------------- - -:oslo.config:option:`conductor.clean_step_priority_override` is a new configuration option -which allows specifying priority of each step using multiple configuration -values: +requires use of :oslo.config:option:`conductor.clean_step_priority_override`, +a configuration option which allows specifying priority of each step using +multiple configuration values: .. code-block:: ini