Merge ~ltrager/maas:hmcz_power_driver into maas:master

[Lee Trager]

Add the HMC power driver for IBM Z

[MAAS Lander (maas-lander)]

UNIT TESTS
-b hmcz_power_driver lp:~ltrager/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas/job/branch-tester/9211/console
COMMIT: 3da16a58b7f193273be918b852fabf2a617c6151

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b hmcz_power_driver lp:~ltrager/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas/job/branch-tester/9212/console
COMMIT: 8dd73384509b457a3538ffb8cfb08359ccf5dc4e

review: Needs Fixing

[Adam Collard (adam-collard)]

Urgh, failure in import linting

src/provisioningserver/drivers/power/hmcz.py
   denied: zhmcclient.Client
   denied: zhmcclient.NotFound
   denied: zhmcclient.Session
 src/provisioningserver/drivers/power/tests/test_hmcz.py
   denied: zhmcclient_mock.FakedSession

 19788 imported names were ALLOWED.
 4 imported names were DENIED.

[Adam Collard (adam-collard)]

nit pick

0270acc... by Lee Trager on 2021-02-17

Allow zhmcclient to be imported

[MAAS Lander (maas-lander)]

UNIT TESTS
-b hmcz_power_driver lp:~ltrager/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 0270acc9c0542b8bde175d0a0cb9ea89a475a1fe

review: Approve

04b9203... by Lee Trager on 2021-02-17

Merge branch 'master' into hmcz_power_driver

7647dad... by Lee Trager on 2021-02-17

adam-collard fix

[Lee Trager (ltrager)]

Thanks for the review, updated as suggested.

[MAAS Lander (maas-lander)]

UNIT TESTS
-b hmcz_power_driver lp:~ltrager/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas/job/branch-tester/9257/console
COMMIT: 7647dadd034c38d584cdd104d2d5916e2db003a7

review: Needs Fixing

[Adam Collard (adam-collard)]

jenkins: !test

[Adam Collard (adam-collard)]

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b hmcz_power_driver lp:~ltrager/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 7647dadd034c38d584cdd104d2d5916e2db003a7

review: Approve

diff --git a/debian/control b/debian/control
index f83bbad..5e7c67e 100644
--- a/debian/control
+++ b/debian/control
@@ -154,6 +154,7 @@ Depends: lshw,
          iproute2,
          ${misc:Depends},
          ${python3:Depends}
+Suggests: python3-zhmcclient (>= 0.22.0-0ubuntu1) 
 Description: MAAS server provisioning libraries (Python 3)
  This package provides the MAAS provisioning server python libraries.
  .
diff --git a/required-packages/base b/required-packages/base
index 7a7f382..4426319 100644
--- a/required-packages/base
+++ b/required-packages/base
@@ -60,6 +60,7 @@ python3-tz
 python3-uvloop
 python3-venv
 python3-yaml
+python3-zhmcclient
 python3-zope.interface
 syslinux-common
 ubuntu-keyring
diff --git a/snap/snapcraft.yaml b/snap/snapcraft.yaml
index 5d3eef9..1a34213 100644
--- a/snap/snapcraft.yaml
+++ b/snap/snapcraft.yaml
@@ -149,6 +149,7 @@ parts:
       - python3-txtftp
       - python3-urllib3 # for macaroonbakery
       - python3-yaml
+      - python3-zhmcclient
       - python3-zope.interface
       - rsyslog
       - snmp # APC
