VKS Workload Cluster upgrade fails with "is not supported" error

Products

• VMware vSphere Kubernetes Service

Issue/Introduction

• When attempting to upgrade a vSphere Kubernetes Service (VKS) workload cluster to a newer Kubernetes release, the operation fails and the cluster version remains unchanged.

• The CAPI admission webhook actively blocks the kubectl edit cluster request.

• An error similar to the following is returned in the CLI or vCenter UI:

  error: clusters.cluster.x-k8s.io "<CLUSTER_NAME>" could not be patched: admission webhook "capi.validating.tanzukubernetescluster.run.tanzu.vmware.com" denied the request: upgrade from Kubernetes Release 'vX.XX.XX---vmware...' to 'vY.YY.YY---vmware...' is not supported

Environment

• VMware vSphere 8.x

• vSphere Kubernetes Service (VKS)

Cause

This error is caused by attempting to upgrade the cluster along an unsupported path that violates the semantic versioning (semver) constraints hardcoded into the source KubernetesRelease (KR) object.

The CAPI admission webhook actively evaluates requested upgrades against this constraint to prevent "back in time" patch regressions. If a source release is highly patched (e.g., released late in its lifecycle with specific CVE fixes), attempting to upgrade to an earlier, unpatched release of the next minor version (e.g., a .0 or .1 release) would result in losing those security fixes.

The webhook enforces this constraint to explicitly prevent security and code regressions.

Resolution

To resolve this issue, the workload cluster must be upgraded following a supported, non-regressive path.

Refer: Product Interoperability Matrix

To validate the supported target using kubectl:

1. Authenticate to the Supervisor cluster and identify the semver constraint on the current source release by describing the KubernetesRelease object: kubectl describe kr <CURRENT_KR_VERSION>

2. Locate the vmware-system.kr.destination-semver-constraint base64 string under the Annotations section of the output.

3. Decode the string to determine the exact allowed target versions using standard base64 and gzip utilities: echo "<BASE64_STRING>" | base64 -d | gzip -d

4. Review the decoded output (e.g., <1.32.0 || >=1.32.7), which provides the conditional range of allowed versions. Select a target version available on the Supervisor cluster that strictly satisfies this equation.

5. If the desired final target version does not satisfy the constraint of the current source version, perform a multi-step upgrade:

   • Update the cluster specification to the highest available patch version of the intermediate minor release that satisfies the initial constraint.

   • Once the cluster stabilizes on the intermediate release, evaluate the constraint on the new release and perform the subsequent upgrade to the final target version.

6. If the required intermediate Tanzu Kubernetes Release (TKR) is missing from the Supervisor cluster, download the TKR from VMware Content and synchronize the Content Library before proceeding.

There is no workaround to bypass the CAPI admission webhook. A supported, non-regressive upgrade path must be followed.