VMware AIops

[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. lateBindin…

[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 clone_vm 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 …

[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_avail…

[WRITE] Create a snapshot of a VM. Returns a status string. Use this before a risky change so revert_vm_snapshot can undo it, then reclaim the space with delete_vm_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] 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 remove_cluster_host first), or one whose members could not be read. Check get_cluster_info first. Returns a dict (action, blast_radius). Args: name: Name …

[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 ask…

[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 …

[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 revert_vm_snapshot). Works while the VM is …

[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 clone_vm for fully independent copies. Requires the named snapshot — run list_vm_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 list_vm_snapshots). new_name: Name for the new linked clone; must not already exist. …

[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 clone_vm. 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 every network in the OVF is mapped to…

[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 clone_vm. 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_host: ESXi host to place…

[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 upload_vm_guest_file for the reverse direction; to capture command output use run_vm_guest_command_with_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. Ar…

[READ] The account this server uses on a target, and whether it holds a tool's privileges. When to use: a tool failed with NoPermission, or before a write you want to know the configured account may run. Ask about one ``tool`` (e.g. clone_vm), or omit it to sort every tool of this server into granted / not granted / undetermined. What it returns: {target, account, checked_on, privileges {id: state}, and either ``tool`` {name, requires, verdict, meaning, missing_at_root} or the tools_* lists}, plus the account's direct permissions (role, on, propagate). Gotchas: privileges are checked on the…

[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 investigate_vm or investigate_host. Returns {totals, top_issues, issues_total, clusters, snapsho…

[READ] Get detailed cluster information: member hosts, HA/DRS config, resource capacity. Read-only, no side effects. Use before add_cluster_host / remove_cluster_host (shows membership and per-host maintenance mode) and to verify configure_cluster 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). …

[READ] "What needs attention now?" across EVERY configured vCenter — one list. Runs get_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, but it is never counted as healthy: ``totals.worst_status`` is at least ``warn`` (``critical`` when no target answered) and ``totals.status_reason`` says why. Delegates to th…

[READ] Poll a long-running vSphere task by its id (from an async delete_vm_snapshot). Use after delete_vm_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 does not know the id: the task finished and was garbage-collected, or the id is wrong. It says nothing about success — 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 r…

[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 get_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…

[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 get_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…

[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 get_cluster_health_summary points at a problem VM. Point-in-time. Args: vm_n…

[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.

[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; om…

[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 `ho…

[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: Option…

[READ] List all pending/failed plans. Use this first to find a plan_id for apply_vm_plan or rollback_vm_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 create_vm_plan, not by this tool.

[READ] List the full snapshot tree of a VM, including nested child snapshots. Read-only, no side effects. Call this before revert_vm_snapshot, delete_vm_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, …

[READ] List all VMs with TTLs registered, including expiry time and status. Use this first to find the exact vm_name for cancel_vm_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] 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 has no resource pool; a target datastore that…

[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:…

[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 shutd…

[WRITE] Power on a virtual machine. Returns a status string; an already-on VM is a no-op. Reverse with power_off_vm. Call this first when a VM is off: guest tools such as run_vm_guest_command 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] Provision a VM by running an ordered sequence of guest operations. Prefer this over repeated run_vm_guest_command / upload_vm_guest_file 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 be…

[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 (power_off_vm). 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] 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 get_cluster_info first for the exact member host names. The host is not deleted — it stay…

[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 neve…

[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. vSphere has no per-alarm clear: this clears EVERY triggered alarm with the named alarm's status (red/yellow) on its entity type (host/VM/all), usually more than the one named. Without confirm=True this only previews: it returns blast_radius with will_clear_count and the alarms it would clear, and changes nothing. Show it to the user and get their decision; …

[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 c…

[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 snapsh…

[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 apply_vm_plan returns status='failed'; check list_vm_plans first for the plan_id. Irreversible steps (delete_vm, revert_snapshot, etc.) are skippe…

[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 can…

[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 run_vm_guest_command 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 e…

[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] 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 …

[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 cancel_vm…

[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 "provi…

[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 download_vm_guest_file for the reverse direction, and provision_vm_guest 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; …