VMware VKS

[READ] Check whether this vCenter supports VKS (requires vSphere 8.x+). Returns compatible (bool), vcenter_version, wcp_enabled_clusters and wcp_clusters ({cluster, status}). Start here: those cluster MoRefs are the cluster_id for get_supervisor_status and create_namespace. Only reports vCenter-level support — a listed cluster may still be CONFIGURING.

[READ] Check the vCenter 9.1.0/9.1.1 Supervisor pre-upgrade advisory scope. Reads the source vCenter version/build and Supervisor cluster inventory. Returns advisory_applicability, supervisor_presence and next_step. The vLCM/VUM database schema is **unmeasured**: this tool never grants upgrade clearance. Use the official checker in Broadcom KB 455737 or VDT before upgrading an affected environment. No database script is run here.

[READ] Get the health of one Supervisor Cluster (vSphere with Tanzu control plane). Returns cluster_id, config_status (RUNNING = healthy, else CONFIGURING / ERROR / REMOVING), kubernetes_status (READY / WARNING / ERROR), api_server_cluster_endpoint, kubernetes_version (null plus kubernetes_version_hint if unavailable), and network_provider. Run check_vks_compatibility first for cluster IDs; use this to confirm a Supervisor is healthy before create_namespace or create_tkc_cluster.

[READ] List vCenter storage policies assignable to Supervisor Namespaces. Returns the list envelope: items of {policy (ID), name, description} plus returned/total/truncated — one call returns them all, so truncated is always false. Call this before create_namespace or update_namespace and pass the 'policy' ID as their storage_policy. For PVC-level usage use list_namespace_storage_usage instead.

[READ] List all vSphere Namespaces on the target vCenter with their status. Returns the list envelope: items of {namespace, config_status (RUNNING = healthy, CONFIGURING, REMOVING, ERROR), description} plus returned/total/truncated — one call returns them all, so truncated is always false. Start here, then call get_namespace for detail, list_tkc_clusters for what runs inside, or update_namespace / delete_namespace to change one.

[READ] Get detailed configuration for a single vSphere Namespace. Returns one raw vCenter namespace object, not the list envelope: config_status, description, storage_specs, quotas. Use list_namespaces first for the name; follow with list_namespace_storage_usage for PVC usage or list_tkc_clusters for the clusters inside. Point-in-time only — a CONFIGURING namespace may not have quotas applied.

[WRITE] Create a vSphere Namespace on a Supervisor Cluster. Without confirm=True this only previews: it returns blast_radius (the spec that would be applied, and whether the name is already taken) and creates 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. confirm=True returns {action: "created", namespace, status, cluster, blast_radius}; it is refused when the name is taken (use update_namespace) or the existing names could not be read. Confirm with get_namespace afterwards.

[WRITE] Update resource quotas or storage policy of an existing vSphere Namespace. Only the fields you pass are patched; omitting all of them returns status "no_changes" without an API call, otherwise {namespace, status: "updated"}. Applies immediately — no dry run, no undo. Use this rather than create_namespace when the namespace exists; valid storage_policy values come from list_supervisor_storage_policies.

[WRITE] Delete a vSphere Namespace and everything inside it (irreversible). Without confirm=True this only previews: it returns blast_radius (the namespace, and the TKC clusters, VMs and PVCs inside it, with counts and names) and deletes 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. confirm=True returns {action: "deleted", namespace, status, blast_radius}. Refused while TKC clusters exist inside (run delete_tkc_cluster on each), and whenever the clusters, VMs or PVCs inside could not be read. Prefer update_namespace to only change quotas.

[READ] List VM classes available for sizing TKC cluster nodes. Returns the list envelope: items of {id (e.g. 'best-effort-large'), cpu_count, memory_mb, gpu_count (vGPU + DirectPath I/O; 0 if none)} plus returned/total/truncated — one call returns them all, so truncated is always false. Call this before create_tkc_cluster and pass the chosen 'id' as its vm_class; 'guaranteed-*' classes reserve resources, 'best-effort-*' do not.

