cloudfront_distribution – create, update and delete aws cloudfront distributions.

From Get docs
Ansible/docs/2.7/modules/cloudfront distribution module


cloudfront_distribution – create, update and delete aws cloudfront distributions.

New in version 2.5.


Synopsis

  • Allows for easy creation, updating and deletion of CloudFront distributions.

Requirements

The below requirements are needed on the host that executes this module.

  • boto
  • boto3 >= 1.0.0
  • python >= 2.6

Parameters

Parameter Choices/Defaults Comments

alias

-

The name of an alias (CNAME) that is used in a distribution. This is used to effectively reference a distribution by its alias as an alias can only be used by one distribution per AWS account. This variable avoids having to provide the distribution_id as well as the e_tag, or caller_reference of an existing distribution.

aliases

-

A list[] of domain name aliases (CNAMEs) as strings to be used for the distribution. Each alias must be unique across all distribution for the AWS account.

aws_access_key

-

AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.


aliases: ec2_access_key, access_key

aws_secret_key

-

AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.


aliases: ec2_secret_key, secret_key

cache_behaviors

-

A config element that is a list[] of complex cache behavior objects to be specified for the distribution. The order of the list is preserved across runs unless purge_cache_behavior is enabled. Each cache behavior comprises the attributes path_pattern target_origin_id forwarded_values query_string cookies forward whitelisted_names headers[] query_string_cache_keys[] trusted_signers enabled items[] viewer_protocol_policy min_ttl allowed_methods items[] cached_methods[] smooth_streaming default_ttl max_ttl compress lambda_function_associations[] field_level_encryption_id

caller_reference

-

A unique identifier for creating and updating cloudfront distributions. Each caller reference must be unique across all distributions. e.g. a caller reference used in a web distribution cannot be reused in a streaming distribution. This parameter can be used instead of distribution_id to reference an existing distribution. If not specified, this defaults to a datetime stamp of the format 'YYYY-MM-DDTHH:MM:SS.ffffff'.

comment

-

A comment that describes the cloudfront distribution. If not specified, it defaults to a generic message that it has been created with Ansible, and a datetime stamp.

custom_error_responses

-

A config element that is a list[] of complex custom error responses to be specified for the distribution. This attribute configures custom http error messages returned to the user. Each custom error response object comprises the attributes error_code reponse_page_path response_code error_caching_min_ttl

default_cache_behavior

-

A config element that is a complex object specifying the default cache behavior of the distribution. If not specified, the target_origin_id is defined as the target_origin_id of the first valid cache_behavior in cache_behaviors with defaults. The default cache behavior comprises the attributes target_origin_id forwarded_values query_string cookies forward whitelisted_names headers[] query_string_cache_keys[] trusted_signers enabled items[] viewer_protocol_policy min_ttl allowed_methods items[] cached_methods[] smooth_streaming default_ttl max_ttl compress lambda_function_associations[] lambda_function_arn event_type field_level_encryption_id

default_origin_domain_name

-

The domain name to use for an origin if no origins have been specified. Should only be used on a first run of generating a distribution and not on subsequent runs. Should not be used in conjunction with distribution_id, caller_reference or alias.

default_origin_path

-

The default origin path to specify for an origin if no origins have been specified. Defaults to empty if not specified.

default_root_object

-

A config element that specifies the path to request when the user requests the origin. e.g. if specified as 'index.html', this maps to www.example.com/index.html when www.example.com is called by the user. This prevents the entire distribution origin from being exposed at the root.

distribution_id

-

The id of the cloudfront distribution. This parameter can be exchanged with alias or caller_reference and is used in conjunction with e_tag.

e_tag

-

A unique identifier of a modified or existing distribution. Used in conjunction with distribution_id. Is determined automatically if not specified.

ec2_url

-

Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.

enabled

boolean

  • no
  • yes

A boolean value that specifies whether the distribution is enabled or disabled.

http_version

-

  • http1.1
  • http2

Default:

"aws defaults this to \u0027http2\u0027"

The version of the http protocol to use for the distribution.

ipv6_enabled

boolean

  • no

  • yes

Determines whether IPv6 support is enabled or not.

logging

-

