vmware-storage 1.2.0__py3-none-any.whl

vmware_storage/__init__.py

@@ -0,0 +1,3 @@
+"""VMware Storage — vSphere datastore, iSCSI, and vSAN management."""
+
+__version__ = "1.2.0"

vmware_storage/cli.py

@@ -0,0 +1,291 @@
+"""vmware-storage CLI — Datastore, iSCSI, and vSAN management."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from vmware_storage.config import load_config
+from vmware_storage.connection import ConnectionManager
+from vmware_storage.notify.audit import AuditLogger
+
+app = typer.Typer(
+    name="vmware-storage",
+    help="VMware vSphere storage management: datastores, iSCSI, vSAN.",
+    no_args_is_help=True,
+)
+
+console = Console()
+_audit = AuditLogger()
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_connection(target: str | None, config_path: str | None = None):
+    config = load_config(Path(config_path) if config_path else None)
+    conn_mgr = ConnectionManager(config)
+    return conn_mgr.connect(target)
+
+
+def _print_json(data) -> None:
+    console.print_json(json.dumps(data, default=str, ensure_ascii=False))
+
+
+def _double_confirm(action: str, detail: str) -> bool:
+    """Two-step confirmation for destructive operations."""
+    console.print(f"\n[bold yellow]WARNING:[/] {action}")
+    console.print(f"  {detail}\n")
+    first = typer.confirm("Are you sure?", default=False)
+    if not first:
+        console.print("[dim]Cancelled.[/]")
+        return False
+    second = typer.confirm("This modifies host storage configuration. Confirm again?", default=False)
+    if not second:
+        console.print("[dim]Cancelled.[/]")
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Datastore commands
+# ---------------------------------------------------------------------------
+
+ds_app = typer.Typer(help="Datastore browsing and image discovery.")
+app.add_typer(ds_app, name="datastore")
+
+
+@ds_app.command("list")
+def ds_list(
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """List all datastores with capacity info."""
+    from vmware_storage.ops.inventory import list_datastores
+    si = _get_connection(target, config)
+    result = list_datastores(si)
+    _audit.log_query(target=target or "default", resource="datastores", query_type="list")
+    table = Table(title="Datastores")
+    table.add_column("Name", style="bold")
+    table.add_column("Type")
+    table.add_column("Total GB", justify="right")
+    table.add_column("Free GB", justify="right")
+    table.add_column("Usage %", justify="right")
+    table.add_column("VMs", justify="right")
+    for ds in result:
+        usage_style = "red" if ds["usage_pct"] > 85 else ""
+        table.add_row(
+            ds["name"], ds["type"],
+            str(ds["total_gb"]), str(ds["free_gb"]),
+            f"[{usage_style}]{ds['usage_pct']}%[/]",
+            str(ds["vm_count"]),
+        )
+    console.print(table)
+
+
+@ds_app.command("browse")
+def ds_browse(
+    ds_name: str = typer.Argument(help="Datastore name"),
+    path: str = typer.Option("", help="Subdirectory path"),
+    pattern: str = typer.Option("*", help="Glob pattern"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Browse files in a datastore."""
+    from vmware_storage.ops.datastore_browser import browse_datastore
+    si = _get_connection(target, config)
+    result = browse_datastore(si, ds_name, path=path, pattern=pattern)
+    _audit.log_query(target=target or "default", resource=ds_name, query_type="browse")
+    _print_json(result)
+
+
+@ds_app.command("scan-images")
+def ds_scan_images(
+    ds_name: str = typer.Argument(help="Datastore name"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Scan a datastore for deployable images (OVA/ISO/OVF/VMDK)."""
+    from vmware_storage.ops.datastore_browser import scan_images
+    si = _get_connection(target, config)
+    result = scan_images(si, ds_name)
+    _audit.log_query(target=target or "default", resource=ds_name, query_type="scan_images")
+    _print_json(result)
+
+
+# ---------------------------------------------------------------------------
+# iSCSI commands
+# ---------------------------------------------------------------------------
+
+iscsi_app = typer.Typer(help="iSCSI adapter and target management.")
+app.add_typer(iscsi_app, name="iscsi")
+
+
+@iscsi_app.command("enable")
+def iscsi_enable(
+    host_name: str = typer.Argument(help="ESXi host name"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without executing"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Enable software iSCSI adapter on a host."""
+    if dry_run:
+        console.print(f"[dim][DRY-RUN] Would enable software iSCSI on host '{host_name}'[/]")
+        return
+    if not _double_confirm(
+        "Enable software iSCSI adapter",
+        f"Host: {host_name}",
+    ):
+        return
+    from vmware_storage.ops.iscsi_config import enable_software_iscsi
+    si = _get_connection(target, config)
+    result = enable_software_iscsi(si, host_name)
+    _audit.log(target=target or "default", operation="iscsi_enable",
+               resource=host_name, parameters={"host_name": host_name}, result=result)
+    console.print(result)
+
+
+@iscsi_app.command("status")
+def iscsi_status(
+    host_name: str = typer.Argument(help="ESXi host name"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Show iSCSI adapter status and targets."""
+    from vmware_storage.ops.iscsi_config import get_iscsi_status
+    si = _get_connection(target, config)
+    _print_json(get_iscsi_status(si, host_name))
+
+
+@iscsi_app.command("add-target")
+def iscsi_add_target(
+    host_name: str = typer.Argument(help="ESXi host name"),
+    address: str = typer.Argument(help="iSCSI target IP address"),
+    port: int = typer.Option(3260, help="iSCSI target port"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without executing"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Add an iSCSI send target and rescan storage."""
+    if dry_run:
+        console.print(
+            f"[dim][DRY-RUN] Would add iSCSI target {address}:{port} "
+            f"to host '{host_name}' and rescan[/]"
+        )
+        return
+    if not _double_confirm(
+        "Add iSCSI send target + rescan storage",
+        f"Host: {host_name}  Target: {address}:{port}",
+    ):
+        return
+    from vmware_storage.ops.iscsi_config import add_iscsi_target
+    si = _get_connection(target, config)
+    result = add_iscsi_target(si, host_name, address, port)
+    _audit.log(target=target or "default", operation="iscsi_add_target",
+               resource=host_name,
+               parameters={"host_name": host_name, "address": address, "port": port},
+               result=result)
+    console.print(result)
+
+
+@iscsi_app.command("remove-target")
+def iscsi_remove_target(
+    host_name: str = typer.Argument(help="ESXi host name"),
+    address: str = typer.Argument(help="iSCSI target IP address"),
+    port: int = typer.Option(3260, help="iSCSI target port"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without executing"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Remove an iSCSI send target and rescan storage."""
+    if dry_run:
+        console.print(
+            f"[dim][DRY-RUN] Would remove iSCSI target {address}:{port} "
+            f"from host '{host_name}' and rescan[/]"
+        )
+        return
+    if not _double_confirm(
+        "Remove iSCSI send target + rescan storage",
+        f"Host: {host_name}  Target: {address}:{port}",
+    ):
+        return
+    from vmware_storage.ops.iscsi_config import remove_iscsi_target
+    si = _get_connection(target, config)
+    result = remove_iscsi_target(si, host_name, address, port)
+    _audit.log(target=target or "default", operation="iscsi_remove_target",
+               resource=host_name,
+               parameters={"host_name": host_name, "address": address, "port": port},
+               result=result)
+    console.print(result)
+
+
+@iscsi_app.command("rescan")
+def iscsi_rescan(
+    host_name: str = typer.Argument(help="ESXi host name"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without executing"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Rescan all HBAs and VMFS volumes."""
+    if dry_run:
+        console.print(f"[dim][DRY-RUN] Would rescan all HBAs and VMFS on host '{host_name}'[/]")
+        return
+    from vmware_storage.ops.iscsi_config import rescan_storage
+    si = _get_connection(target, config)
+    result = rescan_storage(si, host_name)
+    _audit.log(target=target or "default", operation="storage_rescan",
+               resource=host_name, parameters={"host_name": host_name}, result=result)
+    console.print(result)
+
+
+# ---------------------------------------------------------------------------
+# vSAN commands
+# ---------------------------------------------------------------------------
+
+vsan_app = typer.Typer(help="vSAN health and capacity monitoring.")
+app.add_typer(vsan_app, name="vsan")
+
+
+@vsan_app.command("health")
+def vsan_health_cmd(
+    cluster_name: str = typer.Argument(help="Cluster name"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Get vSAN cluster health summary."""
+    from vmware_storage.ops.vsan import get_vsan_health
+    si = _get_connection(target, config)
+    _print_json(get_vsan_health(si, cluster_name))
+
+
+@vsan_app.command("capacity")
+def vsan_capacity_cmd(
+    cluster_name: str = typer.Argument(help="Cluster name"),
+    target: str | None = typer.Option(None, help="Target name"),
+    config: str | None = typer.Option(None, "--config", help="Config file path"),
+) -> None:
+    """Get vSAN capacity overview."""
+    from vmware_storage.ops.vsan import get_vsan_capacity
+    si = _get_connection(target, config)
+    _print_json(get_vsan_capacity(si, cluster_name))
+
+
+# ---------------------------------------------------------------------------
+# Doctor
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def doctor(
+    skip_auth: bool = typer.Option(False, "--skip-auth", help="Skip auth check"),
+) -> None:
+    """Run environment diagnostics."""
+    from vmware_storage.doctor import run_doctor
+    sys.exit(run_doctor(skip_auth=skip_auth))

vmware_storage/config.py

@@ -0,0 +1,133 @@
+"""Configuration management for VMware Storage.
+
+Loads targets and settings from YAML config file + environment variables.
+Passwords are NEVER stored in config files — always via environment variables.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from dotenv import load_dotenv
+
+CONFIG_DIR = Path.home() / ".vmware-storage"
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+ENV_FILE = CONFIG_DIR / ".env"
+
+_log = logging.getLogger("vmware-storage.config")
+
+# Load passwords from .env file (if exists) before any config access
+load_dotenv(ENV_FILE)
+
+
+def _check_env_permissions() -> None:
+    """Warn if .env file has permissions wider than owner-only (600)."""
+    if not ENV_FILE.exists():
+        return
+    try:
+        mode = ENV_FILE.stat().st_mode
+        if mode & (stat.S_IRWXG | stat.S_IRWXO):
+            _log.warning(
+                "Security warning: %s has permissions %s (should be 600). "
+                "Run: chmod 600 %s",
+                ENV_FILE,
+                oct(stat.S_IMODE(mode)),
+                ENV_FILE,
+            )
+    except OSError:
+        pass
+
+
+_check_env_permissions()
+
+
+@dataclass(frozen=True)
+class TargetConfig:
+    """A vCenter or ESXi connection target."""
+
+    name: str
+    host: str
+    username: str
+    type: Literal["vcenter", "esxi"] = "vcenter"
+    port: int = 443
+    verify_ssl: bool = False
+
+    @property
+    def password(self) -> str:
+        env_key = f"VMWARE_{self.name.upper().replace('-', '_')}_PASSWORD"
+        pw = os.environ.get(env_key, "")
+        if not pw:
+            raise OSError(
+                f"Password not found. Set environment variable: {env_key}"
+            )
+        return pw
+
+
+@dataclass(frozen=True)
+class NotifyConfig:
+    """Notification settings."""
+
+    log_file: str = str(CONFIG_DIR / "scan.log")
+    webhook_url: str = ""
+    webhook_timeout: int = 10
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Top-level application config."""
+
+    targets: tuple[TargetConfig, ...] = ()
+    notify: NotifyConfig = field(default_factory=NotifyConfig)
+
+    def get_target(self, name: str) -> TargetConfig:
+        for t in self.targets:
+            if t.name == name:
+                return t
+        available = ", ".join(t.name for t in self.targets)
+        raise KeyError(f"Target '{name}' not found. Available: {available}")
+
+    @property
+    def default_target(self) -> TargetConfig:
+        if not self.targets:
+            raise ValueError("No targets configured. Check config.yaml")
+        return self.targets[0]
+
+
+def load_config(config_path: Path | None = None) -> AppConfig:
+    """Load config from YAML file, with env var overrides for passwords."""
+    path = config_path or CONFIG_FILE
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Config file not found: {path}\n"
+            f"Copy config.example.yaml to {CONFIG_FILE} and edit it."
+        )
+
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    targets = tuple(
+        TargetConfig(
+            name=t["name"],
+            host=t["host"],
+            username=t.get("username", "administrator@vsphere.local"),
+            type=t.get("type", "vcenter"),
+            port=t.get("port", 443),
+            verify_ssl=t.get("verify_ssl", False),
+        )
+        for t in raw.get("targets", [])
+    )
+
+    notify_raw = raw.get("notify", {})
+    notify = NotifyConfig(
+        log_file=notify_raw.get("log_file", str(CONFIG_DIR / "scan.log")),
+        webhook_url=notify_raw.get("webhook_url", ""),
+        webhook_timeout=notify_raw.get("webhook_timeout", 10),
+    )
+
+    return AppConfig(targets=targets, notify=notify)

vmware_storage/connection.py

@@ -0,0 +1,99 @@
+"""Connection management for vCenter and ESXi hosts.
+
+Handles multi-target connections via pyVmomi with session reuse.
+"""
+
+from __future__ import annotations
+
+import atexit
+import ssl
+from typing import TYPE_CHECKING
+
+from pyVmomi import vim, vmodl
+from pyVmomi.VmomiSupport import VmomiJSONEncoder  # noqa: F401
+
+if TYPE_CHECKING:
+    from pyVmomi.vim import ServiceInstance
+
+from vmware_storage.config import AppConfig, TargetConfig, load_config
+
+
+class ConnectionManager:
+    """Manages connections to multiple vCenter/ESXi targets."""
+
+    def __init__(self, config: AppConfig) -> None:
+        self._config = config
+        self._connections: dict[str, ServiceInstance] = {}
+
+    @classmethod
+    def from_config(cls, config: AppConfig | None = None) -> ConnectionManager:
+        cfg = config or load_config()
+        return cls(cfg)
+
+    def connect(self, target_name: str | None = None) -> ServiceInstance:
+        """Connect to a target by name, or the default target."""
+        target = (
+            self._config.get_target(target_name)
+            if target_name
+            else self._config.default_target
+        )
+
+        if target.name in self._connections:
+            si = self._connections[target.name]
+            try:
+                _ = si.content.sessionManager.currentSession
+                return si
+            except (vmodl.fault.NotAuthenticated, Exception):
+                del self._connections[target.name]
+
+        si = self._create_connection(target)
+        self._connections[target.name] = si
+        return si
+
+    def disconnect(self, target_name: str) -> None:
+        """Disconnect from a specific target."""
+        if target_name in self._connections:
+            from pyVim.connect import Disconnect
+
+            Disconnect(self._connections[target_name])
+            del self._connections[target_name]
+
+    def disconnect_all(self) -> None:
+        """Disconnect from all targets."""
+        for name in list(self._connections):
+            self.disconnect(name)
+
+    def list_targets(self) -> list[str]:
+        """List all configured target names."""
+        return [t.name for t in self._config.targets]
+
+    def list_connected(self) -> list[str]:
+        """List currently connected target names."""
+        return list(self._connections.keys())
+
+    @staticmethod
+    def _create_connection(target: TargetConfig) -> ServiceInstance:
+        """Create a new pyVmomi connection."""
+        from pyVim.connect import Disconnect, SmartConnect
+
+        context = None
+        if not target.verify_ssl:
+            context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+            context.check_hostname = False
+            context.verify_mode = ssl.CERT_NONE
+
+        si = SmartConnect(
+            host=target.host,
+            user=target.username,
+            pwd=target.password,
+            port=target.port,
+            sslContext=context,
+            disableSslCertValidation=not target.verify_ssl,
+        )
+        atexit.register(Disconnect, si)
+        return si
+
+
+def get_content(si: ServiceInstance) -> vim.ServiceInstanceContent:
+    """Shortcut to get ServiceContent from a ServiceInstance."""
+    return si.RetrieveContent()

vmware_storage/doctor.py

@@ -0,0 +1,151 @@
+"""vmware-storage doctor — environment and connectivity diagnostics."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import stat
+from pathlib import Path
+from typing import Callable
+
+from rich.console import Console
+from rich.table import Table
+
+from vmware_storage.config import CONFIG_DIR, CONFIG_FILE, ENV_FILE
+
+console = Console()
+
+_PASS = "[green]\u2713[/]"
+_FAIL = "[red]\u2717[/]"
+_INFO = "[cyan]i[/]"
+
+
+def _check(label: str, fn: Callable[[], tuple[bool, str]]) -> tuple[bool, str, str]:
+    try:
+        ok, msg = fn()
+        return ok, label, msg
+    except Exception as e:
+        return False, label, f"Error: {e}"
+
+
+def _check_config_file() -> tuple[bool, str]:
+    if CONFIG_FILE.exists():
+        return True, f"Config found: {CONFIG_FILE}"
+    return False, f"Config not found: {CONFIG_FILE}"
+
+
+def _check_env_file() -> tuple[bool, str]:
+    if not ENV_FILE.exists():
+        return False, f".env not found: {ENV_FILE}"
+    mode = ENV_FILE.stat().st_mode
+    if mode & (stat.S_IRWXG | stat.S_IRWXO):
+        return False, f".env permissions too open ({oct(stat.S_IMODE(mode))}) — Run: chmod 600 {ENV_FILE}"
+    return True, f".env found with correct permissions (600): {ENV_FILE}"
+
+
+def _check_targets() -> tuple[bool, str]:
+    if not CONFIG_FILE.exists():
+        return False, "Config file missing"
+    import yaml
+    with open(CONFIG_FILE) as f:
+        raw = yaml.safe_load(f) or {}
+    targets = raw.get("targets", [])
+    if not targets:
+        return False, "No targets configured in config.yaml"
+    names = [t.get("name", "?") for t in targets]
+    return True, f"{len(targets)} target(s) configured: {', '.join(names)}"
+
+
+def _check_connectivity() -> tuple[bool, str]:
+    if not CONFIG_FILE.exists():
+        return False, "Config file missing"
+    import yaml
+    with open(CONFIG_FILE) as f:
+        raw = yaml.safe_load(f) or {}
+    targets = raw.get("targets", [])
+    if not targets:
+        return False, "No targets to check"
+
+    results = []
+    all_ok = True
+    for t in targets:
+        host = t.get("host", "")
+        port = t.get("port", 443)
+        try:
+            sock = socket.create_connection((host, port), timeout=5)
+            sock.close()
+            results.append(f"{host}:{port} \u2713")
+        except OSError as e:
+            results.append(f"{host}:{port} \u2717 ({e})")
+            all_ok = False
+    return all_ok, "  ".join(results)
+
+
+def _check_auth() -> tuple[bool, str]:
+    if not CONFIG_FILE.exists():
+        return False, "Config file missing"
+    try:
+        from vmware_storage.config import load_config
+        from vmware_storage.connection import ConnectionManager
+        config = load_config()
+        if not config.targets:
+            return False, "No targets configured"
+        conn_mgr = ConnectionManager(config)
+        target = config.default_target
+        conn_mgr.connect(target.name)
+        conn_mgr.disconnect_all()
+        return True, f"Authentication OK for target '{target.name}'"
+    except KeyError as e:
+        return False, f"Missing password env var: {e}"
+    except Exception as e:
+        return False, f"Auth failed: {e}"
+
+
+def _check_mcp_server() -> tuple[bool, str]:
+    try:
+        import importlib
+        importlib.import_module("mcp_server.server")
+        return True, "MCP server module loads OK"
+    except ImportError as e:
+        return False, f"MCP server import failed: {e}"
+
+
+_CHECKS: list[tuple[str, Callable[[], tuple[bool, str]]]] = [
+    ("Config file", _check_config_file),
+    (".env file", _check_env_file),
+    ("Targets configured", _check_targets),
+    ("Network connectivity", _check_connectivity),
+    ("vSphere authentication", _check_auth),
+    ("MCP server", _check_mcp_server),
+]
+
+
+def run_doctor(skip_auth: bool = False) -> int:
+    """Run all checks and print results. Returns exit code (0 = all pass)."""
+    console.print("\n[bold]vmware-storage doctor[/]\n")
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("", width=3)
+    table.add_column("Check", style="bold", min_width=25)
+    table.add_column("Result")
+
+    failures = 0
+    for label, fn in _CHECKS:
+        if skip_auth and label == "vSphere authentication":
+            table.add_row(_INFO, label, "[dim]skipped (--skip-auth)[/]")
+            continue
+        ok, lbl, msg = _check(label, fn)
+        icon = _PASS if ok else _FAIL
+        if not ok:
+            failures += 1
+        table.add_row(icon, lbl, msg)
+
+    console.print(table)
+
+    if failures == 0:
+        console.print("\n[green bold]\u2713 All checks passed.[/]\n")
+    else:
+        console.print(f"\n[red bold]\u2717 {failures} check(s) failed.[/]\n")
+
+    return 0 if failures == 0 else 1