diff --git a/src/provisioningserver/drivers/power/hmc.py b/src/provisioningserver/drivers/power/hmc.py
index 49cb729..0358a69 100644
--- a/src/provisioningserver/drivers/power/hmc.py
+++ b/src/provisioningserver/drivers/power/hmc.py
@@ -1,4 +1,4 @@
-# Copyright 2015-2016 Canonical Ltd.  This software is licensed under the
+# Copyright 2015-2021 Canonical Ltd.  This software is licensed under the
 # GNU Affero General Public License version 3 (see the file LICENSE).
 
 """HMC Power Driver.
@@ -35,7 +35,7 @@ class HMCPowerDriver(PowerDriver):
     name = "hmc"
     chassis = True
     can_probe = False
-    description = "IBM Hardware Management Console (HMC)"
+    description = "IBM Hardware Management Console (HMC) for PowerPC"
     settings = [
         make_setting_field("power_address", "IP for HMC", required=True),
         make_setting_field("power_user", "HMC username"),
diff --git a/src/provisioningserver/drivers/power/hmcz.py b/src/provisioningserver/drivers/power/hmcz.py
 new file mode 100644
index 0000000..0f16af1
--- /dev/null
+++ b/src/provisioningserver/drivers/power/hmcz.py
@@ -0,0 +1,121 @@
+# Copyright 2021 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+"""HMC Z Driver.
+
+Support for managing DPM partitions via the IBM Hardware Management Console
+for Z. The HMC for IBM Z has a different API than the HMC for IBM Power, thus
+two different power drivers. See
+https://github.com/zhmcclient/python-zhmcclient/issues/494
+"""
+
+import contextlib
+
+from provisioningserver.drivers import (
+    make_ip_extractor,
+    make_setting_field,
+    SETTING_SCOPE,
+)
+from provisioningserver.drivers.power import PowerActionError, PowerDriver
+from provisioningserver.logger import get_maas_logger
+from provisioningserver.utils import typed
+from provisioningserver.utils.twisted import asynchronous, threadDeferred
+
+try:
+    from zhmcclient import Client, NotFound, Session
+except ImportError:
+    no_zhmcclient = True
+else:
+    no_zhmcclient = False
+
+maaslog = get_maas_logger("drivers.power.hmcz")
+
+
+class HMCZPowerDriver(PowerDriver):
+
+    name = "hmcz"
+    chassis = False
+    can_probe = False
+    description = "IBM Hardware Management Console (HMC) for Z"
+    settings = [
+        make_setting_field("power_address", "HMC Address", required=True),
+        make_setting_field("power_user", "HMC username", required=True),
+        make_setting_field(
+            "power_pass", "HMC password", field_type="password", required=True
+        ),
+        make_setting_field(
+            "power_partition_name",
+            "HMC partition name",
+            scope=SETTING_SCOPE.NODE,
+            required=True,
+        ),
+    ]
+    ip_extractor = make_ip_extractor("power_address")
+
+    def detect_missing_packages(self):
+        if no_zhmcclient:
+            return ["python3-zhmcclient"]
+        else:
+            return []
+
+    @typed
+    def _get_partition(self, context: dict):
+        session = Session(
+            context["power_address"],
+            context["power_user"],
+            context["power_pass"],
+        )
+        partition_name = context["power_partition_name"]
+        client = Client(session)
+        # Each HMC manages one or more CPCs(Central Processor Complex). To find
+        # a partition MAAS must iterate over all CPCs.
+        for cpc in client.cpcs.list():
+            if not cpc.dpm_enabled:
+                maaslog.warning(
+                    f"DPM is not enabled on '{cpc.get_property('name')}', "
+                    "skipping"
+                )
+                continue
+            with contextlib.suppress(NotFound):
+                return cpc.partitions.find(name=partition_name)
+        raise PowerActionError(f"Unable to find '{partition_name}' on HMC!")
+
+    # IBM Z partitions can take awhile to start/stop. Don't wait for completion
+    # so power actions don't consume a thread.
+
+    @typed
+    @asynchronous
+    @threadDeferred
+    def power_on(self, system_id: str, context: dict):
+        """Power on IBM Z DPM."""
+        partition = self._get_partition(context)
+        partition.start(wait_for_completion=False)
+
+    @typed
+    @asynchronous
+    @threadDeferred
+    def power_off(self, system_id: str, context: dict):
+        """Power off IBM Z DPM."""
+        partition = self._get_partition(context)
+        partition.stop(wait_for_completion=False)
+
+    @typed
+    @asynchronous
+    @threadDeferred
+    def power_query(self, system_id: str, context: dict):
+        """Power on IBM Z DPM."""
+        partition = self._get_partition(context)
+        status = partition.get_property("status")
+        # IBM Z takes time to start or stop a partition. It returns a
+        # transitional state during this time. Associate the transitional
+        # state with on or off so MAAS doesn't repeatedly issue a power
+        # on or off command.
+        if status in {"starting", "active"}:
+            # When a partition is starting it can go into a "paused" state.
+            # This isn't on or off, just that the partition isn't currently
+            # executing instructions.
+            return "on"
+        elif status in {"stopping", "stopped"}:
+            return "off"
+        else:
+            return "unknown"
diff --git a/src/provisioningserver/drivers/power/registry.py b/src/provisioningserver/drivers/power/registry.py
index 5eb0b66..ca742a5 100644
--- a/src/provisioningserver/drivers/power/registry.py
+++ b/src/provisioningserver/drivers/power/registry.py
@@ -13,6 +13,7 @@ from provisioningserver.drivers.power.apc import APCPowerDriver
 from provisioningserver.drivers.power.dli import DLIPowerDriver
 from provisioningserver.drivers.power.eaton import EatonPowerDriver
 from provisioningserver.drivers.power.hmc import HMCPowerDriver
+from provisioningserver.drivers.power.hmcz import HMCZPowerDriver
 from provisioningserver.drivers.power.ipmi import IPMIPowerDriver
 from provisioningserver.drivers.power.manual import ManualPowerDriver
 from provisioningserver.drivers.power.moonshot import MoonshotIPMIPowerDriver
@@ -55,6 +56,7 @@ power_drivers = [
     DLIPowerDriver(),
     EatonPowerDriver(),
     HMCPowerDriver(),
+    HMCZPowerDriver(),
     IPMIPowerDriver(),
     ManualPowerDriver(),
     MoonshotIPMIPowerDriver(),
diff --git a/src/provisioningserver/drivers/power/tests/test_hmcz.py b/src/provisioningserver/drivers/power/tests/test_hmcz.py
 new file mode 100644
index 0000000..abaf15c
--- /dev/null
+++ b/src/provisioningserver/drivers/power/tests/test_hmcz.py
@@ -0,0 +1,255 @@
+# Copyright 2021 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+"""Tests for `provisioningserver.drivers.power.hmcz`."""
+
+from twisted.internet.defer import inlineCallbacks
+from zhmcclient_mock import FakedSession
+
+from maastesting.factory import factory
+from maastesting.matchers import MockCalledOnce, MockCalledOnceWith
+from maastesting.testcase import MAASTestCase, MAASTwistedRunTest
+from provisioningserver.drivers.power import hmcz as hmcz_module
+from provisioningserver.drivers.power import PowerActionError
+
+
+class TestHMCZPowerDriver(MAASTestCase):
+
+    run_tests_with = MAASTwistedRunTest.make_factory(timeout=5)
+
+    def setUp(self):
+        super().setUp()
+        self.power_address = factory.make_ip_address()
+        self.fake_session = FakedSession(
+            self.power_address,
+            factory.make_name("hmc_name"),
+            # The version and API version below were taken from
+            # the test environment given by IBM.
+            "2.14.1",
+            "2.40",
+        )
+        self.patch(hmcz_module, "Session").return_value = self.fake_session
+        self.hmcz = hmcz_module.HMCZPowerDriver()
+
+    def make_context(self, power_partition_name=None):
+        if power_partition_name is None:
+            power_partition_name = factory.make_name("power_partition_name")
+        return {
+            "power_address": self.power_address,
+            "power_user": factory.make_name("power_user"),
+            "power_pass": factory.make_name("power_pass"),
+            "power_partition_name": power_partition_name,
+        }
+
+    def test_detect_missing_packages(self):
+        hmcz_module.no_zhmcclient = False
+        self.assertEqual([], self.hmcz.detect_missing_packages())
+
+    def test_detect_missing_packages_missing(self):
+        hmcz_module.no_zhmcclient = True
+        self.assertEqual(
+            ["python3-zhmcclient"], self.hmcz.detect_missing_packages()
+        )
+
+    def test_get_partition(self):
+        power_partition_name = factory.make_name("power_partition_name")
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add({"name": power_partition_name})
+
+        self.assertEqual(
+            power_partition_name,
+            self.hmcz._get_partition(
+                self.make_context(power_partition_name)
+            ).get_property("name"),
+        )
+
+    def test_get_partition_ignores_cpcs_with_no_dpm(self):
+        mock_logger = self.patch(hmcz_module.maaslog, "warning")
+        power_partition_name = factory.make_name("power_partition_name")
+        self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": False,
+            }
+        )
+        cpc = self.fake_session.hmc.cpcs.add({"dpm-enabled": True})
+        cpc.partitions.add({"name": power_partition_name})
+
+        self.assertEqual(
+            power_partition_name,
+            self.hmcz._get_partition(
+                self.make_context(power_partition_name)
+            ).get_property("name"),
+        )
+        self.assertThat(mock_logger, MockCalledOnce())
+
+    def test_get_partition_doesnt_find_partition(self):
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add({"name": factory.make_name("power_partition_name")})
+
+        self.assertRaises(
+            PowerActionError, self.hmcz._get_partition, self.make_context()
+        )
+
+    # zhmcclient_mock doesn't currently support async so MagicMock
+    # must be used for power on/off
+
+    @inlineCallbacks
+    def test_power_on(self):
+        mock_get_partition = self.patch(self.hmcz, "_get_partition")
+        yield self.hmcz.power_on(None, self.make_context())
+        self.assertThat(
+            mock_get_partition.return_value.start,
+            MockCalledOnceWith(wait_for_completion=False),
+        )
+
+    @inlineCallbacks
+    def test_power_off(self):
+        mock_get_partition = self.patch(self.hmcz, "_get_partition")
+        yield self.hmcz.power_off(None, self.make_context())
+        self.assertThat(
+            mock_get_partition.return_value.stop,
+            MockCalledOnceWith(wait_for_completion=False),
+        )
+
+    @inlineCallbacks
+    def test_power_query_starting(self):
+        power_partition_name = factory.make_name("power_partition_name")
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add(
+            {
+                "name": power_partition_name,
+                "status": "starting",
+            }
+        )
+
+        status = yield self.hmcz.power_query(
+            None, self.make_context(power_partition_name)
+        )
+
+        self.assertEqual("on", status)
+
+    @inlineCallbacks
+    def test_power_query_active(self):
+        power_partition_name = factory.make_name("power_partition_name")
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add(
+            {
+                "name": power_partition_name,
+                "status": "active",
+            }
+        )
+
+        status = yield self.hmcz.power_query(
+            None, self.make_context(power_partition_name)
+        )
+
+        self.assertEqual("on", status)
+
+    @inlineCallbacks
+    def test_power_query_stopping(self):
+        power_partition_name = factory.make_name("power_partition_name")
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add(
+            {
+                "name": power_partition_name,
+                "status": "stopping",
+            }
+        )
+
+        status = yield self.hmcz.power_query(
+            None, self.make_context(power_partition_name)
+        )
+
+        self.assertEqual("off", status)
+
+    @inlineCallbacks
+    def test_power_query_stopped(self):
+        power_partition_name = factory.make_name("power_partition_name")
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add(
+            {
+                "name": power_partition_name,
+                "status": "stopped",
+            }
+        )
+
+        status = yield self.hmcz.power_query(
+            None, self.make_context(power_partition_name)
+        )
+
+        self.assertEqual("off", status)
+
+    @inlineCallbacks
+    def test_power_query_paused(self):
+        power_partition_name = factory.make_name("power_partition_name")
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add(
+            {
+                "name": power_partition_name,
+                "status": "paused",
+            }
+        )
+
+        status = yield self.hmcz.power_query(
+            None, self.make_context(power_partition_name)
+        )
+
+        self.assertEqual("unknown", status)
+
+    @inlineCallbacks
+    def test_power_query_other(self):
+        power_partition_name = factory.make_name("power_partition_name")
+        cpc = self.fake_session.hmc.cpcs.add(
+            {
+                "name": factory.make_name("cpc"),
+                "dpm-enabled": True,
+            }
+        )
+        cpc.partitions.add(
+            {
+                "name": power_partition_name,
+                "status": factory.make_name("status"),
+            }
+        )
+
+        status = yield self.hmcz.power_query(
+            None, self.make_context(power_partition_name)
+        )
+
+        self.assertEqual("unknown", status)
diff --git a/utilities/check-imports b/utilities/check-imports
index ac9a3a7..dc7b496 100755
--- a/utilities/check-imports
+++ b/utilities/check-imports
@@ -164,6 +164,7 @@ TestingLibraries = Pattern(
     "testresources|testresources.**",
     "testscenarios|testscenarios.**",
     "testtools|testtools.**",
+    "zhmcclient_mock.**",
 )
 
 
@@ -235,6 +236,7 @@ RackControllerRule = Rule(
     Allow("urllib3|urllib3.**"),
     Allow("uvloop"),
     Allow("yaml"),
+    Allow("zhmcclient.**"),
     Allow("zope.interface|zope.interface.**"),
     Allow(StandardLibraries),
 )