imagebuilder / Client / create_image_recipe



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

See also: AWS API Documentation

Request Syntax

response = client.create_image_recipe(
            'componentArn': 'string',
            'parameters': [
                    'name': 'string',
                    'value': [
            'deviceName': 'string',
            'ebs': {
                'encrypted': True|False,
                'deleteOnTermination': True|False,
                'iops': 123,
                'kmsKeyId': 'string',
                'snapshotId': 'string',
                'volumeSize': 123,
                'volumeType': 'standard'|'io1'|'io2'|'gp2'|'gp3'|'sc1'|'st1',
                'throughput': 123
            'virtualName': 'string',
            'noDevice': 'string'
        'string': 'string'
        'systemsManagerAgent': {
            'uninstallAfterBuild': True|False
        'userDataOverride': 'string'
  • name (string) –


    The name of the image recipe.

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

  • semanticVersion (string) –


    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.

  • components (list) –


    The components included in the image recipe.

    • (dict) –

      Configuration details of the component.

      • componentArn (string) – [REQUIRED]

        The Amazon Resource Name (ARN) of the component.

      • parameters (list) –

        A group of parameter settings that Image Builder uses to configure the component for a specific recipe.

        • (dict) –

          Contains a key/value pair that sets the named component parameter.

          • name (string) – [REQUIRED]

            The name of the component parameter to set.

          • value (list) – [REQUIRED]

            Sets the value for the named component parameter.

            • (string) –

  • parentImage (string) –


    The base image of the image recipe. The value of the string can be the ARN of the base image or an AMI ID. The format for the ARN follows this example: arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/x.x.x. You can provide the specific version that you want to use, or you can use a wildcard in all of the fields. If you enter an AMI ID for the string value, you must have access to the AMI, and the AMI must be in the same Region in which you are using Image Builder.

  • blockDeviceMappings (list) –

    The block device mappings of the image recipe.

    • (dict) –

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

      • deviceName (string) –

        The device to which these mappings apply.

      • ebs (dict) –

        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.

        • throughput (integer) –

          For GP3 volumes only – The throughput in MiB/s that the volume supports.

      • virtualName (string) –

        Use to manage instance ephemeral devices.

      • noDevice (string) –

        Use to remove a mapping from the base image.

  • tags (dict) –

    The tags of the image recipe.

    • (string) –

      • (string) –

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

  • additionalInstanceConfiguration (dict) –

    Specify additional settings and launch scripts for your build instances.

    • systemsManagerAgent (dict) –

      Contains settings for the Systems Manager agent on your build instance.

      • uninstallAfterBuild (boolean) –

        Controls whether the Systems Manager agent is removed from your final build image, prior to creating the new AMI. If this is set to true, then the agent is removed from the final image. If it’s set to false, then the agent is left in, so that it is included in the new AMI. The default value is false.

    • userDataOverride (string) –

      Use this property to provide commands or a command script to run when you launch your build instance.

      The userDataOverride property replaces any commands that Image Builder might have added to ensure that Systems Manager is installed on your Linux build instance. If you override the user data, make sure that you add commands to install Systems Manager, if it is not pre-installed on your base image.


      The user data is always base 64 encoded. For example, the following commands are encoded as IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhci$:


      mkdir -p /var/bb/

      touch /var

  • clientToken (string) –


    Unique, case-sensitive identifier you provide to ensure idempotency of the request. For more information, see Ensuring idempotency in the Amazon EC2 API Reference.

    This field is autopopulated if not provided.

Return type:



Response Syntax

    'requestId': 'string',
    'clientToken': 'string',
    'imageRecipeArn': 'string'

Response Structure

  • (dict) –

    • requestId (string) –

      The request ID that uniquely identifies this request.

    • clientToken (string) –

      The client token that uniquely identifies the request.

    • imageRecipeArn (string) –

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


  • imagebuilder.Client.exceptions.ServiceException

  • imagebuilder.Client.exceptions.ClientException

  • imagebuilder.Client.exceptions.ServiceUnavailableException

  • imagebuilder.Client.exceptions.InvalidRequestException

  • imagebuilder.Client.exceptions.IdempotentParameterMismatchException

  • imagebuilder.Client.exceptions.ForbiddenException

  • imagebuilder.Client.exceptions.CallRateLimitExceededException

  • imagebuilder.Client.exceptions.InvalidVersionNumberException

  • imagebuilder.Client.exceptions.ResourceInUseException

  • imagebuilder.Client.exceptions.ResourceAlreadyExistsException

  • imagebuilder.Client.exceptions.ServiceQuotaExceededException