tools.vmware_tools module

VMware ESXi / vCenter management via pyVmomi (vSphere API).

Stateless: connect per call in a worker thread, disconnect in finally. Requires UNSANDBOXED_EXEC. TLS verification off by default for self-signed infrastructure certs (trusted networks only).

Connection profiles: encrypted per-user JSON (host, user, password, port, verify_ssl).

async tools.vmware_tools.run(action='', host='', user='', password='', port=443, verify_ssl=False, vm_uuid=None, vm_name=None, snapshot_name=None, credential_profile='', ctx=None)[source]

Validate and execute one VMware vCenter/ESXi management action.

Handler for the vmware_control tool and the module’s primary entry point. It enforces the privilege gate, validates the action against _VALID_ACTIONS, resolves connection settings (optionally from a saved credential profile, with explicit kwargs overriding), checks that the required vm_uuid/vm_name is present for per-VM actions, then runs the blocking vSphere work off the event loop. Results are size-capped to _MAX_JSON_CHARS so an oversized inventory cannot overrun the response.

It calls _check_priv() (UNSANDBOXED_EXEC) for authorization; when credential_profile is set it loads the encrypted profile via _cred_load and combines it with the passed kwargs via _cred_merge (tools._credential_profile_store); and it executes _vmware_dispatch() through asyncio.to_thread so the synchronous pyVmomi session does not block the loop. Invoked by the tool dispatcher in tools/__init__.py, which calls this handler with the tool arguments and the ToolContext; there are no other internal callers.

Parameters:

  • action (str) – The action to perform; must be in _VALID_ACTIONS.

  • host (str) – vCenter/ESXi host; required unless supplied by the profile.

  • user (str) – vSphere login; required unless supplied by the profile.

  • password (str) – Password; required unless supplied by the profile.

  • port (int) – vSphere API TCP port (defaults to 443).

  • verify_ssl (bool) – Whether to verify TLS (defaults to False).

  • vm_uuid (str | None) – VM instance UUID for per-VM actions (preferred).

  • vm_name (str | None) – VM display name for per-VM actions when no UUID is given.

  • snapshot_name (str | None) – Snapshot name, required for the snapshot_* actions.

  • credential_profile (str) – Optional saved profile name; its values are used as defaults and overridden by any non-empty kwargs above.

  • ctx (Any) – The ToolContext; required for privilege check and profile loading.

Return type:

str

Returns:

A JSON string with the dispatch result, or a JSON error (no context, missing privilege, invalid action, profile load failure, missing host/user/password, missing VM identifier, or a size-limit truncation notice when the serialized result exceeds _MAX_JSON_CHARS).