VMware AIops

[WRITE] Create an execution plan for multi-step VM operations. Use for 2+ steps or 2+ VMs. Validates actions, checks the targets exist in vSphere, and generates a plan with rollback info per step. Each operation is a dict with "action" key plus action-specific params. Allowed actions: power_on, power_off, reset, suspend, create_vm, delete_vm, reconfigure, create_snapshot, delete_snapshot, revert_snapshot, clone, migrate, deploy_ova, deploy_template, linked_clone, attach_iso, convert_to_template. Returns plan dict with plan_id, steps, summary (vms_affected, irreversible_steps, rollback_available). Show to user for confirmation before calling vm_apply_plan. Args: operations: List of operation dicts, each with "action" + params. target: Optional vCenter/ESXi target name from config.

[WRITE] Execute a previously created plan step by step. Without confirm=True this only previews: it returns blast_radius listing every step (index, action, target object), the count and indices of the destructive ones (delete, power off, revert, guest commands...), and blockers — and runs nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Each step is shown with its full parameters (passwords redacted). Each destructive step is measured as its own tool would measure it (vm_delete, vm_power_off, vm_revert_snapshot, vm_guest_exec, cluster_delete ...), and that tool's blockers refuse the plan. A step on something an earlier step creates or changes is marked check "deferred": it is measured immediately before it runs, and the plan stops there if it fails. Refused: a target other than the one the plan was created against (no target is a target of its own), a step its tool would refuse, anything it could not read, a delete_vm step without its acknowledge_blast_radius (from a vm_delete preview), and any iscsi_* or storage_rescan step — those are gated in vmware-storage; run storage_iscsi_* / storage_rescan there. With confirm=True steps run sequentially. On failure: stops immediately, keeps the plan file with per-step results, and returns rollback_available. On success: deletes the plan file. If a step fails and rollback_available is true, ask the user whether to rollback, then call vm_rollback_plan. Args: plan_id: The plan ID returned by vm_create_plan. confirm: False (default) returns the blast radius and changes nothing. True applies it. target: The vCenter/ESXi target the plan was created against.

[WRITE] Rollback executed steps of a failed plan in reverse order. Without confirm=True this only previews: it returns blast_radius listing the rollback steps that would run (in order, with the VMs a rollback deletes) and those skipped as irreversible — and runs nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Only call this after vm_apply_plan returns status='failed'; check vm_list_plans first for the plan_id. Irreversible steps (delete_vm, revert_snapshot, etc.) are skipped with a warning. Each destructive rollback step (power off, delete snapshot, cluster delete, host removal) is measured as its own tool measures it, in the preview and again just before it runs; a refused check stops the rollback there and the plan stays 'failed'. Refused on a target other than the one the plan was created against. Args: plan_id: The plan ID of the failed plan. confirm: False (default) returns the blast radius and changes nothing. True applies it. target: The vCenter/ESXi target the plan was created against.

[READ] List all pending/failed plans. Use this first to find a plan_id for vm_apply_plan or vm_rollback_plan. Returns the list envelope: 'items' holds plan summaries (plan_id, created_at, status, steps count, VMs affected), and 'returned'/'total'/ 'truncated' state whether the listing is complete. Every plan file is read, so truncated is always false. Listing never deletes: stale plans (>24h) are swept by vm_create_plan, not by this tool.

[WRITE] Create a new VM by importing a local .ova file (OVF parse + VMDK upload). Use for local OVA files; for vSphere templates use deploy_vm_from_template, to copy an existing VM vm_clone. Returns a status string naming the new VM. Upload time scales with OVA size; fails before creating anything if the datastore is not found. Args: ova_path: Local path to the .ova file (must be readable by this server). vm_name: Name for the new VM; must not already exist. datastore_name: Target datastore (see browse_datastore). network_name: Port group for the NICs (default "VM Network"). folder_path: vCenter folder path; omit for the datacenter root. power_on: Power the VM on after import (default False). snapshot_name: If set, snapshots the new VM with this name. target: vCenter/ESXi target from config.yaml; omit for the default.

