# Create and update container image pipelines
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
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
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
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
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
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
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
```