Linux Custom Machine Images

This procedure walks you through building a Linux (Ubuntu) custom machine image to use when creating class-based clusters on vSphere. It is divided into the following sections:

Linux Image Prerequisites lists what you need to successfully build and use a custom Linux image.
Retrieve the OS Image Version shows how to retrieve the OS image version from a default OVA for vSphere.
Build a Linux Image shows you how to use Kubernetes Image Builder and Docker to customize and build an image.
Upload the Linux Image to vSphere shows you how to upload your custom Linux image to vSphere.

To build a Linux custom machine image for plan-based (legacy) clusters, see Linux Custom Machine Images (Legacy). For more information about cluster types in Tanzu Kubernetes Grid, see Workload Cluster Types.

Linux Image Prerequisites

To build a Linux custom machine image, you need:

An account on vSphere
A macOS or Linux workstation with the following installed:
- Docker Desktop
- The Kubernetes CLI, kubectl
- (Optional) The govc CLI

Retrieve the OS Image Version

In this step, you retrieve the OS image version that is associated with the default Ubuntu OVA for the Kubernetes version that you want to use for your custom image. You will assign this OS image version to your custom image in the Build a Linux Image step below.

To retrieve the OS image version, do one of the following depending on your use case:

If you have a running management cluster that was created using the default Kubernetes version for the current Tanzu Kubernetes Grid version, you can retrieve the OS image version from the cluster:
1. Set your kubectl context to the management cluster.
2. From the list of available TKrs, choose the Tanzu Kubernetes Release (TKr) for the Kubernetes version that you want to use for you custom image. For example, v1.25.7---vmware.1-tkg.1. To list available TKrs, run:
```
kubectl get tkr
```
3. Open the TKr and record the osImages property. This property specifies the names of OSImage objects associated with the TKr.
4. List OSImage objects in Kubernetes:
```
kubectl get osimages
```
5. In the output, find the OSImage object listing that matches the TKr osImages name for the default Ubuntu OVA.
6. Record the NAME property of the OSImage listing and replace its embedded --- with a + character. For example, v1.25.7+vmware.1-tkg.1-765d418b72c247c2310384e640ee075e.
If you do not have a running management cluster that was created using the default Kubernetes version for the current Tanzu Kubernetes Grid version, you can retrieve the OS image version directly from the default Ubuntu OVA, either locally or from vSphere:
- To retrieve the OS image version locally:
  1. Download the default Ubuntu OVA for your target Kubernetes version:
    1. Go to the Broadcom Support Portal and log in with your VMware customer credentials.
    2. Visit the Tanzu Kubernetes Grid downloads page.
    3. In the version drop-down, select 2.2.0.
    4. Download the OVA. For example, Ubuntu 2004 Kubernetes v1.25.7 OVA.
  2. Unpack the downloaded OVA using the extraction tool of your choice.
  3. In the unpacked directory, locate the .ofv file.
  4. In the .ofv file, search for the OVA VERSION property and record its value. For example, v1.25.7+vmware.1-tkg.1-765d418b72c247c2310384e640ee075e. The property looks similar to the following:
```
<Property ovf:key="VERSION" ovf:type="string" ovf:userConfigurable="false" ovf:value="v1.25.7+vmware.1-tkg.1-765d418b72c247c2310384e640ee075e"/>
```
- If you already uploaded the default Ubuntu OVA for your target Kubernetes version to vSphere, you can alternatively retrieve the OS image version by inspecting the OVA VM properties in the vSphere UI or by using the govc CLI. To use this method, retrieve the OS image version before converting the OVA VM to a template.
  - To retrieve the OS image version from the vSphere UI:
    1. Locate the OVA VM and open the Configure tab on the OVA VM summary page.
    2. Go to Settings –> vApp Options.
    3. In the Properties table, locate the VERSION key and record its Default Value. For example, v1.25.7+vmware.1-tkg.1-765d418b72c247c2310384e640ee075e.
  - To retrieve the OS image version using the govc CLI, run the govc vm.info command. For example:
```
govc vm.info -json /dc0/vm/ubuntu-2004-kube-v1.25.7+vmware.1-tkg.1 | jq
```
    In the output, search for "Id": "VERSION" and record the value of the "DefaultValue" property. For example:
```
{
"Key": 10,
"ClassId": "",
"InstanceId": "",
"Id": "VERSION",
"Category": "Cluster API Provider (CAPI)",
"Label": "VERSION",
"Type": "string",
"TypeReference": "",
"UserConfigurable": false,
"DefaultValue": "v1.25.7+vmware.1-tkg.1-765d418b72c247c2310384e640ee075e",
"Value": "",
"Description": ""
}
```

Build a Linux Image

To build a Linux image:

Complete the Build a Linux Image steps for plan-based clusters on vSphere, but with the following exception. When setting the version string for your custom image in metadata.json, set it to the value that you retrieved in the Retrieve the OS Image Version step above, instead of v1.25.7+vmware.1-myorg.0 as recommended in the Build a Linux Image section. For example:
```
{
 "VERSION": "v1.25.7+vmware.1-tkg.1-765d418b72c247c2310384e640ee075e"
}
```
After completing the steps in the Build a Linux Image section, return to this page and proceed to Upload the Linux Image to vSphere below.

Upload the Linux Image to vSphere

After completing the steps in the Build a Linux Image section, do the following:

If you uploaded the default Ubuntu OVA for your target Kubernetes version to vSphere, delete the default OVA before uploading your custom OVA.
Upload your custom OVA to vSphere. For instructions, see Import the Base Image Template into vSphere in the Prepare to Deploy Management Clusters to vSphere.

What to Do Next

You can now deploy management and workload clusters using your custom image. For instructions, see: