Kubernetes Releases (KRs) or OS Images are not visible following a Supervisor Cluster Upgrade in Air-Gapped Environments

Products

• VMware vSphere Kubernetes Service

Issue/Introduction

Following a successful upgrade of the Supervisor Control Plane and vSphere Kubernetes Service (VKS), administrators are unable to upgrade existing guest or workload clusters. The system exhibits the following behaviors:

• Running kubectl get kubernetesreleases returns only a single, legacy release version.
• Running kubectl get osimage -A displays only one legacy operating system image mapping.
• The target guest cluster status reports UpdatesAvailable = False, and no valid lifecycle upgrade progression paths are generated in the cluster management plane.

Environment

• vSphere Supervisor Cluster: 7.x, 8.x / VMware Cloud Foundation 9.x 
• vSphere Kubernetes Service (VKS)

Cause

This behavior is expected in isolated environments where the cluster lacks direct egress to public public repositories.

The vSphere Kubernetes Service relies on Custom Resource Definitions (CRDs) like KubernetesRelease and OSImage to discover and map legitimate upgrade paths. The Kubernetes Release (KR) controller creates these resources by periodically scanning the designated vSphere Content Library for matching Open Virtualization Format (OVF) template objects.

When a Supervisor Cluster is disconnected from the internet, the automated synchronization channels cannot poll public repositories. If the local content library has not been updated with the newer version binaries, the KR controller assumes no upgrade targets exist and locks the current workload status to prevent configuration errors.

Resolution

To unlock the cluster upgrade pipeline, the required Kubernetes Release binaries must be manually introduced into the air-gapped system. Follow these procedural steps to remediate the metadata index:

Step 1: Download the Target OVF Templates

From a jumpstation with secure external internet access, navigate to the official offline distribution mirror and fetch the appropriate version assets (e.g., v1.34/v1.35 resource streams):

• Public Package Hub: VMware Content Distribution Endpoint

Step 2: Import the Assets into the Content Library

1. Log in to the vSphere Client with administrative privileges.
2. Open the main menu and select Content Libraries.
3. Locate the designated vSphere Kubernetes Service Content Library assigned to your Supervisor instance.
4. Click Actions > Import Item, select the manually downloaded OVF/OVA template files, and complete the storage upload sequence.

Step 3: Force Control Plane Reconciliation

Once the OVF assets reside within the backing datastore, connect to your Supervisor Cluster control plane via the terminal using the kubectl CLI tool and run the following checks to verify synchronization:

        1. Validate that the new tracking definitions have generated dynamically: 

             kubectl get kubernetesreleases

        2. Confirm the host operating system mappings are registered:

            kubectl get osimage -A

The target workload cluster will automatically shift its status configuration to UpdatesAvailable = True, validating the sequential upgrade path.