Documentation

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[]
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
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
    Choices:
  • yes ←
  • no
A boolean value that specifies whether the distribution is enabled or disabled.
http_version
    Choices:
  • http1.1
  • http2
Default:
aws defaults this to 'http2'
The version of the http protocol to use for the distribution.
ipv6_enabled
    Choices:
  • yes
  • no ←
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
    Choices:
  • PriceClass_100
  • PriceClass_200
  • PriceClass_All
Default:
aws defaults this to 'PriceClass_All'
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
    Choices:
  • yes
  • no ←
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
    Choices:
  • yes
  • no ←
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
    Choices:
  • 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
(added in 1.5)
    Choices:
  • 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
    Choices:
  • yes
  • no ←
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 http://boto.readthedocs.org/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

 
items
list
when there are trusted signers
Number of trusted signers

Sample:
['key_pair_id']
 
enabled
bool
always
Whether trusted signers are in use

 
quantity
int
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
int
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

 
 
trusted_signers
complex
always
Trusted signers

 
 
 
enabled
bool
always
Whether trusted signers are enabled for this cache behavior

 
 
 
quantity
int
always
Count of trusted signers

Sample:
1
 
 
allowed_methods
complex
always
Methods allowed by the cache behavior

 
 
 
items
list
always
List of methods allowed by the cache behavior

Sample:
['HEAD', 'GET']
 
 
 
cached_methods
complex
always
Methods cached by the cache behavior

 
 
 
 
items
list
always
List of cached methods

Sample:
['HEAD', 'GET']
 
 
 
 
quantity
int
always
Count of cached methods

Sample:
2
 
 
 
quantity
int
always
Count of methods allowed by the cache behavior

Sample:
2
 
 
compress
bool
always
Whether compression is turned on for the cache behavior

 
 
target_origin_id
string
always
Id of origin reference by this cache behavior

Sample:
origin_abcd
 
 
smooth_streaming
bool
always
Whether smooth streaming is enabled

 
 
default_ttl
int
always
Default Time to Live of the cache behavior

Sample:
86400
 
 
min_ttl
int
always
Minimum Time to Live

 
 
viewer_protocol_policy
string
always
Policy of how to handle http/https

Sample:
redirect-to-https
 
 
max_ttl
int
always
Maximum Time to Live

Sample:
31536000
 
 
path_pattern
string
always
Path pattern that determines this cache behavior

Sample:
/path/to/files/*
 
 
forwarded_values
complex
always
Values forwarded to the origin for this cache behavior

 
 
 
query_string
bool
always
Whether the query string is used in cache lookups

 
 
 
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
int
always
Count of headers to vary on

Sample:
1
 
 
 
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
int
always
Count of cookies to forward

Sample:
1
 
 
 
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
int
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
int
always
Count of lambda function associations

Sample:
1
 
quantity
int
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
int
always
Mininum time to cache this error response

Sample:
300
 
 
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
 
 
error_code
int
always
Origin response code that triggers this error response

Sample:
500
 
quantity
int
always
Count of custom error response items

Sample:
1
default_cache_behavior
complex
always
Default cache behavior

 
trusted_signers
complex
always
Trusted signers

 
 
enabled
bool
always
Whether trusted signers are enabled for this cache behavior

 
 
quantity
int
always
Count of trusted signers

Sample:
1
 
allowed_methods
complex
always
Methods allowed by the cache behavior

 
 
items
list
always
List of methods allowed by the cache behavior

Sample:
['HEAD', 'GET']
 
 
cached_methods
complex
always
Methods cached by the cache behavior

 
 
 
items
list
always
List of cached methods

Sample:
['HEAD', 'GET']
 
 
 
quantity
int
always
Count of cached methods

Sample:
2
 
 
quantity
int
always
Count of methods allowed by the cache behavior

Sample:
2
 
compress
bool
always
Whether compression is turned on for the cache behavior

 
target_origin_id
string
always
Id of origin reference by this cache behavior

Sample:
origin_abcd
 
smooth_streaming
bool
always
Whether smooth streaming is enabled

 
default_ttl
int
always
Default Time to Live of the cache behavior

Sample:
86400
 
min_ttl
int
always
Minimum Time to Live

 
viewer_protocol_policy
string
always
Policy of how to handle http/https

Sample:
redirect-to-https
 
max_ttl
int
always
Maximum Time to Live

Sample:
31536000
 
path_pattern
string
always
Path pattern that determines this cache behavior

Sample:
/path/to/files/*
 
forwarded_values
complex
always
Values forwarded to the origin for this cache behavior

 
 
query_string
bool
always
Whether the query string is used in cache lookups

 
 
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
int
always
Count of headers to vary on

Sample:
1
 
 
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
int
always
Count of cookies to forward

Sample:
1
 
 
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
int
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
int
always
Count of lambda function associations

Sample:
1
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
dict
always
Difference between previous configuration and new configuration

domain_name
string
always
Domain name of cloudfront distribution

Sample:
d1vz8pzgurxosf.cloudfront.net
enabled
bool
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
int
always
The number of invalidation batches currently in progress

is_ipv6_enabled
bool
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
 
prefix
string
always
Prefix added to logging object names

Sample:
cloudfront/test
 
enabled
bool
always
Whether logging is enabled

Sample:
True
 
include_cookies
bool
always
Whether to log cookies

origins
complex
always
Origins in the cloudfront distribution

 
items
complex
always
List of origins

 
 
origin_path
string
always
Subdirectory to prefix the request from the S3 or HTTP origin

 
 
custom_headers
complex
always
Custom headers passed to the origin

 
 
 
quantity
int
always
Count of headers

Sample:
1
 
 
id
string
always
ID of the origin

Sample:
test-origin.example.com
 
 
custom_origin_config
complex
always
Configuration of the origin

 
 
 
http_port
int
always
Port on which HTTP is listening

Sample:
80
 
 
 
https_port
int
always
Port on which HTTPS is listening

Sample:
443
 
 
 
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
int
always
Count of SSL protocols

Sample:
3
 
 
 
origin_keepalive_timeout
int
always
Keep-alive timeout

Sample:
5
 
 
 
origin_protocol_policy
string
always
Policy of which protocols are supported

Sample:
https-only
 
 
 
origin_read_timeout
int
always
Timeout for reads to the origin

Sample:
30
 
 
domain_name
string
always
Domain name of the origin

Sample:
test-origin.example.com
 
quantity
int
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
int
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
dict
always
Distribution tags

Sample:
{'Hello': 'World'}
viewer_certificate
complex
always
Certificate used by cloudfront distribution

 
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
 
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
web_acl_id
string
always
ID of Web Access Control List (from WAF service)

Sample:
abcd1234-1234-abcd-abcd-abcd12345678


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Author

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

Hint

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