[READ] List TanzuKubernetesCluster (TKC) clusters, optionally in one namespace. Returns the family list envelope: {items: [{name, namespace, phase, k8s_version}], returned, limit, total, truncated, hint}. The Supervisor list is walked to completion, so truncated is always False. Start here, then call get_tkc_cluster for full detail or issue_tkc_kubeconfig for access. 'clusters' is a deprecated pre-1.8.0 alias of 'items', removed in 2.0 — read 'items'.

[READ] Get detailed status for a single TKC cluster. Returns one object, not the list envelope: name, namespace, phase, k8s_version, control_plane_replicas, worker_replicas, conditions, infrastructure_ready, control_plane_ready. Run list_tkc_clusters first — a TKC name is only unique within one namespace. Poll this after create_tkc_cluster, scale_tkc_cluster or upgrade_tkc_cluster to watch an async change land.

[READ] List Kubernetes versions (TanzuKubernetesReleases) available on the Supervisor. Returns {versions: [{name, version, e.g. 'v1.28.4+vmware.1'}]}, newest first. If the TanzuKubernetesRelease API is unavailable it returns an empty versions list with error and hint rather than raising. Call this before create_tkc_cluster or upgrade_tkc_cluster to pick a valid k8s_version.

[WRITE] Create a TanzuKubernetesCluster in a vSphere Namespace. Without confirm=True this only previews: it returns blast_radius (node counts, VM class, the YAML manifest, and whether the name is taken) and creates 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. confirm=True returns {action: "created", name, namespace, status: "creating", yaml, blast_radius} and provisions in the background — poll get_tkc_cluster until phase is running. Refused when the name is taken or the namespace's clusters could not be read. Call get_tkc_available_versions for k8s_version and list_vm_classes first.

[WRITE] Scale the worker node count of an existing TanzuKubernetesCluster (TKC). Asynchronous: returns {name, namespace, pool, worker_count, status: "scaling"} immediately — poll get_tkc_cluster to watch nodes appear or drain. Scales workers only; use upgrade_tkc_cluster instead for the K8s version. Not destructive, but lowering worker_count drains removed nodes.

[WRITE] Upgrade a TKC cluster to a new Kubernetes version. Returns {name, namespace, new_version, status: "upgrading"}. Asynchronous and irreversible — Kubernetes cannot be downgraded, so poll get_tkc_cluster until phase is running. There is no dry run. Use this only for the K8s version; prefer scale_tkc_cluster for node counts.

[WRITE] Delete a TKC cluster and all of its nodes (irreversible). Without confirm=True this only previews: it returns blast_radius (control plane and worker node counts per pool, and the running Deployments, StatefulSets and DaemonSets) and deletes 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. confirm=True returns {action: "deleted", name, namespace, status: "deleting", blast_radius}. Refused while workloads run (drain them, or pass force=True, which skips the workload check entirely) and whenever the node counts or workloads could not be read. Use scale_tkc_cluster instead for fewer nodes. Empty a namespace of TKC clusters before delete_namespace accepts it.

[WRITE] Credential access: issue a kubeconfig for the Supervisor K8s API. Call only when the user explicitly asks for this kubeconfig; never as a side step. Returns {namespace, kubeconfig} as a YAML string, or {namespace, written_to} when output_path is given. The kubeconfig embeds a Supervisor bearer token (JWT from /wcp/login) that acts as the configured vCenter account until the JWT expires (typically hours; not tied to this process) — always pass output_path so the token never enters agent context, and report only the path. The file is created owner-only (0600). For TKC workloads, see issue_tkc_kubeconfig and its vSphere 9.1 limitation before issuing a guest-cluster credential.