[WRITE] Deploy a new VM by cloning from a vSphere template. Returns a status string. Use for VMs marked as templates; for a running source VM use vm_clone. Requires an existing template — convert_vm_to_template makes one. Args: template_name: Source vSphere template name. new_name: Name for the new VM. datastore_name: Target datastore (template's own if omitted). cpu: Override CPU count (optional). memory_mb: Override memory in MB (optional). power_on: Power on after deployment. snapshot_name: Snapshot the new VM with this name. target: Optional vCenter/ESXi target from config.

[WRITE] Create a linked clone from a VM snapshot — near-instant, minimal disk usage. The clone writes to a copy-on-write delta over the source's base disk, so it depends on the source staying intact. Fastest provisioning for test/dev fleets; use vm_clone for fully independent copies. Requires the named snapshot — run vm_list_snapshots first. Returns a status string with the new clone name. Args: source_vm_name: Source VM name (must have at least one snapshot). snapshot_name: Clone base (from vm_list_snapshots). new_name: Name for the new linked clone; must not already exist. cpu: Override vCPU count; omit to keep the source's value. memory_mb: Override memory in MB; omit to keep the source's value. power_on: Power the clone on after creation (default False). baseline_snapshot: If set, snapshots the new clone with this name. target: vCenter/ESXi target from config.yaml; omit for the default.

[WRITE] Mount a datastore ISO into a VM's virtual CD-ROM drive. Reconfigures the existing CD-ROM (replacing any mounted ISO) or adds one on the VM's IDE controller; fails with a clear message if the VM has no IDE controller. Works whether the VM is powered on or off. Find ISO paths first with browse_datastore using pattern "*.iso". Returns a status string confirming attachment, or a VM-not-found / no-IDE-controller error. Args: vm_name: Exact VM name as shown in vCenter inventory. iso_ds_path: Datastore path in bracket format, e.g. "[datastore1] iso/ubuntu-22.04.iso". target: vCenter/ESXi target from config.yaml; omit for the default target.

[WRITE] Convert a powered-off VM to a vSphere template. Returns a status string. Use this to freeze a golden image: afterwards the VM cannot be powered on and serves only as a clone source for deploy_vm_from_template. Args: vm_name: Name of the VM to convert (must be powered off). target: Optional vCenter/ESXi target name from config.

[WRITE] Batch clone multiple VMs from a source VM (gold image). Each clone: full copy → optional reconfigure → optional snapshot → optional power on. Returns one dict per VM with its status. Clones run sequentially, so a long vm_names list may take a while — prefer batch_linked_clone_vms for disposable test copies. Args: source_vm_name: Source VM to clone from. vm_names: Names for the new VMs. cpu: Override CPU count for all clones (optional). memory_mb: Override memory for all clones (optional). snapshot_name: Snapshot each clone with this name (optional). power_on: Power on each clone after creation. target: Optional vCenter/ESXi target name from config.

[WRITE] Batch create linked clones from a VM snapshot (fastest batch provisioning). Clones share the source disk via copy-on-write, so the source must stay intact. Returns one dict per clone. Prefer batch_clone_vms for independent copies. Args: source_vm_name: Source VM to clone from. snapshot_name: Clone base (from vm_list_snapshots). vm_names: Names for the new linked clones. cpu: Override CPU count (optional). memory_mb: Override memory (optional). power_on: Power on each clone. baseline_snapshot: Snapshot each clone with this name (optional). target: Optional vCenter/ESXi target from config.

[WRITE] Deploy multiple VMs in one call from a declarative YAML spec file. Use for fleet provisioning (several VMs, shared defaults); for a single VM prefer deploy_vm_from_template, vm_clone, deploy_vm_from_ova, or deploy_linked_clone. The channel is chosen by spec keys: "source" (full clone), "template", "linked_clone: {source, snapshot}", per-VM "ova", else empty-VM creation (optionally "iso"). A "defaults" block sets cpu/memory_mb/disk_gb/network/ datastore/snapshot/power_on, overridable per VM. VMs deploy sequentially and one VM's failure does not stop the rest. Args: spec_path: Local filesystem path to the deploy.yaml specification file. target: vCenter/ESXi target name from config.yaml; omit to use the default target. Returns: One dict per VM: name, status ("ok" or "error"), and messages with per-step results.

[READ] Browse files in a vSphere datastore directory. Use this to find OVA/ISO/VMDK paths before calling deploy_vm_from_ova or attach_iso_to_vm; for an estate-wide image sweep use scan_datastore_images. Returns the list envelope: 'items' is one row per file, and 'returned'/'total'/'truncated' state completeness. Every match in the searched folders is returned, so truncated is always false. Args: datastore_name: Name of the datastore to browse. path: Subdirectory path (empty string for root). pattern: Glob pattern to filter files (e.g. "*.ova", "*.iso", "*"). target: Optional vCenter/ESXi target name from config.

[READ] Scan all accessible datastores for deployable images (OVA/ISO/OVF/VMDK). Returns the images found and refreshes the cache at ~/.vmware-aiops/image_registry.json. Use this when you do not know which datastore holds an image; prefer browse_datastore once you do, because this walks every datastore and may take minutes on a large estate. Args: target: Optional vCenter/ESXi target name from config. Returns: The family list envelope {items, returned, limit, total, truncated, hint} plus `last_scan`; each item is one image. `images` is kept as a deprecated alias for `items`.

[WRITE] Set a Time-To-Live (TTL) for a VM. The daemon auto-deletes it when expired. Without confirm=True this only previews: it returns blast_radius — the VM that will be deleted (identity, host, disks, total size, snapshot count), when (expires_at), and any TTL it replaces — and schedules nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused when the VM's identity or disks cannot be read. Use this for short-lived lab VMs so cleanup is not forgotten; cancel with vm_cancel_ttl and review pending expiries with vm_list_ttl. The scheduler daemon must be running (`vmware-aiops daemon start`) or nothing is ever deleted; it powers a running VM off first. TTLs persist in ~/.vmware-aiops/ttl.json. Returns a dict (action, blast_radius). Args: vm_name: Name of the VM to auto-delete. minutes: Minutes until deletion (minimum 1). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter/ESXi target name from config.

[WRITE] Cancel an existing TTL for a VM (prevents auto-deletion). Returns a status string. Use vm_list_ttl first for the exact vm_name. This only removes the schedule and never touches the VM itself. Args: vm_name: Name of the VM whose TTL should be cancelled.

[READ] List all VMs with TTLs registered, including expiry time and status. Use this first to find the exact vm_name for vm_cancel_ttl. Returns the list envelope: 'items' holds TTL entries with remaining_minutes and expired flag, and 'returned'/'total'/'truncated' state whether the listing is complete. The whole TTL store is read, so truncated is always false.

[WRITE] Revert a VM to its baseline snapshot (Clean Slate). Without confirm=True this only previews: it returns blast_radius (VM identity, power state and whether it is powered off first, the snapshot and when it was taken, snapshot count, blockers) and changes nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. With confirm=True: powers off the VM first if it is running, then reverts to the named snapshot. Use this to reset a lab/dev VM to a clean starting state after a task completes. Irreversible — everything written since the snapshot is lost. Refused: no snapshot of that name, more than one, or a VM whose state cannot be read. Returns a dict (action, blast_radius). Args: vm_name: Name of the VM to revert. snapshot_name: Snapshot name to revert to (default: "baseline"). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter/ESXi target name from config.

[READ] One-glance health rollup for every cluster — "is anything on fire?". Aggregates hosts, VM power state, live CPU/memory pressure, triggered alarms and datastores thin-provisioned past 100% of capacity per cluster, assigns each a status ("ok"/"warn"/"critical"), and flattens the anomalies into a ranked ``top_issues`` focus list — the fast triage view for "what's wrong right now?". Read-only (delegates to the vmware-monitor library). Use it FIRST for a cross-cluster glance, then drill in with vm_investigation_bundle or host_investigation_bundle. Returns {totals, top_issues, issues_total, clusters, snapshot, customization_hint}. Lead with ``top_issues`` (worst first, each with a drill-down hint), ``clusters`` as context, ``customization_hint`` last. Point-in-time — no trending. Args: target: Optional vCenter/ESXi target name from config. Uses default if omitted. cluster_filter: Case-insensitive substring to show only matching clusters. include_vms: Roll up VM power counts (default True). False skips the VM pass on very large fleets. top_n: Cap the top_issues focus list (default 10; 0 hides it).

[READ] "What is happening around this VM?" — one correlated drill-down. Correlates everything around one VM so you don't stitch it together yourself: the VM's state, its host, cluster context, backing datastores, snapshots, triggered alarms, live performance, and a merged **event timeline** across VM, host, cluster and datastores (newest first). Batched, cheap even on large fleets. Delegates to the vmware-monitor library (read-only). Explain the result in operational language; do not dump it raw. Use this AFTER cluster_health_summary points at a problem VM. Point-in-time. Args: vm_name: Exact VM name. Unknown names return a teaching error (list VMs first). target: Optional vCenter/ESXi target name from config (default if omitted). hours: Event-timeline look-back window in hours (default 24).

[READ] "What is happening around this ESXi host?" — one correlated drill-down. Correlates a host's state (connection, CPU/memory, ESXi version, uptime), its cluster context, a rollup of the VMs it runs, the datastores it mounts, alarms across host/cluster/datastore, live performance, and a merged **event timeline**. Delegates to the vmware-monitor library (read-only); do not dump the result raw. Use this AFTER cluster_health_summary flags a host. Point-in-time. Args: host_name: Exact host name. Unknown names return a teaching error. target: Optional vCenter/ESXi target name from config (default if omitted). hours: Event-timeline look-back window in hours (default 24).

[READ] "What is happening around this datastore?" — one correlated drill-down. Correlates a datastore's capacity/free space/accessibility, the hosts that mount it, a rollup of the VMs it backs, alarms across datastore/host, and a merged **event timeline**. Delegates to the vmware-monitor library (read-only); do not dump the result raw. (Per-datastore latency is a separate perf report.) Use this AFTER cluster_health_summary flags storage pressure. Point-in-time. Args: datastore_name: Exact datastore name. Unknown names return a teaching error. target: Optional vCenter/ESXi target name from config (default if omitted). hours: Event-timeline look-back window in hours (default 24).

[READ] "What needs attention now?" across EVERY configured vCenter — one list. Runs cluster_health_summary against every configured target and returns one globally ranked ``top_issues`` list (worst first, each tagged with its ``vcenter``) plus a per-target rollup — "where do I look first, anywhere in the estate?". Degrades gracefully: an unreachable target is listed under ``unreachable`` and the rest still aggregate. Delegates to the vmware-monitor library (read-only). Lead with ``top_issues``, then drill in with vm_investigation_bundle. Point-in-time. Args: cluster_filter: Case-insensitive cluster substring applied to every target. top_n: Cap the merged top_issues focus list (default 10).

[WRITE] Execute a command inside a VM via VMware Tools. Requires VMware Tools running in the guest OS. Returns exit_code, stdout, stderr, timed_out, and blast_radius. Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account, the exact command, arguments and working directory, VMware Tools status and any blockers; nothing runs. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, an identity or status that cannot be read, or a name that matches more than one VM. Note: the Guest Ops API does not capture stdout/stderr directly, so use this only for fire-and-forget commands — prefer vm_guest_exec_output whenever you need the output. Args: vm_name: Target VM name. command: Full path to program (e.g. "/bin/bash", "C:\Windows\System32\cmd.exe"). arguments: Command arguments (e.g. "-c 'whoami'"). username: Guest OS account to run as. Required — there is no default, so a call can never act as root without choosing root. password: Guest OS password. working_directory: Working directory inside guest (optional). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter/ESXi target name from config.

[WRITE] Execute a shell command inside a VM and capture stdout + stderr. Automatically detects guest OS (Linux/Windows) and selects the correct shell. Output is captured by redirecting to a temp file, downloading it, then cleaning up — no manual redirection needed. Prefer this over vm_guest_exec whenever you need the output. Requires VMware Tools running and a writable temp directory in the guest. Returns exit_code, stdout, stderr, timed_out, os_family, and blast_radius. Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account, the exact command and the shell it runs through, VMware Tools status and any blockers; nothing runs. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, an unreadable identity or status, or a name that matches more than one VM. Args: vm_name: Target VM name. command: Shell command (e.g. "df -h", "ls /etc", "ipconfig"). username: Guest OS account to run as. Required — there is no default, so a call can never act as root without choosing root. password: Guest OS password. timeout: Max wait seconds (default 300). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter/ESXi target name from config.

[WRITE] Upload a file from local machine to a VM via VMware Tools. Returns a dict with action, message and blast_radius (a status string before the confirmation gate). Requires VMware Tools running in the guest OS. An existing file at guest_path is replaced. Use vm_guest_download for the reverse direction, and vm_guest_provision instead when uploads and commands belong to one ordered provisioning run. Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account, the local path and size, the guest path, VMware Tools status and any blockers; nothing is transferred. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, a local file that is missing or unreadable, an unreadable identity or status, or a name that matches more than one VM. Args: vm_name: Target VM name. local_path: Local file path to upload. guest_path: Destination path inside the guest. username: Guest OS account to run as. Required — there is no default, so a call can never act as root without choosing root. password: Guest OS password. confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter/ESXi target name from config.

[WRITE] Download a file from a VM and write it to a local path. Reads from the guest, writes the local filesystem — the write is why this is not a read tool. Returns a status string. Requires VMware Tools running in the guest OS. Use vm_guest_upload for the reverse direction; to capture command output use vm_guest_exec_output instead — it redirects and downloads for you. Refuses a destination that already exists unless overwrite=True, and never writes through a symlink or over a directory. Pick a path that does not exist yet rather than passing overwrite=True by default. Args: vm_name: Target VM name. guest_path: File path inside the guest to download. local_path: Local destination path, including the file name. username: Guest OS account to run as. Required — there is no default, so a call can never act as root without choosing root. password: Guest OS password. overwrite: True replaces an existing file at local_path (default False). target: Optional vCenter/ESXi target name from config.

[WRITE] Provision a VM by running an ordered sequence of guest operations. Prefer this over repeated vm_guest_exec / vm_guest_upload calls when the steps form one provisioning run. Steps stop on the first failure, so a partial run leaves the guest half-configured. Requires VMware Tools running in the guest. Without confirm=True this only previews: blast_radius names the VM (name, instance UUID), the guest account and every step it would run, in order, with counts per type, local file sizes and any blockers; nothing runs. Show it to the user. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused outright: VM not powered on, VMware Tools not running, an empty step list, a step with an unknown type or a missing key, an upload whose local file is missing or unreadable, a service step on a Windows guest, an unreadable identity or status, or a name that matches more than one VM. Step types: - exec: {"type": "exec", "command": "apt-get install -y nginx"} - upload: {"type": "upload", "local_path": "...", "guest_path": "..."} - service: {"type": "service", "name": "nginx", "action": "start"} Args: vm_name: Target VM name. username: Guest OS username. password: Guest OS password. steps: Ordered list of step dicts (see Step types). timeout: Per-step timeout in seconds (default 300). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter/ESXi target name from config. Returns: dict with success, completed_steps, total_steps, results, error, and blast_radius.

[WRITE] Create a new empty cluster in a datacenter, optionally enabling HA and DRS. Fails with a clear error (no partial state) if the name already exists or drs_behavior is invalid. Then add hosts with cluster_add_host, change HA/DRS later with cluster_configure, and verify with cluster_info. Returns a status string naming the features enabled. Args: name: Name for the new cluster; must be unique in the datacenter. datacenter: Datacenter name; omit for the first one on the target. ha: True enables vSphere HA (default False). drs: True enables DRS (default False). drs_behavior: "fullyAutomated" (default), "partiallyAutomated", or "manual". Only takes effect when drs=True. target: vCenter target from config.yaml; omit for the default target.

[WRITE] Delete an empty cluster (no hosts must remain). Without confirm=True this only previews: it returns blast_radius (cluster name and id, host/VM/datastore counts and names, blockers) and deletes nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused: a cluster that still has hosts or VMs (evacuate members with cluster_remove_host first), or one whose members could not be read. Check cluster_info first. Returns a dict (action, blast_radius). Args: name: Name of the cluster to delete. confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter target name from config.

[WRITE] Move an ESXi host that vCenter already manages into a cluster. The host must already be in vCenter inventory (standalone or in another cluster) — this does NOT register brand-new hosts and takes no host credentials; use the vCenter UI for first-time registration. Idempotent: a host already in the cluster returns success without change. Maintenance mode is not required to join (it IS required by cluster_remove_host). Check membership first with cluster_info. Returns a status string: moved, already-in-cluster, or a not-found error. Args: cluster_name: Destination cluster (create with cluster_create). host_name: Host name as shown in vCenter inventory, usually the FQDN, e.g. "esxi-01.lab.local". target: vCenter target from config.yaml; omit for the default target.

[WRITE] Remove a host from a cluster (host must be in maintenance mode). Without confirm=True this only previews: it returns blast_radius (host name and id, maintenance mode, VM count, powered-on VM count, blockers) and moves nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused: a host not in maintenance mode, a host with powered-on VMs, and a host whose state could not be read. Run cluster_info first for the exact member host names. The host is not deleted — it stays in vCenter inventory standalone; use cluster_add_host to move it back. Returns a dict. Args: cluster_name: Cluster to remove the host from. host_name: ESXi host name to remove (from cluster_info output). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: Optional vCenter target name from config.

[WRITE] Reconfigure cluster HA/DRS settings. Returns a status string naming what changed. Pass only the fields to change; None leaves a setting untouched — then verify with cluster_info. drs_behavior applies only when DRS is enabled. Args: name: Cluster name. ha: Enable (True) or disable (False) HA, or None to leave unchanged. drs: Enable (True) or disable (False) DRS, or None to leave unchanged. drs_behavior: DRS behavior: "fullyAutomated", "partiallyAutomated", or "manual". target: Optional vCenter target name from config.

[READ] Get detailed cluster information: member hosts, HA/DRS config, resource capacity. Read-only, no side effects. Use before cluster_add_host / cluster_remove_host (shows membership and per-host maintenance mode) and to verify cluster_configure changes. Args: name: Exact cluster name. target: vCenter target name from config.yaml; omit to use the default target. Returns: Dict with name, host_count, hosts (each: name, connection_state, power_state, maintenance_mode), ha_enabled, ha_admission_control, drs_enabled, drs_behavior, total/effective CPU (MHz) and memory (GB). Errors return a dict with "error" + hint.

[READ] List a cluster's DRS rules: VM-VM affinity/anti-affinity and VM-Host. Per rule: key, name, type (affinity / antiAffinity / vmHost), enabled, mandatory, and the member VM names (VM-VM) or group names (VM-Host). The verify pair for create/delete/set_drs_rule_enabled. Args: cluster: Exact cluster name. target: vCenter target name from config.yaml; omit to use the default target. Returns: Dict with cluster, count, and rules sorted by name. Errors return a dict with "error" + hint.

[WRITE] Enable or disable an existing DRS rule - preview/confirm gated. The day-2 toggle: anti-affinity rules often must be disabled while a cluster is temporarily too small to satisfy them, then re-enabled when hosts return. Idempotent - matching state returns a noop, no write. Names are matched exactly; ambiguous names refuse. Audited. Args: cluster: Exact cluster name. rule_name: Exact rule name (see list_drs_rules). enabled: True enables the rule; False disables it. confirm: False (default) returns the blast radius and changes nothing. True applies it. Do not set True because the user asked earlier; they have not seen the preview yet. target: vCenter target name from config.yaml; omit to use the default target. Returns: Preview dict (action="preview"), noop dict (action="noop"), or result dict (action="set", rule_now). Errors return "error" + hint.

[WRITE] Create a VM-VM DRS rule (affinity or anti-affinity) - preview/confirm gated. rule_type "affinity" keeps the listed VMs together; "antiAffinity" keeps them apart (e.g. redundant appliance pairs on separate hosts). Requires >=2 distinct VMs, all members of the cluster. VM-Host rules hang off cluster VM/host groups and are not created here. Verify with list_drs_rules. Audited. Args: cluster: Exact cluster name. rule_name: Name for the new rule; must be unique on the cluster. rule_type: "affinity" or "antiAffinity". vm_names: VM names the rule governs (>=2, all in the cluster). enabled: Create the rule enabled (default) or disabled. confirm: False (default) returns the blast radius and changes nothing. True creates it. Do not set True because the user asked earlier; they have not seen the preview yet. target: vCenter target name from config.yaml; omit to use the default target. Returns: Preview dict (action="preview", would_create) or result dict (action="created", created incl. the assigned key). Errors return a dict with "error" + hint.

[WRITE] Delete a VM-VM DRS rule - confirm-gated, guarded. REFUSES non-VM-VM rules: VM-Host rules can carry licensing/compliance placement constraints (must-run-on licensed hosts) and hang off cluster groups - manage those in the vSphere UI. The preview and result both record the full rule definition so a mistaken delete can be recreated from the audit trail. Audited. Args: cluster: Exact cluster name. rule_name: Exact rule name (see list_drs_rules). confirm: False (default) returns the blast radius and changes nothing. True deletes it. Do not set True because the user asked earlier; they have not seen the preview yet. target: vCenter target name from config.yaml; omit to use the default target. Returns: Preview dict (action="preview", would_delete) or result dict (action="deleted", deleted). Errors return a dict with "error" + hint.

[WRITE] Power on a virtual machine. Returns a status string; an already-on VM is a no-op. Reverse with vm_power_off. Call this first when a VM is off: guest tools such as vm_guest_exec only work once VMware Tools has finished booting. Args: vm_name: Exact name of the virtual machine. target: Optional vCenter/ESXi target name from config. Uses default if omitted.

[WRITE] Power off a VM — graceful guest shutdown by default, hard power-off with force=True. Without confirm=True this only previews: it returns blast_radius (VM name and instance UUID, host, power state, VMware Tools status, and whether this is a guest shutdown or a hard power-off) and changes nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Graceful mode calls VMware Tools guest shutdown and waits up to 120s; if it does not finish, action is "still_running". Refused: a graceful shutdown when Tools is not running or the VM is suspended (preview force=True instead), and a VM whose identity or power state cannot be read. An already-off VM returns action "noop". Use vm_power_on to start a VM; vm_delete requires it off first. Args: vm_name: Exact VM name as shown in vCenter inventory (case-sensitive). force: False (default) = graceful guest shutdown via VMware Tools; True = immediate hard power-off (risks guest filesystem damage). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: vCenter/ESXi target from config.yaml; omit for the default target. Returns: Dict with action (preview, noop, powered_off, still_running), blast_radius, and the executor's message under result.

[WRITE] Create a new empty VM with the given hardware sizing. Creates a powered-off VM with one disk and one NIC. To populate it, attach an ISO (attach_iso_to_vm) and power it on, or use deploy_vm_from_ova or vm_clone for a ready-to-run guest. Fails before creating anything if the datastore is not found. Returns a status string with the new VM name. Args: vm_name: Name for the new VM; must not already exist. cpu: vCPU count (default 2). memory_mb: Memory in MB (default 4096). disk_gb: Primary disk size in GB (default 40). network_name: Port group for the NIC (default "VM Network"). datastore_name: Target datastore; omit for the first accessible one. folder_path: vCenter folder path; omit for the datacenter root. target: vCenter/ESXi target from config.yaml; omit for the default.

[WRITE] Change a VM's vCPU count and/or memory. Pass only the fields you want to change; omitted fields are left untouched. Hot-add of CPU/memory requires it to be enabled on the VM and a running guest; otherwise power the VM off first (vm_power_off). Args: vm_name: Exact name of the VM to reconfigure. cpu: New vCPU count; omit to leave unchanged. memory_mb: New memory in MB; omit to leave unchanged. target: vCenter/ESXi target name from config.yaml; omit to use the default target. Returns: Status string describing the applied change, or a VM-not-found error.

[WRITE] Clone a VM. Without to_host/to_datastore the clone lands on the source's host+datastore. Returns a status string naming the clone. Full independent copy — slow and full disk cost; prefer deploy_linked_clone for near-instant test copies and batch_clone_vms for many at once. Cloning a running VM may capture a crash-consistent disk. Args: vm_name: Source VM (or template) name. new_name: Name for the new clone. to_host: Target ESXi host name (default: source's host). to_datastore: Target datastore name (default: source's datastore). power_on: Power on the clone after creation. target: vCenter/ESXi target name from config.

[WRITE] Migrate (vMotion) a VM to another host, optionally with storage vMotion. Without confirm=True this only previews: it returns blast_radius (VM and instance UUID, source host and datastores, target host with its connection and maintenance state, target datastore, and live vMotion vs cold migration) and moves nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Refused: a target host that is not found, not connected, in maintenance mode or outside a cluster; a target datastore that is not found; a target host that does not mount the VM's datastores when to_datastore is omitted (vCenter rejects cross-host vMotion without shared storage — pass to_datastore); and anything above that cannot be read. The VM's current host with no to_datastore returns action "noop". Run cluster_info first for host names. Args: vm_name: VM to migrate. to_host: Target ESXi host name. to_datastore: Target datastore (required for cross-storage hosts). confirm: False (default) returns the blast radius and changes nothing. True applies it. target: vCenter/ESXi target name from config. Returns: Dict with action (preview, noop, migrated), blast_radius, and result.

[WRITE] Delete a VM and its disks and snapshots (irreversible). Without confirm=True this only previews: it returns blast_radius (identity, host, disks, total size, snapshot count, blockers) and destroys nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user said "delete" earlier: they have not seen what it destroys yet. To delete, call again with confirm=True and acknowledge_blast_radius set to the preview's acknowledge_with object, unchanged. The VM is re-measured first; if it changed (another snapshot, a different VM under the same name), nothing is deleted and you must preview again. Refused outright: a powered-on or suspended VM (power it off with vm_power_off first), a VM whose disks or identity cannot be read, and a name that matches more than one VM. Use vm_set_ttl instead when the VM should only expire later. Args: vm_name: Exact name of the VM to delete. confirm: False (default) previews; True deletes, with the acknowledgement. acknowledge_blast_radius: The preview's acknowledge_with object. target: vCenter/ESXi target name from config.

[WRITE] Create a snapshot of a VM. Returns a status string. Use this before a risky change so vm_revert_snapshot can undo it, then reclaim the space with vm_delete_snapshot — snapshots left for days grow delta disks and must not be treated as backups. Args: vm_name: VM to snapshot. snapshot_name: Snapshot name. description: Optional description. memory: Include memory state (heavier, allows resume). quiesce: Quiesce guest filesystem (requires running VMware Tools). target: vCenter/ESXi target name from config.

[WRITE] Revert a VM to a named snapshot (loses changes since snapshot). Without confirm=True this only previews: it returns blast_radius (VM and instance UUID, the snapshot's name, id and creation time, total snapshot count, current power state and the power state after the revert) and changes nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Irreversible — everything written since the snapshot is lost. Refused: a snapshot name that is not found, a name that matches more than one snapshot on the VM (vSphere allows duplicates; rename one first), and a VM whose snapshot tree, identity or power state cannot be read. Run vm_list_snapshots first for exact names. To reclaim space without changing state use vm_delete_snapshot. Args: vm_name: VM to revert. snapshot_name: Snapshot to revert to. confirm: False (default) returns the blast radius and changes nothing. True applies it. target: vCenter/ESXi target name from config. Returns: Dict with action (preview, reverted), blast_radius, and result.

[WRITE] Permanently delete a named snapshot, consolidating its delta disk into the parent. Without confirm=True this only previews: it returns blast_radius (VM and instance UUID, the snapshot's name, id and creation time, remove_children, how many child snapshots sit below it and how many snapshots would be removed) and deletes nothing. Show it to the user and get their decision. Do not set confirm=True on your own because the user asked earlier: they have not seen the preview yet. Frees disk space and does NOT change the VM's current state (unlike vm_revert_snapshot). Works while the VM is powered on. Refused: a snapshot name that is not found, a name that matches more than one snapshot on the VM (vSphere allows duplicates; rename one first), and a snapshot tree that cannot be read. Run vm_list_snapshots first for exact names. Consolidation is slow for old/large deltas (often minutes). By default (wait=False) this returns a task id immediately so it does not block your context — poll it with vm_task_status. Set wait=True only for small snapshots (blocks up to 30 min). Args: vm_name: Exact name of the VM owning the snapshot. snapshot_name: Exact snapshot name from vm_list_snapshots output. remove_children: False (default) = children are kept and consolidated; True = delete the entire snapshot subtree below this one as well. wait: False (default) = async, return task id at once; True = block. confirm: False (default) returns the blast radius and changes nothing. True applies it. target: vCenter/ESXi target from config.yaml; omit for the default target. Returns: Dict with action (preview, snapshot_delete_started, snapshot_deleted), blast_radius, and result (carries the task id to poll via vm_task_status).

[READ] Poll a long-running vSphere task by its id (from an async vm_delete_snapshot). Use after vm_delete_snapshot returns a task id, instead of re-running the delete. Returns state (queued/running/success/error/gone), progress percent, and the entity name. 'gone' means vCenter already garbage-collected a completed task — re-list the resource to confirm the final state. A failed task reports its fault under 'task_error'; a top-level 'error' key would mean this poll itself failed. Args: task_id: The task id string returned by an async write operation. target: vCenter/ESXi target name from config.yaml; omit to use the default target. Returns: Dict with task_id, state, progress_pct, operation, entity, and task_error/note when relevant.

[READ] List the full snapshot tree of a VM, including nested child snapshots. Read-only, no side effects. Call this before vm_revert_snapshot, vm_delete_snapshot, or deploy_linked_clone to get exact snapshot names. 'items' is empty when the VM has no snapshots. Args: vm_name: Exact VM name as shown in vCenter inventory. target: vCenter/ESXi target name from config.yaml; omit to use the default target. Returns: The list envelope. 'items' is one dict per snapshot: name, description, created, state (power state at snapshot time), level (0 = root). The whole tree is walked, so 'total' is the real count and 'truncated' is always false.

[READ] List active/triggered alarms across the vCenter inventory. Start here for alarm work: it supplies the exact entity_name/alarm_name pair that acknowledge_vcenter_alarm and reset_vcenter_alarm require. Returns the list envelope: 'items' holds severity (critical/warning/info), entity name and type, alarm name, acknowledged flag, and trigger time; 'returned'/'limit'/'total'/'truncated'/'hint' state completeness, so a limited page is never mistaken for the whole picture. 'total' is the real active-alarm count — every alarm is collected before the limit is applied. Args: target: Optional vCenter target name from config. Uses default if omitted. limit: Max number of alarms to return (None = all). Use when many alarms are active.

[WRITE] Acknowledge a triggered vCenter alarm — marks it as seen WITHOUT clearing it. This only marks the alarm; it does not clear it. The alarm stays in the active list with acknowledged=true until its condition clears or it is reset. To remove it entirely after fixing the root cause use reset_vcenter_alarm instead. Get exact entity_name and alarm_name from list_vcenter_alarms first; an unknown pair returns a not-found error. Args: entity_name: VM, ESXi host, or cluster the alarm fired on (from list_vcenter_alarms output). alarm_name: Exact alarm definition name, e.g. "Virtual machine CPU usage". target: vCenter target name from config.yaml; omit to use the default target. Returns: Dict: entity_name, alarm_name, action ("acknowledged"), acknowledged (true).

[WRITE] Clear triggered vCenter alarms back to normal state. Use this after resolving the underlying issue; to merely mark an alarm seen use acknowledge_vcenter_alarm instead. Get entity_name and alarm_name from list_vcenter_alarms first. Gotcha: vSphere has no per-alarm clear — this clears ALL triggered alarms matching the named alarm's entity type (host/VM/all) and current status (red/yellow), so confirm the blast radius with the user first. Returns a dict whose 'scope' field states exactly what was cleared. Args: entity_name: Name of the entity with the alarm (VM name, host name, or cluster name). alarm_name: Exact alarm definition name from list_vcenter_alarms output. target: Optional vCenter target name from config.

[READ] List distributed virtual portgroups, optionally scoped to one dvSwitch. Per portgroup: name, parent dvSwitch, binding type (earlyBinding / ephemeral), VLAN setting (id, trunk ranges, or pvlan), configured port count, and whether it is the switch's uplink portgroup. Use to verify create_dvs_portgroup results or to survey network config before changes. Args: dvs_name: dvSwitch name to scope to; omit to list across all switches. limit: Max portgroups to return (default 200). offset: Skip this many portgroups first (paging). target: vCenter target name from config.yaml; omit to use the default target. Returns: The family list envelope {items, returned, limit, total, truncated, hint}; each item is one portgroup. `portgroups` is kept as a deprecated alias for `items`. Errors return a dict with "error" + hint.

[WRITE] Create a VLAN-tagged portgroup on a dvSwitch - preview/confirm gated. confirm=False (default) validates everything (switch exists, name free, binding and VLAN legal) and returns the exact spec that WOULD be created without writing anything. confirm=True creates the portgroup and waits for the task. Verify afterwards with list_dvs_portgroups. Audited. binding="ephemeral" creates a portgroup with no pre-created port pool, attachable from the ESXi host client even when vCenter is down - use for a self-hosted VCSA's own management portgroup. num_ports is ignored for ephemeral. lateBinding is deprecated by vSphere and not offered. Args: name: Name for the new portgroup; must be unique on the switch. dvs_name: Name of the distributed virtual switch to create it on. vlan_id: VLAN ID to tag (0-4094; 0 = none). binding: "earlyBinding" (default) or "ephemeral". num_ports: Port count for earlyBinding portgroups (default 8). confirm: False (default) returns the blast radius and changes nothing. True creates it. Do not set True because the user asked earlier; they have not seen the preview yet. target: vCenter target name from config.yaml; omit to use the default target. Returns: Preview dict (action="preview", would_create) or result dict (action="created", created). Errors return a dict with "error" + hint.

[READ] List VMkernel adapters, optionally scoped to one ESXi host. Per vmk: device, IP/netmask/dhcp, MTU, MAC, portgroup (standard or DVS), netstack, and which host services it is selected for (management, vmotion, vsan, ...). The verify pair for add_host_vmk/remove_host_vmk. Gotcha - this list is not automatically a complete estate inventory. vCenter answers property reads for a host it has lost contact with out of its own cache, so hosts it never reached appear here as rows with `reachable: false`, `device: null` and a `note` naming the connectionState, rather than being dropped. Check `hosts_unreachable` (and the `unreachable_note` present only when it is non-zero) before reporting the result as the full picture, and do not read a null field on such a row as a measurement - it means nobody looked. Adapters shown for an unreachable host are vCenter's last cached view. Args: host_name: ESXi host name; omit to list across all hosts. limit: Max vmks to return (default 100). offset: Skip this many vmks first (paging). target: vCenter target name from config.yaml; omit to use the default target. Returns: The family list envelope {items, returned, limit, total, truncated, hint} plus `hosts_unreachable` (int) and, when that is non-zero, `unreachable_note` (str). Each item is one VMkernel adapter, or one unread host when `reachable` is false; `services` is null when a host's service map could not be read. `truncated` stays a paging fact - an incomplete estate is reported by `hosts_unreachable`, not by it. `vmks` is kept as a deprecated alias for `items`. Errors return "error" + hint.

[WRITE] Add a static-IP VMkernel adapter on a DVS portgroup - preview/confirm gated. Deliberately minimal shape for throwaway test vmks on L2-only segments (e.g. a TEP VLAN): static IPv4, NO gateway, NO services enabled. The DVS port allocation is handled internally - pass the distributed portgroup name. confirm=False validates (host + portgroup exist, IP/netmask/MTU legal, IP not already on the host) and returns the exact spec without writing; confirm=True creates and returns the assigned device name. Verify with list_host_vmks; remove with remove_host_vmk. Audited. Args: host_name: ESXi host to add the vmk on. portgroup: Distributed portgroup name to connect to. ip: Static IPv4 address for the vmk. netmask: Subnet mask (e.g. 255.255.255.0). mtu: MTU for the vmk (default 1500; 9000 for jumbo tests). confirm: False (default) returns the blast radius and changes nothing. True creates it. Do not set True because the user asked earlier; they have not seen the preview yet. target: vCenter target name from config.yaml; omit to use the default target. Returns: Preview dict (action="preview") or result dict (action="created", device=e.g. "vmk2"). Errors return a dict with "error" + hint.

[WRITE] Remove a VMkernel adapter - confirm-gated, guarded, fail-closed. REFUSES (unless force_unprotected=True) when the vmk is selected for any host service (management/vmotion/vsan/...), lives on a non-default netstack (NSX TEPs on vxlan, dedicated vmotion/provisioning stacks - never visible in the service map), carries a default gateway route, or when any of that CANNOT be verified - unverifiable is treated as unsafe, never as clear. Test vmks created by add_host_vmk trip none of these and remove cleanly without force. ABSOLUTE, no override: the host's only management-enabled vmk is never removable - this call rides the interface it would delete. force_unprotected=True (together with confirm=True) overrides the non-absolute protections for deliberate teardown; the override and every bypassed protection are recorded in the result (and the audit trail). Args: host_name: ESXi host the vmk lives on. vmk: Device name to remove (e.g. "vmk2"). confirm: False (default) returns the blast radius and changes nothing. True removes it. Do not set True because the user asked earlier; they have not seen the preview yet. force_unprotected: True bypasses the non-absolute protections above. target: vCenter target name from config.yaml; omit to use the default target. Returns: Preview dict (action="preview") or result dict (action="removed", plus forced/protections_bypassed when overridden). Errors return a dict with "error" + hint.

[WRITE] Enable/disable a host service on an existing vmk - preview/confirm gated. Completes the add_host_vmk story: adapters are created serviceless by design, then tagged here (e.g. enable "vmotion" on a new vMotion vmk). Idempotent - re-applying the current state returns a no-write noop. Verify with list_host_vmks (the services field). Audited. Valid services are the vSphere nicType names: management, vmotion, vsan, vSphereProvisioning, faultToleranceLogging, vSphereReplication, vSphereReplicationNFC, vSphereBackupNFC, ptp, and the nvme/vsan variants. Note "vSphereProvisioning", not "provisioning". FAIL CLOSED: refuses both directions when the host's service map cannot be read. ABSOLUTE, no override: disabling management on the host's only management-enabled vmk - the call rides the interface it would untag. Args: host_name: ESXi host the vmk lives on. vmk: Device name to change (e.g. "vmk3"). service: Service/nicType name to enable or disable. enabled: True selects the vmk for the service; False deselects. confirm: False (default) returns the blast radius and changes nothing. True applies it. Do not set True because the user asked earlier; they have not seen the preview yet. target: vCenter target name from config.yaml; omit to use the default target. Returns: Preview dict (action="preview"), noop dict (action="noop") when the state already matches, or result dict (action="set", services_now). Errors return a dict with "error" + hint.

[READ] DF-bit-capable ping sourced from a host vmk - MTU path validation. Runs `esxcli network diag ping` on the ESXi host through the vSphere API (no host SSH). df=True sets Don't-Fragment so an oversized packet FAILS instead of fragmenting - that failure is the diagnostic: - df=True size=1572 proves a >=1600 MTU path (overlay/TEP floor) - df=True size=8972 proves full jumbo (9000 minus 28 bytes overhead) A too-big result reports 'Message too long' in the fault field rather than erroring - read success + fault together. Args: host_name: ESXi host to source the ping from. source_vmk: VMkernel device to source from (e.g. "vmk2"). dest_ip: IPv4 address to ping. size: ICMP payload bytes (default 56). Path proves size+28 MTU. df: True sets the Don't-Fragment bit (the MTU probe mode). count: Packets to send (default 3, max 60). netstack: Optional netstack instance (e.g. "vxlan" for real TEP vmks). target: vCenter target name from config.yaml; omit to use the default target. Returns: Dict with request, success, and summary (transmitted/received/loss/ rtt) or fault (the esxcli failure text). Errors return "error" + hint.