A config element that is a complex object that defines logging for the distribution. The logging object comprises the attributes enabled include_cookies bucket prefix

origins

-

A config element that is a list[] of complex origin objects to be specified for the distribution. Used for creating and updating distributions. Each origin item comprises the attributes id domain_name (defaults to default_origin_domain_name if not specified) origin_path (defaults to default_origin_path if not specified) custom_headers[] header_name header_value s3_origin_access_identity_enabled custom_origin_config http_port https_port origin_protocol_policy origin_ssl_protocols[] origin_read_timeout origin_keepalive_timeout

price_class

-

  • PriceClass_100
  • PriceClass_200
  • PriceClass_All

Default:

"aws defaults this to \u0027PriceClass_All\u0027"

A string that specifies the pricing class of the distribution. As per https://aws.amazon.com/cloudfront/pricing/ price_class=PriceClass_100 consists of the areas United States Canada Europe price_class=PriceClass_200 consists of the areas United States Canada Europe Hong Kong, Philippines, S. Korea, Singapore & Taiwan Japan India price_class=PriceClass_All consists of the areas United States Canada Europe Hong Kong, Philippines, S. Korea, Singapore & Taiwan Japan India South America Australia

profile

-

added in 1.6

Uses a boto profile. Only works with boto >= 2.24.0.

purge_aliases

boolean

  • no

  • yes

Specifies whether existing aliases will be removed before adding new aliases. When purge_aliases=yes, existing aliases are removed and aliases are added.

purge_cache_behaviors

-

Default:

"no"

Whether to remove any cache behaviors that aren't listed in cache_behaviors. This switch also allows the reordering of cache_behaviors.

purge_custom_error_responses

-

Default:

"no"

Whether to remove any custom error responses that aren't listed in custom_error_responses

purge_origins

-

Default:

"no"

Whether to remove any origins that aren't listed in origins

purge_tags

boolean

  • no

  • yes

Specifies whether existing tags will be removed before adding new tags. When purge_tags=yes, existing tags are removed and tags are added, if specified. If no tags are specified, it removes all existing tags for the distribution. When purge_tags=no, existing tags are kept and tags are added, if specified.

region

-

The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region


aliases: aws_region, ec2_region

restrictions

-

A config element that is a complex object that describes how a distribution should restrict it's content. The restriction object comprises the following attributes geo_restriction restriction_type items[]

security_token

-

added in 1.6

AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.


aliases: access_token

state

-

  • present

  • absent

The desired state of the distribution present - creates a new distribution or updates an existing distribution. absent - deletes an existing distribution.

tags

-

Should be input as a dict() of key-value pairs. Note that numeric keys or values must be wrapped in quotes. e.g. "Priority:" '1'

validate_certs

boolean

added in 1.5

  • no
  • yes

When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.

viewer_certificate

-

A config element that is a complex object that specifies the encryption details of the distribution. Comprises the following attributes cloudfront_default_certificate iam_certificate_id acm_certificate_arn ssl_support_method minimum_protocol_version certificate certificate_source

wait

boolean

  • no

  • yes

Specifies whether the module waits until the distribution has completed processing the creation or update.

wait_timeout

-

Default:

1800

Specifies the duration in seconds to wait for a timeout of a cloudfront create or update. Defaults to 1800 seconds (30 minutes).

web_acl_id

-

The id of a Web Application Firewall (WAF) Access Control List (ACL).



Notes

Note

  • If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence AWS_URL or EC2_URL, AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY or EC2_ACCESS_KEY, AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY or EC2_SECRET_KEY, AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN, AWS_REGION or EC2_REGION
  • Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html
  • AWS_REGION or EC2_REGION can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file


Examples

# create a basic distribution with defaults and tags

- cloudfront_distribution:
    state: present
    default_origin_domain_name: www.my-cloudfront-origin.com
    tags:
      Name: example distribution
      Project: example project
      Priority: '1'

# update a distribution comment by distribution_id

- cloudfront_distribution:
    state: present
    distribution_id: E1RP5A2MJ8073O
    comment: modified by ansible cloudfront.py

# update a distribution comment by caller_reference

- cloudfront_distribution:
    state: present
    caller_reference: my cloudfront distribution 001
    comment: modified by ansible cloudfront.py

