This is the new *CloudFormation Template Reference Guide*. Please update your bookmarks and links. For help getting started with CloudFormation, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).

# AWS::ImageBuilder::ImageRecipe
<a name="aws-resource-imagebuilder-imagerecipe"></a>

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

## Syntax
<a name="aws-resource-imagebuilder-imagerecipe-syntax"></a>

To declare this entity in your CloudFormation template, use the following syntax:

### JSON
<a name="aws-resource-imagebuilder-imagerecipe-syntax.json"></a>

```
{
  "Type" : "AWS::ImageBuilder::ImageRecipe",
  "Properties" : {
      "[AdditionalInstanceConfiguration](#cfn-imagebuilder-imagerecipe-additionalinstanceconfiguration)" : AdditionalInstanceConfiguration,
      "[AmiTags](#cfn-imagebuilder-imagerecipe-amitags)" : {Key: Value, ...},
      "[BlockDeviceMappings](#cfn-imagebuilder-imagerecipe-blockdevicemappings)" : [ InstanceBlockDeviceMapping, ... ],
      "[Components](#cfn-imagebuilder-imagerecipe-components)" : [ ComponentConfiguration, ... ],
      "[Description](#cfn-imagebuilder-imagerecipe-description)" : String,
      "[Name](#cfn-imagebuilder-imagerecipe-name)" : String,
      "[ParentImage](#cfn-imagebuilder-imagerecipe-parentimage)" : String,
      "[Tags](#cfn-imagebuilder-imagerecipe-tags)" : {Key: Value, ...},
      "[Version](#cfn-imagebuilder-imagerecipe-version)" : String,
      "[WorkingDirectory](#cfn-imagebuilder-imagerecipe-workingdirectory)" : String
    }
}
```

### YAML
<a name="aws-resource-imagebuilder-imagerecipe-syntax.yaml"></a>

```
Type: AWS::ImageBuilder::ImageRecipe
Properties:
  [AdditionalInstanceConfiguration](#cfn-imagebuilder-imagerecipe-additionalinstanceconfiguration): 
    AdditionalInstanceConfiguration
  [AmiTags](#cfn-imagebuilder-imagerecipe-amitags): 
    Key: Value
  [BlockDeviceMappings](#cfn-imagebuilder-imagerecipe-blockdevicemappings): 
    - InstanceBlockDeviceMapping
  [Components](#cfn-imagebuilder-imagerecipe-components): 
    - ComponentConfiguration
  [Description](#cfn-imagebuilder-imagerecipe-description): String
  [Name](#cfn-imagebuilder-imagerecipe-name): String
  [ParentImage](#cfn-imagebuilder-imagerecipe-parentimage): String
  [Tags](#cfn-imagebuilder-imagerecipe-tags): 
    Key: Value
  [Version](#cfn-imagebuilder-imagerecipe-version): String
  [WorkingDirectory](#cfn-imagebuilder-imagerecipe-workingdirectory): String
```

## Properties
<a name="aws-resource-imagebuilder-imagerecipe-properties"></a>

`AdditionalInstanceConfiguration`  <a name="cfn-imagebuilder-imagerecipe-additionalinstanceconfiguration"></a>
Before you create a new AMI, Image Builder launches temporary Amazon EC2 instances to build and test your image configuration. Instance configuration adds a layer of control over those instances. You can define settings and add scripts to run when an instance is launched from your AMI.  
*Required*: No  
*Type*: [AdditionalInstanceConfiguration](aws-properties-imagebuilder-imagerecipe-additionalinstanceconfiguration.md)  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`AmiTags`  <a name="cfn-imagebuilder-imagerecipe-amitags"></a>
Tags that are applied to the AMI that Image Builder creates during the Build phase prior to image distribution.  
*Required*: No  
*Type*: Object of String  
*Pattern*: `.{1,}`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`BlockDeviceMappings`  <a name="cfn-imagebuilder-imagerecipe-blockdevicemappings"></a>
The block device mappings to apply when creating images from this recipe.  
*Required*: No  
*Type*: Array of [InstanceBlockDeviceMapping](aws-properties-imagebuilder-imagerecipe-instanceblockdevicemapping.md)  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`Components`  <a name="cfn-imagebuilder-imagerecipe-components"></a>
The components that are included in the image recipe. Recipes require a minimum of one build component, and can have a maximum of 20 build and test components in any combination.  
*Required*: No  
*Type*: Array of [ComponentConfiguration](aws-properties-imagebuilder-imagerecipe-componentconfiguration.md)  
*Minimum*: `1`  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`Description`  <a name="cfn-imagebuilder-imagerecipe-description"></a>
The description of the image recipe.  
*Required*: No  
*Type*: String  
*Minimum*: `1`  
*Maximum*: `1024`  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`Name`  <a name="cfn-imagebuilder-imagerecipe-name"></a>
The name of the image recipe.  
*Required*: Yes  
*Type*: String  
*Pattern*: `^[-_A-Za-z-0-9][-_A-Za-z0-9 ]{1,126}[-_A-Za-z-0-9]$`  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`ParentImage`  <a name="cfn-imagebuilder-imagerecipe-parentimage"></a>
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
*Required*: Yes  
*Type*: String  
*Minimum*: `1`  
*Maximum*: `1024`  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`Tags`  <a name="cfn-imagebuilder-imagerecipe-tags"></a>
The tags of the image recipe.  
*Required*: No  
*Type*: Object of String  
*Pattern*: `.{1,}`  
*Update requires*: [No interruption](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-no-interrupt)

