Skip to main content
Skip table of contents

GCP Konvoy Image Builder

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. 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:

  • Check the supported DKP version.

  • Check the Supported Infrastructure Operating Systems

  • Download the KIB bundle for your version of DKP prefixed with konvoy-image-bundle for your OS.

  • Create a working Docker setup.

  • On Debian-based Linux distributions, install a version of the cri-tools package known to be compatible with both the Kubernetes and container runtime versions.

  • Verify that your Google Cloud project does not have the Enable OS Login feature enabled. See below for more information:

The Enable OS Login feature is sometimes enabled by default in GCP projects.    If the OS login feature is enabled, KIB will not be able to ssh to the VM instances it creates and will not be able to successfully create an image.

To check if it is enabled, use the commands on this page https://cloud.google.com/compute/docs/metadata/setting-custom-metadata#console_2 to inspect the metadata configured in in your project.  If you find the the enable-oslogin flag set to TRUE, you must remove (or set it to FALSE) to successfully use KIB.

GCP Prerequisite Roles

  • 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:

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

      CODE
      export GCP_PROJECT=<your GCP project ID>
      export GCP_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:${GCP_SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com" --role=roles/compute.instanceAdmin.v1
      gcloud projects add-iam-policy-binding ${GCP_PROJECT} --member="serviceAccount:${GCP_SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com" --role=roles/iam.serviceAccountUser
      gcloud iam service-accounts keys create ${GOOGLE_APPLICATION_CREDENTIALS} --iam-account="${GCP_SERVICE_ACCOUNT_USER}@${GCP_PROJECT}.iam.gserviceaccount.com"
    • Export the static credentials that will be used to create the cluster:

      CODE
      export GCP_B64ENCODED_CREDENTIALS=$(base64 < "${GOOGLE_APPLICATION_CREDENTIALS}" | tr -d '\n')

Build the GCP image

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

    CODE
    ./konvoy-image build gcp --project-id ${GCP_PROJECT} --network ${NETWORK_NAME} images/gcp/ubuntu-2004.yaml
  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:

    CODE
    ...
    ==> 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
  3. To find a list of images you have created in your account, run the following command:

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

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.