imagebuilder / Client / update_distribution_configuration

update_distribution_configuration

imagebuilder.Client.update_distribution_configuration(**kwargs)

Updates a distribution configuration. Distribution configurations define and configure the outputs for your images, including the target Regions, accounts, and settings for each Region.

Note

This operation doesn’t support selective updates. The request replaces the stored configuration, so include every setting that you want to keep.

See also: AWS API Documentation

Request Syntax

response = client.update_distribution_configuration(
    distributionConfigurationArn='string',
    description='string',
    distributions=[
        {
            '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': 123
                    },
                    'maxParallelLaunches': 123,
                    'launchTemplate': {
                        'launchTemplateId': 'string',
                        'launchTemplateName': 'string',
                        'launchTemplateVersion': 'string'
                    },
                    'accountId': 'string'
                },
            ],
            'ssmParameterConfigurations': [
                {
                    'amiAccountId': 'string',
                    'parameterName': 'string',
                    'dataType': 'text'|'aws:ec2:image'
                },
            ]
        },
    ],
    clientToken='string'
)

Parameters:

• distributionConfigurationArn (string) –

  [REQUIRED]

  The Amazon Resource Name (ARN) of the distribution configuration that you want to update.

• description (string) – The description of the distribution configuration.

• 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. This list replaces the configuration’s existing distributions entirely.

  • (dict) –

    Defines the settings for a specific Region.

    • region (string) – [REQUIRED]

      The target Region.

    • amiDistributionConfiguration (dict) –

      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.

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

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

        • (string) –

      • amiTags (dict) –

        The tags to apply to AMIs distributed to this Region.

        • (string) –

          • (string) –

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

      • launchPermission (dict) –

        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.

          • (string) –

        • 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) –

        • 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?.

          • (string) –

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

          • (string) –

    • containerDistributionConfiguration (dict) –

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

      • description (string) –

        The description of the container distribution configuration.

      • 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) –

      • targetRepository (dict) – [REQUIRED]

        The destination repository for the container distribution configuration.

        • service (string) – [REQUIRED]

          Specifies the service in which this image was registered.

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

    • licenseConfigurationArns (list) –

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

      • (string) –

    • launchTemplateConfigurations (list) –

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

      • (dict) –

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

        • launchTemplateId (string) – [REQUIRED]

          Identifies the Amazon EC2 launch template to use.

        • accountId (string) –

          The account ID that this configuration applies to.

        • 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 (dict) –

      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.

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

      • s3Bucket (string) – [REQUIRED]

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

      • s3Prefix (string) –

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

    • fastLaunchConfigurations (list) –

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

      • (dict) –

        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 (dict) –

          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.

        • maxParallelLaunches (integer) –

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

        • launchTemplate (dict) –

          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.

          • launchTemplateName (string) –

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

          • launchTemplateVersion (string) –

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

        • accountId (string) –

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

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

      • (dict) –

        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.

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

        • dataType (string) –

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

• clientToken (string) –

  [REQUIRED]

  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.

  This field is autopopulated if not provided.

Return type:

dict

Returns:

Response Syntax

{
    'requestId': 'string',
    'clientToken': 'string',
    'distributionConfigurationArn': 'string'
}

Response Structure

• (dict) –

  • requestId (string) –

    The request ID that uniquely identifies this request.

  • clientToken (string) –

    The client token that uniquely identifies the request.

  • distributionConfigurationArn (string) –

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

Exceptions

• 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.ResourceInUseException

• imagebuilder.Client.exceptions.InvalidParameterCombinationException