openapi: 3.0.0 info: version: 2019-12-02 x-release: v4 title: EC2 Image Builder CancelImageCreation GetImage#imageBuildVersionArn API description: EC2 Image Builder is a fully managed Amazon Web Services service that makes it easier to automate the creation, management, and deployment of customized, secure, and up-to-date "golden" server images that are pre-installed and pre-configured with software and settings to meet specific IT standards. x-logo: url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png backgroundColor: '#FFFFFF' termsOfService: https://aws.amazon.com/service-terms/ contact: name: Mike Ralphson email: mike.ralphson@gmail.com url: https://github.com/mermade/aws2openapi x-twitter: PermittedSoc license: name: Apache 2.0 License url: http://www.apache.org/licenses/ x-providerName: amazonaws.com x-serviceName: imagebuilder x-aws-signingName: imagebuilder x-origin: - contentType: application/json url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/imagebuilder-2019-12-02.normal.json converter: url: https://github.com/mermade/aws2openapi version: 1.0.0 x-apisguru-driver: external x-apiClientRegistration: url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct x-apisguru-categories: - cloud x-preferred: true servers: - url: http://imagebuilder.{region}.amazonaws.com variables: region: description: The AWS region enum: - us-east-1 - us-east-2 - us-west-1 - us-west-2 - us-gov-west-1 - us-gov-east-1 - ca-central-1 - eu-north-1 - eu-west-1 - eu-west-2 - eu-west-3 - eu-central-1 - eu-south-1 - af-south-1 - ap-northeast-1 - ap-northeast-2 - ap-northeast-3 - ap-southeast-1 - ap-southeast-2 - ap-east-1 - ap-south-1 - sa-east-1 - me-south-1 default: us-east-1 description: The imagebuilder multi-region endpoint - url: https://imagebuilder.{region}.amazonaws.com variables: region: description: The AWS region enum: - us-east-1 - us-east-2 - us-west-1 - us-west-2 - us-gov-west-1 - us-gov-east-1 - ca-central-1 - eu-north-1 - eu-west-1 - eu-west-2 - eu-west-3 - eu-central-1 - eu-south-1 - af-south-1 - ap-northeast-1 - ap-northeast-2 - ap-northeast-3 - ap-southeast-1 - ap-southeast-2 - ap-east-1 - ap-south-1 - sa-east-1 - me-south-1 default: us-east-1 description: The imagebuilder multi-region endpoint - url: http://imagebuilder.{region}.amazonaws.com.cn variables: region: description: The AWS region enum: - cn-north-1 - cn-northwest-1 default: cn-north-1 description: The imagebuilder endpoint for China (Beijing) and China (Ningxia) - url: https://imagebuilder.{region}.amazonaws.com.cn variables: region: description: The AWS region enum: - cn-north-1 - cn-northwest-1 default: cn-north-1 description: The imagebuilder endpoint for China (Beijing) and China (Ningxia) security: - hmac: [] tags: - name: GetImage#imageBuildVersionArn paths: /GetImage#imageBuildVersionArn: parameters: - $ref: '#/components/parameters/X-Amz-Content-Sha256' - $ref: '#/components/parameters/X-Amz-Date' - $ref: '#/components/parameters/X-Amz-Algorithm' - $ref: '#/components/parameters/X-Amz-Credential' - $ref: '#/components/parameters/X-Amz-Security-Token' - $ref: '#/components/parameters/X-Amz-Signature' - $ref: '#/components/parameters/X-Amz-SignedHeaders' get: operationId: GetImage description: Gets an image. responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GetImageResponse' examples: GetImage200Example: summary: Default GetImage 200 response x-microcks-default: true value: requestId: example-id-1234 image: example-string '480': description: ServiceException content: application/json: schema: $ref: '#/components/schemas/ServiceException' examples: GetImage480Example: summary: Default GetImage 480 response x-microcks-default: true value: {} '481': description: ClientException content: application/json: schema: $ref: '#/components/schemas/ClientException' examples: GetImage481Example: summary: Default GetImage 481 response x-microcks-default: true value: {} '482': description: ServiceUnavailableException content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableException' '483': description: InvalidRequestException content: application/json: schema: $ref: '#/components/schemas/InvalidRequestException' '484': description: ForbiddenException content: application/json: schema: $ref: '#/components/schemas/ForbiddenException' '485': description: CallRateLimitExceededException content: application/json: schema: $ref: '#/components/schemas/CallRateLimitExceededException' parameters: - name: imageBuildVersionArn in: query required: true description: The Amazon Resource Name (ARN) of the image that you want to get. schema: type: string pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws):image/[a-z0-9-_]+/(?:(?:([0-9]+|x)\.([0-9]+|x)\.([0-9]+|x))|(?:[0-9]+\.[0-9]+\.[0-9]+/[0-9]+))$ summary: Amazon EC2 Image Builder Get Image x-microcks-operation: delay: 0 dispatcher: FALLBACK tags: - GetImage#imageBuildVersionArn components: schemas: LaunchTemplateConfigurationList: type: array items: $ref: '#/components/schemas/LaunchTemplateConfiguration' minItems: 1 maxItems: 100 Platform: type: string enum: - Windows - Linux ImageType: type: string enum: - AMI - DOCKER InstanceProfileNameType: type: string pattern: ^[\w+=,.@-]+$ minLength: 1 maxLength: 256 FastLaunchConfigurationList: type: array items: $ref: '#/components/schemas/FastLaunchConfiguration' minItems: 1 maxItems: 1000 Image: type: object properties: arn: allOf: - $ref: '#/components/schemas/ImageBuilderArn' - description: '
The Amazon Resource Name (ARN) of the image.
Semantic versioning is included in each object''s Amazon Resource Name (ARN), at the level that applies to that object as follows:
Versionless ARNs and Name ARNs do not include specific values in any of the nodes. The nodes are either left off entirely, or they are specified as wildcards, for example: x.x.x.
Version ARNs have only the first three nodes: <major>.<minor>.<patch>
Build version ARNs have all four nodes, and point to a specific build for a specific version of an object.
The semantic version of the image.
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.
Filtering: With semantic versioning, you have the flexibility to use wildcards (x) to specify the most recent versions or nodes when selecting the base image or components for your recipe. When you use a wildcard in any node, all nodes to the right of the first wildcard must also be wildcards.
Indicates the type of build that created this image. The build can be initiated in the following ways:
USER_INITIATED – A manual pipeline build request.
SCHEDULED – A pipeline build initiated by a cron expression in the Image Builder pipeline, or from EventBridge.
IMPORT – A VM import created the image to use as the base image for the recipe.
containerRecipe), which creates a container image, or an image recipe (imageRecipe), which creates an AMI.
InstanceConfiguration:
type: object
properties:
image:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The AMI ID to use as the base image for a container build and test instance. If not specified, Image Builder will use the appropriate ECS-optimized AMI as a base image.
blockDeviceMappings:
allOf:
- $ref: '#/components/schemas/InstanceBlockDeviceMappings'
- description: Defines the block devices to attach for building an instance from this Image Builder AMI.
description: Defines a custom base AMI and block device mapping configurations of an instance used for building and testing container images.
ImageScanState:
type: object
properties:
status:
allOf:
- $ref: '#/components/schemas/ImageScanStatus'
- description: The current state of vulnerability scans for the image.
reason:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The reason for the scan status for the image.
description: Shows the vulnerability scan status for a specific image, and the reason for that status.
ServiceUnavailableException: {}
Ami:
type: object
properties:
region:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The Amazon Web Services Region of the Amazon EC2 AMI.
image:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The AMI ID of the Amazon EC2 AMI.
name:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The name of the Amazon EC2 AMI.
description:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The description of the Amazon EC2 AMI. Minimum and maximum length are in characters.
state:
$ref: '#/components/schemas/ImageState'
accountId:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The account ID of the owner of the AMI.
description: Details of an Amazon EC2 AMI.
LaunchTemplateId:
type: string
pattern: ^lt-[a-z0-9-_]{17}$
ComponentParameterName:
type: string
pattern: '[^\x00]+'
minLength: 1
maxLength: 256
EmptyString:
type: string
minLength: 0
maxLength: 0
OrganizationalUnitArnList:
type: array
items:
$ref: '#/components/schemas/OrganizationalUnitArn'
minItems: 1
maxItems: 25
ImageScanningConfiguration:
type: object
properties:
imageScanningEnabled:
allOf:
- $ref: '#/components/schemas/NullableBoolean'
- description: A setting that indicates whether Image Builder keeps a snapshot of the vulnerability scans that Amazon Inspector runs against the build instance when you create a new image.
ecrConfiguration:
allOf:
- $ref: '#/components/schemas/EcrConfiguration'
- description: Contains Amazon ECR settings for vulnerability scans.
description: Contains settings for Image Builder image resource and container image scans.
AmiNameString:
type: string
pattern: ^[-_A-Za-z0-9{][-_A-Za-z0-9\s:{}\.]+[-_A-Za-z0-9}]$
minLength: 1
maxLength: 127
SecurityGroupIds:
type: array
items:
$ref: '#/components/schemas/NonEmptyString'
OrganizationArnList:
type: array
items:
$ref: '#/components/schemas/OrganizationArn'
minItems: 1
maxItems: 25
MaxParallelLaunches:
type: integer
minimum: 1
maximum: 10000
FastLaunchLaunchTemplateSpecification:
type: object
properties:
launchTemplateId:
allOf:
- $ref: '#/components/schemas/LaunchTemplateId'
- description: The ID of the launch template to use for faster launching for a Windows AMI.
launchTemplateName:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The name of the launch template to use for faster launching for a Windows AMI.
launchTemplateVersion:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The version of the launch template to use for faster launching for a Windows AMI.
description: Identifies the launch template that the associated Windows AMI uses for launching an instance when faster launching is enabled.
You can specify either the launchTemplateName or the launchTemplateId, but not both.
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$:
#!/bin/bash
mkdir -p /var/bb/
touch /var
In addition to your infrastructure configuration, these settings provide an extra layer of control over your build instances. You can also specify commands to run on launch for all of your build instances.
Image Builder does not automatically install the Systems Manager agent on Windows instances. If your base image includes the Systems Manager agent, then the AMI that you create will also include the agent. For Linux instances, if the base image does not already include the Systems Manager agent, Image Builder installs it. For Linux instances where Image Builder installs the Systems Manager agent, you can choose whether to keep it for the AMI that you create.
Distribution: type: object required: - region properties: region: allOf: - $ref: '#/components/schemas/NonEmptyString' - description: The target Region. example: example-string amiDistributionConfiguration: allOf: - $ref: '#/components/schemas/AmiDistributionConfiguration' - description: The specific AMI settings; for example, launch permissions or AMI tags. example: example-id-1234 containerDistributionConfiguration: allOf: - $ref: '#/components/schemas/ContainerDistributionConfiguration' - description: Container distribution settings for encryption, licensing, and sharing in a specific Region. example: example-string licenseConfigurationArns: allOf: - $ref: '#/components/schemas/LicenseConfigurationArnList' - description: The License Manager Configuration to associate with the AMI in the specified Region. example: arn:aws:service:us-east-1:123456789012:resource/example launchTemplateConfigurations: allOf: - $ref: '#/components/schemas/LaunchTemplateConfigurationList' - description: A group of launchTemplateConfiguration settings that apply to image distribution for specified accounts. example: example-string s3ExportConfiguration: allOf: - $ref: '#/components/schemas/S3ExportConfiguration' - description: Configure export settings to deliver disk images created from your image build, using a file format that is compatible with your VMs in that Region. example: example-string fastLaunchConfigurations: allOf: - $ref: '#/components/schemas/FastLaunchConfigurationList' - description: The Windows faster-launching configurations to use for AMI distribution. example: example-string description: Defines the settings for a specific Region. AmiDistributionConfiguration: type: object properties: name: allOf: - $ref: '#/components/schemas/AmiNameString' - description: The name of the output AMI. description: allOf: - $ref: '#/components/schemas/NonEmptyString' - description: The description of the AMI distribution configuration. Minimum and maximum length are in characters. targetAccountIds: allOf: - $ref: '#/components/schemas/AccountList' - description: The ID of an account to which you want to distribute an image. amiTags: allOf: - $ref: '#/components/schemas/TagMap' - description: The tags to apply to AMIs distributed to this Region. kmsKeyId: allOf: - $ref: '#/components/schemas/NonEmptyString' - description: The KMS key identifier used to encrypt the distributed image. launchPermission: allOf: - $ref: '#/components/schemas/LaunchPermissionConfiguration' - description: Launch permissions can be used to configure which Amazon Web Services accounts can use the AMI to launch instances. description: Define and configure the output AMIs of the pipeline. SystemsManagerAgent: type: object properties: uninstallAfterBuild: allOf: - $ref: '#/components/schemas/NullableBoolean' - description: 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. example: example-string description: Contains settings for the Systems Manager agent on your build instance. InstanceBlockDeviceMappings: type: array items: $ref: '#/components/schemas/InstanceBlockDeviceMapping' Logging: type: object properties: s3Logs: allOf: - $ref: '#/components/schemas/S3Logs' - description: The Amazon S3 logging configuration. description: Logging configuration defines where Image Builder uploads your logs. Container: type: object properties: region: allOf: - $ref: '#/components/schemas/NonEmptyString' - description: Containers and container images are Region-specific. This is the Region context for the container. imageUris: allOf: - $ref: '#/components/schemas/StringList' - description: A list of URIs for containers created in the context Region. description: A container encapsulates the runtime environment for an application. EbsVolumeThroughput: type: integer minimum: 125 maximum: 1000 HttpTokens: type: string pattern: optional|required ContainerRecipe: type: object properties: arn: allOf: - $ref: '#/components/schemas/ImageBuilderArn' - description: 'The Amazon Resource Name (ARN) of the container recipe.
Semantic versioning is included in each object''s Amazon Resource Name (ARN), at the level that applies to that object as follows:
Versionless ARNs and Name ARNs do not include specific values in any of the nodes. The nodes are either left off entirely, or they are specified as wildcards, for example: x.x.x.
Version ARNs have only the first three nodes: <major>.<minor>.<patch>
Build version ARNs have all four nodes, and point to a specific build for a specific version of an object.
The semantic version of the container recipe.
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.
Filtering: With semantic versioning, you have the flexibility to use wildcards (x) to specify the most recent versions or nodes when selecting the base image or components for your recipe. When you use a wildcard in any node, all nodes to the right of the first wildcard must also be wildcards.
The Amazon Resource Name (ARN) for the SNS topic to which we send image build event notifications.
EC2 Image Builder is unable to send notifications to SNS topics that are encrypted using keys from other accounts. The key that is used to encrypt the SNS topic must reside in the account that the Image Builder service runs under.
all. See the examples for making an AMI public at Amazon EC2 ModifyImageAttribute.
EbsVolumeSizeInteger:
type: integer
minimum: 1
maximum: 16000
OrganizationArn:
type: string
pattern: ^arn:aws[^:]*:organizations::[0-9]{12}:organization/o-[a-z0-9]{10,32}$
ImageScanStatus:
type: string
enum:
- PENDING
- SCANNING
- COLLECTING
- COMPLETED
- ABANDONED
- FAILED
- TIMED_OUT
Boolean:
type: boolean
ImageTestsConfiguration:
type: object
properties:
imageTestsEnabled:
allOf:
- $ref: '#/components/schemas/NullableBoolean'
- description: Determines if tests should run after building the image. Image Builder defaults to enable tests to run following the image build, before image distribution.
timeoutMinutes:
allOf:
- $ref: '#/components/schemas/ImageTestsTimeoutMinutes'
- description: The maximum time in minutes that tests are permitted to run.
The timeoutMinutes attribute is not currently active. This value is ignored.
Indicates whether a signed token header is required for instance metadata retrieval requests. The values affect the response as follows:
required – When you retrieve the IAM role credentials, version 2.0 credentials are returned in all cases.
optional – You can include a signed token header in your request to retrieve instance metadata, or you can leave it out. If you include it, version 2.0 credentials are returned for the IAM role. Otherwise, version 1.0 credentials are returned.
The default setting is optional.
httpPutResponseHopLimit: allOf: - $ref: '#/components/schemas/HttpPutResponseHopLimit' - description: Limit the number of hops that an instance metadata request can traverse to reach its destination. The default is one hop. However, if HTTP tokens are required, container image builds need a minimum of two hops. description: The instance metadata options that apply to the HTTP requests that pipeline builds use to launch EC2 build and test instances. For more information about instance metadata options, see Configure the instance metadata options in the Amazon EC2 User Guide for Linux instances, or Configure the instance metadata options in the Amazon EC2 Windows Guide for Windows instances. AmiList: type: array items: $ref: '#/components/schemas/Ami' ComponentParameterValueList: type: array items: $ref: '#/components/schemas/ComponentParameterValue' UserDataOverride: type: string pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ minLength: 1 maxLength: 21847 ContainerRepositoryService: type: string enum: - ECR InstanceType: type: string EcrConfiguration: type: object properties: repositoryName: allOf: - $ref: '#/components/schemas/NonEmptyString' - description: The name of the container repository that Amazon Inspector scans to identify findings for your container images. The name includes the path for the repository location. If you don’t provide this information, Image Builder creates a repository in your account namedimage-builder-image-scanning-repository for vulnerability scans of your output container images.
example: example-resource-name
containerTags:
allOf:
- $ref: '#/components/schemas/StringList'
- description: Tags for Image Builder to apply to the output container image that &INS; scans. Tags can help you identify and manage your scanned images.
example: example-string
description: Settings that Image Builder uses to configure the ECR repository and the output container images that Amazon Inspector scans.
ImageBuilderArn:
type: string
pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws):(?:image-recipe|container-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline|workflow\/(?:build|test|distribution))/[a-z0-9-_]+(?:/(?:(?:x|[0-9]+)\.(?:x|[0-9]+)\.(?:x|[0-9]+))(?:/[0-9]+)?)?$
OsVersion:
type: string
minLength: 1
S3ExportConfiguration:
type: object
required:
- roleName
- diskImageFormat
- s3Bucket
properties:
roleName:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The name of the role that grants VM Import/Export permission to export images to your S3 bucket.
diskImageFormat:
allOf:
- $ref: '#/components/schemas/DiskImageFormat'
- 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.
true to start using Windows faster launching, or false to stop using it.
snapshotConfiguration:
allOf:
- $ref: '#/components/schemas/FastLaunchSnapshotConfiguration'
- description: Configuration settings for managing the number of snapshots that are created from pre-provisioned instances for the Windows AMI when faster launching is enabled.
maxParallelLaunches:
allOf:
- $ref: '#/components/schemas/MaxParallelLaunches'
- description: The maximum number of parallel instances that are launched for creating resources.
launchTemplate:
allOf:
- $ref: '#/components/schemas/FastLaunchLaunchTemplateSpecification'
- description: The launch template that the fast-launch enabled Windows AMI uses when it launches Windows instances to create pre-provisioned snapshots.
accountId:
allOf:
- $ref: '#/components/schemas/AccountId'
- description: The owner account ID for the fast-launch enabled Windows AMI.
description: Define and configure faster launching for output Windows AMIs.
GetImageResponse:
type: object
properties:
requestId:
allOf:
- $ref: '#/components/schemas/NonEmptyString'
- description: The request ID that uniquely identifies this request.
image:
allOf:
- $ref: '#/components/schemas/Image'
- description: The image object.
parameters:
X-Amz-SignedHeaders:
name: X-Amz-SignedHeaders
in: header
schema:
type: string
required: false
X-Amz-Credential:
name: X-Amz-Credential
in: header
schema:
type: string
required: false
X-Amz-Security-Token:
name: X-Amz-Security-Token
in: header
schema:
type: string
required: false
X-Amz-Algorithm:
name: X-Amz-Algorithm
in: header
schema:
type: string
required: false
X-Amz-Content-Sha256:
name: X-Amz-Content-Sha256
in: header
schema:
type: string
required: false
X-Amz-Signature:
name: X-Amz-Signature
in: header
schema:
type: string
required: false
X-Amz-Date:
name: X-Amz-Date
in: header
schema:
type: string
required: false
securitySchemes:
hmac:
type: apiKey
name: Authorization
in: header
description: Amazon Signature authorization v4
x-amazon-apigateway-authtype: awsSigv4
externalDocs:
description: Amazon Web Services documentation
url: https://docs.aws.amazon.com/imagebuilder/
x-hasEquivalentPaths: true