# Manage custom image creation in Image Builder through a repeatable pipeline process Manage pipelines Image Builder image pipelines provide an automation framework for creating and maintaining custom AMIs and container images. Pipelines deliver the following functionality: + Assemble the base image, build and test components for image customization, infrastructure configuration, and distribution settings. + Facilitate scheduling for automated maintenance processes using the `Schedule builder` in the console wizard, or entering cron expressions for recurring updates to your images. + Enable change detection for the base image and components, to automatically skip scheduled builds when there are no changes. + Enable rule-based automation through Amazon EventBridge. **Note** For more information about using the EventBridge API to view or change rules, see the [Amazon EventBridge API Reference](https://docs.aws.amazon.com/eventbridge/latest/APIReference/). For more information about using EventBridge **events** commands in the AWS CLI to view or change rules, see [events](https://docs.aws.amazon.com/cli/latest/reference/events/) in the *AWS CLI Command Reference*. **Topics** + [ # Configure pipeline execution settings for image pipelines ](schedule-pipeline.md) + [ # List and view pipeline details ](pipeline-details.md) + [ # Create and update AMI image pipelines ](ami-image-pipelines.md) + [ # Create and update container image pipelines ](container-image-pipelines.md) + [ # Configure image pipeline workflows in Image Builder ](pipeline-workflows.md) + [ # Use EventBridge rules with Image Builder pipelines ](ev-rules-for-pipeline.md) # Configure pipeline execution settings for image pipelines Configure pipeline execution You can choose from the following options to schedule pipeline execution: Schedule Builder Use the Schedule Builder to configure automatic, recurring pipeline execution. You define when and how often your pipeline should run (day, time, and frequency). The default schedule is every week based on the day and time that the schedule is created (UTC). Cron expression Automatically run the pipeline with a cron expression that specifies the schedule. For more information about the cron syntax that Image Builder uses, see [Use cron expressions in Image Builder](cron-expressions.md). Manual The pipeline does not run on a schedule. In the console, choose **Run pipeline** from the **Actions** menu to run the pipeline. From the AWS CLI, you can run `start-image-pipeline-execution`. **Dependency settings** For scheduled builds, you can choose whether to always run on the schedule or to skip pipeline execution unless there are dependency updates, such as a change to the base image or to a component that's used in the recipe. ## Automatically disable a failing pipeline For image pipelines that run on a schedule, you can configure the maximum number of consecutive failures to allow (up to`10`) before Image Builder automatically disables the pipeline. **Auto-disable settings** Image Builder tracks the number of consecutive failures for scheduled pipeline executions and takes one of the following actions each time it runs on a schedule: + If the pipeline execution is successful, the number of consecutive failures resets to zero. + If the pipeline execution fails, Image Builder increments the number of consecutive failures. If the failure count exceeds the limit defined in the `AutoDisablePolicy`, Image Builder disables the pipeline. The consecutive failure count is also reset to zero under the following conditions: + The pipeline runs manually and succeeds. + The pipeline configuration is updated. If the pipeline runs manually and fails, the count remains the same. The next scheduled run continues to increment where it left off before. ## Configure pipeline logging When you create or update an image pipeline, you can configure custom CloudWatch Logs groups for image build and pipeline logs. Make sure that your custom pipeline execution role has the following permissions to create and access the log group resources. + logs:CreateLogGroup + logs:CreateLogStream + logs:PutLogEvents **Custom log groups** To use custom log groups for image build or pipeline execution, first create the log group in CloudWatch Logs. For more information, see [Create a log group](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#Create-Log-Group) in the *Amazon CloudWatch Logs User Guide*. For additional guidance on log group naming requirements, see [CreateLogGroup](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogGroup.html) in the *Amazon CloudWatch Logs API Reference*. ------ #### [ Console ] Specify the **Image log group** or **Pipeline log group** for your pipeline in the **Logging configuration** section under **Advanced settings**. ------ #### [ CLI ] Specify the following fields within the `logging-configuration` object if you use a JSON object for configuration: + `imageLogGroupName` + `pipelineLogGroupName` To specify all parameters directly in the command line, see [create-image-pipeline](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-image-pipeline.html) in the *AWS CLI Command Reference*. ------ Image Builder uses the following default log groups if you don't specify a custom log group: Image build logs Image Builder writes build logs to the following Image Builder CloudWatch Logs group and stream: **LogGroup:** `/aws/imagebuilder/ImageName` **LogStream (x.x.x/x):** `ImageVersion/ImageBuildVersion` Pipeline execution logs Image Builder writes pipeline execution logs to the following Image Builder CloudWatch Logs group and stream: **LogGroup:** `/aws/imagebuilder/pipeline/pipeline-name` **LogStream:** `2025/09/01` (the pipeline execution date in YYYY/MM/DD format) Each pipeline log is appended to the stream for that day. # Run an image pipeline manually Run pipeline manually If you chose the manual schedule option for your pipeline, it will only run when you manually kick off the build. If you chose one of the automatic scheduling options, you can also run it manually, in between regularly scheduled runs. For example, if you have a pipeline that normally runs once a month, but you need to incorporate an update to one of your components two weeks after the prior run, you can choose to run your pipeline manually. ------ #### [ Console ] To run your pipeline from the pipeline details page in the Image Builder console, choose **Run pipeline** from the **Actions** menu at the top of the page. A status message appears at the top of the page to notify you that your pipeline has started, or if there is an error. 1. In the upper left corner of the pipeline details page, choose **Run pipeline**, from the **Actions** menu. 1. You can see the current status of your pipeline on the **Output images** tab, in the **Status** column. ------ #### [ AWS CLI ] The following example shows how to use the **[start-image-pipeline-execution](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/start-image-pipeline-execution.html)** command in the AWS CLI to start an image pipeline manually. When you run this command, the pipeline builds and distributes a new image. ``` aws imagebuilder start-image-pipeline-execution --image-pipeline-arn arn:aws:imagebuilder:us-west-2:111122223333:image-pipeline/my-example-pipeline ``` To see what resources are created when the build pipeline runs, see [Resources created](how-image-builder-works.md#image-builder-resources). ------ # Use cron expressions in Image Builder Use cron expressions Use cron expressions for EC2 Image Builder to set up a time window to refresh your image with updates that apply to your pipeline's base image and components. The time window for your pipeline refresh starts with the time you set in the cron expression. You can set the time in your cron expression down to the minute. Your pipeline build can run on or after the start time. It can sometimes take a few seconds, or up to a minute for your build to start running. **Note** Cron expressions use the Universal Coordinated Time (UTC) time zone by default, or you can specify the time zone. For more information about UTC time, and to find the offset for your time zone, see [Time Zone Abbreviations – Worldwide List](https://www.timeanddate.com/time/zones/). ## Supported values for cron expressions in Image Builder EC2 Image Builder uses a cron format that consists of six required fields. Each one is separated from the others by a space in between, with no leading or trailing spaces: ` ` The following table shows supported values for required cron entries. **Supported values for cron expressions** | Field | Values | Wildcards | | --- | --- | --- | | Minute | 0-59 | , - \$1 / | | Hour | 0-23 | , - \$1 / | | Day | 1-31 | , - \$1 ? / L W | | Month | 1-12 or jan-dec | , - \$1 / | | Day of the week | 1-7 or sun-sat | , - \$1 ? L \$1 | | Year | 1970-2199 | , - \$1 / | **Wildcards** The following table describes how Image Builder uses wildcards for cron expressions. Keep in mind that it can take up to a minute after the time you specify for the build to start. **Supported wildcards for cron expressions** | Wildcard | Description | | --- | --- | | , | The , (comma) wildcard includes additional values. In the Month field, jan,feb,mar includes January, February, and March. | | - | The - (dash) wildcard specifies ranges. In the day of the month field, 1-15 includes days 1 through 15 of the specified month. | | \$1 | The \$1 (asterisk) wildcard includes all valid values for the field. | | ? | The ? (question mark) wildcard specifies that the field value depends on another setting. In the case of the Day and Day-of-week fields, when one is specified or includes all possible values (\$1), the other must be a ?. You cannot specify both. For example, if you enter a 7 in the Day field (run the build on the seventh day of the month), the Day-of-week position must contain a ?. | | / | The / (forward slash) wildcard specifies increments. For example, if you want your build to run every other day, enter \$1/2 in the day field. | | L | The L wildcard in either of the day fields, specifies the last day: 28-31 for the day of the month, depending on what the month is, or Sunday, for the day of the week. | | W | The W wildcard in the Day-of-month field specifies a weekday. In the Day-of-month field, if you enter a number prior to the W, that means you want to target the weekday that is closest to that day. For instance, if you specify 3W, you want your build to run on the weekday closest to the third day of the month. | | \$1 | The \$1 (hash) is allowed only for the day of the week field, and must be followed by a number between 1 and 5. The number specifies which weeks in a given month apply for the build to run. For example, if you want your build to run on the second Friday of each month, use fri\$12 for the day of the week field. | **Restrictions** + You can't specify the Day-of-month and Day-of-week fields in the same cron expression. If you specify a value or `*` in one of these fields, you must use a `?` in the other. + Cron expressions that lead to rates faster than one minute are not supported. ## Examples of cron expressions in Image Builder Cron expressions are entered differently for the Image Builder console, than they are for the API or CLI. To see examples, choose the tab that applies to you. ------ #### [ Image Builder console ] The following examples show cron expressions that you can enter into the console for your build schedule. UTC time is specified using a 24-hour clock. **Run daily at 10:00 AM (UTC)** `0 10 * * ? *` **Run daily at 12:15 PM (UTC)** `15 12 * * ? *` **Run daily at midnight (UTC)** `0 0 * * ? *` **Run at 10:00 AM (UTC) every weekday morning** `0 10 ? * 2-6 *` **Run at 6 PM (UTC) every weekday evening** `0 18 ? * mon-fri *` **Run at 8:00 AM (UTC) on the first day of every month** `0 8 1 * ? *` **Run on the second Tuesday of every month at 10:30 PM (UTC)** `30 22 ? * tue#2 *` **Tip** If you don't want your pipeline job to extend into the next day while it's running, make sure that you factor in time for your build when you specify the start time. ------ #### [ API/CLI ] The following examples show cron expressions that you can enter for your build schedule using CLI commands or API requests. Only the cron expression is shown. **Run daily at 10:00 AM (UTC)** `cron(0 10 * * ? *)` **Run daily at 12:15 PM (UTC)** `cron(15 12 * * ? *)` **Run daily at midnight (UTC)** `cron(0 0 * * ? *)` **Run at 10:00 AM (UTC) every weekday morning** `cron(0 10 ? * 2-6 *)` **Run at 6:00 PM (UTC) every weekday evening** `cron(0 18 ? * mon-fri *)` **Run at 8:00 AM (UTC) on the first day of every month** `cron(0 8 1 * ? *)` **Run on the second Tuesday of every month at 10:30 PM (UTC)** `cron(30 22 ? * tue#2 *)` **Tip** If you don't want your pipeline job to extend into the next day while it's running, make sure that you factor in time for your build when you specify the start time. ------ ## Rate expressions in Image Builder Rate expressions A rate expression starts when you create the scheduled event rule, and then runs on its defined schedule. Rate expressions have two required fields. Fields are separated by white space. **Syntax** ``` rate(value unit) ``` *value* A positive number. *unit* The unit of time. Different units are required for values of 1, such as `minute`, and values over 1, such as `minutes`. Valid values: minute \$1 minutes \$1 hour \$1 hours \$1 day \$1 days **Restrictions** If the value is equal to `1`, then the unit must be singular. Similarly, for values greater than `1`, the unit must be plural. For example, `rate(1 hours)` and `rate(5 hour)` are not valid, but `rate(1 hour)` and `rate(5 hours)` are valid. # List and view pipeline details List and view pipelines This section describes the various ways that you can find information and view details for your EC2 Image Builder image pipelines. **Topics** + [ ## List image pipelines from the AWS CLI ](#cli-list-image-pipelines) + [ ## Get image pipeline details from the AWS CLI ](#cli-get-image-pipeline-details) ## List image pipelines from the AWS CLI The following example shows how to use the **list-image-pipelines** command in the AWS CLI to list all of your image pipelines. ``` aws imagebuilder list-image-pipelines ``` ## Get image pipeline details from the AWS CLI The following example shows how to use the **get-image-pipeline** command in the AWS CLI to get the details about an image pipeline through its ARN. ``` aws imagebuilder get-image-pipeline --image-pipeline-arn arn:aws:imagebuilder:us-west-2:123456789012:image-pipeline/my-example-pipeline ``` # Create and update AMI image pipelines Create and update pipelines (AMI) You can set up, configure, and manage AMI image pipelines from the Image Builder console, through the Image Builder API, SDKs or the AWS CLI. In the console, you can use the **Create image pipeline** console wizard to guide you through the following steps. + Specify pipeline details such as name, description, and resource tags. + Configure pipeline schedule and logging defaults. For scheduled pipeline execution, you can set the number of consecutive failures that are allowed before Image Builder disables the pipeline. + Select an AMI image recipe that includes a base image from quick-start Amazon managed images, images that you created or that were shared with you, or images that you subscribe to through the AWS Marketplace. The recipe also includes components that perform the following tasks on the EC2 instances that Image Builder uses to build your image: + Add and remove software + Customize settings and scripts + Run selected tests + Specify workflows to configure image build and test steps that your pipeline runs. + Define infrastructure configuration for your pipeline with default settings or settings that you configure yourself. Configuration includes the instance type and key pair to use for your image, security and network settings, log storage and troubleshooting settings, and SNS notifications. This is an *optional* step. Image Builder uses default settings for your infrastructure configuration if you don't define the configuration yourself. + Define distribution settings to deliver your images to destination AWS Regions and accounts. You can specify a KMS key for encryption, configure AMI sharing or license configuration, or configure a launch template for the AMIs you distribute. This is an *optional* step. If you don't define the configuration yourself, Image Builder uses default naming for your output AMI, and distributes the AMI to the source Region. The source Region is the Region where you run the pipeline. For more information and a step-by-step tutorial about using the **Create image pipeline** console wizard with default values where provided, see [Tutorial: Create an image pipeline with output AMI from the Image Builder console wizard](start-build-image-pipeline.md). **Topics** + [ # Create an AMI image pipeline from the AWS CLI ](cli-create-image-pipeline.md) + [ # Update AMI image pipelines from the console ](update-image-pipeline-console.md) + [ # Update AMI image pipelines from the AWS CLI ](cli-update-image-pipeline.md) # Create an AMI image pipeline from the AWS CLI Create AMI pipeline from the AWS CLI To create an image pipeline from the AWS CLI, run the **create-image-pipeline** command with the configuration options that apply for your pipeline. You have the option to create a JSON file that contains all of your pipeline configuration, or to specify configuration at runtime. This section uses the JSON configuration file method to simplify the command. How often your pipeline builds a new image to incorporate any pending updates from your base image and components depends on the `schedule` that you have configured. A `schedule` has the following attributes: + `scheduleExpression` – Sets the schedule for when your pipeline runs to evaluate the `pipelineExecutionStartCondition` and determine if it should start a build. The schedule is configured with cron expressions. For more information on how to format a cron expression in Image Builder, see [Use cron expressions in Image Builder](cron-expressions.md). + `pipelineExecutionStartCondition` – Determines if your pipeline should start the build. Valid values include: + `EXPRESSION_MATCH_ONLY` – your pipeline will build a new image every time the cron expression matches the current time. + `EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE` – your pipeline will not start a new image build unless there are pending changes to your base image or components. When you run the **create-image-pipeline** command in the AWS CLI, many of the configuration resources are optional. However, some of the resources have conditional requirements, depending on what type of image the pipeline creates. The following resource identifiers are required for AMI image pipelines: + Image recipe ARN + Infrastructure configuration ARN   **Example: Create a Windows 2019 image** This example configures a pipeline that is scheduled to run once a week on Sunday. The configuration file shown in the first step uses existing resources for the image recipe, infrastructure, and distribution configuration, along with other settings to create a Windows 2019 image. 1. **Create a configuration file (optional)** This example uses a configuration file named `create-image-pipeline.json` to configure the settings in one place. Alternatively, you can use command line options when you run the command to specify all of the details that are shown here in the configuration file. ``` { "name": "ExampleWindows2019Pipeline", "description": "Builds Windows 2019 Images", "enhancedImageMetadataEnabled": true, "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03", "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration", "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration", "imageTestsConfiguration": { "imageTestsEnabled": true, "timeoutMinutes": 60 }, "schedule": { "scheduleExpression": "cron(0 0 * * SUN *)", "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE" }, "status": "ENABLED" } ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). 1. **Run the command to create an image** This example uses the configuration file created in the first step as input to the `create-image-pipeline` command. Alternatively, you can specify the settings and resources for your pipeline directly when you run the command. For more information, see [create-image-pipeline](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-image-pipeline.html) in the *AWS CLI Reference*. ``` aws imagebuilder create-image-pipeline --cli-input-json file://create-image-pipeline.json ``` # Update AMI image pipelines from the console Update pipeline from the console After you have created an Image Builder image pipeline for your AMI image, you can make changes to the infrastructure configuration and distribution settings from the Image Builder console. To update an image pipeline with a new image recipe, you must use the AWS CLI. For more information, see [Update AMI image pipelines from the AWS CLI](cli-update-image-pipeline.md) in this guide. **Choose an existing Image Builder pipeline** 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. To see a list of the image pipelines created under your account, choose **Image pipelines** from the navigation pane. **Note** The list of image pipelines includes an indicator for the type of output image that is created by the pipeline – AMI or Docker. 1. To view details or edit a pipeline, choose the **Pipeline name** link. This opens the detail view for the pipeline. **Note** You can also select the check box next to the **Pipeline name**, then choose **View detail**. ## Pipeline details The pipeline details page includes the following sections: ****Summary**** The section at the top of the page summarizes key details for the pipeline that are visible with any of the detail tabs open. The details displayed in this section are editable only on their respective detail tabs. **Detail tabs** + **Output images** – Shows output images that the pipeline has produced. + **Image recipe** – Shows recipe details. After you create a recipe, you cannot edit it. You must create a new version of the recipe from the **Image recipes** page in the Image Builder console, or by using Image Builder commands in the AWS CLI. For more information, see [Manage recipes in Image BuilderRecipes](manage-recipes.md). + **Infrastructure configuration** – Shows editable information for configuring your build pipeline infrastructure. + **Distribution settings** – Shows editable information for AMI distribution. + **EventBridge rules** – For the selected **Event Bus**, shows EventBridge rules that target the current pipeline. Includes **Create event bus** and **Create rule** actions that link to the EventBridge console. For more information about this tab, see [Use EventBridge rules](ev-rules-for-pipeline.md). ## Edit infrastructure configuration for your pipeline Edit infrastructure configuration Infrastructure configuration includes the following details that you can edit after creating the pipeline: + The **Description** for your infrastructure configuration. + The **IAM role** to associate with the instance profile. + **AWS infrastructure**, including the **Instance type** and an **SNS topic** for notifications. + **VPC, subnet, and security groups**. + **Troubleshooting settings**, including **Terminate instance on failure**, the **Key pair** for connecting, and an optional S3 bucket location for instance logs. To edit infrastructure configuration from the pipeline details page, follow these steps: 1. Choose the **Infrastructure configuration** tab. 1. Choose **Edit** from the upper right corner of the **Configuration details** panel. 1. When you are ready to save updates you've made to your infrastructure configuration, choose **Save changes**. ## Edit distribution settings for your pipeline Edit distribution settings Distribution settings include the following details that you can edit after creating the pipeline: + The **Description** for your distribution configuration. + **Region settings** for the Regions where you distribute your image. Region 1 defaults to the Region where you created the pipeline. You can add Regions for distribution with the **Add Region** button, and you can remove all Regions except Region 1. **Region settings** include: + Target **Region** + The **Output AMI name** + **Launch permissions**, and accounts to share them with + Associated licenses (**Associate license configurations**) **Note** License Manager settings will not replicate across AWS Regions that must be enabled in your account, for example, between the `ap-east-1` (Hong Kong) and the `me-south-1` (Bahrain) Regions. To edit your distribution settings from the pipeline details page, follow these steps: 1. Choose the **Distribution settings** tab. 1. Choose **Edit** from the upper right corner of the **Distribution details** panel. 1. When you are ready to save your updates, choose **Save changes**. ## Edit the build schedule for your pipeline Edit build schedule The **Edit pipeline** page includes the following details that you can edit after creating the pipeline: + The **Description** for your pipeline. + **Enhanced metadata collection**. This is turned on by default. To turn it off, clear the **Enable enhanced metadata collection** check box. + The **Build schedule** for your pipeline. You can change your **Schedule options** and all of the settings here. To edit your pipeline from the pipeline details page, follow these steps: 1. In the upper right corner of the pipeline details page, choose **Actions**, and then **Edit pipeline**. 1. When you are ready to save your updates, choose **Save changes**. **Note** For more information about scheduling your build using cron expressions, see [Use cron expressions in Image Builder](cron-expressions.md). # Update AMI image pipelines from the AWS CLI Update pipeline from the AWS CLI You can update an AMI image pipeline using a JSON file as input to the **update-image-pipeline** command in the AWS CLI. To configure the JSON file, you must have Amazon Resource Names (ARNs) to reference the following existing resources: + Image pipeline to update + Image recipe + Infrastructure configuration + Distribution settings You can update an AMI image pipeline with the **update-image-pipeline** command in the AWS CLI as follows: **Note** UpdateImagePipeline does not support selective updates for the pipeline. You must specify all of the required properties in the update request, not just the properties that have changed. 1. **Create a CLI input JSON file** Use your favorite file editing tool to create a JSON file with the following keys, plus values that are valid for your environment. This example uses a file named `create-component.json`: ``` { "imagePipelineArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-pipeline/my-example-pipeline", "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2019.12.08", "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration", "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration", "imageTestsConfiguration": { "imageTestsEnabled": true, "timeoutMinutes": 120 }, "schedule": { "scheduleExpression": "cron(0 0 * * MON *)", "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE" }, "status": "DISABLED" } ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). 1. Run the following command, using the file you created as input. ``` aws imagebuilder update-image-pipeline --cli-input-json file://update-image-pipeline.json ``` # Create and update container image pipelines Create and update pipelines (container) You can set up, configure, and manage container image pipelines using the Image Builder console, through the Image Builder API, or with **imagebuilder** commands in the AWS CLI. The **Create image pipeline** console wizard provides starting artifacts, and guides you through steps to: + Select a base image from quick-start managed images, Amazon ECR, or Docker Hub repositories + Add and remove software + Customize settings and scripts + Run selected tests + Create a Dockerfile using pre-configured build-time variables. + Distribute images to AWS Regions For more information and a step-by-step tutorial about using the **Create image pipeline** console wizard, see [Tutorial: Create an image pipeline with output Docker container image from the Image Builder console wizard](start-build-container-pipeline.md). **Topics** + [ # Create a container image pipeline from the AWS CLI ](cli-create-container-pipeline.md) + [ # Update a container image pipeline from the console ](update-container-pipeline-console.md) + [ # Update container image pipelines from the AWS CLI ](cli-update-container-pipeline.md) # Create a container image pipeline from the AWS CLI Create pipeline from the AWS CLI To create an image pipeline from the AWS CLI, run the **create-image-pipeline** command with the configuration options that apply for your pipeline. You have the option to create a JSON file that contains all of your pipeline configuration, or to specify configuration at runtime. This section uses the JSON configuration file method to simplify the command. How often your pipeline builds a new image to incorporate any pending updates from your base image and components depends on the `schedule` that you have configured. A `schedule` has the following attributes: + `scheduleExpression` – Sets the schedule for when your pipeline runs to evaluate the `pipelineExecutionStartCondition` and determine if it should start a build. The schedule is configured with cron expressions. For more information on how to format a cron expression in Image Builder, see [Use cron expressions in Image Builder](cron-expressions.md). + `pipelineExecutionStartCondition` – Determines if your pipeline should start the build. Valid values include: + `EXPRESSION_MATCH_ONLY` – your pipeline will build a new image every time the cron expression matches the current time. + `EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE` – your pipeline will not start a new image build unless there are pending changes to your base image or components. When you run the **create-image-pipeline** command in the AWS CLI, many of the configuration resources are optional. However, some of the resources have conditional requirements, depending on what type of image the pipeline creates. The following resources are required for container image pipelines: + Container recipe ARN + Infrastructure configuration ARN If you do not include a distribution configuration resource when you run the **create-image-pipeline** command, the output image is stored in the ECR repository that you specify as the target repository in your container recipe in the Region where you run the command. If you include a distribution configuration resource for your pipeline, the target repository that you have specified for the first Region in the distribution is used. 1. **Create a CLI input JSON file** Use your favorite file editing tool to create a JSON file with the following keys, plus values that are valid for your environment. This example uses a file named `create-image-pipeline.json`: ``` { "name": "MyWindows2019Pipeline", "description": "Builds Windows 2019 Images", "enhancedImageMetadataEnabled": true, "containerRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.03", "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration", "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration", "imageTestsConfiguration": { "imageTestsEnabled": true, "timeoutMinutes": 60 }, "schedule": { "scheduleExpression": "cron(0 0 * * SUN *)", "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE" }, "status": "ENABLED" } ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). 1. Run the following command, using the file you created as input. ``` aws imagebuilder create-image-pipeline --cli-input-json file://create-image-pipeline.json ``` # Update a container image pipeline from the console Update pipeline from the console After you have created an Image Builder container image pipeline for your Docker image, you can make changes to the infrastructure configuration and distribution settings from the Image Builder console. To update a container image pipeline with a new container recipe, you must use the AWS CLI. For more information, see [Update container image pipelines from the AWS CLI](cli-update-container-pipeline.md) in this guide. **Choose an existing Image Builder Docker image pipeline** 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. To see a list of the image pipelines created under your account, choose **Image pipelines** from the navigation pane. **Note** The list of image pipelines includes an indicator for the type of output image that is created by the pipeline – AMI or Docker. 1. To view details or edit a pipeline, choose the **Pipeline name** link. This opens the detail view for the pipeline. **Note** You can also select the check box next to the **Pipeline name**, then choose **View detail**. ## Pipeline details The EC2 Image Builder pipeline details page includes the following sections: ****Summary**** The section at the top of the page summarizes key details for the pipeline that are visible with any of the detail tabs open. The details displayed in this section are editable only on their respective detail tabs. **Detail tabs** + **Output images** – Shows output images that the pipeline has produced. + **Container recipe** – Shows recipe details. After you create a recipe, you cannot edit it. You must create a new version of the recipe from the **Container recipes** page. For more information, see [Create a new version of a container recipe](create-container-recipes.md). + **Infrastructure configuration** – Shows editable information for configuring your build pipeline infrastructure. + **Distribution settings** – Shows editable information for Docker image distribution. + **EventBridge rules** – For the selected **Event Bus**, shows EventBridge rules that target the current pipeline. Includes **Create event bus** and **Create rule** actions that link to the EventBridge console. For more information about this tab, see [Use EventBridge rules](ev-rules-for-pipeline.md). ## Edit infrastructure configuration for your pipeline Edit infrastructure configuration Infrastructure configuration includes the following details that you can edit after creating the pipeline: + The **Description** for your infrastruction configuration. + The **IAM role** to associate with the instance profile. + **AWS infrastructure**, including the **Instance type** and an **SNS topic** for notifications. + **VPC, subnet, and security groups**. + **Troubleshooting settings**, including **Terminate instance on failure**, the **Key pair** for connecting, and an optional S3 bucket location for instance logs. To edit infrastructure configuration from the pipeline details page, follow these steps: 1. Choose the **Infrastructure configuration** tab. 1. Choose **Edit** from the upper right corner of the **Configuration details** panel. 1. When you are ready to save updates you've made to your infrastructure configuration, choose **Save changes**. ## Edit distribution settings for your pipeline Edit distribution settings Distribution settings include the following details that you can edit after creating the pipeline: + The **Description** for your distribution settings. + **Region settings** for the Regions where you distribute your image. Region 1 defaults to the Region where you created the pipeline. You can add Regions for distribution with the **Add Region** button, and you can remove all Regions except Region 1. **Region settings** include: + Target **Region** + The **Service** defaults to "ECR", and is not editable. + **Repository name** – the name of your target repository (*not including the Amazon ECR location*). For example, the repository name with the location would look like the following pattern: `.dkr.ecr..amazonaws.com/` **Note** If you change the **Repository name**, only the images created after the name change will be added under the new name. Any prior images that your pipeline created remain in their original repository. To edit your distribution settings from the pipeline details page, follow these steps: 1. Choose the **Distribution settings** tab. 1. Choose **Edit** from the upper right corner of the **Distribution details** panel. 1. When you are ready to save updates you've made to your distribution settings, choose **Save changes**. ## Edit the build schedule for your pipeline Edit build schedule The **Edit pipeline** page includes the following details that you can edit after creating the pipeline: + The **Description** for your pipeline. + **Enhanced metadata collection**. This is turned on by default. To turn it off, clear the **Enable enhanced metadata collection** check box. + The **Build schedule** for your pipeline. You can change your **Schedule options** and all of the settings in this section. To edit your pipeline from the pipeline details page, follow these steps: 1. In the upper right corner of the pipeline details page, choose **Actions**, and then **Edit pipeline**. 1. When you are ready to save your updates, choose **Save changes**. **Note** For more information about scheduling your build using cron expressions, see [Use cron expressions in Image Builder](cron-expressions.md). # Update container image pipelines from the AWS CLI Update pipeline from the AWS CLI You can update a container image pipeline using a JSON file as input to the **[update-image-pipeline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-image-pipeline.html)** command in the AWS CLI. To configure the JSON file, you must have Amazon Resource Names (ARNs) to reference the following existing resources: + Image pipeline to update + Container recipe + Infrastructure configuration + Distribution settings (if included in the current pipeline) **Note** If the distribution settings resource is included, then the ECR repository that's specified as the target repository in the distribution settings for the Region where the command runs (Region 1) takes precedence over the target repository that's specified in the container recipe. Follow these steps to update a container image pipeline using the **update-image-pipeline** command in the AWS CLI: **Note** UpdateImagePipeline does not support selective updates for the pipeline. You must specify all of the required properties in the update request, not just the properties that have changed. 1. **Create a CLI input JSON file** Use your favorite file editing tool to create a JSON file with the following keys, plus values that are valid for your environment. This example uses a file named `create-component.json`: ``` { "imagePipelineArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-pipeline/my-example-pipeline", "containerRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.08", "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration", "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration", "imageTestsConfiguration": { "imageTestsEnabled": true, "timeoutMinutes": 120 }, "schedule": { "scheduleExpression": "cron(0 0 * * MON *)", "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE" }, "status": "DISABLED" } ``` **Note** You must include the `file://` notation at the beginning of the JSON file path. The path for the JSON file should follow the appropriate convention for the base operating system where you are running the command. For example, Windows uses the backslash (\$1) to refer to the directory path, while Linux and macOS use the forward slash (/). 1. Run the following command, using the file you created as input. ``` aws imagebuilder update-image-pipeline --cli-input-json file://update-image-pipeline.json ``` # Configure image pipeline workflows in Image Builder Configure pipeline workflows With image workflows, you can customize the workflows that your pipeline runs to build and test images according to your needs. The workflows that you define run within the context of the Image Builder workflow framework. For more information about the stages that make up the workflow framework, see [Manage build and test workflows for Image Builder images](manage-image-workflows.md). Build workflow Build workflows run during the `Build` stage of the workflow framework. You can specify only one build workflow for your pipeline. Or you can skip the build entirely to configure a test-only pipeline. Test workflow Test workflows run during the `Test` stage of the workflow framework. You can specify up to ten test workflows for your pipeline. You can also skip tests entirely if you only want your pipeline to build. ## Define test groups for test workflows Test workflows are defined within test groups. You can run up to ten test workflows for your pipeline. You decide whether to run the test workflows in a specific order or to run as many as possible at the same time. How they run depends on how you define your test groups. The following scenarios demonstrate several ways that you can define your test workflows. **Note** If you use the console to create workflows, we recommend that you take time to plan how you want to run your test workflows before you define your test groups. In the console, you can add or remove test workflows and groups, but you can’t reorder them. **Scenario 1: Run one test workflow at a time** To run all of your test workflows one at a time, you can configure up to ten test groups, each with a single test workflow in it. Test groups run one at a time, in the order that you add them to your pipeline. This is one way to ensure that your test workflows run one at a time in a specific order. **Scenario 2: Run multiple test workflows at the same time** If the order doesn't matter, and you want to run as many test workflows as possible at the same time, you can configure a single test group and put the maximum number of test workflows in it. Image Builder starts up to five test workflows at the same time, and starts additional test workflows as others complete. If your goal is to run your test workflows as fast as possible, this is one way to do it. **Scenario 3: Mix and match** If you have a mixed scenario, with some test workflows that can run at the same time and some that should run one at a time, you can configure your test groups to accomplish this goal. The only limit to how you configure your test groups is the maximum number of test workflows that can run for your pipeline ## Set workflow parameters in an Image Builder pipeline from the console Workflow parameters function the same way for build workflows and test workflows. When you create or update a pipeline, you select build and test workflows that you want to include. If you defined parameters in the workflow document for a workflow that you selected, Image Builder displays them in the **Parameters** panel. The panel is hidden for workflows that don't have parameters defined. Each parameter displays the following attributes that your workflow document defined: + **Name** (*not editable*) – The name of the parameter. + **Type** (*not editable*) – The data type for the parameter value. + **Value** – The value for the parameter. You can edit the parameter value to set it for your pipeline. ## Specify the IAM service role that Image Builder uses to run workflow actions To run image workflows, Image Builder needs permission to perform workflow actions. You can specify the [AWSServiceRoleForImageBuilder](security-iam-awsmanpol.md#sec-iam-manpol-AWSServiceRoleForImageBuilder) service-linked role, or you can specify your own custom role for service access, as follows. + **Console** – In the pipeline wizard **Step 3 Define image creation process**, select the service-linked role or your own custom role from the **IAM role** list in the **Service access** panel. + **Image Builder API** – In the [CreateImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImage.html) action request, specify the service-linked role or your own custom role as the value for the `executionRole` parameter. To learn more about how to create a service role, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *AWS Identity and Access Management User Guide*. # Use EventBridge rules with Image Builder pipelines Use EventBridge rules Events from a wide range of AWS and partner services are streamed to Amazon EventBridge event buses in near real-time. You can also generate custom events, and send events from your own applications to EventBridge. The event buses use rules to determine where to route event data. Image Builder pipelines are available as EventBridge rule targets, which means that you can run an Image Builder pipeline based on rules that you create to respond to events on the bus, or on a schedule. For a summary of system generated events that Image Builder sends to EventBridge, see [Event messages that Image Builder sends](integ-eventbridge.md#integ-eb-event-summary). **Note** Event buses are specific to a Region. The rule and the target must be in the same Region. **Topics** + [ ## EventBridge terms ](#ev-terms) + [ ## View EventBridge rules for your Image Builder pipeline ](#ev-rules-pipeline-tab) + [ ## Use EventBridge rules to schedule a pipeline build ](#ev-rules-schedule-pipeline) ## EventBridge terms This section contains a summary of terms to help you understand how EventBridge integrates with your Image Builder pipelines. Event Describes a change in an environment that might affect one or more application resources. The environment can be an AWS environment, a SaaS partner service or application, or one of your applications or services. You can also set up scheduled events on a timeline. Event bus A pipeline that receives event data from applications and services. Source The service or application that sent the event to the event bus. Target A resource or endpoint that EventBridge invokes when it matches a rule, delivering data from the event to the target. Rule A rule matches incoming events and sends them to targets for processing. A single rule can send an event to multiple targets, which can then run in parallel. Rules are based either on an event pattern or a schedule. Pattern An event pattern defines the event structure and the fields that a rule matches in order to initiate the target action. Schedule Schedule rules perform an action on a schedule, such as running an Image Builder pipeline to refresh an image on a quarterly basis. There are two types of schedule expressions: + **Cron expressions** – Match specific scheduling criteria using the cron syntax that can outline simple criteria; for example, running weekly on a specific day. You can also establish more complex criteria, such as running quarterly on the fifth day of the month, between 2 AM and 4 AM. + **Rate expressions** – Specify a regular interval when the target is invoked, such as every 12 hours. ## View EventBridge rules for your Image Builder pipeline The **EventBridge rules** tab in the Image Builder **Image pipelines** detail page displays EventBridge event buses that your account has access to, and the rules for the selected event bus that apply to the current pipeline. This tab also links directly to the EventBridge console for creating new resources. **Actions that link to the EventBridge console** + **Create event bus** + **Create rule** To learn more about EventBridge, see the following topics in the *Amazon EventBridge User Guide*. + [What is Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) + [Amazon EventBridge event buses](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-bus.html) + [Amazon EventBridge events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) + [Amazon EventBridge rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) ## Use EventBridge rules to schedule a pipeline build For this example, we create a new schedule rule for the default event bus, using a rate expression. The rule in this example generates an event on the event bus every 90 days. The event initiates a pipeline build to refresh the image. 1. Open the EC2 Image Builder console at [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/). 1. To see a list of the image pipelines created under your account, choose **Image pipelines** from the navigation pane. **Note** The list of image pipelines includes an indicator for the type of output image that is created by the pipeline – AMI or Docker. 1. To view details or edit a pipeline, choose the **Pipeline name** link. This opens the detail view for the pipeline. **Note** You can also select the check box next to the **Pipeline name**, then choose **View detail**. 1. Open the **EventBridge rules** tab. 1. Keep the default event bus that is pre-selected in the **Event Bus** panel. 1. Choose **Create rule**. This takes you to the **Create rule** page in the Amazon EventBridge console. 1. Enter a name and description for the rule. The rule name must be unique within the event bus for the selected Region. 1. In the **Define pattern** panel, choose the **Schedule** option. This expands the panel, with the **Fixed rate every** option selected. 1. Enter `90` in the first box, and select **Days** from the drop-down list. 1. Perform the following actions in the **Select targets** panel: 1. Select `EC2 Image Builder` from the **Target** drop-down list. 1. To apply the rule to an Image Builder pipeline, select the target pipeline from the **Image Pipeline** drop-down list. 1. EventBridge needs permission to initiate a build for the selected pipeline. For this example, keep the default option to **Create a new role for this specific resource**. 1. Choose **Add target**. 1. Choose **Create** **Note** To learn more about settings for rate expression rules that are not covered in this example, see [Rate expressions](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html#eb-rate-expressions) in the *Amazon EventBridge User Guide*.