Build Machine Images

This section describes how to build custom machine images to use as node VM templates for a Tanzu Kubernetes Grid (TKG) standalone management cluster and the workload clusters that it creates.

To build custom images for a vSphere with Tanzu Supervisor cluster, see the vSphere Tanzu Kubernetes Grid Image Builder repository.

This topic provides background on TKG custom images.

Note
To use a custom machine image for management cluster nodes, you need to deploy the management cluster with the installer interface, not from a configuration file.

Overview

Each custom machine image packages a base operating system (OS) version and a Kubernetes version, along with any additional customizations, into an image that runs on vSphere. Linux custom images can also run on AWS or Microsoft Azure infrastructure. A custom image must be based on the OS versions that are supported by Tanzu Kubernetes Grid. The base OS can be an OS that VMware supports but does not distribute, for example, Red Hat Enterprise Linux (RHEL) v8. To view the list of supported OSes, see Target Operating Systems.

Kubernetes Image Builder

To build custom machine images for Tanzu Kubernetes Grid cluster nodes, you use the container image from the upstream Kubernetes Image Builder project. Kubernetes Image Builder runs on your local workstation and uses the following:

Ansible standardizes the process of configuring and provisioning machines across multiple target distribution families, such as Ubuntu and CentOS.
Packer automates and standardizes the image-building process for current and future CAPI providers, and packages the images for their target infrastructure once they are built.
Image Builder builds the images using native infrastructure for each provider:
- Amazon Web Services (AWS)
  - Image Builder builds custom images from base AMIs that are published on AWS, such as official Ubuntu AMIs.
  - The custom image is built inside AWS and then stored in your AWS account in one or more regions.
  - See Building Images for AWS in the Image Builder documentation.
- Azure:
  - You can store your custom image in an Azure Shared Image Gallery.
  - See Building Images for Azure in the Image Builder documentation.
- vSphere:
  - Image Builder builds Open Virtualization Archive (OVA) images from the Linux distribution’s original installation ISO.
  - You import the resulting OVA into a vSphere cluster, take a snapshot for fast cloning, and then mark the machine image as a vm template.
  - See Building Images for vSphere in the Image Builder documentation.

Custom Images Replace Default Images

For common combinations of OS version, Kubernetes version, and target infrastructure, Tanzu Kubernetes Grid provides default machine images. For example, one ova-ubuntu-2004-v1.26.8+vmware.1-tkg image serves as the OVA image for Ubuntu v20.04 and Kubernetes v1.26.8 on vSphere.

For other combinations of OS version, Kubernetes version, and infrastructure, such as with the RHEL v8 OS or Windows, there are no default machine images, but you can build them.

If you build and use a custom image with the same OS version, Kubernetes version, and infrastructure that a default image already has, your custom image replaces the default. The Tanzu CLI then creates new clusters using your custom image, and no longer uses the default image, for that combination of OS version, Kubernetes version, and target infrastructure.

Cluster API

Cluster API (CAPI) is built on the principles of immutable infrastructure. All nodes that make up a cluster are derived from a common template or machine image.

When CAPI creates a cluster from a machine image, it expects several things to be configured, installed, and accessible or running, including:

The versions of kubeadm, kubelet and kubectl specified in the cluster manifest.
A container runtime, most often containerd.
All required images for kubeadm init and kubeadm join. You must include any images that are not published and must be pulled locally, as with VMware-signed images.
cloud-init configured to accept bootstrap instructions.

What to Do Next

For information about how to build images, see the following topics.