Konvoy Image Builder (KIB) is a complete solution for building Cluster API compliant images.

This procedure describes how to use the Konvoy Image Builder (KIB) to create a Cluster API compliant GCP image. GCP images contain configuration information and software to create a specific, pre-configured, operating environment. For example, you can create a GCP image of your current computer system settings and software. The GCP image can then be replicated and distributed, creating your computer system for other users. The KIB uses variable overrides to specify base image and container images to use in your new GCP image.

Google Cloud Platform does not publish images. You must first build the image using Konvoy Image Builder. For more information regarding images and clusters, refer to the GCP Infrastructure section of the documentation.

Prerequisites

Before you begin, you must:

  • Download the supported version of the KIB bundle (prefixed with konvoy-image-bundle) for your OS. Do not use the release prefixed with konvoy-image-builder.

  • Create a working Docker setup.

GCP Prerequisites

  • If you are creating your image on either a non-GCP instance or one that does not have the required roles:

    • (option 1) Create a service account using the following gcloud commands:

      export GCP_PROJECT=<your GCP project ID>
      export SERVICE_ACCOUNT_USER=<some new service account user>
      export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcloud/credentials.json"
      
      gcloud iam service-accounts create "${SERVICE_ACCOUNT_USER}" --project=${GCP_PROJECT}
      gcloud projects add-iam-policy-binding ${GCP_PROJECT} --member="serviceAccount:${SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com" --role=roles/compute.instanceAdmin.v1
      gcloud projects add-iam-policy-binding ${GCP_PROJECT} --member="serviceAccount:${SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com" --role=roles/iam.serviceAccountUser
      gcloud iam service-accounts keys create ${GOOGLE_APPLICATION_CREDENTIALS} --iam-account="${SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com"
      CODE
    • (option 2) If you have already created a service account, retrieve the credentials for an existing service account using the following gcloud commands:

      export GCP_PROJECT=<your GCP project ID>
      export SERVICE_ACCOUNT_USER=<existing service account user>
      export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcloud/credentials.json"
      
      gcloud projects add-iam-policy-binding ${GCP_PROJECT} --member="serviceAccount:${SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com" --role=roles/compute.instanceAdmin.v1
      gcloud projects add-iam-policy-binding ${GCP_PROJECT} --member="serviceAccount:${SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com" --role=roles/iam.serviceAccountUser
      gcloud iam service-accounts keys create ${GOOGLE_APPLICATION_CREDENTIALS} --iam-account="${SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com"
      CODE

Create a Network (optional)

Building an image requires a Network with firewall rules that allow SSH access to the VM instance.

  1. Set your GCP Project ID for your gcp account unless already set previously:

    export GCP_PROJECT=<your GCP project ID>
    CODE
  2. Run the following to create a new network:

    export NETWORK_NAME=kib-ssh-network
    gcloud compute networks create "${NETWORK_NAME}" --project="${GCP_PROJECT}" --subnet-mode=auto --mtu=1460 --bgp-routing-mode=regional
    CODE
  3. Create the firewall rule to allow Ingress access on port 22:

    gcloud compute firewall-rules create "${NETWORK_NAME}-allow-ssh" --project="${GCP_PROJECT}" --network="projects/${GCP_PROJECT}/global/networks/${NETWORK_NAME}" --description="Allows TCP connections from any source to any instance on the network using port 22." --direction=INGRESS --priority=65534 --source-ranges=0.0.0.0/0 --action=ALLOW --rules=tcp:22
    CODE

Build the GCP image

  1. Run the konvoy-image command to build and validate the image:

    ./konvoy-image build gcp --project-id ${GCP_PROJECT} --network ${NETWORK_NAME} images/gcp/ubuntu-2004.yaml
    CODE
  2. KIB will run and print out the name of the created image, you will use this name when creating a Kubernetes cluster. See sample output below:

    ...
    ==> ubuntu-2004-focal-v20220419: Deleting instance...
        ubuntu-2004-focal-v20220419: Instance has been deleted!
    ==> ubuntu-2004-focal-v20220419: Creating image...
    ==> ubuntu-2004-focal-v20220419: Deleting disk...
        ubuntu-2004-focal-v20220419: Disk has been deleted!
    ==> ubuntu-2004-focal-v20220419: Running post-processor: manifest
    Build 'ubuntu-2004-focal-v20220419' finished after 7 minutes 46 seconds.
    
    ==> Wait completed after 7 minutes 46 seconds
    
    ==> Builds finished. The artifacts of successful builds are:
    --> ubuntu-2004-focal-v20220419: A disk image was created: konvoy-ubuntu-2004-1-23-7-1658523168
    --> ubuntu-2004-focal-v20220419: A disk image was created: konvoy-ubuntu-2004-1-23-7-1658523168
    CODE
  3. To find a list of images you have created in your account, run the following command:

    gcloud compute images list --no-standard-images
    CODE

With your KIB image now created, you can now move onto Bootstrap GCP and set up your Cluster API (CAPI) controllers, or run GCP Quick Start to create a cluster with little customization.

Konvoy Image Builder has a more detailed section in the documentation if you need to refer there for compatible versions with DKP and other specific information.