# EC2 Image Builder: Create a New Image Recipe

- URL: https://karandeepsingh.ca/posts/create-a-new-image-recipe/
- Author: Karandeep Singh
- Published: 2022-04-02
- Updated: 2026-02-14
- Tags: aws, ec2
- Summary: How to create a new version of an EC2 Image Builder image recipe, update the pipeline, and verify the AMI build through testing and distribution.

EC2 Image Builder uses **image recipes** to define the base image and components that make up your custom AMI. When you need to update packages, add new components, or change the base image, you create a new version of the recipe rather than editing the existing one. This ensures you maintain a versioned history of your AMI configurations.

This guide walks through creating a new recipe version, updating your pipeline to use it, and verifying the resulting AMI.

## Prerequisites

- An existing EC2 Image Builder pipeline with an image recipe
- IAM permissions for EC2 Image Builder, EC2, and Systems Manager

## Step 1: Go to the Existing Image Recipe

Open the EC2 Image Builder console and go to **Image recipes**. Select the recipe you want to update.

![Go to EC2 Image Builder Image Recipes](https://karandeepsingh.ca/images/screenshots/medium-044-1_jOHn1XYoW1fMWsaEi407BA.png)

## Step 2: Create a New Version

From the recipe detail page, click **Create new version**. This pre-fills the configuration from the existing recipe so you only need to change what's different.

![Create a new version of the image recipe](https://karandeepsingh.ca/images/screenshots/medium-009-1_8HlSx2PvJa2z8uliqXfWVA.png)

## Step 3: Update the Version Number

Increment the version number following semantic versioning (e.g., `1.0.0` to `1.1.0` for minor changes, `2.0.0` for major changes).

![Update the image recipe version number](https://karandeepsingh.ca/images/screenshots/medium-032-1__PDBGoASRvzWqvM03PEttw.png)

## Step 4: Modify Components and Settings

Update any components, build steps, or configuration options as needed. This is where you add new packages, update security patches, or change the base image. Click **Create recipe** when done.

![Update image recipe options and create](https://karandeepsingh.ca/images/screenshots/medium-031-1_ZDzxKVvAUaD7H3MkDNvglw.png)

## Step 5: Verify the New Recipe Version

Confirm the new version appears in the recipe list. Image Builder maintains all previous versions for rollback if needed.

![Verify the new recipe version is listed](https://karandeepsingh.ca/images/screenshots/medium-018-1_Iq760LohAVQ1W8NuYao4pA.png)

## Step 6: Navigate to the Image Pipeline

Go to **Image pipelines** and select the pipeline that uses this recipe.

![Navigate to EC2 Image Builder pipelines](https://karandeepsingh.ca/images/screenshots/medium-013-1_ClNpWLE5MBurcYrK5XeWxg.png)

## Step 7: Edit the Pipeline

Click **Edit pipeline** to update its configuration.

![Edit the image pipeline](https://karandeepsingh.ca/images/screenshots/medium-023-1_NqmTGnxXpB0bjeMvyC6aaQ.png)

## Step 8: Update the Recipe Version

In the pipeline settings, change the image recipe to the new version you just created. Save your changes.

![Update pipeline to use new recipe version](https://karandeepsingh.ca/images/screenshots/medium-025-1_SGL-T22p_kbAZWqKKTB4kA.png)

## Step 9: Run the Pipeline

Trigger a manual pipeline run to build an AMI from the updated recipe.

![Run the image pipeline](https://karandeepsingh.ca/images/screenshots/medium-052-1_xgTb8r9ENN2e_ySwF5Pk0A.png)

![Pipeline execution started](https://karandeepsingh.ca/images/screenshots/medium-042-1_gSrmC2kDHtILxlGydPjraA.png)

## Step 10: Monitor the Build Instance

During the build phase, Image Builder launches a temporary EC2 instance to create the AMI. You can see this instance in the **EC2 Console > Instances** section.

![Temporary EC2 instance used for AMI build](https://karandeepsingh.ca/images/screenshots/medium-045-1_k2SeWqfDX0hrMspl_wqWVg.png)

## Step 11: Check Systems Manager Run Command

Image Builder uses **AWS Systems Manager** to execute build and test commands on the instance. Navigate to **Systems Manager > Run Command** to monitor progress.

![Systems Manager Run Command](https://karandeepsingh.ca/images/screenshots/medium-001-1_xZE_j1RczlVkM9z-guDEOw.png)

## Step 12: Review Command History

The command history shows all commands that have been executed on the build instance, including component installations and test scripts.

![Command history in Systems Manager](https://karandeepsingh.ca/images/screenshots/medium-048-1_rPmyauFEszcgWx7j8U0u9A.png)

## Step 13: Check the New AMI

Navigate to **EC2 Console > AMIs**. The new AMI will appear with a status of "Pending" during creation.

![New AMI being created in EC2 Console](https://karandeepsingh.ca/images/screenshots/medium-011-1_9a__i9HxxJAqnXp3vQ0vsg.png)

## Step 14: Wait for the Testing Phase

Once the AMI becomes "Available", the pipeline enters the **Testing phase**. Image Builder runs any test components defined in the recipe to validate the AMI.

![Pipeline enters testing phase](https://karandeepsingh.ca/images/screenshots/medium-017-1_He6RRF1R2zT8MK0x9CpMSg.png)

![Testing phase in progress](https://karandeepsingh.ca/images/screenshots/medium-029-1_Ueo6puvSdQfJ5y76G5CUsQ.png)

## Step 15: Distribution

After testing completes successfully, the pipeline moves to the **Distribution phase**. The AMI is distributed according to your distribution settings (target regions, shared accounts, etc.) and the pipeline status changes to "Available".

![Distribution phase completed](https://karandeepsingh.ca/images/screenshots/medium-030-1_YMk1dnXR9Aoc-BT0P7hIxA.png)

![Pipeline completed successfully](https://karandeepsingh.ca/images/screenshots/medium-012-1_AutnG5epZx2Vqy8H7U0_pQ.png)

The entire build-test-distribute cycle typically takes 20-30 minutes depending on instance type and the number of components being installed.