Amazon EC2 Image Builder CreateDistributionConfiguration API

openapi: 3.1.0
info:
  title: EC2 Image Builder Createdistributionconfiguration 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:
  /CreateDistributionConfiguration:
    put:
      operationId: CreateDistributionConfiguration
      summary: Create Distribution Configuration
      description: Creates a new distribution configuration. Distribution configurations define and configure the outputs
        for your images, including the target Regions, accounts, and settings for each Region.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDistributionConfigurationResponse'
              example:
                requestId: ca5312ad-a273-4c8c-817e-042941a5762d
                clientToken: a1b2c3d4-5678-90ab-cdef-EXAMPLE44444
                distributionConfigurationArn: arn:aws:imagebuilder:us-west-2:111122223333:distribution-configuration/my-example-distribution
        '429':
          description: CallRateLimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallRateLimitExceededException'
        '400':
          description: ClientException; IdempotentParameterMismatchException; InvalidParameterCombinationException; InvalidRequestException;
            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/CreateDistributionConfigurationRequest'
            example:
              name: my-example-distribution
              description: Copies the output AMI to a second Region
              distributions:
              - region: us-west-2
                amiDistributionConfiguration:
                  name: my-example-image-{{ imagebuilder:buildDate }}
              - region: us-east-1
                amiDistributionConfiguration:
                  name: my-example-image-{{ imagebuilder:buildDate }}
              clientToken: a1b2c3d4-5678-90ab-cdef-EXAMPLE44444
      tags:
      - Createdistributionconfiguration
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:
    AmiDistributionConfiguration:
      type: object
      properties:
        name:
          type: string
          description: The name of the output AMI. The name must include the {{ imagebuilder:buildDate }} dynamic tag so that
            each build produces a uniquely named AMI. If you don't specify a name, Image Builder names the output AMI with
            the image name followed by the build timestamp, for example my-image 2022-10-26T22-30-05.912619Z.
        description:
          type: string
          description: The description to apply to the distributed AMI. Image Builder sets this as the output AMI's description
            in each target Region and account. If you don't specify a description, the AMI in the build Region uses the image
            recipe's description, if the recipe has one. Copies distributed to other Regions and accounts don't receive a
            default description.
        targetAccountIds:
          type: array
          items:
            type: string
          description: The Amazon Web Services account IDs to distribute the AMI to in this Region. Each listed account receives
            its own copy of the output AMI. If you don't specify accounts, Image Builder distributes the AMI only to your
            own account.
        amiTags:
          type: object
          additionalProperties:
            type: string
          description: The tags to apply to AMIs distributed to this Region.
        kmsKeyId:
          type: string
          description: The Amazon Resource Name (ARN) that uniquely identifies the KMS key used to encrypt the distributed
            image. 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.
        launchPermission:
          $ref: '#/components/schemas/LaunchPermissionConfiguration'
    CallRateLimitExceededException:
      type: object
      properties:
        message:
          type: string
    ClientException:
      type: object
      properties:
        message:
          type: string
    ContainerDistributionConfiguration:
      type: object
      properties:
        description:
          type: string
          description: The description of the container distribution configuration.
        containerTags:
          type: array
          items:
            type: string
          description: Tags that Image Builder applies to the distributed container image in the target repository. These
            are repository image tags, not resource tags.
        targetRepository:
          $ref: '#/components/schemas/TargetContainerRepository'
      required:
      - targetRepository
    CreateDistributionConfigurationRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the distribution configuration. Distribution configuration names must be unique to your
            account in each Amazon Web Services Region. Image Builder generates the distribution configuration 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 distribution configuration.
        distributions:
          type: array
          items:
            $ref: '#/components/schemas/Distribution'
          description: The distribution settings for the configuration. Each entry defines how output images are distributed
            in one target Amazon Web Services Region. A Region can appear at most once in the list.
        tags:
          type: object
          additionalProperties:
            type: string
          description: The tags of the distribution configuration.
        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
      - distributions
      - clientToken
    CreateDistributionConfigurationResponse:
      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.
        distributionConfigurationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the distribution configuration that was created by this request.
    Distribution:
      type: object
      properties:
        region:
          type: string
          description: The target Region.
        amiDistributionConfiguration:
          $ref: '#/components/schemas/AmiDistributionConfiguration'
        containerDistributionConfiguration:
          $ref: '#/components/schemas/ContainerDistributionConfiguration'
        licenseConfigurationArns:
          type: array
          items:
            type: string
          description: The License Manager Configuration to associate with the AMI in the specified Region.
        launchTemplateConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/LaunchTemplateConfiguration'
          description: A group of launchTemplateConfiguration settings that apply to image distribution for specified accounts.
        s3ExportConfiguration:
          $ref: '#/components/schemas/S3ExportConfiguration'
        fastLaunchConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/FastLaunchConfiguration'
          description: The Windows faster-launching configurations to use for AMI distribution.
        ssmParameterConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/SsmParameterConfiguration'
          description: Contains settings to update Amazon Web Services Systems Manager (SSM) Parameter Store Parameters with
            output AMI IDs from the build by target Region.
      required:
      - region
    DryRunOperationException:
      type: object
      properties:
        message:
          type: string
    FastLaunchConfiguration:
      type: object
      properties:
        enabled:
          type: boolean
          description: Specifies whether to enable Windows fast launch on the output AMI during distribution. A value of false
            means Image Builder takes no fast-launch action for this configuration.
        snapshotConfiguration:
          $ref: '#/components/schemas/FastLaunchSnapshotConfiguration'
        maxParallelLaunches:
          type: integer
          description: The maximum number of parallel instances that are launched for creating resources.
        launchTemplate:
          $ref: '#/components/schemas/FastLaunchLaunchTemplateSpecification'
        accountId:
          type: string
          description: The owner account ID for the fast-launch enabled Windows AMI.
      required:
      - enabled
    FastLaunchLaunchTemplateSpecification:
      type: object
      properties:
        launchTemplateId:
          type: string
          description: The ID of the launch template to use for Windows fast launch for a Windows AMI.
        launchTemplateName:
          type: string
          description: The name of the launch template to use for Windows fast launch for a Windows AMI.
        launchTemplateVersion:
          type: string
          description: The version of the launch template to use for Windows fast launch for a Windows AMI.
    FastLaunchSnapshotConfiguration:
      type: object
      properties:
        targetResourceCount:
          type: integer
          description: The number of pre-provisioned snapshots to keep on hand for a fast-launch enabled Windows AMI.
    ForbiddenException:
      type: object
      properties:
        message:
          type: string
    LaunchPermissionConfiguration:
      type: object
      properties:
        userIds:
          type: array
          items:
            type: string
          description: The Amazon Web Services account IDs to grant launch permission to. Each listed account can use the
            distributed AMI to launch instances.
        userGroups:
          type: array
          items:
            type: string
          description: The name of the group that you want to grant launch permission to. The only supported value is all,
            which makes the distributed AMI public.
        organizationArns:
          type: array
          items:
            type: string
          description: The ARN for an Amazon Web Services Organization that you want to share your AMI with. For more information,
            see What is Organizations?.
        organizationalUnitArns:
          type: array
          items:
            type: string
          description: The ARN for an Organizations organizational unit (OU) that you want to share your AMI with. For more
            information about key concepts for Organizations, see Organizations terminology and concepts.
    LaunchTemplateConfiguration:
      type: object
      properties:
        launchTemplateId:
          type: string
          description: Identifies the Amazon EC2 launch template to use.
        accountId:
          type: string
          description: The account ID that this configuration applies to.
        setDefaultVersion:
          type: boolean
          description: Specifies whether to make the new launch template version that Image Builder creates the default version
            of the launch template. If you don't set a value, Image Builder treats it as true.
      required:
      - launchTemplateId
    S3ExportConfiguration:
      type: object
      properties:
        roleName:
          type: string
          description: The name of the role that grants VM Import/Export permission to export images to your S3 bucket.
        diskImageFormat:
          type: string
          enum:
          - VMDK
          - RAW
          - VHD
          description: 'Export the updated image to one of the following supported disk image formats: Virtual Hard Disk (VHD)
            – Compatible with Citrix Xen and Microsoft Hyper-V virtualization products. Stream-optimized ESX Virtual Machine
            Disk (VMDK) – Compatible with VMware ESX and VMware vSphere versions 4, 5, and 6. Raw – Raw format.'
        s3Bucket:
          type: string
          description: The S3 bucket in which to store the output disk images for your VM.
        s3Prefix:
          type: string
          description: The Amazon S3 path for the bucket where the output disk images for your VM are stored.
      required:
      - roleName
      - diskImageFormat
      - s3Bucket
    ServiceException:
      type: object
      properties:
        message:
          type: string
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
    ServiceUnavailableException:
      type: object
      properties:
        message:
          type: string
    SsmParameterConfiguration:
      type: object
      properties:
        amiAccountId:
          type: string
          description: Specify the account that will own the Parameter in a given Region. During distribution, this account
            must be specified in distribution settings as a target account for the Region.
        parameterName:
          type: string
          description: This is the name of the Parameter in the target Region or account. The image distribution creates the
            Parameter if it doesn't already exist. Otherwise, it updates the parameter.
        dataType:
          type: string
          enum:
          - text
          - aws:ec2:image
          description: The type of value the parameter contains. We recommend the aws:ec2:image data type.
      required:
      - parameterName
    TargetContainerRepository:
      type: object
      properties:
        service:
          type: string
          enum:
          - ECR
          description: Specifies the service in which this image was registered.
        repositoryName:
          type: string
          description: The name of the container repository where the output container image is stored. Provide the repository
            name only (a namespace path such as team-a/my-repo is allowed, but not the registry hostname).
      required:
      - service
      - repositoryName
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)