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.

Synopsis¶

  create-distribution-configuration
--name <value>
[--description <value>]
--distributions <value>
[--tags <value>]
[--client-token <value>]
[--dry-run | --no-dry-run]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
[--cli-error-format <value>]

Options¶

--name (string) [required]

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.

Constraints:

pattern: ^[-_A-Za-z-0-9][-_A-Za-z0-9 ]{1,126}[-_A-Za-z-0-9]$

--description (string)

The description of the distribution configuration.

Constraints:

min: 1

max: 1024

--distributions (list) [required]

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.

(structure)

Defines the settings for a specific Region.

region -> (string) [required]

The target Region.

Constraints:

min: 1

max: 1024

amiDistributionConfiguration -> (structure)

The specific AMI settings; for example, launch permissions or AMI tags.

name -> (string)

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 .

Constraints:

min: 1

max: 127

pattern: ^[-_A-Za-z0-9{][-_A-Za-z0-9\s:{}\.]+[-_A-Za-z0-9}]$

description -> (string)

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.

Constraints:

min: 1

max: 1024

targetAccountIds -> (list)

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.

Constraints:

min: 1

max: 1536

(string)

Constraints:

pattern: ^[0-9]{12}$

amiTags -> (map)

The tags to apply to AMIs distributed to this Region.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

pattern: ^(?!aws:)[a-zA-Z0-9\s_.:/=+\-@]*$

value -> (string)

Constraints:

max: 256

kmsKeyId -> (string)

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 .

Constraints:

min: 1

max: 1024

launchPermission -> (structure)

Launch permissions can be used to configure which Amazon Web Services accounts can use the AMI to launch instances.

userIds -> (list)

The Amazon Web Services account IDs to grant launch permission to. Each listed account can use the distributed AMI to launch instances.

Constraints:

min: 1

max: 1536

(string)

Constraints:

pattern: ^[0-9]{12}$

userGroups -> (list)

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.

(string)

Constraints:

min: 1

max: 1024

organizationArns -> (list)

The ARN for an Amazon Web Services Organization that you want to share your AMI with. For more information, see What is Organizations? .

Constraints:

min: 1

max: 25

(string)

Constraints:

pattern: ^arn:aws[^:]*:organizations::[0-9]{12}:organization/o-[a-z0-9]{10,32}$

organizationalUnitArns -> (list)

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 .

Constraints:

min: 1

max: 25

(string)

Constraints:

pattern: ^arn:aws[^:]*:organizations::[0-9]{12}:ou/o-[a-z0-9]{10,32}/ou-[0-9a-z]{4,32}-[0-9a-z]{8,32}

containerDistributionConfiguration -> (structure)

Container distribution settings for encryption, licensing, and sharing in a specific Region.

description -> (string)

The description of the container distribution configuration.

Constraints:

min: 1

max: 1024

containerTags -> (list)

Tags that Image Builder applies to the distributed container image in the target repository. These are repository image tags, not resource tags.

(string)

Constraints:

min: 1

max: 1024

targetRepository -> (structure) [required]

The destination repository for the container distribution configuration.

service -> (string) [required]

Specifies the service in which this image was registered.

Possible values:

ECR

repositoryName -> (string) [required]

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).

Constraints:

min: 1

max: 1024

licenseConfigurationArns -> (list)

The License Manager Configuration to associate with the AMI in the specified Region.

Constraints:

min: 1

max: 50

(string)

Constraints:

pattern: ^arn:aws[^:]*:license-manager:[^:]+:[0-9]{12}:license-configuration:lic-[a-z0-9-_]{32}$

launchTemplateConfigurations -> (list)

A group of launchTemplateConfiguration settings that apply to image distribution for specified accounts.

Constraints:

min: 1

max: 100

(structure)

Identifies an Amazon EC2 launch template to use for a specific account.

launchTemplateId -> (string) [required]

Identifies the Amazon EC2 launch template to use.

Constraints:

pattern: ^lt-[a-z0-9-_]{17}$

