Using KIB with Azure
Learn how to build a custom Azure Image for use with DKP
This procedure describes how to use the Konvoy Image Builder (KIB) to create a Cluster API compliant Azure Virtual Machine (VM) Image. The VM Image contains the base operating system you specify and all the necessary Kubernetes components. The Konvoy Image Builder uses variable overrides
to specify the base image and container images to use in your new Azure VM image.
DKP is configured to try and use the Azure Virtual Machine images created by the Cluster-API Azure project if you do not specify your own. However, the Cluster-API Azure project has stopped publishing these images for Kubernetes 1.27, so you now must use KIB for Azure to build a Virtual Machine Image for DKP 2.7. Explore the Customize your Image topic for more options.
For more information regarding using the image in creating clusters, refer to the Azure Create a New Cluster section of the documentation.
Prerequisites
Before you begin, you must:
Download the Konvoy Image Builder bundle for your version of DKP.
Check the Supported Kubernetes Version for your Provider.
Create a working
Docker
setup.
Extract the KIB Bundle
Extract the bundle and cd
into the extracted konvoy-image-bundle-$VERSION_$OS
folder. The bundled version of konvoy-image
contains an embedded docker
image that contains all the requirements for building.
The konvoy-image
binary and all supporting folders are also extracted. When extracted, konvoy-image
bind mounts the current working directory (${PWD}
) into the container to be used.
Configure Azure Prerequisites
If you have already followed the Azure Prerequisites topic steps, then the environment variables needed by KIB ([AZURE_CLIENT_SECRET
, AZURE_CLIENT_ID
, AZURE_TENANT_ID
, AZURE_SUBSCRIPTION_ID
] ) are set and do not need repeated if you are still working in the same window.
If you have not executed the Azure Prerequisite steps, they are listed below.
Sign in to Azure:
CODEaz login
CODE[ { "cloudName": "AzureCloud", "homeTenantId": "a1234567-b132-1234-1a11-1234a5678b90", "id": "b1234567-abcd-11a1-a0a0-1234a5678b90", "isDefault": true, "managedByTenants": [], "name": "Mesosphere Developer Subscription", "state": "Enabled", "tenantId": "a1234567-b132-1234-1a11-1234a5678b90", "user": { "name": "user@azuremesosphere.onmicrosoft.com", "type": "user" } } ]
Create an Azure Service Principal (SP) by running the following command:
If an SP with the name exists, this command will rotate the password.
CODEaz ad sp create-for-rbac --role contributor --name "$(whoami)-konvoy" --scopes=/subscriptions/$(az account show --query id -o tsv) --query "{ client_id: appId, client_secret: password, tenant_id: tenant }"
CODE{ "client_id": "7654321a-1a23-567b-b789-0987b6543a21", "client_secret": "Z79yVstq_E.R0R7RUUck718vEHSuyhAB0C", "tenant_id": "a1234567-b132-1234-1a11-1234a5678b90" }
Set the
AZURE_CLIENT_SECRET
environment variable:CODEexport AZURE_CLIENT_SECRET="<azure_client_secret>" # Z79yVstq_E.R0R7RUUck718vEHSuyhAB0C export AZURE_CLIENT_ID="<client_id>" # 7654321a-1a23-567b-b789-0987b6543a21 export AZURE_TENANT_ID="<tenant_id>" # a1234567-b132-1234-1a11-1234a5678b90 export AZURE_SUBSCRIPTION_ID="<subscription_id>" # b1234567-abcd-11a1-a0a0-1234a5678b90
Ensure you have an override file to configure specific attributes of your Azure image.
Ensure you have named the correct file for your OS in the konvoy-image build
command.
Build the Image
Run the konvoy-image
command to build and validate the image.
konvoy-image build azure --client-id ${AZURE_CLIENT_ID} --tenant-id ${AZURE_TENANT_ID} --overrides override-source-image.yaml images/azure/ubuntu-2004.yaml
By default, the image builder builds in the westus2
location. To specify another location set the --location
flag (shown in example below is how to change the location to eastus
):
konvoy-image build azure --client-id ${AZURE_CLIENT_ID} --tenant-id ${AZURE_TENANT_ID} --location eastus --overrides override-source-image.yaml images/azure/centos-7.yaml
When the command is complete, the image id is printed and written to the ./packer.pkr.hcl
file. This file has an artifact_id
field whose value provides the name of the image. You should then specify this image id when creating the cluster.
Image Gallery
By default Konvoy Image Builder will create a Resource Group, Gallery, and Image Name to store the resulting image in. To specify a specific Resource Group, Gallery, or Image Name flags may be specified:
--gallery-image-locations string a list of locations to publish the image (default same as location)
--gallery-image-name string the gallery image name to publish the image to
--gallery-image-offer string the gallery image offer to set (default "dkp")
--gallery-image-publisher string the gallery image publisher to set (default "dkp")
--gallery-image-sku string the gallery image sku to set
--gallery-name string the gallery name to publish the image in (default "dkp")
--resource-group string the resource group to create the image in (default "dkp")
When creating your cluster, you will then add this flag during the create process for your custom image: --compute-gallery-id "<Managed Image Shared Image Gallery Id>"
. See Create a New Azure Cluster for specific consumption of image commands.
The SKU and Image Name will default to the values found in the image YAML.
Ensure you have named the correct YAML file for your OS in the konvoy-image build
command.
Marketplace Images for Rocky Linux
Similar to Image Gallery, additional flags allow DKP to create a cluster with Marketplace based images for Rocky Linux 9.0: --plan-offer
, --plan-publisher
and --plan-sku
.
If you use these fields in the override file when you create a machine image with KIB, you must also set the corresponding flags when you create your cluster with DKP.
Conversely, if you do not use these fields when you create a machine image with KIB, you do not need to set these flags when you create your cluster with DKP.