Skip to main content
Learn how to automate AMI creation with EC2 Image Builder. In this guide, we’ll set up a pipeline that uses Amazon Linux 2 as a base, installs Nginx, runs validation and reboot tests, and outputs a ready-to-use Nginx AMI.
  • An AWS account with Image Builder, EC2, and IAM permissions
  • An IAM role or instance profile with ImageBuilderInstanceProfile and iam:PassRole
  • AWS Management Console access

​
1. Access EC2 Image Builder

  1. Sign in to the AWS Management Console.
  2. In the Services menu, search for EC2 Image Builder.
  3. Open the service to view the Image Builder dashboard, which highlights three main steps: Recipe, Infrastructure configuration, and Distribution.
The image shows the AWS EC2 Image Builder interface, detailing steps for creating an image pipeline, including creating a recipe, defining infrastructure configuration, and setting distribution options.

​
2. Create a New Image Pipeline

  1. Click Create image pipeline.
  2. Enter a Pipeline name (e.g., nginx-pipeline).
  3. Add a description such as Install Nginx.
  4. Enable Enhanced metadata collection to capture detailed build metrics.
  5. Optionally, turn on security scanning for vulnerability reports.
The image shows an AWS console interface for creating an image pipeline, with options for enhanced metadata collection and security scanning settings. A description field is filled with "install nginx," and there are scheduling options for the build.

​
3. Schedule Your Builds

You can trigger your image builds automatically or manually.
Schedule TypeDescription
ManualRun the pipeline on demand
CRONAutomate builds on a time-based schedule
For this demo, select Manual.
The image shows an AWS console interface for setting up a build schedule in Image Builder, with options for schedule builder, CRON expression, and manual execution. The selected schedule is set to run weekly on Mondays at 09:00 UTC.

​
4. Define Your Recipe

A recipe lists the components and settings for your AMI.
  1. Click Next and choose Create new recipe.
  2. Select AMI as the target image type.
  3. Fill out the form:
FieldValue
Namenginx
Version1.22.0
DescriptionInstall Nginx latest
Base ImageQuick Start → Amazon Linux 2 (ARM64)
  1. Check Remove after build to uninstall the SSM agent post-build.
  2. Leave the working directory at /tmp.
Ensure the version follows semantic versioning (x.y.z) to avoid validation errors.
The image shows an AWS Image Builder configuration screen where a user is setting up a pipeline with the name "nginx" and version "1.22," but there's an error indicating the version format is incorrect.
The image shows an AWS console interface for creating a pipeline, with options to select image origins like CentOS, Red Hat, and SUSE, and configuration settings for instance management.

​
5. Create a Build Component

Components are YAML definitions that execute commands in phases.
  1. Click Create build component.
  2. Choose Linux as the compatible OS.
  3. Fill in component details:
    • Name: nginx
    • Version: 1.22.0
    • Description: Install Nginx version 1.22.0
  4. In the YAML editor, define the build, validate, and test phases: 
name: install-nginx-latest
description: Install Nginx version 1.22.0
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: update-os
        action: ExecuteBash
        inputs:
          commands:
            - sudo yum update -y
      - name: install-nginx
        action: ExecuteBash
        inputs:
          commands:
            - sudo amazon-linux-extras enable nginx1
            - sudo yum install nginx -y
      - name: enable-nginx
        action: ExecuteBash
        inputs:
          commands:
            - sudo systemctl enable nginx

  - name: validate
    steps:
      - name: validate-status
        action: ExecuteBash
        inputs:
          commands:
            - systemctl status nginx

  - name: test
    steps:
      - name: reboot-test
        action: ExecuteBash
        inputs:
          commands:
            - sudo reboot
The image shows an AWS console interface for creating a build component in Amazon Linux, with options to select and filter components. A cursor is hovering over the "Create build component" button.
The image shows an AWS Image Builder console screen where a user is configuring component details, including selecting the operating system as Linux and specifying component version and name.
Save the component. Back in the pipeline wizard, filter Components by Owned by me and select your nginx component.