accountId -> (string)

The account ID that this configuration applies to.

Constraints:

pattern: ^[0-9]{12}$

setDefaultVersion -> (boolean)

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 .

s3ExportConfiguration -> (structure)

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.

roleName -> (string) [required]

The name of the role that grants VM Import/Export permission to export images to your S3 bucket.

Constraints:

min: 1

max: 1024

diskImageFormat -> (string) [required]

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.

Possible values:

VMDK

RAW

VHD

s3Bucket -> (string) [required]

The S3 bucket in which to store the output disk images for your VM.

Constraints:

min: 1

max: 1024

s3Prefix -> (string)

The Amazon S3 path for the bucket where the output disk images for your VM are stored.

Constraints:

min: 1

max: 1024

fastLaunchConfigurations -> (list)

The Windows faster-launching configurations to use for AMI distribution.

Constraints:

min: 1

max: 1000

(structure)

Defines and configures EC2 Fast Launch for output Windows AMIs.

enabled -> (boolean) [required]

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 -> (structure)

Configuration settings for managing the number of snapshots that are created from pre-provisioned instances for the Windows AMI when Windows fast launch is enabled.

targetResourceCount -> (integer)

The number of pre-provisioned snapshots to keep on hand for a fast-launch enabled Windows AMI.

Constraints:

min: 1

max: 10000

maxParallelLaunches -> (integer)

The maximum number of parallel instances that are launched for creating resources.

Constraints:

min: 1

launchTemplate -> (structure)

The launch template that the fast-launch enabled Windows AMI uses when it launches Windows instances to create pre-provisioned snapshots.

launchTemplateId -> (string)

The ID of the launch template to use for Windows fast launch for a Windows AMI.

Constraints:

pattern: ^lt-[a-z0-9-_]{17}$

launchTemplateName -> (string)

The name of the launch template to use for Windows fast launch for a Windows AMI.

Constraints:

min: 1

max: 1024

launchTemplateVersion -> (string)

The version of the launch template to use for Windows fast launch for a Windows AMI.

Constraints:

min: 1

max: 1024

accountId -> (string)

The owner account ID for the fast-launch enabled Windows AMI.

Constraints:

pattern: ^[0-9]{12}$

ssmParameterConfigurations -> (list)

Contains settings to update Amazon Web Services Systems Manager (SSM) Parameter Store Parameters with output AMI IDs from the build by target Region.

(structure)

Configuration for a single Parameter in the Amazon Web Services Systems Manager (SSM) Parameter Store in a given Region.

amiAccountId -> (string)

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.

Constraints:

pattern: ^[0-9]{12}$

parameterName -> (string) [required]

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.

Constraints:

min: 1

max: 1011

pattern: ^[a-zA-Z0-9_.\-\/]+$

dataType -> (string)

The type of value the parameter contains. We recommend the aws:ec2:image data type.

Possible values:

text

aws:ec2:image

JSON Syntax:

[
  {
    "region": "string",
    "amiDistributionConfiguration": {
      "name": "string",
      "description": "string",
      "targetAccountIds": ["string", ...],
      "amiTags": {"string": "string"
        ...},
      "kmsKeyId": "string",
      "launchPermission": {
        "userIds": ["string", ...],
        "userGroups": ["string", ...],
        "organizationArns": ["string", ...],
        "organizationalUnitArns": ["string", ...]
      }
    },
    "containerDistributionConfiguration": {
      "description": "string",
      "containerTags": ["string", ...],
      "targetRepository": {
        "service": "ECR",
        "repositoryName": "string"
      }
    },
    "licenseConfigurationArns": ["string", ...],
    "launchTemplateConfigurations": [
      {
        "launchTemplateId": "string",
        "accountId": "string",
        "setDefaultVersion": true|false
      }
      ...
    ],
    "s3ExportConfiguration": {
      "roleName": "string",
      "diskImageFormat": "VMDK"|"RAW"|"VHD",
      "s3Bucket": "string",
      "s3Prefix": "string"
    },
    "fastLaunchConfigurations": [
      {
        "enabled": true|false,
        "snapshotConfiguration": {
          "targetResourceCount": integer
        },
        "maxParallelLaunches": integer,
        "launchTemplate": {
          "launchTemplateId": "string",
          "launchTemplateName": "string",
          "launchTemplateVersion": "string"
        },
        "accountId": "string"
      }
      ...
    ],
    "ssmParameterConfigurations": [
      {
        "amiAccountId": "string",
        "parameterName": "string",
        "dataType": "text"|"aws:ec2:image"
      }
      ...
    ]
  }
  ...
]

