Custom Kubernetes AMIs

Cluster API uses the Kubernetes Image Builder tools. You should use the AWS images from that project as a starting point for your custom image.

The Image Builder Book explains how to build the images defined in that repository, with instructions for AWS CAPI Images in particular.

Operating system requirements

For custom images to work with Cluster API, it must meet the operating system requirements of the bootstrap provider. For example, the default kubeadm bootstrap provider has a set of [preflight checks][kubeadm-preflight-checks] that a VM is expected to pass before it can join the cluster.

Kubernetes version requirements

The pre-built public images are each built to support a specific version of Kubernetes. When using custom images, make sure to match the image to the version: field of the KubeadmControlPlane and MachineDeployment in the YAML template for your workload cluster.

To upgrade to a new Kubernetes release with custom images requires this preparation:

• create a new custom image which supports the Kubernetes release version
• copy the existing AWSMachineTemplate and change its ami: section to reference the new custom image
• create the new AWSMachineTemplate on the management cluster
• modify the existing KubeadmControlPlane and MachineDeployment to reference the new AWSMachineTemplate and update the version: field to match

See Upgrading workload clusters for more details.

Creating a cluster from a custom image

To use a custom image, it needs to be referenced in an ami: section of your AWSMachineTemplate.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AWSMachineTemplate
metadata:
  name: capa-image-id-example
  namespace: default
spec:
  template:
    spec:
      ami:
        id: ami-09709369c53539c11
      iamInstanceProfile: control-plane.cluster-api-provider-aws.sigs.k8s.io
      instanceType: m5.xlarge
      sshKeyName: default