distributions

Creates, updates, deletes, gets or lists a distributions resource.

Overview

Name	distributions
Type	Resource
Id	aws.cloudfront.distributions

Fields

The following fields are returned by SELECT queries:

get_distribution

Name	Datatype	Description
arn	string	The distribution's Amazon Resource Name (ARN).
active_trusted_key_groups	string	This field contains a list of key groups and the public keys in each key group that CloudFront can use to verify the signatures of signed URLs or signed cookies.
active_trusted_signers	string	We recommend using TrustedKeyGroups instead of TrustedSigners. This field contains a list of Amazon Web Services account IDs and the active CloudFront key pairs in each account that CloudFront can use to verify the signatures of signed URLs or signed cookies.
alias_icp_recordals	string	Amazon Web Services services in China customers must file for an Internet Content Provider (ICP) recordal if they want to serve content publicly on an alternate domain name, also known as a CNAME, that they've added to CloudFront. AliasICPRecordal provides the ICP recordal status for CNAMEs associated with distributions. For more information about ICP recordals, see Signup, Accounts, and Credentials in Getting Started with Amazon Web Services services in China.
distribution_config	string	The distribution's configuration.
domain_name	string	The distribution's CloudFront domain name. For example: d111111abcdef8.cloudfront.net.
id	string	The distribution's identifier. For example: E1U5RQF7T870K0.
in_progress_invalidation_batches	integer	The number of invalidation batches currently in progress.
last_modified_time	string	The date and time when the distribution was last modified.
status	string	The distribution's status. When the status is Deployed, the distribution's information is fully propagated to all CloudFront edge locations.

list_distributions