​
6. Add Tests

By default, Image Builder offers several tests. Select the Reboot Test to ensure the AMI boots correctly after a restart.
The image shows an AWS console interface for creating an image pipeline, specifically focusing on selecting test components for Amazon Linux. It includes options for verifying the output AMI and a list of test components.
The image shows an AWS console interface for creating a pipeline, specifically selecting test components for Amazon Linux, with a focus on a "reboot-test-linux" component.

​
7. Configure Storage

Specify EBS settings for the build instance’s root volume:
  • Size: 8 GB
  • Type: gp3
  • IOPS: Default
  • Encryption: Enable (recommended)
The image shows an AWS console interface for configuring storage volumes, including options for EBS volume size, type, and encryption settings. There are also fields for adding tags to the configuration.

​
8. Select a Workflow

Choose Default to let Image Builder orchestrate phases automatically. Use Custom if you need to reorder or skip specific steps.
The image shows an AWS EC2 Image Builder interface where a user is defining an image creation process, with options for selecting default or custom workflows.

​
9. Infrastructure Configuration

Define the compute environment for builds:
  1. Click Create new configuration.
  2. Name it (e.g., nginx-build-config).
  3. Attach an IAM instance profile with ImageBuilderInstanceProfile.
  4. Choose an instance type, such as t4g.medium for ARM64.
  5. Optionally, add an SNS topic for notifications.
The image shows an AWS EC2 Image Builder interface for defining infrastructure configuration, with options to create or use existing configurations and details about IAM instance profiles.

​
10. Distribution Settings

By default, the AMI is shared in the current account and region. Add other accounts or regions if you need cross-account or cross-region distribution.
The image shows an AWS console interface for defining distribution settings in an EC2 image builder pipeline. It includes options for configuration and region settings.

​
11. Review & Create

Double-check all settings:
  • Pipeline name and metadata
  • Recipe details
  • Component tests
  • Storage configuration
  • Workflow selection
  • Infrastructure profile
  • Distribution targets
Click Create pipeline to launch.
The image shows an AWS EC2 Image Builder interface reviewing pipeline details for creating an image pipeline named "nginx," with settings for metadata collection and scanning.
The image shows an AWS console interface for creating an image pipeline, detailing instance configuration, storage volumes, and image creation process steps.

​
12. Run the Pipeline

  1. Navigate to Image pipelines in the console.
  2. Select your newly created nginx-pipeline.
  3. Click Run pipeline.
The status will change to Building.
The image shows the AWS EC2 Image Builder interface with a successful image pipeline execution notification. It displays details of an image pipeline named "nginx" with its status, type, creation time, version, and ARN.

​
13. Monitor Build Execution

As the pipeline runs, a build instance spins up. To view logs:
  1. Under Pipeline executions, select the active run.
  2. Click Log stream to open CloudWatch Logs.
The image shows an AWS CloudWatch interface displaying log events related to an image build process, including timestamps and messages about the state transitions and instance launches.

​
14. Verify AMI Creation

After completion, go to the EC2 AMIs console.
Filter by Owned by me to confirm your new AMI and its status.
The image shows an Amazon Web Services (AWS) EC2 console displaying details of an Amazon Machine Image (AMI) with ID ami-053941b29e996e446, including its status, architecture, and platform details.

​
15. Test Instance Launch

Image Builder automatically launches a test instance:
  1. It boots the AMI.
  2. Runs the reboot-test.
  3. Terminates the instance upon success.
Check the EC2 Instances console or the component library to confirm.
The image shows an AWS EC2 Image Builder interface displaying a list of components, with one component named "nginx latest" for Linux. There's a notification about viewing components after subscribing to a CIS-hardened image.
To dive deeper into execution details, view the CloudWatch logs:
The image shows an AWS CloudWatch console displaying log entries related to system executions and command completions. The logs include timestamps and details about various execution steps and their outcomes.

​
16. Completion

When the test instance terminates successfully and the pipeline status shows Available, your custom Nginx AMI is ready to deploy.

Watch Video