[WRITE] Credential access: issue a kubeconfig for one TKC cluster. Call only when the user explicitly asks for this kubeconfig; never as a side step. Returns {cluster, kubeconfig}, or {cluster, written_to} when output_path is given. The kubeconfig embeds a Supervisor bearer token (JWT from /wcp/login) that acts as the configured vCenter account until the JWT expires (typically hours; not tied to this process) — always pass output_path so the token never enters agent context, and report only the path. Nothing in the managed cluster changes, but output_path creates parent directories and truncates the named file (owner-only, 0600), so output_path='~/.kube/config' replaces the user's own kubeconfig. Run list_tkc_clusters first for name and namespace; use issue_supervisor_kubeconfig instead for Supervisor-level access. On one reported VCF 9.1 deployment, the guest cluster API rejects this Supervisor JWT with 401. A generated file does not prove guest access; verify it against the guest API before relying on it (issue #27).

[READ] Get status of the embedded Harbor container registry on the Supervisor. Returns {registries: [{id, cluster (Supervisor MoRef), version, url, status, storage_used_mb}]}; status and storage come from a detail call and are null if it fails. If Harbor is not enabled it returns {error, hint} rather than raising. Use it to check registry health or find the push URL — it does not list repositories or images. Run check_vks_compatibility first if the Supervisor may be down.

[READ] List PersistentVolumeClaims and storage usage inside one vSphere Namespace. Via the Supervisor K8s API. Returns the family list envelope: {namespace, items: [{name, namespace, status (Bound / Pending / Lost), capacity ('10Gi'), storage_class}], returned, limit, total, truncated, hint}. Every PVC comes back in one call, so truncated is always False. Run list_namespaces first for the namespace; use list_supervisor_storage_policies instead for policy-level rather than PVC-level information. 'pvcs' and 'pvc_count' are deprecated pre-1.8.0 aliases of 'items' and 'returned', removed in 2.0 — read 'items'.

[READ] List VirtualMachineSnapshot objects in a vSphere Namespace. VM Service snapshots (vmoperator.vmware.com CRD, new at v1alpha5) via the Supervisor K8s API — the served CRD version is discovered at runtime, not hardcoded. Returns the family list envelope: items of {name, namespace, vm_name, created, ready} plus returned/total/truncated (walked to completion, so truncated is always false) and served_version. If the Supervisor is older than v1alpha5 the error names the required version. Run list_namespaces first for the namespace; use list_vm_service_network_interfaces for a VM's NICs.

[READ] List VirtualMachineGroup objects and their bootOrder in a Namespace. VM Service groups (vmoperator.vmware.com CRD, v1alpha4+) via the Supervisor K8s API — the served CRD version is discovered at runtime. Returns the family list envelope: items of {name, namespace, boot_order, member_count} plus returned/total/truncated (walked to completion) and served_version. ``boot_order`` mirrors spec.bootOrder: an ordered list of {members: [{kind, name}], power_on_delay?}. Older Supervisors without v1alpha4 return a teaching error naming the required version.

[READ] List the network interfaces (multi-NIC) of one VirtualMachine. Reads spec.network.interfaces[] off a single VM Service VirtualMachine (vmoperator.vmware.com) via the Supervisor K8s API; the served CRD version is discovered at runtime. Returns the family list envelope: items of {name, network_name, network_kind, network_api_version} plus returned/total/truncated and vm_name/served_version. A VM with no network block returns an empty list, not an error. Run list_namespaces for the namespace; the VM name comes from your own VM inventory in that namespace.

[READ] Which account this server uses, and whether it holds each tool's vSphere privileges. Use this when a tool fails with a permission error, or before a write, to check what the configured account may do. Asks vCenter about the current session (needs only System.View, so any account can ask about itself). Returns target, account, the privilege states, and for one tool its requires/verdict/meaning; without tool, every tool grouped by verdict. Gotchas: privileges are checked on the root folder only, and a verdict of not_granted_at_root is NOT "no access" — it may be granted on a specific cluster. undetermined means vCenter did not answer; never read it as granted. Kubernetes calls (TKC, VM Service, kubeconfigs) are authorized by the namespace's view/edit/owner permission, which this cannot check, so those tools report undetermined. Namespace writes need Namespaces.Configure.