vc_patch

Client for vCenter’s VAMI appliance-update REST API (VCSA self-patching).

Manages the vCenter appliance’s own update lifecycle — configuring an update repository, listing/resolving pending updates, staging a build, running prechecks, and installing — via:

/rest/appliance/update/...

This is a distinct workflow from ESXi host patching (saltext.vcf.clients.esxi_vlcm, vLCM) or NSX/SDDC Manager component upgrades — it patches the vCenter Server Appliance itself.

Authentication reuses the same vCenter session as every other /api/... client in this package (saltext.vcf.utils.vcenter): a vmware-api-session-id token obtained via POST /api/session is also valid against the legacy /rest/... vSphere Automation API namespace used here — both namespaces share the same underlying vAPI session on modern vCenter builds, so no separate login is needed. If a target vCenter build rejects that token for /rest/... calls, a read-only call like get_update_policy() will fail fast with 401/403 — verify with one before running anything mutating.

saltext.vcf.clients.vc_patch.is_transient_error(exc)

True if exc is an HTTP error VAMI services commonly throw mid-patch.

The appliance’s own update services restart during staging/install, which can surface as 401/403/404/500/502/503 on the next poll — treated as transient (retry after re-authenticating), not a hard failure.

saltext.vcf.clients.vc_patch.is_stage_timeout_error(exc)

True if exc is VAMI’s “stage still running server-side” signature.

The REST call itself can time out client-side while staging continues on the appliance; callers should fall back to polling get_staged_update() instead of treating this as a hard failure.

saltext.vcf.clients.vc_patch.is_staging_in_progress_error(exc)

True if exc is VAMI refusing a precheck because staging isn’t done yet.

saltext.vcf.clients.vc_patch.get_update_policy(opts, profile=None)

Return the appliance’s current update-repository policy.

saltext.vcf.clients.vc_patch.set_update_policy(opts, repository_url, auto_stage=False, certificate_check=True, check_schedule=None, repo_username='', repo_password='', profile=None)

Configure the appliance’s update-repository policy.

repository_url is required. All other fields are always sent with a real value (never omitted), matching the reference implementation this was ported from — every field of this action is meant to fully replace the prior policy, not merge into it.

saltext.vcf.clients.vc_patch.list_pending_updates(opts, repository_url=None, source_type='LOCAL_AND_ONLINE', profile=None)

List updates available from the configured sources.

source_type is forced to "LOCAL_AND_URL" whenever repository_url is given, regardless of what’s passed in, matching VAMI’s expectation that a URL-scoped lookup declares itself as such.

saltext.vcf.clients.vc_patch.get_pending_update(opts, version, profile=None)

Return details for one specific pending update version.

saltext.vcf.clients.vc_patch.list_upgradeable_components(opts, version, profile=None)

List the components that would be upgraded by version.

saltext.vcf.clients.vc_patch.get_update_status(opts, profile=None)

Return the appliance’s overall update state machine status.

saltext.vcf.clients.vc_patch.precheck(opts, version, component=None, profile=None)

Run pre-update health checks for version.

No body is sent when component is omitted — a whole-appliance precheck doesn’t take one.

saltext.vcf.clients.vc_patch.stage(opts, version, component=None, profile=None)

Download/stage the update payload for version. See precheck() on body.

saltext.vcf.clients.vc_patch.install(opts, version, sso_password, component=None, profile=None)

Install the staged update for version.

sso_password (the SSO admin/vmdir password) is required — VAMI needs it to re-authenticate vmdir during the appliance install.

saltext.vcf.clients.vc_patch.get_staged_update(opts, profile=None)

Return the currently staged update, or an empty/error body if nothing is staged.

saltext.vcf.clients.vc_patch.delete_staged_update(opts, profile=None)

Discard the currently staged update. Tolerant of “nothing staged” (404).

saltext.vcf.clients.vc_patch.get_update_history(opts, profile=None)

Return the appliance’s update history log.

saltext.vcf.clients.vc_patch.staged_matches(staged_update, version=None)

True if staged_update (a get_staged_update() response) is non-empty.

If version is given, also requires it to match the staged entry’s version-like fields (exact, or a prefix match in either direction — VAMI’s version strings mix build numbers/dotted versions/display names, so exact string equality is too strict).

saltext.vcf.clients.vc_patch.resolve_update_version(opts, repository_url=None, version=None, profile=None)

Resolve a requested (or absent) version to a concrete pending-update version.

If version is given, try a direct lookup first; on failure (or if omitted), list pending updates and match by exact-then-prefix on version/name/id/display_version. An absent version resolves to the first pending update returned by the server.

Returns (resolved_version, pending_updates_raw, pending_update_detail).

saltext.vcf.clients.vc_patch.wait_for_staged_update(opts, version=None, poll_interval=10, timeout=600, profile=None)

Block until get_staged_update() matches version (or anything staged, if omitted).

Used as a fallback after a client-side timeout on stage() — the stage call may still be running server-side even though the REST response never came back in time.

saltext.vcf.clients.vc_patch.monitor_stage(opts, version=None, poll_interval=50, timeout=3600, max_transient_errors=10, profile=None)

Block until version is staged, or raise on failure/timeout.

Tolerates transient HTTP errors (appliance services bouncing mid-patch) up to max_transient_errors, re-authenticating before each retry.

saltext.vcf.clients.vc_patch.monitor_install(opts, poll_interval=120, timeout=7200, max_transient_errors=10, profile=None)

Block until the appliance reports UP_TO_DATE, or raise on failure/timeout.