saltext.vcf.utils.vcenter

vCenter REST API connection helpers.

Authentication uses the vCenter session API (POST /api/session), which returns a vmware-api-session-id token. The token is cached per (host, username) pair in a module-level dict so that multiple calls within the same Salt loader session do not re-authenticate on every invocation.

Config is read from Salt opts/pillar under saltext.vcf.vcenter:

saltext.vcf:
  vcenter:
    host: mgmt-vc.example.test
    username: administrator@vsphere.local
    password: secret
    verify_ssl: false
    # Optional. Default 30s; bump for long-running calls like OVF deploy.
    timeout: 1800

saltext.vcf.utils.vcenter.get_config(opts, profile=None)

Extract vCenter connection config from Salt opts/pillar.

Returns a dict with keys: host, username, password, verify_ssl, timeout.

saltext.vcf.utils.vcenter.get_session(opts, profile=None)

Return an authenticated (requests.Session, host) tuple for vCenter.

The session has the vmware-api-session-id header pre-set. The token is cached for the lifetime of the Python process; call invalidate_session() to force re-authentication.

saltext.vcf.utils.vcenter.invalidate_session(opts, profile=None)

Remove the cached session token, forcing re-authentication on next call.

saltext.vcf.utils.vcenter.api_get(opts, path, params=None, profile=None, timeout=None)

GET /api/<path> from vCenter and return parsed JSON.

timeout overrides the per-request timeout in seconds. Defaults to the pillar saltext.vcf.vcenter.timeout value, or DEFAULT_TIMEOUT.

saltext.vcf.utils.vcenter.api_post(opts, path, body=None, params=None, profile=None, timeout=None)

POST JSON body to vCenter and return parsed JSON.

timeout overrides the per-request timeout (seconds). Long-running calls like OVF deploy should pass an explicit higher value.

saltext.vcf.utils.vcenter.api_patch(opts, path, body=None, profile=None, timeout=None)

PATCH JSON body to vCenter and return parsed JSON.

saltext.vcf.utils.vcenter.api_put(opts, path, body=None, profile=None, timeout=None)

PUT JSON body to vCenter and return parsed JSON.

saltext.vcf.utils.vcenter.api_delete(opts, path, params=None, profile=None, timeout=None)

DELETE a resource from vCenter.

saltext.vcf.utils.vcenter.wait_for_task(opts, task_id, timeout=1800, poll_interval=10, profile=None)

Block until vCenter CIS task task_id reaches a terminal state.

Polls GET /api/cis/tasks/{task_id} until status is SUCCEEDED/SUCCESS (returns the final task dict) or FAILED/CANCELED/CANCELLED (raises RuntimeError with the task payload attached). Raises TimeoutError if timeout elapses first. Generic to any vCenter API that returns a CIS task id (e.g. ?vmw-task=true responses).

vmw-task=true only requests async execution — vAPI operations may still complete synchronously and never create a task at all, in which case task_id is actually the caller’s direct result (e.g. a draft id), not a task reference. A 404 on the very first lookup is treated as “ran synchronously, nothing to wait for” rather than an error; a 404 after the task was previously seen running is a real failure and still raises.