Add diagnostics for Proxmox config entries

Implement diagnostics for Proxmox configuration entries with public-safe sanitization for sensitive data.

CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 0.7.5
+- Added extended Diagnostics export
+  - Includes Proxmox version information (`/version`)
+  - Includes cluster metadata (`/cluster/status`)
+  - Adds node, VM and container counts
+- Diagnostics are safe for public sharing
+  - All IP addresses are masked
+  - API tokens remain redacted
+  - Token names are partially anonymized (first 2 + last 2 characters)
+
+## 0.7.4
+- Added Home Assistant Diagnostics support
+  - New “Download diagnostics” feature for each Easy Proxmox config entry
+  - Diagnostics include:
+    - Config entry data and options (sanitized)
+    - Runtime client information
+    - Coordinator states (last update success, exceptions, update interval)
+    - Safe previews of nodes and guests
+  - Sensitive data such as API tokens and credentials are automatically redacted
+  - Diagnostics are fully JSON-serializable and suitable for GitHub issue attachments
+
+## 0.7.3
+- Fixed service execution when using device targets in automations and scripts
+- Services now work correctly on Home Assistant versions where `ServiceCall.target` is not available
+- Improved target resolution:
+  - Supports `device_id` passed via UI targets and via service data
+  - Supports `entity_id` targets and automatically resolves them to the corresponding device
+  - Accepts both `str` and `list[str]` formats for target identifiers
+- Fixed issue where service calls were accepted but no Proxmox action was executed
+- Improved compatibility with the Home Assistant automation editor and mobile UI
+
+## 0.7.2
+- Fixed service validation for device targets:
+  - Home Assistant may pass `device_id` as a list (target/data wrapper)
+  - Services now accept both `str` and `list[str]` for `device_id`
+  - Improved device target parsing for UI and script wrappers
+
+## 0.7.1
+- Fixed Home Assistant service UI integration:
+  - Services now properly expose the **Device selector** in the visual automation editor
+  - Implemented correct handling of `call.target.device_id`
+  - Services are now fully compatible with Home Assistant’s target system
+- Fixed issue where only a YAML data field was shown instead of a device selection field
+- Improved service robustness when used in multi-host environments
+- This release is a bugfix release for v0.7.0
+
+## 0.7.0
+- Added full service support for automations and scripts:
+  - `proxmox_pve.start`
+  - `proxmox_pve.shutdown`
+  - `proxmox_pve.stop_hard`
+  - `proxmox_pve.reboot`
+- Services are now fully multi-host capable:
+  - Automatic detection of the correct Proxmox host when using `device_id`
+  - Optional selection via `config_entry_id`
+  - Optional selection via `host`
+  - Automatic lookup by `node/vmid/type` if no host is given
+  - Clear error handling for ambiguous multi-host targets
+- Services can be used in:
+  - Automations
+  - Scripts
+  - Dashboards
+- Added `services.yaml` for proper UI descriptions in Home Assistant
+- Easy Proxmox can now be fully controlled without any buttons or switches, purely via automations
+
 ## 0.6.1
 - Fix correct autor in hacs
 
@@ -92,3 +157,7 @@
 - Basic connectivity test via Config Flow
 - First experimental entities
 
+
+
+
+

README.md

