Custom AMI in Cluster Creation

The default AWS image is not recommended for use in production. D2iQ suggests using Konvoy Image Builder to create a custom AMI and take advantage of enhanced cluster operations.

⚠️ IMPORTANT: The AMI must be created with Konvoy Image Builder in order to use the registry mirror feature.

Depending on which version of DKP you are running, steps and flags will be different. To deploy in a region where CAPI images are not provided, you need to use KIB to create your own image for the region. For a list of supported AWS regions, refer to the Published AMI information from AWS.

Begin image creation:

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

CODE

konvoy-image build aws images/ami/rhel-86.yaml

By default it builds in the us-west-2 region. to specify another region set the --region flag as shown in the command below:

CODE

konvoy-image build aws --region us-east-1 images/ami/rhel-86.yaml

Ensure you have named the correct AMI image YAML file for your OS in the konvoy-image build command.

After KIB provisions the image successfully, the ami id is printed and written to the packer.pkr.hcl (Packer config) file. This file has an artifact_id field whose value provides the name of the AMI ID as shown in the example below. That is the ami you use in the dkp create cluster command:

CODE

{
  "builds": [
    {
      "name": "kib_image",
      "builder_type": "amazon-ebs",
      "build_time": 1698086886,
      "files": null,
      "artifact_id": "us-west-2:ami-04b8dfef8bd33a016",
      "packer_run_uuid": "80f8296c-e975-d394-45f9-49ef2ccc6e05",
      "custom_data": {
        "containerd_version": "",
        "distribution": "RHEL",
        "distribution_version": "8.6",
        "kubernetes_cni_version": "",
        "kubernetes_version": "1.26.6"
      }
    }
  ],
  "last_run_uuid": "80f8296c-e975-d394-45f9-49ef2ccc6e05"
}

To use a custom AMI when creating your cluster, you must create that AMI using KIB first. Then perform the export and name the custom AMI for use in the command dkp create cluster:

CODE

export AWS_AMI_ID=ami-<ami-id-here>

Inside the sections for either Non-air-gapped or Air-gapped cluster creation, you will find the instructions for how to apply custom images.

The export command is similar to this:

CODE

export AWS_AMI_ID=ami-ami-04b8dfef8bd33a016

The create cluster command would then be:

CODE

dkp create cluster aws \
--cluster-name=${CLUSTER_NAME} \
--additional-tags=owner=$(whoami) \
--with-aws-bootstrap-credentials=true \
--ami AMI_ID

OR for ID lookup:

CODE

dkp create cluster aws \
--cluster-name=${CLUSTER_NAME} \
--additional-tags=owner=$(whoami) \
--with-aws-bootstrap-credentials=true \
--ami-owner AWS_ACCOUNT_ID \
--ami-base-os ubuntu-20.04 \
--ami-format 'konvoy-ami-{{.BaseOS}}-?{{.K8sVersion}}-*'

More information about using the custom AMI in cluster creation can be found here: Use Custom AMI to Build Cluster.

Next Step

AWS Bootstrap Cluster