Konvoy Image Builder

Konvoy Image Builder (KIB) is a complete solution for building Cluster API compliant images. The goal of Konvoy Image Builder is to produce a common operating surface to run Konvoy across heterogeneous infrastructure. KIB relies on ansible to install software, configure, and sanitize systems for running Konvoy. Packer is used to build images for cloud environments. Goss is used to validate systems are capable of running Konvoy.

This section describes how to use KIB to create a Cluster API compliant machine images. Machine images contain configuration information and software to create a specific, pre-configured, operating environment. For example, you can create an image of your current computer system settings and software. The machine image can then be replicated and distributed, creating your computer system for other users. KIB uses variable overrides to specify base image and container images to use in your new machine image. The variable overrides files for Nvidia and FIPS can be ignored unless adding an overlay feature.

How KIB Works

You can use KIB to build machine images, but first you need to be aware of the default behaviors of KIB.  Stated very simply, KIB installs kubeadm and the other basic components you need, so that when the machine boots for the first time, it becomes a Kubernetes control plane or worker node, and then can form or join a cluster.

KIB does this by booting a computer using a stripped-down base image, like an AMI, and then runs a series of steps to install all of the components that DKP needs.  When the installation completes, KIB takes a snapshot or backup of that machine image and saves it. This becomes the image or AMI, and so on, that you use when building the cluster.

Using Override files

You can use overrides files to customize some of the components installed on this machine image. (The KIB base override files are located in this Github repository.)  For example, you could tell KIB to install the FIPS versions of the Kubernetes components. You could also add offline overrides, used for air-gapped environments, that will upload the necessary OS packages and other files to the image, so that KIB doesn't try to look for those using the Internet.  Or you could use an override file to provide similar configurations for using a GPU-enabled cluster.

You can only change certain, predefined parameters using this mechanism. The set of parameters you can change depends on which of the supported infrastructure providers you are using. For example, for vSphere, there are many settings that you use to tell the KIB how to talk to your vCenter implementation, where to store the images, which credentials to use, and so on.

Using HTTP/S Proxies

In some networked environments, the machines used for building images can reach the Internet, but only through an HTTP/S proxy. For DKP to operate in these networks, you need a way to specify what proxies to use.  You can use an HTTP proxy override file to specify that proxy. When KIB is trying to install a particular OS package, it uses that proxy to reach the Internet to download that package.

The proxy setting specified here is NOT “baked into” the image - it is only used while the image is being built. The settings are removed before the image is finalized.

While it might seem logical to include the proxy information in the image, the reality is that many companies have multiple proxies - one perhaps for each geographical region, or maybe even a proxy per Datacenter or office.  All network traffic to the Internet goes through the proxy. If you were in Germany, you would probably not want to send all your traffic to a U.S.-based proxy. Doing that would slow traffic down and consume too many network resources. If you baked the proxy settings into the image, you would have to create a separate image for each specific region. It makes more sense to create an image with no proxy included, but remember that you still need a proxy to access the Internet. Thus, when creating the cluster, (and also when installing the Kommander component of DKP), you must specify the correct proxy settings for the network environment into which you are installing the cluster. You will use the same base image for that cluster as one installed in an environment with different proxy settings.

Prerequisites

Before you begin, you must ensure your versions of KIB and DKP are compatible:

• Download the Konvoy Image Builder bundle from the KIB Version column of the chart below for your version of DKP prefixed with konvoy-image-bundle for your Operating System.

• Check the Supported Infrastructure Operating Systems  

• Check the Supported Kubernetes Version for your Provider.

• An x86_64-based Linux or MacOS machine

• A Container engine installed:

  • Version Docker® container engine version 18.09.2 or higher installed for Linux or MacOS - On macOS, Docker runs in a virtual machine which needs configured with at least 8 GB of memory.

  • Version 4.0 of Podman or higher for Linux.

• For air-gapped only - a local registry

Compatible DKP to KIB Versions

Along with the KIB Bundle, we publish a file containing checksums for the bundle files. The recommendation for using these checksums is to verify the integrity of the downloads.

• On the corresponding link page, download the package prefixed with konvoy-image-bundle for your OS.

KIB will run and print out the name of the created image for your infrastructure provider as shown on specific provider KIB pages below. Use this name when creating a Kubernetes cluster.

Next Steps:

Either return to Basic Install or Custom Install instructions, or for more KIB specific provider information you can continue to the provider link below for additional information: