Skip to content

Latest commit

 

History

History
165 lines (110 loc) · 4.9 KB

tutorial_building_an_image.md

File metadata and controls

165 lines (110 loc) · 4.9 KB

Tutorial for Using the vSphere Tanzu Kubernetes Grid Image Builder

This tutorial describes how to use the vSphere Tanzu Kubernetes Grid Image Builder to build a custom TKR for use on Supervisor in the vSphere.

The vSphere Tanzu Kubernetes Grid Image Builder uses Hashicorp Packer to generate images. Packer invokes vCenter APIs to create a VM from a TKR.

Requirements

  • vCenter Server 8, which can be any vCenter 8 instance, it does not have to be the same vCenter managing your vSphere
  • Packer requires the vSphere environment to have DHCP configured; you cannot use static IP address management
  • Tutorial uses Ubuntu 22.04 based Linux VM to generate the image

Clone the Repository

Clone the vSphere Tanzu Kubernetes Grid Image Builder repository on the Linux VM where you are building the image.

git clone https://github.com/vmware-tanzu/vsphere-tanzu-kubernetes-grid-image-builder.git

Install Docker

The vSphere Tanzu Kubernetes Grid Image Builder runs components as Docker images to generate VMs.

Refer to the Docker installation guide for setting up Docker Engine.

Install JQ

Install:

sudo apt install -y jq

Verify:

jq --version

Install Make

Install:

sudo apt install make

Verify:

make --version

Update vsphere.j2 with vSphere Environment Details

The vsphere.j2 file is a packer configuration file with vSphere environment details.

CD to the vsphere-tanzu-kubernetes-grid-image-builder/packer-variables/ directory.

Update the vsphere.j2 environment variables with details for your vCenter 8 instance.

vi vsphere.j2

For example:

{
    {# vCenter server IP or FQDN #}
    "vcenter_server":"192.2.2.2",
    {# vCenter username #}
    "username":"[email protected]",
    {# vCenter user password #}
    "password":"ADMIN-PASSWORD",
    {# Datacenter name where packer creates the VM for customization #}
    "datacenter":"Datacenter",
    {# Datastore name for the VM #}
    "datastore":"datastore22",
    {# [Optional] Folder name #}
    "folder":"",
    {# Cluster name where packer creates the VM for customization #}
    "cluster": "Management-Cluster",
    {# Packer VM network #}
    "network": "PG-MGMT-VLAN-1050",
    {# To use insecure connection with vCenter  #}
    "insecure_connection": "true",
    {# TO create a clone of the Packer VM after customization#}
    "linked_clone": "true",
    {# To create a snapshot of the Packer VM after customization #}
    "create_snapshot": "true",
    {# To destroy Packer VM after Image Build is completed #}
    "destroy": "true"
}

Select Kubernetes version

To identify the version of Kubernetes Release to be used, from the vsphere-tanzu-kubernetes-grid-image-builder directory where the Makefile is located run:

make list-versions

Run the Artifacts Server Container for the Selected Kubernetes Version

Running the run-artifacts-container Makefile target, will pull the Artifacts Server container image corresponding to the selected Kubernetes Release.

Usage:

make run-artifacts-container KUBERNETES_VERSION=<version>

Example:

make run-artifacts-container KUBERNETES_VERSION=v1.31.1+vmware.2-fips

Run the Image Builder Application

Usage:

make build-node-image OS_TARGET=<os_target> KUBERNETES_VERSION=v1.31.1+vmware.2-fips TKR_SUFFIX=<tkr_suffix> HOST_IP=<host_ip> IMAGE_ARTIFACTS_PATH=<image_artifacts_path> ARTIFACTS_CONTAINER_PORT=8081

NOTE: The HOST_IP must be reachable from the vCenter.

Example:

make build-node-image OS_TARGET=ubuntu-2004-efi KUBERNETES_VERSION=v1.31.1+vmware.2-fips TKR_SUFFIX=byoi HOST_IP=192.2.2.3 IMAGE_ARTIFACTS_PATH=/home/ubuntu/image ARTIFACTS_CONTAINER_PORT=8081

Verify the Custom Image

Locally the image is stored in the /image/ovas directory. For example, /home/ubuntu/image/ovas.

The /image/logs directory contains the packer-xxxx.log file that you can use to troubleshoot image building errors.

To verify that image is built successfully, check vCenter Server.

You should see the image being built in the datacenter, cluster, folder that you specified in the vsphere.j2 file.

Customize the image

Refer to the customization examples.

Upload the Image to generate custom Kubernetes Release

Download the custom image from local storage or from the vCenter Server.

In your vSphere environment, create a local content library and upload the custom image there.

Refer to the documentation for creating a local content library for use with Supervisor.

To use the custom TKR, configure the vSphere Namespace to use the local content library.