--tags (map)

The tags of the distribution configuration.

Constraints:

min: 1

max: 50

key -> (string)

Constraints:

min: 1

max: 128

pattern: ^(?!aws:)[a-zA-Z0-9\s_.:/=+\-@]*$

value -> (string)

Constraints:

max: 256

Shorthand Syntax:

KeyName1=string,KeyName2=string

JSON Syntax:

{"string": "string"
  ...}

--client-token (string)

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 .

Constraints:

min: 1

max: 64

--dry-run | --no-dry-run (boolean)

Validates the required permissions and request parameters without performing the operation. If validation succeeds, the operation returns a DryRunOperationException error response.

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

Global Options¶

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

json
text
table
yaml
yaml-stream
off

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

on
off
auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--cli-binary-format (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob fileb:// will always be treated as binary and use the file contents directly regardless of the cli-binary-format setting. When using file:// the file contents will need to properly formatted for the configured cli-binary-format.

base64
raw-in-base64-out

--no-cli-pager (boolean)

Disable cli pager for output.

--cli-auto-prompt (boolean)

Automatically prompt for CLI input parameters.

--no-cli-auto-prompt (boolean)

Disable automatically prompt for CLI input parameters.

--cli-error-format (string)

The formatting style for error output. By default, errors are displayed in enhanced format.

legacy
json
yaml
text
table
enhanced

Examples¶

Note

To use the following examples, you must have the AWS CLI installed and configured. See the Getting started guide in the AWS CLI User Guide for more information.

Unless otherwise stated, all examples have unix-like quotation rules. These examples will need to be adapted to your terminal’s quoting rules. See Using quotation marks with strings in the AWS CLI User Guide .

To create a distribution configuration

The following create-distribution-configuration example creates a distribution configuration using a JSON file.

aws imagebuilder create-distribution-configuration \
    --cli-input-json file:/create-distribution-configuration.json

Contents of create-distribution-configuration.json:

{
    "name": "MyExampleDistribution",
    "description": "Copies AMI to eu-west-1",
    "distributions": [
        {
            "region": "us-west-2",
            "amiDistributionConfiguration": {
                "name": "Name {{imagebuilder:buildDate}}",
                "description": "An example image name with parameter references",
                "amiTags": {
                    "KeyName": "{{ssm:parameter_name}}"
                },
                "launchPermission": {
                    "userIds": [
                        "123456789012"
                    ]
                }
            }
        },
        {
            "region": "eu-west-1",
            "amiDistributionConfiguration": {
                "name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}",
                "amiTags": {
                    "KeyName": "Value"
                },
                "launchPermission": {
                    "userIds": [
                        "123456789012"
                    ]
                }
            }
        }
    ]
}

Output:

{
    "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "clientToken": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/myexampledistribution"
}

For more information, see Setting Up and Managing an EC2 Image Builder Image Pipeline Using the AWS CLI in the EC2 Image Builder Users Guide.

Output¶

requestId -> (string)

The request ID that uniquely identifies this request.

Constraints:

min: 1

max: 1024

clientToken -> (string)

The client token that uniquely identifies the request.

Constraints:

min: 1

max: 64

distributionConfigurationArn -> (string)

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

Constraints:

pattern: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:[0-9]{12}|aws):distribution-configuration/[a-z0-9-_]+$

Table of Contents

Feedback

User Guide