Quick Tip - Correctly naming TKR's in Local Content Library for vSphere with Tanzu in vSphere 8

Customers can create a Tanzu Kubernetes Releases (TKR) content library by either subscribing to VMware's online repository or by creating a local content library and manually importing the images, which can be useful for air-gapped or non-internet accessible environments.

If you automatically subscribe to VMware's online repository, the TKR images (OVF) will automatically be downloaded and will be stored with a default item name that looks like the following:

However, when creating a local content library, customers must manually import the OVF images after downloading them from VMware's online repository (https://wp-content.vmware.com/v2/latest/). During the OVF import wizard, you will notice that each TKR has the same default name called "photon-ova" and you will most likely rename it to something more useful.

Prior to vSphere 8, you could use any name and vSphere with Tanzu would not care as there is metadata associated within each TKR image that provides version that is needed when creating a Tanzu Kubernetes Grid Cluster (TKC).

I was attempting to deploy a TKC using a new TKR version, which I needed to download and import into my vSphere 8 environment and that is where I ran into a strange error:

Error from server (Spec.Topology.ControlPlane.TKR.Reference.Name unable to resolve that TKR due to could not resolve TKR/OSImage for controlPlane, machineDeployments: [np-2], query: {controlPlane: {k8sVersionPrefix: 'v1.22.9+vmware.1-tkg', tkrSelector: '!run.tanzu.vmware.com/legacy-tkr', osImageSelector: 'os-name=photon'}, machineDeployments: [{k8sVersionPrefix: 'v1.22.9+vmware.1-tkg', tkrSelector: '!run.tanzu.vmware.com/legacy-tkr', osImageSelector: 'os-name=photon'}]}, result: {controlPlane: {k8sVersion: '', tkrName: '', osImagesByTKR: map[]}, machineDeployments: [{k8sVersion: '', tkrName: '', osImagesByTKR: map[]}]}): error when creating "tkc.yaml": admission webhook "default.validating.tanzukubernetescluster.run.tanzu.vmware.com" denied the request: Spec.Topology.ControlPlane.TKR.Reference.Name unable to resolve that TKR due to could not resolve TKR/OSImage for controlPlane, machineDeployments: [np-2], query: {controlPlane: {k8sVersionPrefix: 'v1.22.9+vmware.1-tkg', tkrSelector: '!run.tanzu.vmware.com/legacy-tkr', osImageSelector: 'os-name=photon'}, machineDeployments: [{k8sVersionPrefix: 'v1.22.9+vmware.1-tkg', tkrSelector: '!run.tanzu.vmware.com/legacy-tkr', osImageSelector: 'os-name=photon'}]}, result: {controlPlane: {k8sVersion: '', tkrName: '', osImagesByTKR: map[]}, machineDeployments: [{k8sVersion: '', tkrName: '', osImagesByTKR: map[]}]}

After some debugging with Engineering, I came to find out that vSphere with Tanzu now requires the TKR image name to match the original name as defined in the online repository. You can see the original TKR name by either inspecting the URL path or by clicking on the item.json file for a specific TKR.

If your browser automatically renders the JSON output, you can look for the name property to find the correct TKR image name.

Simply renaming the item name did not work for me, I assume because the UUID of the content library item is stored rather than the actual name. Since I only had a single image, my simple solution was to just clone the image and rename it to the correct label and that allowed me to deploy the TKC without any issues.

I think a much better experience than having our customers name the image correctly is by simply changing the default photon-ova name to the actual TKR image name. This will ensure when you import the image, it uses the default name and as long as you do not change it, you should not run into this specific issue. I have already shared this feedback with both documentation team and Engineering and hopefully this can be enhanced in the future but hopefully this will help anyone who needs to create a local content library for use with vSphere with Tanzu.