Table Of Contents


User Guide

First time using the AWS CLI? See the User Guide for help getting started.

Note: You are viewing the documentation for an older major version of the AWS CLI (version 1).

AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click here. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws . imagebuilder ]



Creates a new container recipe. Container recipes define how images are configured, tested, and assessed.

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.


--container-type <value>
--name <value>
[--description <value>]
--semantic-version <value>
--components <value>
[--instance-configuration <value>]
[--dockerfile-template-data <value>]
[--dockerfile-template-uri <value>]
[--platform-override <value>]
[--image-os-version-override <value>]
--parent-image <value>
[--tags <value>]
[--working-directory <value>]
--target-repository <value>
[--kms-key-id <value>]
[--client-token <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]


--container-type (string)

The type of container to create.

Possible values:


--name (string)

The name of the container recipe.

--description (string)

The description of the container recipe.

--semantic-version (string)

The semantic version of the container recipe (major.minor.patch).

--components (list)

Components for build and test that are included in the container recipe.


Configuration details of the component.

componentArn -> (string)

The Amazon Resource Name (ARN) of the component.

Shorthand Syntax:

componentArn=string ...

JSON Syntax:

    "componentArn": "string"

--instance-configuration (structure)

A group of options that can be used to configure an instance for building and testing container images.

image -> (string)

The AMI ID to use as the base image for a container build and test instance. If not specified, Image Builder will use the appropriate ECS-optimized AMI as a base image.

blockDeviceMappings -> (list)

Defines the block devices to attach for building an instance from this Image Builder AMI.


Defines block device mappings for the instance used to configure your image.

deviceName -> (string)

The device to which these mappings apply.

ebs -> (structure)

Use to manage Amazon EBS-specific configuration for this mapping.

encrypted -> (boolean)

Use to configure device encryption.

deleteOnTermination -> (boolean)

Use to configure delete on termination of the associated device.

iops -> (integer)

Use to configure device IOPS.

kmsKeyId -> (string)

Use to configure the KMS key to use when encrypting the device.

snapshotId -> (string)

The snapshot that defines the device contents.

volumeSize -> (integer)

Use to override the device's volume size.

volumeType -> (string)

Use to override the device's volume type.

virtualName -> (string)

Use to manage instance ephemeral devices.

noDevice -> (string)

Use to remove a mapping from the parent image.

JSON Syntax:

  "image": "string",
  "blockDeviceMappings": [
      "deviceName": "string",
      "ebs": {
        "encrypted": true|false,
        "deleteOnTermination": true|false,
        "iops": integer,
        "kmsKeyId": "string",
        "snapshotId": "string",
        "volumeSize": integer,
        "volumeType": "standard"|"io1"|"io2"|"gp2"|"gp3"|"sc1"|"st1"
      "virtualName": "string",
      "noDevice": "string"

--dockerfile-template-data (string)

The Dockerfile template used to build your image as an inline data blob.

--dockerfile-template-uri (string)

The S3 URI for the Dockerfile that will be used to build your container image.

--platform-override (string)

Specifies the operating system platform when you use a custom source image.

Possible values:

  • Windows
  • Linux

--image-os-version-override (string)

Specifies the operating system version for the source image.

--parent-image (string)

The source image for the container recipe.

--tags (map)

Tags that are attached to the container recipe.

key -> (string)

value -> (string)

Shorthand Syntax:


JSON Syntax:

{"string": "string"

--working-directory (string)

The working directory for use during build and test workflows.

--target-repository (structure)

The destination repository for the container image.

service -> (string)

Specifies the service in which this image was registered.

repositoryName -> (string)

The name of the container repository where the output container image is stored. This name is prefixed by the repository location.

Shorthand Syntax:


JSON Syntax:

  "service": "ECR",
  "repositoryName": "string"

--kms-key-id (string)

Identifies which KMS key is used to encrypt the container image.

--client-token (string)

The client token used to make this request idempotent.

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.


requestId -> (string)

The request ID that uniquely identifies this request.

clientToken -> (string)

The client token used to make this request idempotent.

containerRecipeArn -> (string)

Returns the Amazon Resource Name (ARN) of the container recipe that the request created.