Amazon EC2 Image Builder CreateImageRecipe API

openapi: 3.1.0
info:
  title: EC2 Image Builder Createimagerecipe API
  version: '2019-12-02'
  description: Generated from AWS's published Smithy model for EC2 Image Builder. 1 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://imagebuilder.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /CreateImageRecipe:
    put:
      operationId: CreateImageRecipe
      summary: Create Image Recipe
      description: Creates a new image recipe. Image recipes define how images are configured, tested, and assessed.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateImageRecipeResponse'
              example:
                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
        '429':
          description: CallRateLimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRateLimitExceededException'
        '400':
          description: ClientException; IdempotentParameterMismatchException; InvalidRequestException; InvalidVersionNumberException;
            ResourceAlreadyExistsException; ResourceInUseException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientException'
        '412':
          description: DryRunOperationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DryRunOperationException'
        '403':
          description: ForbiddenException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenException'
        '500':
          description: ServiceException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImageRecipeRequest'
            example:
              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
      tags:
      - Createimagerecipe
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: imagebuilder
  schemas:
    AdditionalInstanceConfiguration:
      type: object
      properties:
        systemsManagerAgent:
          $ref: '#/components/schemas/SystemsManagerAgent'
        userDataOverride:
          type: string
          description: '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 IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg==: #!/bin/bash
            mkdir -p /var/bb/ touch /var'
    CallRateLimitExceededException:
      type: object
      properties:
        message:
          type: string
    ClientException:
      type: object
      properties:
        message:
          type: string
    ComponentConfiguration:
      type: object
      properties:
        componentArn:
          type: string
          description: The Amazon Resource Name (ARN) of the component. You can specify a build version ARN, or a component
            version ARN whose version segments can use x wildcards, for example 1.x.x.
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/ComponentParameter'
          description: A group of parameter settings that Image Builder uses to configure the component for a specific recipe.
            You must supply a value for every component parameter that has no default value, and you can only supply parameters
            that the component defines.
      required:
      - componentArn
    ComponentParameter:
      type: object
      properties:
        name:
          type: string
          description: The name of the component parameter to set.
        value:
          type: array
          items:
            type: string
          description: Sets the value for the named component parameter.
      required:
      - name
      - value
    CreateImageRecipeRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the image recipe. The recipe name, combined with the semantic version, must be unique to
            your account in each Amazon Web Services 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.
        description:
          type: string
          description: The description of the image recipe.
        semanticVersion:
          type: string
          description: 'The semantic version of the image recipe. This version follows the semantic version syntax. The semantic
            version has four nodes: ../. 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 ve'
        components:
          type: array
          items:
            $ref: '#/components/schemas/ComponentConfiguration'
          description: 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.
        parentImage:
          type: string
          description: '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) Amazon Web Services
            Systems Manager (SSM) Parameter Store Parameter, prefixed by ssm:, followed by the parameter name or ARN. Amazon
            Web Services 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.'
        blockDeviceMappings:
          type: array
          items:
            $ref: '#/components/schemas/InstanceBlockDeviceMapping'
          description: 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.
        tags:
          type: object
          additionalProperties:
            type: string
          description: The tags of the image recipe.
        workingDirectory:
          type: string
          description: 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.
        additionalInstanceConfiguration:
          $ref: '#/components/schemas/AdditionalInstanceConfiguration'
        amiTags:
          type: object
          additionalProperties:
            type: string
          description: Tags that are applied to the AMI that Image Builder creates during the Build phase prior to image distribution.
        amiWatermarks:
          type: array
          items:
            type: string
          description: 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. AMI watermarks are supported only for image recipes. AMIs with watermarks cannot be made public.
        clientToken:
          type: string
          description: 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.
        dryRun:
          type: boolean
          description: Validates the required permissions and request parameters without performing the operation. If validation
            succeeds, the operation returns a DryRunOperationException error response.
      required:
      - name
      - semanticVersion
      - parentImage
      - clientToken
    CreateImageRecipeResponse:
      type: object
      properties:
        requestId:
          type: string
          description: The request ID that uniquely identifies this request.
        clientToken:
          type: string
          description: The client token that uniquely identifies the request.
        imageRecipeArn:
          type: string
          description: The Amazon Resource Name (ARN) of the image recipe that was created by this request.
        latestVersionReferences:
          $ref: '#/components/schemas/LatestVersionReferences'
    DryRunOperationException:
      type: object
      properties:
        message:
          type: string
    EbsInstanceBlockDeviceSpecification:
      type: object
      properties:
        encrypted:
          type: boolean
          description: Specifies whether to encrypt the device.
        deleteOnTermination:
          type: boolean
          description: Specifies whether to delete the associated device on termination.
        iops:
          type: integer
          description: The IOPS value for the device. Required only when volumeType is io1 or io2.
        kmsKeyId:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the KMS key to use when encrypting the device.
            This can be either the Key ARN or the Alias ARN. For more information, see Key identifiers (KeyId) in the Key
            Management Service Developer Guide.
        snapshotId:
          type: string
          description: The snapshot that defines the device contents.
        volumeSize:
          type: integer
          description: Overrides the volume size for the device.
        volumeType:
          type: string
          enum:
          - standard
          - io1
          - io2
          - gp2
          - gp3
          - sc1
          - st1
          description: Overrides the volume type for the device.
        throughput:
          type: integer
          description: For GP3 volumes only – The throughput in MiB/s that the volume supports.
    ForbiddenException:
      type: object
      properties:
        message:
          type: string
    InstanceBlockDeviceMapping:
      type: object
      properties:
        deviceName:
          type: string
          description: The device to which these mappings apply.
        ebs:
          $ref: '#/components/schemas/EbsInstanceBlockDeviceSpecification'
        virtualName:
          type: string
          description: The virtual device name for instance ephemeral devices.
        noDevice:
          type: string
          description: Specifies a mapping to remove from the base image.
    LatestVersionReferences:
      type: object
      properties:
        latestVersionArn:
          type: string
          description: The latest version Amazon Resource Name (ARN) of the Image Builder resource.
        latestMajorVersionArn:
          type: string
          description: The latest version Amazon Resource Name (ARN) with the same major version of the Image Builder resource.
        latestMinorVersionArn:
          type: string
          description: The latest version Amazon Resource Name (ARN) with the same minor version of the Image Builder resource.
        latestPatchVersionArn:
          type: string
          description: The latest version Amazon Resource Name (ARN) with the same patch version of the Image Builder resource.
    ServiceException:
      type: object
      properties:
        message:
          type: string
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
    ServiceUnavailableException:
      type: object
      properties:
        message:
          type: string
    SystemsManagerAgent:
      type: object
      properties:
        uninstallAfterBuild:
          type: boolean
          description: Specifies whether the Systems Manager agent is removed from your final build image before Image Builder
            creates the new AMI. If true, the agent is removed. If false, the agent is kept, so that it's included in the
            AMI. If you don't set this property, Image Builder removes the agent only if Image Builder installed the agent
            during the build. An agent that was pre-installed on the base image is kept.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/imagebuilder/service/2019-12-02/imagebuilder-2019-12-02.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)