Name	Datatype	Description
is_truncated	boolean	A flag that indicates whether more distributions remain to be listed. If your results were truncated, you can make a follow-up pagination request using the Marker request parameter to retrieve more distributions in the list.
items	string	A complex type that contains one DistributionSummary element for each distribution that was created by the current Amazon Web Services account.
marker	string	The value you provided for the Marker request parameter.
max_items	integer	The value you provided for the MaxItems request parameter.
next_marker	string	If IsTruncated is true, this element is present and contains the value you can use for the Marker request parameter to continue listing your distributions where they left off.
quantity	integer	The number of distributions that were created by the current Amazon Web Services account.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_distribution	select	id, region		Get the information about a distribution.
list_distributions	select	region	Marker, MaxItems	List CloudFront distributions.
create_distribution	insert	region, DistributionConfig		Creates a CloudFront distribution.
associate_distribution_web_acl	update	id, region, WebACLArn	If-Match	Associates the WAF web ACL with a distribution.
update_distribution	update	id, region, DistributionConfig	If-Match	Updates the configuration for a CloudFront distribution. The update process includes getting the current distribution configuration, updating it to make your changes, and then submitting an UpdateDistribution request to make the updates. To update a web distribution using the CloudFront API Use GetDistributionConfig to get the current configuration, including the version identifier (ETag). Update the distribution configuration that was returned in the response. Note the following important requirements and restrictions: You must copy the ETag field value from the response. (You'll use it for the IfMatch parameter in your request.) Then, remove the ETag field from the distribution configuration. You can't change the value of CallerReference. Submit an UpdateDistribution request, providing the updated distribution configuration. The new configuration replaces the existing configuration. The values that you specify in an UpdateDistribution request are not merged into your existing configuration. Make sure to include all fields: the ones that you modified and also the ones that you didn't.
disassociate_distribution_web_acl	update	id, region	If-Match	Disassociates a distribution from the WAF web ACL.
delete_distribution	delete	id, region	If-Match	Delete a distribution. Before you can delete a distribution, you must disable it, which requires permission to update the distribution. Once deleted, a distribution cannot be recovered.
update_distribution_with_staging_config	exec	id, region	StagingDistributionId, If-Match	Copies the staging distribution's configuration to its corresponding primary distribution. The primary distribution retains its Aliases (also known as alternate domain names or CNAMEs) and ContinuousDeploymentPolicyId value, but otherwise its configuration is overwritten to match the staging distribution. You can use this operation in a continuous deployment workflow after you have tested configuration changes on the staging distribution. After using a continuous deployment policy to move a portion of your domain name's traffic to the staging distribution and verifying that it works as intended, you can use this operation to copy the staging distribution's configuration to the primary distribution. This action will disable the continuous deployment policy and move your domain's traffic back to the primary distribution. This API operation requires the following IAM permissions: GetDistribution UpdateDistribution

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
id	string	The identifier of the primary distribution to which you are copying a staging distribution's configuration.
region	string	AWS region (default: us-east-1)
If-Match	string	The current versions (ETag values) of both primary and staging distributions. Provide these in the following format: <primary ETag>, <staging ETag>
Marker	string	Use this when paginating results to indicate where to begin in your list of distributions. The results include distributions in the list that occur after the marker. To get the next page of results, set the Marker to the value of the NextMarker from the current page's response (which is also the ID of the last distribution on that page).
MaxItems	string	The maximum number of distributions you want in the response body.
StagingDistributionId	string	The identifier of the staging distribution whose configuration you are copying to the primary distribution.

SELECT examples

get_distribution

Get the information about a distribution.

SELECT
arn,
active_trusted_key_groups,
active_trusted_signers,
alias_icp_recordals,
distribution_config,
domain_name,
id,
in_progress_invalidation_batches,
last_modified_time,
status
FROM aws.cloudfront.distributions
WHERE id = '{{ id }}' -- required
AND region = '{{ region }}' -- required
;

list_distributions

List CloudFront distributions.

SELECT
is_truncated,
items,
marker,
max_items,
next_marker,
quantity
FROM aws.cloudfront.distributions
WHERE region = '{{ region }}' -- required
AND Marker = '{{ Marker }}'
AND MaxItems = '{{ MaxItems }}'
;

INSERT examples

create_distribution

Creates a CloudFront distribution.

INSERT INTO aws.cloudfront.distributions (
DistributionConfig,
region
)
SELECT 
'{{ DistributionConfig }}' /* required */,
'{{ region }}'
RETURNING
arn,
active_trusted_key_groups,
active_trusted_signers,
alias_icp_recordals,
distribution_config,
domain_name,
id,
in_progress_invalidation_batches,
last_modified_time,
status
;

Manifest

# Description fields are for documentation purposes
- name: distributions
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the distributions resource.
  - name: DistributionConfig
    description: |
      A distribution configuration.
    value:
      CallerReference: "{{ CallerReference }}"
      Aliases:
        Quantity: {{ Quantity }}
        Items:
          - "{{ Items }}"
      DefaultRootObject: "{{ DefaultRootObject }}"
      Origins:
        Quantity: {{ Quantity }}
        Items:
          - Id: "{{ Id }}"
            DomainName: "{{ DomainName }}"
            OriginPath: "{{ OriginPath }}"
            CustomHeaders:
              Quantity: {{ Quantity }}
              Items:
                - HeaderName: "{{ HeaderName }}"
                  HeaderValue: "{{ HeaderValue }}"
            S3OriginConfig:
              OriginAccessIdentity: "{{ OriginAccessIdentity }}"
              OriginReadTimeout: {{ OriginReadTimeout }}
            CustomOriginConfig:
              HTTPPort: {{ HTTPPort }}
              HTTPSPort: {{ HTTPSPort }}
              OriginProtocolPolicy: "{{ OriginProtocolPolicy }}"
              OriginSslProtocols:
                Quantity: {{ Quantity }}
                Items: "{{ Items }}"
              OriginReadTimeout: {{ OriginReadTimeout }}
              OriginKeepaliveTimeout: {{ OriginKeepaliveTimeout }}
              IpAddressType: "{{ IpAddressType }}"
              OriginMtlsConfig:
                ClientCertificateArn: "{{ ClientCertificateArn }}"
            VpcOriginConfig:
              VpcOriginId: "{{ VpcOriginId }}"
              OwnerAccountId: "{{ OwnerAccountId }}"
              OriginReadTimeout: {{ OriginReadTimeout }}
              OriginKeepaliveTimeout: {{ OriginKeepaliveTimeout }}
            ConnectionAttempts: {{ ConnectionAttempts }}
            ConnectionTimeout: {{ ConnectionTimeout }}
            ResponseCompletionTimeout: {{ ResponseCompletionTimeout }}
            OriginShield:
              Enabled: {{ Enabled }}
              OriginShieldRegion: "{{ OriginShieldRegion }}"
            OriginAccessControlId: "{{ OriginAccessControlId }}"
      OriginGroups:
        Quantity: {{ Quantity }}
        Items:
          - Id: "{{ Id }}"
            FailoverCriteria:
              StatusCodes:
                Quantity: {{ Quantity }}
                Items: "{{ Items }}"
            Members:
              Quantity: {{ Quantity }}
              Items:
                - OriginId: "{{ OriginId }}"
            SelectionCriteria: "{{ SelectionCriteria }}"
      DefaultCacheBehavior:
        TargetOriginId: "{{ TargetOriginId }}"
        TrustedSigners:
          Enabled: {{ Enabled }}
          Quantity: {{ Quantity }}
          Items:
            - "{{ Items }}"
        TrustedKeyGroups:
          Enabled: {{ Enabled }}
          Quantity: {{ Quantity }}
          Items:
            - "{{ Items }}"
        ViewerProtocolPolicy: "{{ ViewerProtocolPolicy }}"
        AllowedMethods:
          Quantity: {{ Quantity }}
          Items:
            - "{{ Items }}"
          CachedMethods:
            Quantity: {{ Quantity }}
            Items:
              - "{{ Items }}"
        SmoothStreaming: {{ SmoothStreaming }}
        Compress: {{ Compress }}
        LambdaFunctionAssociations:
          Quantity: {{ Quantity }}
          Items:
            - LambdaFunctionARN: "{{ LambdaFunctionARN }}"
              EventType: "{{ EventType }}"
              IncludeBody: {{ IncludeBody }}
        FunctionAssociations:
          Quantity: {{ Quantity }}
          Items:
            - FunctionARN: "{{ FunctionARN }}"
              EventType: "{{ EventType }}"
        FieldLevelEncryptionId: "{{ FieldLevelEncryptionId }}"
        RealtimeLogConfigArn: "{{ RealtimeLogConfigArn }}"
        CachePolicyId: "{{ CachePolicyId }}"
        OriginRequestPolicyId: "{{ OriginRequestPolicyId }}"
        ResponseHeadersPolicyId: "{{ ResponseHeadersPolicyId }}"
        GrpcConfig:
          Enabled: {{ Enabled }}
        ForwardedValues:
          QueryString: {{ QueryString }}
          Cookies:
            Forward: "{{ Forward }}"
            WhitelistedNames:
              Quantity: {{ Quantity }}
              Items: "{{ Items }}"
          Headers:
            Quantity: {{ Quantity }}
            Items:
              - "{{ Items }}"
          QueryStringCacheKeys:
            Quantity: {{ Quantity }}
            Items:
              - "{{ Items }}"
        MinTTL: {{ MinTTL }}
        DefaultTTL: {{ DefaultTTL }}
        MaxTTL: {{ MaxTTL }}
      CacheBehaviors:
        Quantity: {{ Quantity }}
        Items:
          - PathPattern: "{{ PathPattern }}"
            TargetOriginId: "{{ TargetOriginId }}"
            TrustedSigners:
              Enabled: {{ Enabled }}
              Quantity: {{ Quantity }}
              Items:
                - "{{ Items }}"
            TrustedKeyGroups:
              Enabled: {{ Enabled }}
              Quantity: {{ Quantity }}
              Items:
                - "{{ Items }}"
            ViewerProtocolPolicy: "{{ ViewerProtocolPolicy }}"
            AllowedMethods:
              Quantity: {{ Quantity }}
              Items:
                - "{{ Items }}"
              CachedMethods:
                Quantity: {{ Quantity }}
                Items: "{{ Items }}"
            SmoothStreaming: {{ SmoothStreaming }}
            Compress: {{ Compress }}
            LambdaFunctionAssociations:
              Quantity: {{ Quantity }}
              Items:
                - LambdaFunctionARN: "{{ LambdaFunctionARN }}"
                  EventType: "{{ EventType }}"
                  IncludeBody: {{ IncludeBody }}
            FunctionAssociations:
              Quantity: {{ Quantity }}
              Items:
                - FunctionARN: "{{ FunctionARN }}"
                  EventType: "{{ EventType }}"
            FieldLevelEncryptionId: "{{ FieldLevelEncryptionId }}"
            RealtimeLogConfigArn: "{{ RealtimeLogConfigArn }}"
            CachePolicyId: "{{ CachePolicyId }}"
            OriginRequestPolicyId: "{{ OriginRequestPolicyId }}"
            ResponseHeadersPolicyId: "{{ ResponseHeadersPolicyId }}"
            GrpcConfig:
              Enabled: {{ Enabled }}
            ForwardedValues:
              QueryString: {{ QueryString }}
              Cookies:
                Forward: "{{ Forward }}"
                WhitelistedNames: "{{ WhitelistedNames }}"
              Headers:
                Quantity: {{ Quantity }}
                Items: "{{ Items }}"
              QueryStringCacheKeys:
                Quantity: {{ Quantity }}
                Items: "{{ Items }}"
            MinTTL: {{ MinTTL }}
            DefaultTTL: {{ DefaultTTL }}
            MaxTTL: {{ MaxTTL }}
      CustomErrorResponses:
        Quantity: {{ Quantity }}
        Items:
          - ErrorCode: {{ ErrorCode }}
            ResponsePagePath: "{{ ResponsePagePath }}"
            ResponseCode: "{{ ResponseCode }}"
            ErrorCachingMinTTL: {{ ErrorCachingMinTTL }}
      Comment: "{{ Comment }}"
      Logging:
        Enabled: {{ Enabled }}
        IncludeCookies: {{ IncludeCookies }}
        Bucket: "{{ Bucket }}"
        Prefix: "{{ Prefix }}"
      PriceClass: "{{ PriceClass }}"
      Enabled: {{ Enabled }}
      ViewerCertificate:
        CloudFrontDefaultCertificate: {{ CloudFrontDefaultCertificate }}
        IAMCertificateId: "{{ IAMCertificateId }}"
        ACMCertificateArn: "{{ ACMCertificateArn }}"
        SSLSupportMethod: "{{ SSLSupportMethod }}"
        MinimumProtocolVersion: "{{ MinimumProtocolVersion }}"
        Certificate: "{{ Certificate }}"
        CertificateSource: "{{ CertificateSource }}"
      Restrictions:
        GeoRestriction:
          RestrictionType: "{{ RestrictionType }}"
          Quantity: {{ Quantity }}
          Items:
            - "{{ Items }}"
      WebACLId: "{{ WebACLId }}"
      HttpVersion: "{{ HttpVersion }}"
      IsIPV6Enabled: {{ IsIPV6Enabled }}
      ContinuousDeploymentPolicyId: "{{ ContinuousDeploymentPolicyId }}"
      Staging: {{ Staging }}
      AnycastIpListId: "{{ AnycastIpListId }}"
      TenantConfig:
        ParameterDefinitions:
          - Name: "{{ Name }}"
            Definition:
              StringSchema:
                Comment: "{{ Comment }}"
                DefaultValue: "{{ DefaultValue }}"
                Required: {{ Required }}
      ConnectionMode: "{{ ConnectionMode }}"
      ViewerMtlsConfig:
        Mode: "{{ Mode }}"
        TrustStoreConfig:
          TrustStoreId: "{{ TrustStoreId }}"
          AdvertiseTrustStoreCaNames: {{ AdvertiseTrustStoreCaNames }}
          IgnoreCertificateExpiry: {{ IgnoreCertificateExpiry }}
      ConnectionFunctionAssociation:
        Id: "{{ Id }}"
      CacheTagConfig:
        HeaderName: "{{ HeaderName }}"

UPDATE examples

associate_distribution_web_acl

Associates the WAF web ACL with a distribution.

UPDATE aws.cloudfront.distributions
SET 
WebACLArn = '{{ WebACLArn }}'
WHERE 
id = '{{ id }}' --required
AND region = '{{ region }}' --required
AND WebACLArn = '{{ WebACLArn }}' --required
AND `If-Match` = '{{ If-Match}}'
RETURNING
e_tag,
id,
web_acl_arn;

update_distribution

Updates the configuration for a CloudFront distribution. The update process includes getting the current distribution configuration, updating it to make your changes, and then submitting an UpdateDistribution request to make the updates. To update a web distribution using the CloudFront API Use GetDistributionConfig to get the current configuration, including the version identifier (ETag). Update the distribution configuration that was returned in the response. Note the following important requirements and restrictions: You must copy the ETag field value from the response. (You'll use it for the IfMatch parameter in your request.) Then, remove the ETag field from the distribution configuration. You can't change the value of CallerReference. Submit an UpdateDistribution request, providing the updated distribution configuration. The new configuration replaces the existing configuration. The values that you specify in an UpdateDistribution request are not merged into your existing configuration. Make sure to include all fields: the ones that you modified and also the ones that you didn't.

UPDATE aws.cloudfront.distributions
SET 
DistributionConfig = '{{ DistributionConfig }}'
WHERE 
id = '{{ id }}' --required
AND region = '{{ region }}' --required
AND DistributionConfig = '{{ DistributionConfig }}' --required
AND `If-Match` = '{{ If-Match}}'
RETURNING
arn,
active_trusted_key_groups,
active_trusted_signers,
alias_icp_recordals,
distribution_config,
domain_name,
id,
in_progress_invalidation_batches,
last_modified_time,
status;

disassociate_distribution_web_acl

Disassociates a distribution from the WAF web ACL.

UPDATE aws.cloudfront.distributions
SET 
-- No updatable properties
WHERE 
id = '{{ id }}' --required
AND region = '{{ region }}' --required
AND `If-Match` = '{{ If-Match}}'
RETURNING
e_tag,
id;

DELETE examples

delete_distribution

Delete a distribution. Before you can delete a distribution, you must disable it, which requires permission to update the distribution. Once deleted, a distribution cannot be recovered.

DELETE FROM aws.cloudfront.distributions
WHERE id = '{{ id }}' --required
AND region = '{{ region }}' --required
AND `If-Match` = '{{ If-Match }}'
;

Lifecycle Methods

update_distribution_with_staging_config

Copies the staging distribution's configuration to its corresponding primary distribution. The primary distribution retains its Aliases (also known as alternate domain names or CNAMEs) and ContinuousDeploymentPolicyId value, but otherwise its configuration is overwritten to match the staging distribution. You can use this operation in a continuous deployment workflow after you have tested configuration changes on the staging distribution. After using a continuous deployment policy to move a portion of your domain name's traffic to the staging distribution and verifying that it works as intended, you can use this operation to copy the staging distribution's configuration to the primary distribution. This action will disable the continuous deployment policy and move your domain's traffic back to the primary distribution. This API operation requires the following IAM permissions: GetDistribution UpdateDistribution

EXEC aws.cloudfront.distributions.update_distribution_with_staging_config 
@id='{{ id }}' --required, 
@region='{{ region }}' --required, 
@StagingDistributionId='{{ StagingDistributionId }}', 
@If-Match='{{ If-Match }}'
;