# update a distribution's aliases and comment using the distribution_id as a reference

- cloudfront_distribution:
    state: present
    distribution_id: E1RP5A2MJ8073O
    comment: modified by cloudfront.py again
    aliases: [ 'www.my-distribution-source.com', 'zzz.aaa.io' ]

# update a distribution's aliases and comment using an alias as a reference

- cloudfront_distribution:
    state: present
    caller_reference: my test distribution
    comment: modified by cloudfront.py again
    aliases:
      - www.my-distribution-source.com
      - zzz.aaa.io

# update a distribution's comment and aliases and tags and remove existing tags

- cloudfront_distribution:
    state: present
    distribution_id: E15BU8SDCGSG57
    comment: modified by cloudfront.py again
    aliases:
      - tested.com
    tags:
      Project: distribution 1.2
    purge_tags: yes

# create a distribution with an origin, logging and default cache behavior

- cloudfront_distribution:
    state: present
    caller_reference: unique test distribution id
    origins:
        - id: 'my test origin-000111'
          domain_name: www.example.com
          origin_path: /production
          custom_headers:
            - header_name: MyCustomHeaderName
              header_value: MyCustomHeaderValue
    default_cache_behavior:
      target_origin_id: 'my test origin-000111'
      forwarded_values:
        query_string: true
        cookies:
          forward: all
        headers:
         - '*'
      viewer_protocol_policy: allow-all
      smooth_streaming: true
      compress: true
      allowed_methods:
        items:
          - GET
          - HEAD
        cached_methods:
          - GET
          - HEAD
    logging:
      enabled: true
      include_cookies: false
      bucket: mylogbucket.s3.amazonaws.com
      prefix: myprefix/
    enabled: false
    comment: this is a cloudfront distribution with logging

# delete a distribution

- cloudfront_distribution:
    state: absent
    caller_reference: replaceable distribution

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description

active_trusted_signers

complex

always

Key pair IDs that CloudFront is aware of for each trusted signer


enabled

boolean

always

Whether trusted signers are in use


items

list

when there are trusted signers

Number of trusted signers


Sample:

['key_pair_id']

quantity

integer

always

Number of trusted signers


Sample:

1

aliases

complex

always

Aliases that refer to the distribution


items

list

always

List of aliases


Sample:

['test.example.com']

quantity

integer

always

Number of aliases


Sample:

1

arn

string

always

Amazon Resource Name of the distribution


Sample:

arn:aws:cloudfront::123456789012:distribution/E1234ABCDEFGHI

cache_behaviors

complex

always

Cloudfront cache behaviors


items

complex

always

List of cache behaviors


allowed_methods

complex

always

Methods allowed by the cache behavior


cached_methods

complex

always

Methods cached by the cache behavior


items

list

always

List of cached methods


Sample:

['HEAD', 'GET']

quantity

integer

always

Count of cached methods


Sample:

2

items

list

always

List of methods allowed by the cache behavior


Sample:

['HEAD', 'GET']

quantity

integer

always

Count of methods allowed by the cache behavior


Sample:

2

compress

boolean

always

Whether compression is turned on for the cache behavior


default_ttl

integer

always

Default Time to Live of the cache behavior


Sample:

86400

forwarded_values

complex

always

Values forwarded to the origin for this cache behavior


cookies

complex

always

Cookies to forward to the origin


forward

string

always

Which cookies to forward to the origin for this cache behavior


Sample:

none

whitelisted_names

complex

when forward is whitelist

The names of the cookies to forward to the origin for this cache behavior


items

list

when list is not empty

List of cookies to forward


Sample:

my_cookie

quantity

integer

always

Count of cookies to forward


Sample:

1

headers

complex

always

Which headers are used to vary on cache retrievals


items

list

when list is not empty

List of headers to vary on


Sample:

['Host']

quantity

integer

always

Count of headers to vary on


Sample:

1

query_string

boolean

always

Whether the query string is used in cache lookups


query_string_cache_keys

complex

always

Which query string keys to use in cache lookups


items

list

when list is not empty

List of query string cache keys to use in cache lookups


quantity

integer

always

Count of query string cache keys to use in cache lookups