`Version`  <a name="cfn-imagebuilder-imagerecipe-version"></a>
The semantic version of the image recipe. This version follows the semantic version syntax.  
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, with an upper limit of 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.
*Required*: Yes  
*Type*: String  
*Pattern*: `^(?:[0-9]+|x)\.(?:[0-9]+|x)\.(?:[0-9]+|x)$`  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

`WorkingDirectory`  <a name="cfn-imagebuilder-imagerecipe-workingdirectory"></a>
The working directory to be used during build and test workflows.  
*Required*: No  
*Type*: String  
*Minimum*: `1`  
*Maximum*: `1024`  
*Update requires*: [Replacement](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)

## Return values
<a name="aws-resource-imagebuilder-imagerecipe-return-values"></a>

### Ref
<a name="aws-resource-imagebuilder-imagerecipe-return-values-ref"></a>

When you pass the logical ID of this resource to the intrinsic `Ref` function, `Ref` returns the resource ARN, such as `arn:aws:imagebuilder:us-east-1:123456789012:image-recipe/mybasicrecipe/2019.12.03`.

For more information about using the `Ref` function, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html).

### Fn::GetAtt
<a name="aws-resource-imagebuilder-imagerecipe-return-values-fn--getatt"></a>

The `Fn::GetAtt` intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the `Fn::GetAtt` intrinsic function, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-getatt.html).

#### 
<a name="aws-resource-imagebuilder-imagerecipe-return-values-fn--getatt-fn--getatt"></a>

`Arn`  <a name="Arn-fn::getatt"></a>
Returns the Amazon Resource Name (ARN) of the image recipe. For example, `arn:aws:imagebuilder:us-east-1:123456789012:image-recipe/mybasicrecipe/2019.12.03`.

`LatestVersion.Arn`  <a name="LatestVersion.Arn-fn::getatt"></a>
The latest version Amazon Resource Name (ARN) of the Image Builder resource.

`LatestVersion.Major`  <a name="LatestVersion.Major-fn::getatt"></a>
The latest version Amazon Resource Name (ARN) with the same `major` version of the Image Builder resource.

`LatestVersion.Minor`  <a name="LatestVersion.Minor-fn::getatt"></a>
The latest version Amazon Resource Name (ARN) with the same `minor` version of the Image Builder resource.

`LatestVersion.Patch`  <a name="LatestVersion.Patch-fn::getatt"></a>
The latest version Amazon Resource Name (ARN) with the same `patch` version of the Image Builder resource.

`Name`  <a name="Name-fn::getatt"></a>
The name of the image recipe.

## Examples
<a name="aws-resource-imagebuilder-imagerecipe--examples"></a>



### Create an image recipe
<a name="aws-resource-imagebuilder-imagerecipe--examples--Create_an_image_recipe"></a>

The following example shows the schema for all of the parameters of the ImageRecipe resource document in both YAML and JSON format .

#### YAML
<a name="aws-resource-imagebuilder-imagerecipe--examples--Create_an_image_recipe--yaml"></a>

```
Resources:
  ImageRecipeAllParameters:
    Type: 'AWS::ImageBuilder::ImageRecipe'
    Properties:
      Name: 'image-recipe-name'
      Version: '1.0.0'
      ParentImage: !Ref ParentImage
      Description: 'description'
      Components:
        - ComponentArn: !Ref ComponentArn
        - ComponentArn: !Ref AnotherComponentArn
      BlockDeviceMappings:
        - DeviceName: "device-name"
          VirtualName: "virtual-name"
          Ebs:
            DeleteOnTermination: true
            Encrypted: true
            Iops: 100
            KmsKeyId: !Ref KmsKeyId
            SnapshotId: "snapshot-id"
            VolumeType: "gp2"
            VolumeSize: 100
      Tags:
        CustomerImageRecipeTagKey1: 'CustomerImageRecipeTagValue1'
        CustomerImageRecipeTagKey2: 'CustomerImageRecipeTagValue2'
```

#### JSON
<a name="aws-resource-imagebuilder-imagerecipe--examples--Create_an_image_recipe--json"></a>

```
{
    "Resources": {
        "ImageRecipeAllParameters": {
            "Type": "AWS::ImageBuilder::ImageRecipe",
            "Properties": {
                "Name": "image-recipe-name",
                "Version": "1.0.0",
                "ParentImage": {
                    "Ref": "ParentImage"
                },
                "Description": "description",
                "Components": [
                    {
                        "ComponentArn": {
                            "Ref": "ComponentArn"
                        }
                    },
                    {
                        "ComponentArn": {
                            "Ref": "AnotherComponentArn"
                        }
                    }
                ],
                "BlockDeviceMappings": [
                    {
                        "DeviceName": "device-name",
                        "VirtualName": "virtual-name",
                        "Ebs": {
                            "DeleteOnTermination": true,
                            "Encrypted": true,
                            "Iops": 100,
                            "KmsKeyId": {
                                "Ref": "KmsKeyId"
                            },
                            "SnapshotId": "snapshot-id",
                            "VolumeType": "gp2",
                            "VolumeSize": 100
                        }
                    }
                ],
                "Tags": {
                    "CustomerImageRecipeTagKey1": "CustomerImageRecipeTagValue1",
                    "CustomerImageRecipeTagKey2": "CustomerImageRecipeTagValue2"
                }
            }
        }
    }
}
```

## See also
<a name="aws-resource-imagebuilder-imagerecipe--seealso"></a>
+ [Create a basic image recipe](https://docs.aws.amazon.com/imagebuilder/latest/userguide/managing-image-builder-cli.html#image-builder-cli-create-recipe) in the *Image Builder User Guide*.