Skip to content

Custom OS Image

Users can build a Custom OS image for vSphere using the Kubernetes Image Builder, a collection of cross-provider Kubernetes virtual machine image building utilities.


  • Ensure Ansible is installed on the system where you intend to build the custom OS
  • Clone this Git repo

Procedure to build Custom OS Image

Below is an example to build RHEL OS image

  1. Navigate to the path image-builder/images/capi
  2. Based on the operating system, run make help | grep
  3. Run the command make help | grep rhel and this will list out all the targets related to rhel OS and builders
  4. Once you find the target, ensure the packer configuration is up-to-date according to your requirement
  5. Navigate to the path image-builder/images/capi/packer/config and find the kubernetes.json file
  6. Update the required K8s version in the json file

    • kubernetes_rpm_version
    • kubernetes_semver
    • kubernetes_series
    • kubernetes_deb_version

    If you prefer to use a different configuration file, you can create it with the same format and export PACKER_VAR_FILES environment variable containing the full path to it.

    Along with k8s version, user can also update cni, container run time version details as per the requirement. User can find the file in image-builder/images/capi/packer/config

  7. In addition to the configuration found in images/capi/packer/config, the OVA directory includes several JSON files that define the configuration for the images:

    File Description
    centos-7.json The settings for the CentOS 7 image
    flatcar.json The settings for the Flatcar image
    photon-3.json The settings for the Photon 3 image
    rhel-7.json The settings for the RHEL 7 image
    ubuntu-1804.json The settings for the Ubuntu 18.04 image
    ubuntu-2004.json The settings for the Ubuntu 20.04 image
    vsphere.json Additional settings needed when building on a remote vSphere
    rhel-8.json The settings for the RHEL 8 image
  8. Update Vsphere config

    Complete the vsphere.json configuration file with credentials and informations specific to the remote vSphere hypervisor used to build the ova file. This file must have the following format (cluster can be replaced by host):

        "vcenter_server":"FQDN of vcenter",
        "folder": "template_folder_on_vcenter",
        "cluster": "esxi_cluster_used_for_template_creation",
        "network": "network_attached_to_template",
        "insecure_connection": "false",
        "template": "base_template_used_by_clone_builder",
        "create_snbapshot": "creates a snaphot on base OVA after building",
        "linked_clone": "Uses link cloning in vsphere-clone builder: true, by default"

    Note: You can replace the cluster with hostname

  9. The build prerequisites for using image-builder for building OVAs are managed by running the below command in the directory image-builder/images/capi

    make deps-ova

  10. When building the RHEL image, the OS must register itself with the Red Hat Subscription Manager (RHSM). Supply a username and password via environment variables and run the below command. The two environment variables are RHSM_USER and RHSM_PASS

    PACKER_FLAGS=-on-error=ask RHSM_USER=******* RHSM_PASS=g******** make build-node-ova-vsphere-rhel-8

    where, RHSM_USER=*********, a username and RHSM_PASS=*********, a password to register

This will create a "Kubernetes Cluster API" conformant OVA image.

Note: The above procedure can be used to build images with any supported Operating System.