@@ -1,3 +1,11 @@
+# Easy Proxmox (by René Bachmann)
+
+![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/bahmcloud/easy_proxmox?sort=semver)
+![HACS Integration](https://img.shields.io/badge/HACS%20Integration-blue)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+[![Add to HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=bahmcloud&repository=easy_proxmox)
+
+
 <img width="1230" height="300" alt="logo" src="https://github.com/user-attachments/assets/7649cc04-bdcd-449e-bf83-c4f980f3de74" />
 
 A powerful Home Assistant integration to monitor and control Proxmox VE. With Easy Proxmox you can monitor nodes, VMs and containers directly in Home Assistant, start/stop/reboot guests and display detailed system metrics.
@@ -35,20 +43,30 @@ A powerful Home Assistant integration to monitor and control Proxmox VE. With Ea
 
 ---
 
-## Installation
+## 📦 Installation via HACS (Recommended)
 
-1. Create the folder:
-    /config/custom_components/proxmox_pve/
+To install Easy Proxmox through HACS:
 
+1. **Ensure HACS is already installed** in your Home Assistant instance.  
+   If not, follow the official guide: https://hacs.xyz/
 
-2. Copy all integration files into that folder.
+2. Open **HACS → Integrations**.
 
-3. Restart Home Assistant.
+3. Click the **“⋯” (three dots)** → **Custom repositories**.
 
-4. Add the integration:
+4. Add the following repository:
+   - Repository URL:  
+     ```
+     https://github.com/bahmcloud/easy_proxmox
+     ```
+   - Category: **Integration**
+   - Version: **Tags (recommended)**
 
-    Settings → Devices & Services → Add Integration → Easy Proxmox
+5. Click **Add**, then locate **Easy Proxmox** in the HACS list and click **Install**.
 
+6. After installation, **restart Home Assistant**.
+
+7. Go to **Settings → Devices & Services → Add Integration → Easy Proxmox**.
 ---
 
 ## Proxmox: Create User & API Token
@@ -64,8 +82,6 @@ Example:
 - Realm: `pam` or `pve`
 - Set a password (only for management; the token will be used for API access)
 
----
-
 ### 2) Create an API Token
 
 Datacenter → Permissions → API Tokens → Add
@@ -81,9 +97,6 @@ You will get:
     Token Name: homeassistant@pve!easyproxmox
     Token Secret: <long secret string>
 
-
----
-
 ### 3) Assign Permissions (Admin Rights)
 
 To ensure full functionality (monitoring + guest controls), assign admin rights:
@@ -121,12 +134,117 @@ After saving:
 
 ---
 
+## 🚀 Services & Automations (since v0.7.0)
+
+Easy Proxmox provides Home Assistant services so you can fully control your VMs and containers in automations and scripts without using buttons or switches.
+
+Available services:
+
+| Service | Description |
+|--------|------------|
+| `proxmox_pve.start` | Start a VM or container |
+| `proxmox_pve.shutdown` | Gracefully shutdown a VM or container |
+| `proxmox_pve.stop_hard` | Hard stop a VM or container |
+| `proxmox_pve.reboot` | Reboot a VM or container |
+
+All services are **multi-host aware** and automatically select the correct Proxmox server.
+
+### ✅ Recommended usage: Device based
+
+This is the safest and easiest way, especially for multi-host setups.
+
+In an automation or script:
+
+```yaml
+service: proxmox_pve.shutdown
+target:
+  device_id: YOUR_DEVICE_ID
+```
+
+In the UI, you can simply select the VM/CT device from the dropdown.
+
+Home Assistant will automatically:
+
+ - Find the correct Proxmox host
+ - Find the correct node
+ - Execute the action
+
+### 🔧 Manual usage: Node / VMID based
+
+You can also call services manually:
+
+```yaml
+service: proxmox_pve.reboot
+data:
+  node: pve1
+  vmid: 100
+  type: qemu
+```
+If you have multiple Proxmox servers configured, you should also specify one of:
+```yaml
+host: 192.168.178.101
+```
+
+or
+```yaml
+config_entry_id: 8d9f2e7b1c3d4a5f...
+```
+
+This avoids ambiguity.
+
+### 🧠 Resolution priority
+
+When a service is called, Easy Proxmox resolves the target in this order:
+
+ 1. `config_entry_id`
+ 2. `device_id`
+ 3. `host`
+ 4. Guest lookup by `node + vmid + type`
+
+If a guest exists on multiple Proxmox hosts, the call fails and asks for clarification.
+
+### 🏗 Example automations
+
+Shutdown all test systems at night:
+```yaml
+alias: Stop Test VM at Night
+trigger:
+  - platform: time
+    at: "23:00:00"
+action:
+  - service: proxmox_pve.shutdown
+    target:
+      device_id: 123456abcdef...
+```
+
+Start a VM when electricity price is low:
+```yaml
+alias: Start VM on cheap power
+trigger:
+  - platform: numeric_state
+    entity_id: sensor.power_price
+    below: 0.20
+action:
+  - service: proxmox_pve.start
+    target:
+      device_id: 123456abcdef...
+```
+
+### 🧩 Why this matters
+
+With services you can:
+
+ - Fully automate your Proxmox infrastructure
+ - Remove dependency on dashboard buttons
+ - Build power-saving or maintenance automations
+ - Control multiple Proxmox clusters cleanly
+
+---
 ## Options (Gear Icon)
 
 After setup, open:
     Settings → Devices & Services → Easy Proxmox → Options (gear icon)
 
-
 ### Polling Interval
 How often data is fetched from Proxmox.
 
@@ -138,8 +256,6 @@ How often data is fetched from Proxmox.
 
 Changes are applied immediately (no restart required).
 
----
-
 ### IP Preference Mode
 
 Controls which IP is shown as the “primary” IP for a guest:
@@ -151,8 +267,6 @@ Controls which IP is shown as the “primary” IP for a guest:
 | any | Use the first available IP |
 | custom_prefix | Use a custom prefix |
 
----
-
 ### Custom IP Prefix
 
 Only relevant if `custom_prefix` is selected.
@@ -215,12 +329,26 @@ The API token has admin rights. Treat it like a root password:
 | Buttons don’t work        | Check Proxmox permissions (PVEAdmin role)                                              |
 | Old devices remain        | Fully cleaned up automatically since version 0.4.1                                     |
 
+### Diagnostics
+
+If you open an issue on GitHub, please attach a diagnostics export:
+
+Settings → Devices & Services → Easy Proxmox → (⋮) → Download diagnostics
+
+This export is automatically sanitized (API token is redacted).
+
 ---
 
-## License / Support
+## Support & Contributing
 
-Look into LICENSE file. 
+If you need help, open an issue in GitHub.  
+Want to contribute? Feel free to submit PRs!
 
 ---
 
 **Easy Proxmox aims to provide a complete Proxmox VE experience in Home Assistant.**
+
+See [CHANGELOG.md](CHANGELOG.md) for full version history.
+
+Releases: https://github.com/bahmcloud/easy_proxmox/releases
+

custom_components/proxmox_pve/__init__.py

@@ -17,6 +17,7 @@ from .const import (
     DEFAULT_IP_PREFIX,
 )
 from .coordinator import ProxmoxResourcesCoordinator, ProxmoxNodesCoordinator
+from .services import async_register_services, async_unregister_services
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -33,14 +34,12 @@ async def _apply_options_now(hass: HomeAssistant, entry: ConfigEntry) -> None:
     new_ip_mode = str(_opt(entry, CONF_IP_MODE, DEFAULT_IP_MODE))
     new_ip_prefix = str(_opt(entry, CONF_IP_PREFIX, DEFAULT_IP_PREFIX))
 
-    # store new values for future coordinator creations
     data["scan_interval"] = new_scan_interval
     data["ip_mode"] = new_ip_mode
     data["ip_prefix"] = new_ip_prefix
 
     td = timedelta(seconds=new_scan_interval)
 
-    # cluster coordinators
     resources = data.get("resources")
     if resources:
         resources.update_interval = td
@@ -49,11 +48,9 @@ async def _apply_options_now(hass: HomeAssistant, entry: ConfigEntry) -> None:
     if nodes:
         nodes.update_interval = td
 
-    # node coordinators
     for node_coord in (data.get("node_coordinators") or {}).values():
         node_coord.update_interval = td
 
-    # guest coordinators (also update ip preference config)
     for guest_coord in (data.get("guest_coordinators") or {}).values():
         guest_coord.update_interval = td
         guest_coord.ip_mode = new_ip_mode
@@ -72,8 +69,6 @@ async def _apply_options_now(hass: HomeAssistant, entry: ConfigEntry) -> None:
     for guest_coord in (data.get("guest_coordinators") or {}).values():
         tasks.append(guest_coord.async_request_refresh())
 
-    if tasks:
-        # don't fail all if one refresh fails
     for t in tasks:
         hass.async_create_task(t)
 
@@ -87,7 +82,6 @@ async def _apply_options_now(hass: HomeAssistant, entry: ConfigEntry) -> None:
 
 
 async def _update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
-    """Called by HA when options are changed."""
     await _apply_options_now(hass, entry)
 
 
@@ -122,12 +116,15 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         "scan_interval": scan_interval,
         "ip_mode": ip_mode,
         "ip_prefix": ip_prefix,
-        "guest_coordinators": {},   # (node, vmtype, vmid) -> ProxmoxGuestCoordinator
-        "node_coordinators": {},    # node -> ProxmoxNodeCoordinator
-        "platform_cache": {},       # per-platform caches + unsub handles
+        "guest_coordinators": {},
+        "node_coordinators": {},
+        "platform_cache": {},
     }
 
