- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# cloudfront_distribution – create, update and delete aws cloudfront distributions

New in version 2.5.

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## 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 string |  | 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 string |  | 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 response_page_path response_code error_caching_min_ttl
debug_botocore_endpoint_logs boolean added in 2.8 | Choices: no ← yes | Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.
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 string |  | 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 | Choices: no yes ← | A boolean value that specifies whether the distribution is enabled or disabled.
http_version - | Choices: http1.1 http2 Default: "aws defaults this to \u0027http2\u0027" | The version of the http protocol to use for the distribution.
ipv6_enabled boolean | Choices: 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 - | Choices: 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 string |  | Uses a boto profile. Only works with boto >= 2.24.0.
purge_aliases boolean | Choices: 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 boolean | Choices: no ← yes | 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 boolean | Choices: no ← yes | Whether to remove any custom error responses that aren't listed in custom_error_responses
purge_origins boolean | Choices: no ← yes | Whether to remove any origins that aren't listed in origins
purge_tags boolean | Choices: 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 string |  | 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 string |  | 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 boolean | 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 boolean | Choices: 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 | Minimum 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

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

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