saltext.bmc 0.0.1__py2.py3-none-any.whl

saltext/bmc/__init__.py

@@ -0,0 +1,17 @@
+# pylint: disable=missing-module-docstring
+import pathlib
+
+PACKAGE_ROOT = pathlib.Path(__file__).resolve().parent
+try:
+    from .version import __version__
+except ImportError:  # pragma: no cover
+    __version__ = "0.0.0.not-installed"
+    try:
+        from importlib.metadata import version, PackageNotFoundError
+
+        try:
+            __version__ = version(__name__)
+        except PackageNotFoundError:
+            pass
+    except ImportError:
+        pass

saltext/bmc/modules/bmc.py

@@ -0,0 +1,229 @@
+"""
+Execution module for BMC (Baseboard Management Controller) hardware.
+
+Supports two protocol backends — Redfish and IPMI (via ``pyghmi``) —
+selected per profile by a ``backend`` key.  The default is ``auto``,
+which probes Redfish first and falls back to IPMI.  See
+:mod:`saltext.bmc.utils.backend` for backend selection details.
+
+Configuration via Pillar::
+
+    saltext.bmc:
+      profiles:
+        bmc-host-01:
+          host: 10.0.0.5
+          username: root
+          password: calvin
+          verify_ssl: false
+          # backend defaults to 'auto'; set explicitly to skip the probe:
+          # backend: redfish    # or 'ipmi'
+        legacy-host:
+          host: 10.0.0.7
+          username: ADMIN
+          password: ADMIN
+          backend: ipmi
+          port: 623           # IPMI-only
+
+CLI examples::
+
+    salt-call --local bmc.power_status     bmc-host-01
+    salt-call --local bmc.set_boot_device  bmc-host-01 device=http persistent=False
+    salt-call --local bmc.power_cycle      bmc-host-01
+    salt-call --local bmc.get_system_info  bmc-host-01
+    salt-call --local bmc.get_sensor_data  bmc-host-01
+
+    # Bypass pillar with explicit connection kwargs:
+    salt-call --local bmc.power_status host=10.0.0.5 username=root password=calvin verify_ssl=False
+    salt-call --local bmc.power_status host=10.0.0.7 username=ADMIN password=ADMIN backend=ipmi
+"""
+
+from __future__ import annotations
+
+import logging
+
+from saltext.bmc.utils import backend as bk
+from saltext.bmc.utils import boot as boot_canon
+
+log = logging.getLogger(__name__)
+
+__virtualname__ = "bmc"
+
+
+def __virtual__():
+    return __virtualname__
+
+
+# ----------------------------------------------------------------------
+# Power operations
+# ----------------------------------------------------------------------
+
+
+def power_status(name: str | None = None, **conn) -> str:
+    """
+    Return the current power state: ``'on'``, ``'off'``, or ``'unknown'``.
+
+    :param name: BMC profile name (key under ``saltext.bmc:profiles``).
+                 Omit to use the top-level ``saltext.bmc`` config.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.power_status bmc-host-01
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.power_status()
+
+
+def power_on(name: str | None = None, **conn) -> dict:
+    """
+    Power on the host.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.power_on bmc-host-01
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.do_reset("On")
+
+
+def power_off(name: str | None = None, force: bool = False, **conn) -> dict:
+    """
+    Power off the host.
+
+    :param force: If True, issue ``ForceOff`` (hard cut).  Otherwise
+                  ``GracefulShutdown`` is attempted.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.power_off bmc-host-01
+        salt-call --local bmc.power_off bmc-host-01 force=True
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.do_reset("ForceOff" if force else "GracefulShutdown")
+
+
+def power_cycle(name: str | None = None, **conn) -> dict:
+    """
+    Power-cycle the host (off then on).
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.power_cycle bmc-host-01
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.do_reset("PowerCycle")
+
+
+def power_reset(name: str | None = None, force: bool = False, **conn) -> dict:
+    """
+    Reset the host.  Prefers ``GracefulRestart``; pass ``force=True`` for ``ForceRestart``.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.power_reset bmc-host-01
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.do_reset("ForceRestart" if force else "GracefulRestart")
+
+
+# ----------------------------------------------------------------------
+# Boot-device operations
+# ----------------------------------------------------------------------
+
+
+def get_boot_device(name: str | None = None, **conn) -> dict:
+    """
+    Return the current one-shot/persistent boot override.
+
+    Returns a dict with keys ``device`` (friendly name), ``redfish_target``,
+    ``native_target``, and ``enabled`` (``Once``/``Continuous``/``Disabled``).
+    On IPMI backends ``redfish_target`` is ``None``.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.get_boot_device bmc-host-01
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.get_boot()
+
+
+def set_boot_device(
+    name: str | None = None,
+    device: str = "none",
+    persistent: bool = False,
+    **conn,
+) -> dict:
+    """
+    Set the boot override.
+
+    :param str device: One of ``disk``, ``pxe``, ``http``, ``bios``, ``cd``,
+                       ``usb``, ``none``.  ``http`` and ``usb`` are not
+                       supported by the IPMI backend.
+    :param bool persistent: If True, override persists across reboots
+                            (Redfish ``Continuous``).  Otherwise it is
+                            consumed on the next boot (``Once``).
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.set_boot_device bmc-host-01 device=http
+        salt-call --local bmc.set_boot_device bmc-host-01 device=pxe persistent=True
+    """
+    # Validate the device name up-front so we fail fast without opening a
+    # connection on a typo.
+    boot_canon.canonicalize(device)
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.set_boot(device=device, persistent=persistent)
+
+
+# ----------------------------------------------------------------------
+# Inventory and sensors
+# ----------------------------------------------------------------------
+
+
+def get_system_info(name: str | None = None, **conn) -> dict:
+    """
+    Return a normalised inventory dict.
+
+    Keys: ``manufacturer``, ``model``, ``serial_number``, ``uuid``, ``sku``,
+    ``host_name``, ``bios_version``, ``firmware_version``, ``power_state``.
+    Unknown fields are returned as ``None``.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.get_system_info bmc-host-01
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.get_system_info()
+
+
+def get_sensor_data(name: str | None = None, **conn) -> dict:
+    """
+    Return ``{"temperatures": [...], "fans": [...], "voltages": [...]}``.
+
+    Each sensor entry has ``name``, ``reading``, ``unit``, ``status``.
+    A backend may return an empty list for a sensor class it does not
+    expose.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc.get_sensor_data bmc-host-01
+    """
+    with bk.open_backend(__opts__, name=name, **conn) as backend:
+        return backend.get_sensors()

saltext/bmc/modules/bmc_redfish.py

@@ -0,0 +1,126 @@
+"""
+Low-level Redfish HTTP passthrough.
+
+Bypasses the backend abstraction in :mod:`saltext.bmc.modules.bmc` to let
+operators read or write any Redfish endpoint directly.  Useful for
+ad-hoc inspection, vendor-specific OEM extensions, and one-off
+operations that the high-level module does not cover.
+
+This module is Redfish-only.  If the profile's ``backend`` is set to
+``ipmi``, calls raise :class:`~saltext.bmc.utils.redfish.RedfishError`
+immediately.
+
+CLI examples (``path`` is the first positional arg; pass the profile via
+``name=``)::
+
+    salt-call --local bmc_redfish.get   /redfish/v1/         name=bmc-host-01
+    salt-call --local bmc_redfish.get   /redfish/v1/Systems  name=bmc-host-01
+    salt-call --local bmc_redfish.patch /redfish/v1/Systems/1 \\
+        body='{"AssetTag": "rack-7-slot-3"}' name=bmc-host-01
+    salt-call --local bmc_redfish.post \\
+        /redfish/v1/Systems/1/Actions/ComputerSystem.Reset \\
+        body='{"ResetType": "On"}' name=bmc-host-01
+"""
+
+from __future__ import annotations
+
+import logging
+
+from saltext.bmc.utils import redfish as rf
+
+log = logging.getLogger(__name__)
+
+__virtualname__ = "bmc_redfish"
+
+
+def __virtual__():
+    return __virtualname__
+
+
+def _require_redfish(name: str | None, conn: dict) -> None:
+    """Raise if the resolved profile uses a non-Redfish backend."""
+    cfg = rf.resolve_conn(__opts__, name=name, **conn)
+    backend = (cfg.get("backend") or "redfish").lower()
+    if backend == "ipmi":
+        raise rf.RedfishError(
+            f"Profile {name!r} uses backend={backend!r}; bmc_redfish.* requires Redfish."
+        )
+
+
+def _client(name: str | None, conn: dict) -> rf.RedfishClient:
+    _require_redfish(name, conn)
+    return rf.open_client(__opts__, name=name, **conn)
+
+
+def get(path: str, name: str | None = None, **conn) -> dict:
+    """
+    Raw Redfish GET.
+
+    :param str path: Redfish path (must start with ``/redfish/v1/``).
+    :param str name: Profile name; falls back to top-level config.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc_redfish.get /redfish/v1/Systems name=bmc-host-01
+    """
+    with _client(name, conn) as client:
+        return client.get(path)
+
+
+def post(path: str, name: str | None = None, body: dict | None = None, **conn) -> dict | None:
+    """
+    Raw Redfish POST.
+
+    :param str path: Redfish action path.
+    :param dict body: Request body (optional for some Redfish actions).
+    :param str name: Profile name.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc_redfish.post \\
+            /redfish/v1/Systems/1/Actions/ComputerSystem.Reset \\
+            body='{"ResetType": "On"}' name=bmc-host-01
+    """
+    with _client(name, conn) as client:
+        return client.post(path, body)
+
+
+def patch(path: str, body: dict, name: str | None = None, **conn) -> dict | None:
+    """
+    Raw Redfish PATCH.
+
+    :param str path: Redfish resource path.
+    :param dict body: Request body (required).
+    :param str name: Profile name.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc_redfish.patch /redfish/v1/Systems/1 \\
+            body='{"AssetTag": "rack-7-slot-3"}' name=bmc-host-01
+    """
+    with _client(name, conn) as client:
+        return client.patch(path, body)
+
+
+def delete(path: str, name: str | None = None, **conn) -> dict | None:
+    """
+    Raw Redfish DELETE.
+
+    :param str path: Redfish resource path.
+    :param str name: Profile name.
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt-call --local bmc_redfish.delete \\
+            /redfish/v1/SessionService/Sessions/3 name=bmc-host-01
+    """
+    with _client(name, conn) as client:
+        return client.delete(path)

saltext/bmc/resources/bmc/__init__.py

@@ -0,0 +1,190 @@
+"""
+``bmc`` resource type — per-host BMC management over Redfish or IPMI.
+
+Each ``bmc`` resource maps to one physical machine, addressed by its BMC
+host/credentials.  The resource ID is the human-friendly name used in
+Pillar and targeting.
+
+Configuration (via Pillar)::
+
+    resources:
+      bmc:
+        bmc-host-01:
+          host: 10.10.10.5
+          username: root
+          password: calvin
+          verify_ssl: false
+          # backend defaults to 'auto'; set explicitly to skip the probe:
+          # backend: redfish        # or 'ipmi'
+        legacy-host:
+          host: 10.10.10.7
+          username: ADMIN
+          password: ADMIN
+          backend: ipmi
+          port: 623
+
+Targeting::
+
+    salt  bmc-host-01              bmc_host.power_status   # by resource ID alone
+    salt -C 'T@bmc:bmc-host-01'    bmc_host.power_status   # by full SRN
+    salt -C 'T@bmc'                bmc_host.power_status   # all bmc resources
+    salt  bmc-host-01              state.sls baremetal/boot_http
+
+Per-host execution functions live in
+:mod:`saltext.bmc.resources.bmc.modules.bmc_host`; the per-host states
+in :mod:`saltext.bmc.resources.bmc.states.bmc_host`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import salt.utils.resources  # pylint: disable=import-error,no-name-in-module
+
+from saltext.bmc.utils import backend as bk
+
+log = logging.getLogger(__name__)
+
+CONTEXT_KEY = "bmc_resource"
+
+
+def __virtual__():
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resource_id() -> str:
+    return __resource__["id"]  # pylint: disable=undefined-variable
+
+
+def _ctx() -> dict:
+    return __context__.get(CONTEXT_KEY, {})  # pylint: disable=undefined-variable
+
+
+def _host_cfg(resource_id: str) -> dict:
+    cfg = _ctx().get("hosts", {}).get(resource_id, {})
+    if not cfg:
+        raise ValueError(f"No bmc resource '{resource_id}' in pillar resources:bmc:")
+    return cfg
+
+
+def _opts_for(resource_id: str) -> dict:
+    """
+    Build a Salt-opts shim that routes through :func:`backend.open_backend`.
+
+    ``open_backend`` reads its connection config from ``opts["pillar"]["saltext.bmc"]``;
+    we synthesise that from the per-resource pillar entry so we can reuse the same
+    factory.
+    """
+    cfg = _host_cfg(resource_id)
+    return {
+        "pillar": {
+            "saltext.bmc": {
+                "profiles": {resource_id: cfg},
+            }
+        }
+    }
+
+
+def _open(resource_id: str | None = None):
+    rid = resource_id or _resource_id()
+    return bk.open_backend(_opts_for(rid), name=rid)
+
+
+# ---------------------------------------------------------------------------
+# Required resource interface
+# ---------------------------------------------------------------------------
+
+
+def init(opts: dict) -> None:
+    """
+    Initialise the ``bmc`` resource type.
+
+    Reads BMC host configs from Pillar and caches them in
+    ``__context__["bmc_resource"]``.
+    """
+    type_cfg = salt.utils.resources.pillar_resources_tree(opts).get("bmc", {}) or {}
+    __context__[CONTEXT_KEY] = {  # pylint: disable=undefined-variable
+        "initialized": True,
+        "hosts": type_cfg,
+    }
+    log.debug("bmc init(), managing: %s", list(type_cfg))
+
+
+def initialized() -> bool:
+    """Return ``True`` if :func:`init` has been called successfully."""
+    return _ctx().get("initialized", False)
+
+
+def discover(opts: dict) -> list:
+    """
+    Return the list of BMC resource IDs declared in Pillar.
+
+    :param dict opts: The Salt opts dict.
+    :rtype: list[str]
+    """
+    type_cfg = salt.utils.resources.pillar_resources_tree(opts).get("bmc", {}) or {}
+    return list(type_cfg.keys())
+
+
+# ---------------------------------------------------------------------------
+# Per-resource operations
+# ---------------------------------------------------------------------------
+
+
+def power_status() -> str:
+    """Return ``'on'`` / ``'off'`` / ``'unknown'`` for this host."""
+    with _open() as backend:
+        return backend.power_status()
+
+
+def power_on() -> dict:
+    """Power on this host."""
+    with _open() as backend:
+        return backend.do_reset("On")
+
+
+def power_off(force: bool = False) -> dict:
+    """Power off this host (``GracefulShutdown`` by default, ``ForceOff`` if force=True)."""
+    with _open() as backend:
+        return backend.do_reset("ForceOff" if force else "GracefulShutdown")
+
+
+def power_cycle() -> dict:
+    """Power-cycle this host."""
+    with _open() as backend:
+        return backend.do_reset("PowerCycle")
+
+
+def power_reset(force: bool = False) -> dict:
+    """Reset this host (``GracefulRestart`` by default, ``ForceRestart`` if force=True)."""
+    with _open() as backend:
+        return backend.do_reset("ForceRestart" if force else "GracefulRestart")
+
+
+def get_boot_device() -> dict:
+    """Return the current boot override (device/enabled/native_target)."""
+    with _open() as backend:
+        return backend.get_boot()
+
+
+def set_boot_device(device: str = "none", persistent: bool = False) -> dict:
+    """Set the boot override on this host."""
+    with _open() as backend:
+        return backend.set_boot(device=device, persistent=persistent)
+
+
+def get_system_info() -> dict:
+    """Return a normalised inventory dict for this host."""
+    with _open() as backend:
+        return backend.get_system_info()
+
+
+def get_sensor_data() -> dict:
+    """Return temperatures/fans/voltages dict for this host."""
+    with _open() as backend:
+        return backend.get_sensors()