-    # Apply option updates live (gear icon -> save)
+    # Register services once
+    await async_register_services(hass)
+
+    # Apply option updates live
     entry.async_on_unload(entry.add_update_listener(_update_listener))
 
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
@@ -152,4 +149,8 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             if data.get("session"):
                 await data["session"].close()
 
+        # If no entries remain, unregister services
+        if not hass.data.get(DOMAIN):
+            await async_unregister_services(hass)
+
     return unload_ok

custom_components/proxmox_pve/diagnostics.py

@@ -0,0 +1,340 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Awaitable, Callable
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+
+from .const import DOMAIN
+
+
+# ---------------------------
+# Masking helpers
+# ---------------------------
+
+_IPV4_RE = re.compile(r"\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b")
+
+
+def _mask_ipv4(ip: str) -> str:
+    """Mask IPv4 addresses (keep first two octets). Example: 192.168.178.101 -> 192.168.xxx.xxx"""
+    parts = ip.split(".")
+    if len(parts) != 4:
+        return ip
+    return f"{parts[0]}.{parts[1]}.xxx.xxx"
+
+
+def _mask_ipv4_in_text(text: str) -> str:
+    """Replace any IPv4 occurrences inside a string."""
+    return _IPV4_RE.sub(lambda m: _mask_ipv4(m.group(0)), text)
+
+
+def _mask_token_name(value: Any) -> Any:
+    """Show only first 2 and last 2 chars of token_name."""
+    if not isinstance(value, str):
+        return value
+    s = value.strip()
+    if len(s) <= 4:
+        return "*" * len(s) if s else s
+    return f"{s[:2]}***{s[-2:]}"
+
+
+def _redact_secret(value: Any) -> Any:
+    """Redact secrets while keeping structure intact."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        s = value.strip()
+        if not s:
+            return value
+        if len(s) <= 6:
+            return "***"
+        return s[:3] + "***" + s[-3:]
+    if isinstance(value, dict):
+        return {k: _redact_secret(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_redact_secret(v) for v in value]
+    return value
+
+
+def _sanitize_public(value: Any) -> Any:
+    """
+    Public-safe sanitization:
+    - Mask all IPv4 strings anywhere
+    - Keep structure
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return _mask_ipv4_in_text(value)
+    if isinstance(value, dict):
+        return {str(k): _sanitize_public(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_sanitize_public(v) for v in value]
+    if isinstance(value, tuple):
+        return [_sanitize_public(v) for v in value]
+    return value
+
+
+# ---------------------------
+# Coordinator helpers
+# ---------------------------
+
+def _safe_coordinator_state(coord: Any) -> dict[str, Any]:
+    if not coord:
+        return {}
+    data = getattr(coord, "data", None)
+    preview = None
+    if isinstance(data, list):
+        preview = data[:3]
+    return {
+        "name": getattr(coord, "name", None),
+        "update_interval": str(getattr(coord, "update_interval", None)),
+        "last_update_success": getattr(coord, "last_update_success", None),
+        "last_exception": repr(getattr(coord, "last_exception", None)),
+        "data_type": type(data).__name__,
+        "data_preview": preview,
+    }
+
+
+def _stringify_key(key: Any) -> str:
+    if isinstance(key, tuple):
+        return ":".join(str(x) for x in key)
+    return str(key)
+
+
+def _safe_coord_map(coord_map: Any) -> dict[str, Any]:
+    if not isinstance(coord_map, dict):
+        return {}
+    return {_stringify_key(k): _safe_coordinator_state(v) for k, v in coord_map.items()}
+
+
+# ---------------------------
+# Proxmox client access
+# ---------------------------
+
+async def _try_call(func: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> Any:
+    return await func(*args, **kwargs)
+
+
+async def _client_get_json(client: Any, path: str) -> Any:
+    """
+    Best-effort JSON GET against the Proxmox client.
+    Tries multiple method names to stay compatible with different client styles.
+    """
+    if client is None:
+        return None
+
+    if not path.startswith("/"):
+        path = "/" + path
+
+    candidates = []
+    for name in (
+        "get",
+        "api_get",
+        "request",
+        "api_request",
+        "_request",
+        "_api_request",
+        "get_json",
+        "async_get",
+    ):
+        fn = getattr(client, name, None)
+        if callable(fn):
+            candidates.append((name, fn))
+
+    last_err: Exception | None = None
+
+    for name, fn in candidates:
+        try:
+            if name in ("request", "api_request", "_request", "_api_request"):
+                data = await _try_call(fn, "GET", path)
+            else:
+                data = await _try_call(fn, path)
+
+            # Unwrap {"data": ...} responses
+            if isinstance(data, dict) and "data" in data and len(data) == 1:
+                return data["data"]
+
+            return data
+        except Exception as err:  # noqa: BLE001
+            last_err = err
+            continue
+
+    if last_err:
+        return {
+            "error": f"Could not query {path} via client "
+                     f"({type(last_err).__name__}: {last_err})"
+        }
+
+    return {"error": f"Could not query {path} via client (no compatible method found)"}
+
+
+# ---------------------------
+# Proxmox data processing
+# ---------------------------
+
+def _count_resources(resources_data: Any) -> dict[str, int]:
+    counts = {
+        "nodes": 0,
+        "vms": 0,
+        "containers": 0,
+        "total_guests": 0,
+    }
+    if not isinstance(resources_data, list):
+        return counts
+
+    for r in resources_data:
+        if not isinstance(r, dict):
+            continue
+        r_type = r.get("type")
+        if r_type == "node":
+            counts["nodes"] += 1
+        elif r_type == "qemu":
+            counts["vms"] += 1
+            counts["total_guests"] += 1
+        elif r_type == "lxc":
+            counts["containers"] += 1
+            counts["total_guests"] += 1
+
+    return counts
+
+
+def _extract_cluster_info(cluster_status: Any) -> dict[str, Any] | None:
+    if not isinstance(cluster_status, list):
+        return None
+
+    cluster_name = None
+    node_count = 0
+
+    for item in cluster_status:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") == "cluster":
+            cluster_name = item.get("name") or cluster_name
+        if item.get("type") == "node":
+            node_count += 1
+
+    return {
+        "name": cluster_name,
+        "nodes": node_count,
+        "raw_preview": cluster_status[:5],
+    }
+
+
+# ---------------------------
+# Main diagnostics entrypoint
+# ---------------------------
+
+async def async_get_config_entry_diagnostics(
+    hass: HomeAssistant, entry: ConfigEntry
+) -> dict[str, Any]:
+    """Return diagnostics for a config entry (public-safe, JSON serializable)."""
+    domain_data = hass.data.get(DOMAIN, {}).get(entry.entry_id, {}) or {}
+
+    client = domain_data.get("client")
+    resources = domain_data.get("resources")
+    nodes = domain_data.get("nodes")
+    guest_coordinators = domain_data.get("guest_coordinators", {}) or {}
+    node_coordinators = domain_data.get("node_coordinators", {}) or {}
+
+    # ---- Entry data/options with focused redaction ----
+    entry_data = dict(entry.data)
+    # Mask secrets
+    for key in ("token_value", "password", "api_key", "secret"):
+        if key in entry_data:
+            entry_data[key] = _redact_secret(entry_data[key])
+    # Mask token_name per requirement
+    if "token_name" in entry_data:
+        entry_data["token_name"] = _mask_token_name(entry_data["token_name"])
+    # Host/IP should be masked
+    if "host" in entry_data and isinstance(entry_data["host"], str):
+        entry_data["host"] = _mask_ipv4_in_text(entry_data["host"])
+
+    options = dict(entry.options)
+    # ip_prefix may reveal network; mask if it looks like an IP-ish prefix
+    if "ip_prefix" in options and isinstance(options["ip_prefix"], str):
+        options["ip_prefix"] = _mask_ipv4_in_text(options["ip_prefix"])
+
+    # ---- Resource previews & counts ----
+    res_preview = None
+    res_counts = {"nodes": 0, "vms": 0, "containers": 0, "total_guests": 0}
+    try:
+        if resources and isinstance(resources.data, list):
+            res_counts = _count_resources(resources.data)
+            res_preview = [
+                {
+                    "type": r.get("type"),
+                    "node": r.get("node"),
+                    "vmid": r.get("vmid"),
+                    "name": r.get("name"),
+                    "status": r.get("status"),
+                }
+                for r in resources.data[:25]
+                if isinstance(r, dict)
+            ]
+    except Exception:  # noqa: BLE001
+        res_preview = None
+
+    node_preview = None
+    try:
+        if nodes and isinstance(nodes.data, list):
+            node_preview = [
+                {
+                    "node": n.get("node"),
+                    "status": n.get("status"),
+                    "uptime": n.get("uptime"),
+                    "cpu": n.get("cpu"),
+                    "mem": n.get("mem"),
+                    "maxmem": n.get("maxmem"),
+                }
+                for n in nodes.data[:15]
+                if isinstance(n, dict)
+            ]
+    except Exception:  # noqa: BLE001
+        node_preview = None
+
+    # ---- Proxmox meta information ----
+    version_info = await _client_get_json(client, "/version")
+    cluster_status = await _client_get_json(client, "/cluster/status")
+    cluster_info = _extract_cluster_info(cluster_status)
+
+    proxmox_meta = {
+        "version": version_info,
+        "cluster": cluster_info,
+        "counts": res_counts,
+    }
+
+    result = {
+        "entry": {
+            "entry_id": entry.entry_id,
+            # Title can contain IPs (like "Proxmox 192.168.x.x") -> mask it
+            "title": _mask_ipv4_in_text(entry.title),
+            "data": entry_data,
+            "options": options,
+        },
+        "runtime": {
+            "client": {
+                "host": _mask_ipv4_in_text(str(getattr(client, "host", ""))) if client else None,
+                "port": getattr(client, "port", None) if client else None,
+                "verify_ssl": getattr(client, "verify_ssl", None) if client else None,
+            },
+            "scan_interval": domain_data.get("scan_interval"),
+            "ip_mode": domain_data.get("ip_mode"),
+            "ip_prefix": _mask_ipv4_in_text(str(domain_data.get("ip_prefix"))) if domain_data.get("ip_prefix") else None,
+        },
+        "proxmox": proxmox_meta,
+        "coordinators": {
+            "resources": _safe_coordinator_state(resources),
+            "nodes": _safe_coordinator_state(nodes),
+            "node_coordinators": _safe_coord_map(node_coordinators),
+            "guest_coordinators": _safe_coord_map(guest_coordinators),
+        },
+        "data_preview": {
+            "resources_preview": res_preview,
+            "nodes_preview": node_preview,
+        },
+    }
+
+    # FINAL PASS: mask any IPv4 that still appears anywhere (including cluster raw_preview "ip")
+    return _sanitize_public(result)

custom_components/proxmox_pve/manifest.json

@@ -1,8 +1,8 @@
 {
   "domain": "proxmox_pve",
   "name": "Easy Proxmox (by René Bachmann)",
-  "version": "0.6.0-alpha",
-  "documentation": "https://example.invalid",
+  "version": "0.7.5",
+  "documentation": "https://github.com/bahmcloud/easy_proxmox ",
   "requirements": ["aiohttp>=3.9.0"],
   "codeowners": ["@BAHMCLOUD"],
   "config_flow": true,
@@ -10,3 +10,4 @@
   "integration_type": "service"
 }
 
+

custom_components/proxmox_pve/services.py

@@ -0,0 +1,270 @@
+import logging
+from typing import Any, Tuple
+
+import voluptuous as vol
+
+from homeassistant.core import HomeAssistant, ServiceCall
+from homeassistant.helpers import device_registry as dr
+from homeassistant.helpers import entity_registry as er
+
+from .const import DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+SERVICE_START = "start"
+SERVICE_SHUTDOWN = "shutdown"
+SERVICE_STOP_HARD = "stop_hard"
+SERVICE_REBOOT = "reboot"
+
+ATTR_DEVICE_ID = "device_id"
+ATTR_ENTITY_ID = "entity_id"
+ATTR_CONFIG_ENTRY_ID = "config_entry_id"
+ATTR_HOST = "host"
+ATTR_NODE = "node"
+ATTR_VMID = "vmid"
+ATTR_TYPE = "type"
+
+VALID_TYPES = ("qemu", "lxc")
+
+# Accept device_id passed as str or list[str] (depends on HA UI/script)
+SERVICE_SCHEMA = vol.Schema(
+    {
+        vol.Optional(ATTR_DEVICE_ID): vol.Any(str, [str]),
+        vol.Optional(ATTR_ENTITY_ID): vol.Any(str, [str]),
+        vol.Optional(ATTR_CONFIG_ENTRY_ID): str,
+        vol.Optional(ATTR_HOST): str,
+        vol.Optional(ATTR_NODE): str,
+        vol.Optional(ATTR_VMID): vol.Coerce(int),
+        vol.Optional(ATTR_TYPE, default="qemu"): vol.In(VALID_TYPES),
+    }
+)
+
+
+def _first_str(value: Any) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    if isinstance(value, list) and value:
+        v0 = value[0]
+        if isinstance(v0, str) and v0.strip():
+            return v0.strip()
+    return None
+
+
+def _first_str_from_target(target: Any, key: str) -> str | None:
+    if isinstance(target, dict):
+        return _first_str(target.get(key))
+    return None
+
+
+def _get_device_id(hass: HomeAssistant, call: ServiceCall) -> str | None:
+    """
+    Robust device_id extraction across HA versions.
+
+    Priority:
+    1) call.target.device_id (newer HA)
+    2) call.data.device_id (some wrappers)
+    3) call.target.entity_id -> map to device_id
+    4) call.data.entity_id -> map to device_id
+    """
+    target = getattr(call, "target", None)
+
+    # 1) target.device_id
+    dev_id = _first_str_from_target(target, "device_id")
+    if dev_id:
+        return dev_id
+
+    # 2) data.device_id
+    dev_id = _first_str(call.data.get(ATTR_DEVICE_ID))
+    if dev_id:
+        return dev_id
+
+    # 3) target.entity_id -> device_id
+    ent_id = _first_str_from_target(target, "entity_id")
+    if ent_id:
+        ent_reg = er.async_get(hass)
+        ent = ent_reg.async_get(ent_id)
+        if ent and ent.device_id:
+            return ent.device_id
+
+    # 4) data.entity_id -> device_id
+    ent_id = _first_str(call.data.get(ATTR_ENTITY_ID))
+    if ent_id:
+        ent_reg = er.async_get(hass)
+        ent = ent_reg.async_get(ent_id)
+        if ent and ent.device_id:
+            return ent.device_id
+
+    return None
+
+
+def _parse_guest_identifier(identifier: str) -> Tuple[str, str, int]:
+    parts = identifier.split(":")
+    if len(parts) != 3:
+        raise ValueError(f"Invalid guest identifier: {identifier}")
+    node, vmtype, vmid_s = parts
+    vmid = int(vmid_s)
+    if vmtype not in VALID_TYPES:
+        raise ValueError(f"Invalid VM type: {vmtype}")
+    return node, vmtype, vmid
+
+
+def _resolve_target(hass: HomeAssistant, call: ServiceCall) -> Tuple[str, str, int]:
+    device_id = _get_device_id(hass, call)
+    node = call.data.get(ATTR_NODE)
+    vmid = call.data.get(ATTR_VMID)
+    vmtype = call.data.get(ATTR_TYPE, "qemu")
+
+    if device_id:
+        dev_reg = dr.async_get(hass)
+        device = dev_reg.async_get(device_id)
+        if not device:
+            raise ValueError(f"Device not found: {device_id}")
+
+        for ident_domain, ident_value in device.identifiers:
+            if ident_domain != DOMAIN:
+                continue
+            if ident_value.startswith("node:"):
+                continue
+            return _parse_guest_identifier(ident_value)
+
+        raise ValueError(f"Selected device has no Easy Proxmox guest identifier: {device_id}")
+
+    if not node or vmid is None:
+        raise ValueError("Provide a Device/Entity target OR node + vmid (+ optional type/host/config_entry_id).")
+
+    if vmtype not in VALID_TYPES:
+        raise ValueError(f"Invalid type: {vmtype} (allowed: {VALID_TYPES})")
+
+    return str(node), str(vmtype), int(vmid)
+
+
+def _get_domain_entries(hass: HomeAssistant) -> dict[str, Any]:
+    domain_data: dict[str, Any] = hass.data.get(DOMAIN, {})
+    if not domain_data:
+        raise ValueError("Easy Proxmox is not set up.")
+    return domain_data
+
+
+def _pick_entry_id_for_device(hass: HomeAssistant, device_id: str) -> str:
+    dev_reg = dr.async_get(hass)
+    device = dev_reg.async_get(device_id)
+    if not device:
+        raise ValueError(f"Device not found: {device_id}")
+
+    domain_entries = _get_domain_entries(hass)
+    candidates = [eid for eid in device.config_entries if eid in domain_entries]
+    if not candidates:
+        raise ValueError("Device is not linked to any loaded Easy Proxmox config entry.")
+    if len(candidates) > 1:
+        _LOGGER.warning("Device %s belongs to multiple Easy Proxmox entries, using first.", device_id)
+    return candidates[0]
+
+
+def _pick_entry_id_by_host(hass: HomeAssistant, host: str) -> str:
+    domain_entries = _get_domain_entries(hass)
+    matches = []
+    for entry_id, data in domain_entries.items():
+        if not isinstance(data, dict):
+            continue
+        client = data.get("client")
+        if client and getattr(client, "host", None) == host:
+            matches.append(entry_id)
+
+    if not matches:
+        raise ValueError(f"No Easy Proxmox entry found for host '{host}'.")
+    if len(matches) > 1:
+        raise ValueError(f"Multiple Easy Proxmox entries found for host '{host}'. Please use config_entry_id.")
+    return matches[0]
+
+
+def _pick_entry_id_by_guest_lookup(hass: HomeAssistant, node: str, vmtype: str, vmid: int) -> str:
+    domain_entries = _get_domain_entries(hass)
+    matches = []
+
+    for entry_id, data in domain_entries.items():
+        if not isinstance(data, dict):
+            continue
+        resources = data.get("resources")
+        res_list = getattr(resources, "data", None)
+        if not res_list:
+            continue
+
+        for r in res_list:
+            try:
+                if r.get("type") == vmtype and str(r.get("node")) == node and int(r.get("vmid")) == vmid:
+                    matches.append(entry_id)
+                    break
+            except Exception:
+                continue
+
+    if not matches:
+        raise ValueError(
+            f"Could not find guest {node}/{vmtype}/{vmid} in any configured Proxmox host. "
+            "Provide host or config_entry_id, or use a Device/Entity target."
+        )
+    if len(matches) > 1:
+        raise ValueError(
+            f"Guest {node}/{vmtype}/{vmid} exists on multiple configured hosts (ambiguous). "
+            "Please provide host or config_entry_id, or use a Device/Entity target."
+        )
+    return matches[0]
+
+
+def _resolve_entry_id(hass: HomeAssistant, call: ServiceCall, node: str, vmtype: str, vmid: int) -> str:
+    domain_entries = _get_domain_entries(hass)
+
+    config_entry_id = call.data.get(ATTR_CONFIG_ENTRY_ID)
+    if config_entry_id:
+        if config_entry_id not in domain_entries:
+            raise ValueError(f"config_entry_id '{config_entry_id}' not found or not loaded.")
+        return config_entry_id
+
+    device_id = _get_device_id(hass, call)
+    if device_id:
+        return _pick_entry_id_for_device(hass, device_id)
+
+    host = call.data.get(ATTR_HOST)
+    if host:
+        return _pick_entry_id_by_host(hass, host)
+
+    return _pick_entry_id_by_guest_lookup(hass, node, vmtype, vmid)
+
+
+async def async_register_services(hass: HomeAssistant) -> None:
+    if hass.services.has_service(DOMAIN, SERVICE_START):
+        return
+
+    async def _call_action(call: ServiceCall, action: str) -> None:
+        node, vmtype, vmid = _resolve_target(hass, call)
+        entry_id = _resolve_entry_id(hass, call, node, vmtype, vmid)
+
+        entry_data = _get_domain_entries(hass).get(entry_id)
+        if not isinstance(entry_data, dict) or not entry_data.get("client"):
+            raise ValueError(f"Selected config entry '{entry_id}' has no client (not loaded).")
+
+        client = entry_data["client"]
+        _LOGGER.debug("Service action=%s entry=%s target=%s/%s/%s data=%s", action, entry_id, node, vmtype, vmid, call.data)
+        await client.guest_action(node=node, vmid=vmid, vmtype=vmtype, action=action)
+
+    async def handle_start(call: ServiceCall) -> None:
+        await _call_action(call, "start")
+
+    async def handle_shutdown(call: ServiceCall) -> None:
+        await _call_action(call, "shutdown")
+
+    async def handle_stop_hard(call: ServiceCall) -> None:
+        await _call_action(call, "stop")
+
+    async def handle_reboot(call: ServiceCall) -> None:
+        await _call_action(call, "reboot")
+
+    hass.services.async_register(DOMAIN, SERVICE_START, handle_start, schema=SERVICE_SCHEMA)
+    hass.services.async_register(DOMAIN, SERVICE_SHUTDOWN, handle_shutdown, schema=SERVICE_SCHEMA)
+    hass.services.async_register(DOMAIN, SERVICE_STOP_HARD, handle_stop_hard, schema=SERVICE_SCHEMA)
+    hass.services.async_register(DOMAIN, SERVICE_REBOOT, handle_reboot, schema=SERVICE_SCHEMA)
+
+
+async def async_unregister_services(hass: HomeAssistant) -> None:
+    for svc in (SERVICE_START, SERVICE_SHUTDOWN, SERVICE_STOP_HARD, SERVICE_REBOOT):
+        if hass.services.has_service(DOMAIN, svc):
+            hass.services.async_remove(DOMAIN, svc)

custom_components/proxmox_pve/services.yaml

@@ -0,0 +1,111 @@
+start:
+  name: Start guest
+  description: Start a VM or container.
+  target:
+    device:
+      integration: proxmox_pve
+  fields:
+    config_entry_id:
+      name: Config entry id
+      description: Optional. Force a specific Proxmox host configuration entry.
+      example: "8d9f2e7b1c3d4a5f..."
+    host:
+      name: Host
+      description: Optional. Proxmox host/IP of the configured entry (only used when device is not selected).
+      example: "192.168.178.101"
+    node:
+      name: Node
+      description: Proxmox node name (only used when device is not selected).
+      example: "pve1"
+    vmid:
+      name: VMID
+      description: Guest VMID (only used when device is not selected).
+      example: 100
+    type:
+      name: Type
+      description: Guest type (only used when device is not selected).
+      example: "qemu"
+
+shutdown:
+  name: Shutdown guest
+  description: Gracefully shutdown a VM or container.
+  target:
+    device:
+      integration: proxmox_pve
+  fields:
+    config_entry_id:
+      name: Config entry id
+      description: Optional. Force a specific Proxmox host configuration entry.
+      example: "8d9f2e7b1c3d4a5f..."
+    host:
+      name: Host
+      description: Optional. Proxmox host/IP of the configured entry (only used when device is not selected).
+      example: "192.168.178.101"
+    node:
+      name: Node
+      description: Proxmox node name (only used when device is not selected).
+      example: "pve1"
+    vmid:
+      name: VMID
+      description: Guest VMID (only used when device is not selected).
+      example: 100
+    type:
+      name: Type
+      description: Guest type (only used when device is not selected).
+      example: "qemu"
+
+stop_hard:
+  name: Stop guest (hard)
+  description: Hard stop a VM or container (equivalent to Stop).
+  target:
+    device:
+      integration: proxmox_pve
+  fields:
+    config_entry_id:
+      name: Config entry id
+      description: Optional. Force a specific Proxmox host configuration entry.
+      example: "8d9f2e7b1c3d4a5f..."
+    host:
+      name: Host
+      description: Optional. Proxmox host/IP of the configured entry (only used when device is not selected).
+      example: "192.168.178.101"
+    node:
+      name: Node
+      description: Proxmox node name (only used when device is not selected).
+      example: "pve1"
+    vmid:
+      name: VMID
+      description: Guest VMID (only used when device is not selected).
+      example: 100
+    type:
+      name: Type
+      description: Guest type (only used when device is not selected).
+      example: "qemu"
+
+reboot:
+  name: Reboot guest
+  description: Reboot a VM or container.
+  target:
+    device:
+      integration: proxmox_pve
+  fields:
+    config_entry_id:
+      name: Config entry id
+      description: Optional. Force a specific Proxmox host configuration entry.
+      example: "8d9f2e7b1c3d4a5f..."
+    host:
+      name: Host
+      description: Optional. Proxmox host/IP of the configured entry (only used when device is not selected).
+      example: "192.168.178.101"
+    node:
+      name: Node
+      description: Proxmox node name (only used when device is not selected).
+      example: "pve1"
+    vmid:
+      name: VMID
+      description: Guest VMID (only used when device is not selected).
+      example: 100
+    type:
+      name: Type
+      description: Guest type (only used when device is not selected).
+      example: "qemu"