Sample:

1

lambda_function_associations

complex

always

Lambda function associations for a cache behavior


items

list

when list is not empty

List of lambda function associations


Sample:

[{'lambda_function_arn': 'arn:aws:lambda:123456789012:us-east-1/lambda/lambda-function', 'event_type': 'viewer-response'}]

quantity

integer

always

Count of lambda function associations


Sample:

1

max_ttl

integer

always

Maximum Time to Live


Sample:

31536000

min_ttl

integer

always

Minimum Time to Live


path_pattern

string

always

Path pattern that determines this cache behavior


Sample:

/path/to/files/*

smooth_streaming

boolean

always

Whether smooth streaming is enabled


target_origin_id

string

always

Id of origin reference by this cache behavior


Sample:

origin_abcd

trusted_signers

complex

always

Trusted signers


enabled

boolean

always

Whether trusted signers are enabled for this cache behavior


quantity

integer

always

Count of trusted signers


Sample:

1

viewer_protocol_policy

string

always

Policy of how to handle http/https


Sample:

redirect-to-https

quantity

integer

always

Count of cache behaviors


Sample:

1

caller_reference

string

always

Idempotency reference given when creating cloudfront distribution


Sample:

1484796016700

comment

string

always

Any comments you want to include about the distribution


Sample:

my first cloudfront distribution

custom_error_responses

complex

always

Custom error responses to use for error handling


items

complex

always

List of custom error responses


error_caching_min_ttl

integer

always

Mininum time to cache this error response


Sample:

300

error_code

integer

always

Origin response code that triggers this error response


Sample:

500

response_code

string

always

Response code to return to the requester


Sample:

500

response_page_path

string

always

Path that contains the error page to display


Sample:

/errors/5xx.html

quantity

integer

always

Count of custom error response items


Sample:

1

default_cache_behavior

complex

always

Default cache behavior


allowed_methods

complex

always

Methods allowed by the cache behavior


cached_methods

complex

always

Methods cached by the cache behavior


items

list

always

List of cached methods


Sample:

['HEAD', 'GET']

quantity

integer

always

Count of cached methods


Sample:

2

items

list

always

List of methods allowed by the cache behavior


Sample:

['HEAD', 'GET']

quantity

integer

always

Count of methods allowed by the cache behavior


Sample:

2

compress

boolean

always

Whether compression is turned on for the cache behavior


default_ttl

integer

always

Default Time to Live of the cache behavior


Sample:

86400

forwarded_values

complex

always

Values forwarded to the origin for this cache behavior


cookies

complex

always

Cookies to forward to the origin


forward

string

always

Which cookies to forward to the origin for this cache behavior


Sample:

none

whitelisted_names

complex

when forward is whitelist

The names of the cookies to forward to the origin for this cache behavior


items

list

when list is not empty

List of cookies to forward


Sample:

my_cookie

quantity

integer

always

Count of cookies to forward


Sample:

1

headers

complex

always

Which headers are used to vary on cache retrievals


items

list

when list is not empty

List of headers to vary on


Sample:

['Host']

quantity

integer

always

Count of headers to vary on


Sample:

1

query_string

boolean

always

Whether the query string is used in cache lookups


query_string_cache_keys

complex

always

Which query string keys to use in cache lookups


items

list

when list is not empty

List of query string cache keys to use in cache lookups


quantity

integer

always

Count of query string cache keys to use in cache lookups


Sample:

1

lambda_function_associations

complex

always

Lambda function associations for a cache behavior


items

list

when list is not empty

List of lambda function associations


Sample:

[{'lambda_function_arn': 'arn:aws:lambda:123456789012:us-east-1/lambda/lambda-function', 'event_type': 'viewer-response'}]

quantity

integer

always

Count of lambda function associations


Sample:

1

max_ttl

integer

always

Maximum Time to Live


Sample:

31536000

min_ttl

integer

always

Minimum Time to Live


path_pattern

string

always

Path pattern that determines this cache behavior


Sample:

/path/to/files/*

smooth_streaming

boolean

always

Whether smooth streaming is enabled


target_origin_id

string

always

Id of origin reference by this cache behavior


Sample:

origin_abcd

trusted_signers

complex

always

Trusted signers


enabled

boolean

always

Whether trusted signers are enabled for this cache behavior


quantity

integer

always

Count of trusted signers


Sample:

1

viewer_protocol_policy

string

always

Policy of how to handle http/https


Sample:

redirect-to-https

default_root_object

string

always

The object that you want CloudFront to request from your origin (for example, index.html) when a viewer requests the root URL for your distribution


diff

dictionary

always

Difference between previous configuration and new configuration


domain_name

string

always

Domain name of cloudfront distribution


Sample:

d1vz8pzgurxosf.cloudfront.net

enabled

boolean

always

Whether the cloudfront distribution is enabled or not


Sample:

True

http_version

string

always

Version of HTTP supported by the distribution


Sample:

http2

id

string

always

Cloudfront distribution ID


Sample:

E123456ABCDEFG

in_progress_invalidation_batches

integer

always

The number of invalidation batches currently in progress


is_ipv6_enabled

boolean

always

Whether IPv6 is enabled


Sample:

True

last_modified_time

string

always

Date and time distribution was last modified


Sample:

2017-10-13T01:51:12.656000+00:00

logging

complex

always

Logging information


bucket

string

always

S3 bucket logging destination


Sample:

logs-example-com.s3.amazonaws.com

enabled

boolean

always

Whether logging is enabled


Sample:

True

include_cookies

boolean

always

Whether to log cookies


prefix

string

always

Prefix added to logging object names


Sample:

cloudfront/test

origins

complex

always

Origins in the cloudfront distribution


items

complex

always

List of origins


custom_headers

complex

always

Custom headers passed to the origin


quantity

integer

always

Count of headers


Sample:

1

custom_origin_config

complex

always

Configuration of the origin


http_port

integer

always

Port on which HTTP is listening


Sample:

80

https_port

integer

always

Port on which HTTPS is listening


Sample:

443

origin_keepalive_timeout

integer

always

Keep-alive timeout


Sample:

5

origin_protocol_policy

string

always

Policy of which protocols are supported


Sample:

https-only

origin_read_timeout

integer

always

Timeout for reads to the origin


Sample:

30

origin_ssl_protocols

complex

always

SSL protocols allowed by the origin


items

list

always

List of SSL protocols


Sample:

['TLSv1', 'TLSv1.1', 'TLSv1.2']

quantity

integer

always

Count of SSL protocols


Sample:

3

domain_name

string

always

Domain name of the origin


Sample:

test-origin.example.com

id

string

always

ID of the origin


Sample:

test-origin.example.com

origin_path

string

always

Subdirectory to prefix the request from the S3 or HTTP origin


quantity

integer

always

Count of origins


Sample:

1

price_class

string

always

Price class of cloudfront distribution


Sample:

PriceClass_All

restrictions

complex

always

Restrictions in use by Cloudfront


geo_restriction

complex

always

Controls the countries in which your content is distributed.


items

list

always

List of country codes allowed or disallowed


Sample:

xy

quantity

integer

always

Count of restrictions


Sample:

1

restriction_type

string

always

Type of restriction


Sample:

blacklist

status

string

always

Status of the cloudfront distribution


Sample:

InProgress

tags

dictionary

always

Distribution tags


Sample:

{'Hello': 'World'}

viewer_certificate

complex

always

Certificate used by cloudfront distribution


acm_certificate_arn

string

when certificate comes from ACM

ARN of ACM certificate


Sample:

arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456abcdef

certificate

string

always

Reference to certificate


Sample:

arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456abcdef

certificate_source

string

always

Where certificate comes from


Sample:

acm

minimum_protocol_version

string

always

Minimum SSL/TLS protocol supported by this distribution


Sample:

TLSv1

ssl_support_method

string

always

Support for pre-SNI browsers or not


Sample:

sni-only

web_acl_id

string

always

ID of Web Access Control List (from WAF service)


Sample:

abcd1234-1234-abcd-abcd-abcd12345678




Status

Authors

  • Willem van Ketwich (@wilvk)
  • Will Thames (@willthames)

Hint

If you notice any issues in this documentation you can edit this document to improve it.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/cloudfront_distribution_module.html