Create a new version of a container recipe

To create a new container recipe version:

1. On the container recipe details page, choose Create new version at the top of the page. The console opens the Create recipe page for container recipes.

2. To create the new version, make your changes, and then choose Create recipe.

1. Create a CLI input JSON file

   You can provide all of the input for the create-container-recipe command with inline command parameters. However, the resulting command can be quite long. To streamline the command, you can instead provide a JSON file that contains all of the container recipe settings

   Note

   The naming convention for the data values in the JSON file follows the pattern that is specified for the Image Builder API operation request parameters. To review the API operation request parameters, see the CreateContainerRecipe command in the EC2 Image Builder API Reference.

   To provide the data values as command line parameters, refer to the parameter names specified in the AWS CLI Command Reference.

   Here is a summary of the parameters in this example:

   • components (array of objects, optional) – Contains an array of ComponentConfiguration objects. Components are optional for container recipes. You can customize the output image with BUILD components, with instructions in your Dockerfile template (for example, RUN or COPY statements), or both. TEST components validate the image but don't modify it.

     Note

     Image Builder installs components in the order that you specified them in the recipe. However, CIS hardening components always run last to ensure that the benchmark tests run against your output image.

     • componentARN (string, required) – The component ARN.

       Tip

       To use the example to create your own container recipe, replace the example ARNs with the ARNs for the components that you are using for your recipe,. These include the AWS Region, name, and the version number for each.

     • parameters (array of objects) – Contains an array of ComponentParameter objects. If an input parameter is required, but doesn't have a default value defined in the component, you must provide a value. Image Builder won't create the recipe version if there are any required parameters that are missing and don't have a default value defined.

       Important

       Component parameters are plain text values, and are logged in AWS CloudTrail. We recommend that you use AWS Secrets Manager or the AWS Systems Manager Parameter Store to store your secrets. For more information about Secrets Manager, see What is Secrets Manager? in the AWS Secrets Manager User Guide. For more information about AWS Systems Manager Parameter Store, see AWS Systems Manager Parameter Store in the AWS Systems Manager User Guide.

       • name (string, required) – The name of the component parameter to set.

       • value (array of strings, required) – Contains an array of strings to set the value for the named component parameter. If there is a default value defined for the component, and no other value is provided, AWSTOE uses the default value.

   • containerType (string, required) – The type of container to create. Valid values include DOCKER.

   • dockerfileTemplateData (string) – The inline Dockerfile template for building your image. Inline data is limited to 16,000 characters. You must specify either dockerfileTemplateData or dockerfileTemplateUri, but not both.

     Your Dockerfile template can include contextual variables (placeholders that Image Builder replaces with build information at runtime). Include at least the parentImage variable. If your recipe includes components, also include the environments variable and the components variable.

     parentImage (required)

     At build time, this variable resolves to the base image for your recipe.

     Example:

     FROM
     {{{ imagebuilder:parentImage }}}

     environments (required if components are specified)

     At build time, this variable resolves to the Dockerfile directives that stage your components in the build context. These directives copy the component scripts into the image and set the environment variables that those scripts use. It prepares the environment but doesn't run the components that you specify. Place this variable before the components variable.

     Example:

     {{{ imagebuilder:environments }}}

     components (optional)

     At build time, this variable resolves to the command that runs the build and test component scripts for the components that the container recipe includes, and then removes those scripts from the image. This is the variable that runs your components. Place it after the environments variable.

     Example:

     {{{ imagebuilder:components }}}

     To store the template in Amazon S3 instead, use the dockerfileTemplateUri parameter with a valid Amazon S3 URI (for example, s3://my-bucket/templates/Dockerfile).

   • name (string, required) – The name of the container recipe.

   • description (string) – The description of the container recipe.

   • parentImage (string, required) – The Docker container image to use in the container recipe as a baseline for your customized image.

     • Public images hosted on DockerHub

     • Existing container images in Amazon ECR

     • Amazon-managed container images

   • platformOverride (string) – Specifies the operating system platform when you use a custom base image. We recommend that you set this value when you use a Docker Hub or Amazon ECR image. If you omit it, Image Builder attempts to detect the platform from the container manifest, which might not always be available. You can't specify platformOverride when your parent image is an Image Builder image ARN. Valid values are Linux and Windows. Container recipes don't support the macOS platform.

   • semanticVersion (string, required) – The semantic version of the container recipe specified in the following format, with numeric values in each position to indicate a specific version: <major>.<minor>.<patch>. An example would be 1.0.0. To learn more about semantic versioning for Image Builder resources, see Semantic versioning in Image Builder.

   • tags (string map) – Tags that are attached to the container recipe.

   • instanceConfiguration (object) – A group of options that can be used to configure an instance for building and testing container images.

     • image (string) – The base image for a container build and test instance. This can contain an AMI ID or it can specify an AWS Systems Manager (SSM) Parameter Store parameter, prefixed by ssm:, followed by the parameter name or ARN. If you use an SSM parameter, the parameter value must contain an AMI ID. If you don't specify a base image, Image Builder uses the appropriate Amazon ECS optimized AMI as a base image.

     • blockDeviceMappings (array of objects) – Defines the block devices to attach for building an instance from the Image Builder AMI specified in the image parameter.

       • deviceName (string) – The device that these mappings apply to.

       • ebs (object) – Used to manage Amazon EBS specific configuration for this mapping.

         • deleteOnTermination (Boolean) – Used to configure delete on termination of the associated device.

         • encrypted (Boolean) – Used to configure device encryption.

         • volumeSize (integer) – Used to override the device's volume size.

         • volumeType (string) – Used to override the device's volume type.

   • targetRepository (object, required) – The destination repository for the container image if there is no other repository specified in your pipeline's distribution configuration for the Region where the pipeline runs (Region 1).

     • repositoryName (string, required) – The name of the container repository where the output container image is stored. This name is prefixed by the repository location.

     • service (string, required) – Specifies the repository service that stores the output image. The valid value is ECR. The target repository must already exist.

   • workingDirectory (string) – The working directory for use during build and test workflows.

   The following example shows a complete container recipe input file that defines a Linux Docker container with build components. Save it as create-container-recipe.json, and use it in the create-container-recipe command.

   {
   	"components": [ 
   	  { 
   		 "componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/helloworldal2/x.x.x"
   	  }
   	],
   	"containerType": "DOCKER",
   	"description": "My Linux Docker container image",
   	"dockerfileTemplateData": "FROM {{{ imagebuilder:parentImage }}}\n{{{ imagebuilder:environments }}}\n{{{ imagebuilder:components }}}",
   	"name": "amazonlinux-container-recipe",
   	"parentImage": "amazonlinux:latest",
   	"platformOverride": "Linux",
   	"semanticVersion": "1.0.2",
   	"tags": { 
   	  "sometag" : "Tag detail" 
   	},
   	"instanceConfiguration": {
   	  "image": "ami-1234567890abcdef1",
   	  "blockDeviceMappings": [
   		 {
   			"deviceName": "/dev/xvda",
   			"ebs": {
   				"deleteOnTermination": true,
   				"encrypted": false,
   				"volumeSize": 8,
   				"volumeType": "gp2"
   			 }
   		  }			
   	  ]
   	},
   	"targetRepository": { 
   	  "repositoryName": "myrepo",
   	  "service": "ECR"
   	},
   	"workingDirectory": "/tmp"
   }

2. Create the recipe

   Use the following command to create the recipe. Provide the name of the JSON file that you created in the prior step in the --cli-input-json parameter:

   aws imagebuilder create-container-recipe --cli-input-json file://create-container-recipe.json

   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 (\) to refer to the directory path, while Linux and macOS use the forward slash (/).

   The following example output shows the ARN of the newly created container recipe, along with the request ID and client token for the request.

   {
   	"requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
   	"clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
   	"containerRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-container-recipe/1.0.2"
   }