From 3a465865f6fefbf47b3caac319d0b541722ce302 Mon Sep 17 00:00:00 2001
From: Jay Faulkner <jay.faulkner@verizonmedia.com>
Date: Tue, 29 Sep 2020 08:39:26 -0700
Subject: [PATCH] Add example for custom disk erasure

It's a common use case for operators to need to use vendor utilities
to erase block devices. This adds an example that specifically
addresses this use case.

Change-Id: I20dfc37e04466dc0ded9571637818e8f6fb10216
---
 examples/README.rst                           |  9 +++
 .../custom-disk-erase/example_disk_eraser.py  | 59 +++++++++++++++++++
 examples/custom-disk-erase/setup.cfg          | 20 +++++++
 examples/custom-disk-erase/setup.py           |  6 ++
 4 files changed, 94 insertions(+)
 create mode 100644 examples/custom-disk-erase/example_disk_eraser.py
 create mode 100644 examples/custom-disk-erase/setup.cfg
 create mode 100644 examples/custom-disk-erase/setup.py

diff --git a/examples/README.rst b/examples/README.rst
index 73f5be6b5..4c8423fb5 100644
--- a/examples/README.rst
+++ b/examples/README.rst
@@ -15,6 +15,15 @@ Use Cases include:
 * Implementing erase_device() using a vendor-provided utility for a given
   disk model.
 
+``custom-disk-erase``
+---------------------
+
+This example manager is meant to demonstrate good patterns for developing a
+hardware manager to perform disk erasure using a custom vendor utility.
+
+Use case:
+* Ensuring block devices of a specific model are erased using custom code
+
 ``business-logic``
 ------------------
 
diff --git a/examples/custom-disk-erase/example_disk_eraser.py b/examples/custom-disk-erase/example_disk_eraser.py
new file mode 100644
index 000000000..a79e3af3b
--- /dev/null
+++ b/examples/custom-disk-erase/example_disk_eraser.py
@@ -0,0 +1,59 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from oslo_log import log
+
+from ironic_python_agent import exceptions
+from ironic_python_agent import hardware
+
+LOG = log.getLogger()
+
+
+def _is_supported_disk(block_device):
+    # Helper methods are outside the class, to prevent them from being called
+    # by dispatch_to_managers.
+    #
+    # This method would perform checks to see if this is a disk that is
+    # supported by this custom hardware manager.
+    return True
+
+
+class ExampleDiskEraserHardwareManager(hardware.HardwareManager):
+    """Example hardware manager to support wiping a specific model disk"""
+
+    # All hardware managers have a name and a version.
+    # Version should be bumped anytime a change is introduced. This will
+    # signal to Ironic that if automatic node cleaning is in progress to
+    # restart it from the beginning, to ensure consistency. The value can
+    # be anything; it's checked for equality against previously seen
+    # name:manager pairs.
+    HARDWARE_MANAGER_NAME = 'ExampleDiskEraserHardwareManager'
+    HARDWARE_MANAGER_VERSION = '1'
+
+    def evaluate_hardware_support(self):
+        """Declare level of hardware support provided.
+
+        Since this example covers a case of supporting a specific device,
+        for disk erasure, we're going to return SERVICE_PROVIDER statically,
+        and actually do disk detection in erase_device method.
+
+        :returns: HardwareSupport level for this manager.
+        """
+        return hardware.HardwareSupport.SERVICE_PROVIDER
+
+    def erase_block_device(self, node, block_device):
+        """Erases hardware via custom utility if supported."""
+        if not _is_supported_disk(block_device):
+            raise exceptions.IncompatibleHardwareMethodError(
+                  "Not supported by this manager")
+
+        # Put your code here to wipe the disk.
diff --git a/examples/custom-disk-erase/setup.cfg b/examples/custom-disk-erase/setup.cfg
new file mode 100644
index 000000000..33d23d98a
--- /dev/null
+++ b/examples/custom-disk-erase/setup.cfg
@@ -0,0 +1,20 @@
+[metadata]
+name = example-disk-eraser
+author = Jay Faulkner
+author-email = jay@jvf.cc
+summary = IPA Example Hardware Managers: Example Disk Eraser
+license = Apache-2
+classifier =
+    Intended Audience :: Developers
+    Operating System :: OS Independent
+    License :: OSI Approved :: Apache Software License
+    Programming Language :: Python :: 3
+    Development Status :: 4 - Beta
+
+[files]
+modules =
+    example_disk_eraser
+
+[entry_points]
+ironic_python_agent.hardware_managers =
+    example_disk_eraser = example_disk_eraser:ExampleDiskEraserHardwareManager
diff --git a/examples/custom-disk-erase/setup.py b/examples/custom-disk-erase/setup.py
new file mode 100644
index 000000000..ed58d0f26
--- /dev/null
+++ b/examples/custom-disk-erase/setup.py
@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+import setuptools
+
+setuptools.setup(
+    setup_requires=['pbr'],
+    pbr=True)