Create a Custom AMI

Learn how to build a custom AMI for use with DKP

This procedure describes how to use the Konvoy Image Builder (KIB) to create a Cluster API compliant Amazon Machine Image (AMI). AMI images contain configuration information and software to create a specific, pre-configured, operating environment. For example, you can create an AMI image of your current computer system settings and software. The AMI 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 AMI.

The default AWS image is not recommended for use in production. We suggest using Konvoy Image Builder to Create a Custom AMI to take advantage of enhanced cluster operations, and to explore the Advanced AWS Install topics for more options.

Prerequisites

Before you begin, you must:

Check the DKP Supported Kubernetes Versions and download 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.
Ensure you have met the minimal set of permissions from the AWS Image Builder Book.

Extract AMI Bundle

Extract the bundle and cd into the extracted konvoy-image-bundle-$VERSION 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 run, konvoy-image bind mounts the current working directory (${PWD}) into the container to be used.

Set environment variables for AWS access. The following variables must be set using your credentials including required IAM:
CODE
```
export AWS_ACCESS_KEY_ID
export AWS_SECRET_ACCESS_KEY
export AWS_DEFAULT_REGION
```
Ensure you have an override file to configure specific attributes of your AMI file.

Build the Image

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.

Execute the following to begin image creation:

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

CODE

konvoy-image build images/ami/centos-79.yaml

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

CODE

./konvoy-image build --region us-east-1 images/ami/centos-79.yaml

When the command is complete the ami id is printed and written to ./manifest.json.

Launch a DKP Cluster with a Custom AMI

To use the built ami with DKP, specify it with the --ami flag when calling cluster create.

CODE

dkp create cluster aws --cluster-name=$(whoami)-aws-cluster --ami ami-0123456789

Launch a DKP Cluster with Custom AMI Lookup

By default konvoy-image will name the AMI in such a way that dkp can discover the latest AMI for a base OS and Kubernetes version. To create a cluster that will use the latest AMI, specify the --ami-format, --ami-base-os and --ami-owner flags:

CODE

dkp create cluster aws --cluster-name=$(whoami)-aws-cluster --ami-format "konvoy-ami-{{.BaseOS}}-?{{.K8sVersion}}-*" --ami-base-os centos-7 --ami-owner 123456789012

CODE

Using custom source AMIsWhen using KIB for building machine images to Amazon, the default source AMIs that we provide are based on looking up an AMI based on the owner, and a filter for that operating system and version.You can view an example of that with the provided `centos-79.yaml` snippet below:```yamldownload_images: truepacker:  ami_filter_name: "CentOS 7.9.2009 x86_64"  ami_filter_owners: "125523088429"  distribution: "CentOS"  distribution_version: "7.9"  source_ami: ""  ssh_username: "centos"  root_device_name: "/dev/sda1"...```At times, a particular upstream AMI may not be available in your region, or something could be renamed, or perhaps you want to provide a custom AMI for whatever reason you need.If this is the case, you will want to edit, or create your own, yaml file that looks up based on the `source_ami` field.For example, [CentOS also provides an image](https://wiki.centos.org/Cloud/AWS) on the [AWS marketplace](https://aws.amazon.com/marketplace/pp/prodview-foff247vr2zfw) which you can subscribe to for free.Once you select the source AMI that you want, you can declare that when running your build command:```bash./konvoy-image build path/to/ami/centos-79.yaml --source-ami ami-0123456789```Alternatively, if you want to add it to your yaml file, or are making your own file, you can do that as well.You just need to add that AMI ID into the `source_ami` in the yaml file:```yamldownload_images: truepacker:  ami_filter_name: ""  ami_filter_owners: ""  distribution: "CentOS"  distribution_version: "7.9"  source_ami: "ami-123456789"  ssh_username: "centos"  root_device_name: "/dev/sda1"...```When you're done selecting your `source_ami`, you can build your KIB image as you would normally:```bashkonvoy-image build path/to/ami/centos-79.yaml```

Using Custom Source AMIs

When using KIB for building machine images to Amazon, the default source AMIs that we provide are modeled by looking up an AMI based on the owner. Then we apply a filter for that operating system and version.

You can view an example of that with the provided centos-79.yaml snippet below:

CODE

yaml
download_images: true

packer:
  ami_filter_name: "CentOS Linux 7"  
  ami_filter_owners: "125523088429"  
  distribution: "CentOS"  
  distribution_version: "7.9"  
  source_ami: ""  
  ssh_username: "centos"  
  root_device_name: "/dev/sda1"
...

At times, a particular upstream AMI may not be available in your region or something could be renamed. Other times you want to provide a custom AMI. If this is the case, you will want to edit or create your own YAML file that looks up based on the source_ami field. For example, CentOS also provides an image on the AWS marketplace or you can select other images that are otherwise deprecated.

Once you select the source AMI that you want, you can declare that when running your build command:

CODE

./konvoy-image build path/to/ami/centos-79.yaml --source-ami ami-0123456789

Alternatively, if you want to add it to your YAML file, or make your own file, you can do that as well. You add that AMI ID into the source_ami in the YAML file:

CODE

yaml
download_images: true

packer:
  ami_filter_name: ""
  ami_filter_owners: ""
  distribution: "CentOS"
  distribution_version: "7.9"
  source_ami: "ami-123456789"
  ssh_username: "centos"
  root_device_name: "/dev/sda1"
...

When you're done selecting your source_ami, you can build your KIB image as you would normally:

CODE

konvoy-image build path/to/ami/centos-79.yaml

Related Information

For information on related topics or procedures, refer to the following:

Creating GPU enabled on-premises configurations