CreateImageRecipe - EC2 Image Builder
Request SyntaxURI Request ParametersRequest BodyResponse SyntaxResponse ElementsErrorsExamplesSee Also
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

CreateImageRecipe

Creates a new image recipe. Image recipes define how images are configured, tested, and assessed.

Request Syntax

PUT /CreateImageRecipe HTTP/1.1
Content-type: application/json

{
   "additionalInstanceConfiguration": { 
      "systemsManagerAgent": { 
         "uninstallAfterBuild": boolean
      },
      "userDataOverride": "string"
   },
   "amiTags": { 
      "string" : "string" 
   },
   "amiWatermarks": [ "string" ],
   "blockDeviceMappings": [ 
      { 
         "deviceName": "string",
         "ebs": { 
            "deleteOnTermination": boolean,
            "encrypted": boolean,
            "iops": number,
            "kmsKeyId": "string",
            "snapshotId": "string",
            "throughput": number,
            "volumeSize": number,
            "volumeType": "string"
         },
         "noDevice": "string",
         "virtualName": "string"
      }
   ],
   "clientToken": "string",
   "components": [ 
      { 
         "componentArn": "string",
         "parameters": [ 
            { 
               "name": "string",
               "value": [ "string" ]
            }
         ]
      }
   ],
   "description": "string",
   "dryRun": boolean,
   "name": "string",
   "parentImage": "string",
   "semanticVersion": "string",
   "tags": { 
      "string" : "string" 
   },
   "workingDirectory": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

additionalInstanceConfiguration

The additional settings and launch scripts for your build instances.

Type: AdditionalInstanceConfiguration object

Required: No

amiTags

Tags that are applied to the AMI that Image Builder creates during the Build phase prior to image distribution.

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^(?!aws:)[a-zA-Z0-9\s_.:/=+\-@]*$

Value Length Constraints: Maximum length of 256.

Required: No

amiWatermarks

The AMI watermark names to attach to the output AMI from this recipe. AMI watermarks are lineage markers. They automatically propagate to derivative AMIs when the source AMI is copied or distributed across Regions or accounts.

Note

AMI watermarks are supported only for image recipes. AMIs with watermarks cannot be made public.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 5 items.

Length Constraints: Minimum length of 3. Maximum length of 128.

Pattern: ^[A-Za-z0-9()\[\]./'@_\-][A-Za-z0-9 ()\[\]./'@_\-]{1,126}[A-Za-z0-9()\[\]./'@_\-]$

Required: No

blockDeviceMappings

The block device mappings that Image Builder applies to the build instance and the output AMI. For example, you can override the size of the base image's root volume or attach additional EBS volumes.

Type: Array of InstanceBlockDeviceMapping objects

Required: No

clientToken

A unique, case-sensitive identifier you provide to ensure that the operation runs no more than one time. If you retry a request with the same client token, Image Builder returns the original response without running the operation again. For more information, see Ensuring idempotency in the Amazon EC2 API Reference.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: Yes

components

The components included in the image recipe. Components are optional. A recipe with no components bakes the base image without additional customization. You can specify each component only one time in a recipe. Components with a status of DEPRECATED or DISABLED can't be added to new recipes.

Type: Array of ComponentConfiguration objects

Array Members: Minimum number of 1 item.

Required: No

description

The description of the image recipe.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: No

dryRun

Validates the required permissions and request parameters without performing the operation. If validation succeeds, the operation returns a DryRunOperationException error response.

Type: Boolean

Required: No

name

The name of the image recipe. The recipe name, combined with the semantic version, must be unique to your account in each AWS Region. Image Builder generates the image recipe ARN from a normalized form of the name, so names that differ only in case, spaces, or underscores count as the same name.

Type: String

Pattern: ^[-_A-Za-z-0-9][-_A-Za-z0-9 ]{1,126}[-_A-Za-z-0-9]$

Required: Yes

parentImage

The base image for customizations specified in the image recipe. You can specify the parent image using one of the following options:

  • AMI ID

  • Image Builder image Amazon Resource Name (ARN)

  • AWS Systems Manager (SSM) Parameter Store Parameter, prefixed by ssm:, followed by the parameter name or ARN.

  • AWS Marketplace product ID

If you enter an AMI ID or an SSM parameter that contains the AMI ID, you must have access to the AMI. The AMI must also be in the Region where you're creating the recipe.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: Yes

semanticVersion

The semantic version of the image recipe. This version follows the semantic version syntax.

Note

The semantic version has four nodes: <major>.<minor>.<patch>/<build>. You can assign values for the first three, and can filter on all of them.

Assignment: For the first three nodes, you can assign any positive integer value, including zero. The upper limit is 2^30-1, or 1073741823, for each node. Image Builder automatically assigns the build number to the fourth node.

Patterns: You can use any numeric pattern that adheres to the assignment requirements for the nodes that you can assign. For example, you might choose a software version pattern, such as 1.0.0, or a date, such as 2021.01.01.

Type: String

Pattern: ^(?:[0-9]+|x)\.(?:[0-9]+|x)\.(?:[0-9]+|x)$

Required: Yes

tags

The tags of the image recipe.

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ^(?!aws:)[a-zA-Z0-9\s_.:/=+\-@]*$

Value Length Constraints: Maximum length of 256.

Required: No

workingDirectory

The working directory used during build and test workflows. If you don't specify a working directory, Image Builder uses /tmp for Linux and macOS build instances, and C:/ for Windows build instances.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: No

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
   "clientToken": "string",
   "imageRecipeArn": "string",
   "latestVersionReferences": { 
      "latestMajorVersionArn": "string",
      "latestMinorVersionArn": "string",
      "latestPatchVersionArn": "string",
      "latestVersionArn": "string"
   },
   "requestId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

clientToken

The client token that uniquely identifies the request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

imageRecipeArn

The Amazon Resource Name (ARN) of the image recipe that was created by this request.

Type: String

Pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws):image-recipe/[a-z0-9-_]+/(?:[0-9]+|x)\.(?:[0-9]+|x)\.(?:[0-9]+|x)$

latestVersionReferences

A set of wildcard version ARNs that always reference the latest version of the resource. ARNs are included for the latest version overall, and for the latest versions within the same major, minor, and patch levels.

Type: LatestVersionReferences object

requestId

The request ID that uniquely identifies this request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Errors

For information about the errors that are common to all actions, see Common Error Types.

CallRateLimitExceededException

You have exceeded the permitted request rate for the Amazon EC2 APIs that Image Builder calls on your behalf. Retry with an increasing or variable delay between requests.

HTTP Status Code: 429

ClientException

A generic client error. This error usually indicates that the request failed a validation check, such as when a downstream service rejects a configured value.

HTTP Status Code: 400

DryRunOperationException

The dry run operation of the resource was successful, and no resources or mutations were actually performed due to the dry run flag in the request.

HTTP Status Code: 412

ForbiddenException

You are not authorized to perform the requested operation.

HTTP Status Code: 403

IdempotentParameterMismatchException

You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token.

HTTP Status Code: 400

InvalidRequestException

The request is malformed or otherwise invalid. Verify the request and try again.

HTTP Status Code: 400

InvalidVersionNumberException

Your version number is out of bounds or does not follow the required syntax.

HTTP Status Code: 400

ResourceAlreadyExistsException

The resource that you are trying to create already exists.

HTTP Status Code: 400

ResourceInUseException

The resource that you are trying to operate on is currently in use. Review the message details and retry later.

HTTP Status Code: 400

ServiceException

An internal server error occurred while Image Builder processed the request. Retrying the request may succeed.

HTTP Status Code: 500

ServiceQuotaExceededException

You have exceeded the number of permitted resources or operations for this service. For service quotas, see EC2 Image Builder endpoints and quotas.

HTTP Status Code: 402

ServiceUnavailableException

The service is unable to process your request at this time.

HTTP Status Code: 503

Examples

Create an image recipe

The following example creates an image recipe that applies a custom component on top of the latest Amazon Linux 2023 base image.

Sample Request

PUT /CreateImageRecipe HTTP/1.1
Content-type: application/json

{
    "name": "my-example-recipe",
    "semanticVersion": "1.0.0",
    "description": "An image recipe that installs my application on Amazon Linux 2023",
    "parentImage": "arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x",
    "components": [
        {
            "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/1.0.0/1"
        }
    ],
    "clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222"
}

Sample Response

HTTP/1.1 200
Content-type: application/json

{
    "requestId": "89f4af2f-4f28-45e6-a9d8-abeba591df6a",
    "clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0",
    "latestVersionReferences": {
        "latestVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/x.x.x",
        "latestMajorVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.x.x",
        "latestMinorVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.x",
        "latestPatchVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.0.0"
    }
}

Create an image recipe with component parameters and block device mappings

The following example creates an image recipe that configures its components and storage. The AppVersion component parameter selects the application version to install. The block device mapping increases the root volume to an encrypted 30 GiB gp3 volume.

Sample Request

PUT /CreateImageRecipe HTTP/1.1
Content-type: application/json

{
    "name": "my-example-recipe",
    "semanticVersion": "1.1.0",
    "description": "Installs a specific version of my application on Amazon Linux 2023 with a larger encrypted root volume",
    "parentImage": "arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x",
    "components": [
        {
            "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-parameterized-component/1.0.0/1",
            "parameters": [
                {
                    "name": "AppVersion",
                    "value": ["2.5.0"]
                }
            ]
        }
    ],
    "blockDeviceMappings": [
        {
            "deviceName": "/dev/xvda",
            "ebs": {
                "volumeSize": 30,
                "volumeType": "gp3",
                "encrypted": true,
                "deleteOnTermination": true
            }
        }
    ],
    "clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE20202"
}

Sample Response

HTTP/1.1 200
Content-type: application/json

{
    "requestId": "e3bdc054-d12e-4578-a847-68a18da724ca",
    "clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE20202",
    "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.1.0",
    "latestVersionReferences": {
        "latestVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/x.x.x",
        "latestMajorVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.x.x",
        "latestMinorVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.1.x",
        "latestPatchVersionArn": "arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-example-recipe/1.1.0"
    }
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: