ansible / ansible.builtin / v2.9.17 / module / cloudfront_distribution create, update and delete aws cloudfront distributions. | "added in version" 2.5 of ansible.builtin" Authors: Willem van Ketwich (@wilvk), Will Thames (@willthames) preview | supported by communityansible.builtin.cloudfront_distribution (v2.9.17) — module
pip
Install with pip install ansible==2.9.17
Allows for easy creation, updating and deletion of CloudFront distributions.
# 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
tags: description: - 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' wait: default: 'no' description: - Specifies whether the module waits until the distribution has completed processing the creation or update. type: bool alias: description: - 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 I(distribution_id) as well as the I(e_tag), or I(caller_reference) of an existing distribution. e_tag: description: - A unique identifier of a modified or existing distribution. Used in conjunction with I(distribution_id). Is determined automatically if not specified. state: choices: - present - absent default: present description: - The desired state of the distribution present - creates a new distribution or updates an existing distribution. absent - deletes an existing distribution. region: aliases: - aws_region - ec2_region description: - 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 U(http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region) type: str aliases: description: - A I(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. comment: description: - 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. ec2_url: aliases: - aws_endpoint_url - endpoint_url description: - 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. type: str enabled: default: 'yes' description: - A boolean value that specifies whether the distribution is enabled or disabled. type: bool logging: description: - A config element that is a complex object that defines logging for the distribution. The logging object comprises the attributes I(enabled) I(include_cookies) I(bucket) I(prefix) origins: description: - A config element that is a I(list[]) of complex origin objects to be specified for the distribution. Used for creating and updating distributions. Each origin item comprises the attributes I(id) I(domain_name) (defaults to default_origin_domain_name if not specified) I(origin_path) (defaults to default_origin_path if not specified) I(custom_headers[]) I(header_name) I(header_value) I(s3_origin_access_identity_enabled) I(custom_origin_config) I(http_port) I(https_port) I(origin_protocol_policy) I(origin_ssl_protocols[]) I(origin_read_timeout) I(origin_keepalive_timeout) profile: aliases: - aws_profile description: - Using I(profile) will override I(aws_access_key), I(aws_secret_key) and I(security_token) and support for passing them at the same time as I(profile) has been deprecated. - I(aws_access_key), I(aws_secret_key) and I(security_token) will be made mutually exclusive with I(profile) after 2022-06-01. type: str aws_config: description: - A dictionary to modify the botocore configuration. - Parameters can be found at U(https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config). - Only the 'user_agent' key is used for boto modules. See U(http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto) for more boto configuration. type: dict purge_tags: default: 'no' description: - Specifies whether existing tags will be removed before adding new tags. When I(purge_tags=yes), existing tags are removed and I(tags) are added, if specified. If no tags are specified, it removes all existing tags for the distribution. When I(purge_tags=no), existing tags are kept and I(tags) are added, if specified. type: bool web_acl_id: description: - The id of a Web Application Firewall (WAF) Access Control List (ACL). price_class: choices: - PriceClass_100 - PriceClass_200 - PriceClass_All default: aws defaults this to 'PriceClass_All' description: - A string that specifies the pricing class of the distribution. As per U(https://aws.amazon.com/cloudfront/pricing/) I(price_class=PriceClass_100) consists of the areas United States Canada Europe I(price_class=PriceClass_200) consists of the areas United States Canada Europe Hong Kong, Philippines, S. Korea, Singapore & Taiwan Japan India I(price_class=PriceClass_All) consists of the areas United States Canada Europe Hong Kong, Philippines, S. Korea, Singapore & Taiwan Japan India South America Australia http_version: choices: - http1.1 - http2 default: aws defaults this to 'http2' description: - The version of the http protocol to use for the distribution. ipv6_enabled: default: 'no' description: - Determines whether IPv6 support is enabled or not. type: bool restrictions: description: - 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 I(geo_restriction) I(restriction_type) I(items[]) wait_timeout: default: 1800 description: - Specifies the duration in seconds to wait for a timeout of a cloudfront create or update. Defaults to 1800 seconds (30 minutes). aws_ca_bundle: description: - The location of a CA Bundle to use when validating SSL certificates. - Not used by boto 2 based modules. - 'Note: The CA Bundle is read ''module'' side and may need to be explicitly copied from the controller if not run locally.' type: path purge_aliases: default: 'no' description: - Specifies whether existing aliases will be removed before adding new aliases. When I(purge_aliases=yes), existing aliases are removed and I(aliases) are added. type: bool purge_origins: default: false description: Whether to remove any origins that aren't listed in I(origins) type: bool aws_access_key: aliases: - ec2_access_key - access_key description: - C(AWS access key). If not set then the value of the C(AWS_ACCESS_KEY_ID), C(AWS_ACCESS_KEY) or C(EC2_ACCESS_KEY) environment variable is used. - If I(profile) is set this parameter is ignored. - Passing the I(aws_access_key) and I(profile) options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. type: str aws_secret_key: aliases: - ec2_secret_key - secret_key description: - C(AWS secret key). If not set then the value of the C(AWS_SECRET_ACCESS_KEY), C(AWS_SECRET_KEY), or C(EC2_SECRET_KEY) environment variable is used. - If I(profile) is set this parameter is ignored. - Passing the I(aws_secret_key) and I(profile) options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. type: str security_token: aliases: - aws_security_token - access_token description: - C(AWS STS security token). If not set then the value of the C(AWS_SECURITY_TOKEN) or C(EC2_SECURITY_TOKEN) environment variable is used. - If I(profile) is set this parameter is ignored. - Passing the I(security_token) and I(profile) options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. type: str validate_certs: default: true description: - When set to "no", SSL certificates will not be validated for communication with the AWS APIs. type: bool cache_behaviors: description: - A config element that is a I(list[]) of complex cache behavior objects to be specified for the distribution. The order of the list is preserved across runs unless C(purge_cache_behavior) is enabled. Each cache behavior comprises the attributes I(path_pattern) I(target_origin_id) I(forwarded_values) I(query_string) I(cookies) I(forward) I(whitelisted_names) I(headers[]) I(query_string_cache_keys[]) I(trusted_signers) I(enabled) I(items[]) I(viewer_protocol_policy) I(min_ttl) I(allowed_methods) I(items[]) I(cached_methods[]) I(smooth_streaming) I(default_ttl) I(max_ttl) I(compress) I(lambda_function_associations[]) I(field_level_encryption_id) distribution_id: description: - The id of the cloudfront distribution. This parameter can be exchanged with I(alias) or I(caller_reference) and is used in conjunction with I(e_tag). caller_reference: description: - 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 I(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'. viewer_certificate: description: - A config element that is a complex object that specifies the encryption details of the distribution. Comprises the following attributes I(cloudfront_default_certificate) I(iam_certificate_id) I(acm_certificate_arn) I(ssl_support_method) I(minimum_protocol_version) I(certificate) I(certificate_source) default_origin_path: description: - The default origin path to specify for an origin if no I(origins) have been specified. Defaults to empty if not specified. default_root_object: description: - 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. purge_cache_behaviors: default: false description: Whether to remove any cache behaviors that aren't listed in I(cache_behaviors). This switch also allows the reordering of cache_behaviors. type: bool custom_error_responses: description: - A config element that is a I(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 I(error_code) I(response_page_path) I(response_code) I(error_caching_min_ttl) default_cache_behavior: description: - A config element that is a complex object specifying the default cache behavior of the distribution. If not specified, the I(target_origin_id) is defined as the I(target_origin_id) of the first valid I(cache_behavior) in I(cache_behaviors) with defaults. The default cache behavior comprises the attributes I(target_origin_id) I(forwarded_values) I(query_string) I(cookies) I(forward) I(whitelisted_names) I(headers[]) I(query_string_cache_keys[]) I(trusted_signers) I(enabled) I(items[]) I(viewer_protocol_policy) I(min_ttl) I(allowed_methods) I(items[]) I(cached_methods[]) I(smooth_streaming) I(default_ttl) I(max_ttl) I(compress) I(lambda_function_associations[]) I(lambda_function_arn) I(event_type) I(field_level_encryption_id) default_origin_domain_name: description: - The domain name to use for an origin if no I(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 I(distribution_id), I(caller_reference) or I(alias). debug_botocore_endpoint_logs: default: 'no' description: - 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. type: bool purge_custom_error_responses: default: false description: Whether to remove any custom error responses that aren't listed in I(custom_error_responses) type: bool
active_trusted_signers: contains: enabled: description: Whether trusted signers are in use returned: always sample: false type: bool items: description: Number of trusted signers returned: when there are trusted signers sample: - key_pair_id type: list quantity: description: Number of trusted signers returned: always sample: 1 type: int description: Key pair IDs that CloudFront is aware of for each trusted signer returned: always type: complex aliases: contains: items: description: List of aliases returned: always sample: - test.example.com type: list quantity: description: Number of aliases returned: always sample: 1 type: int description: Aliases that refer to the distribution returned: always type: complex arn: description: Amazon Resource Name of the distribution returned: always sample: arn:aws:cloudfront::123456789012:distribution/E1234ABCDEFGHI type: str cache_behaviors: contains: items: contains: allowed_methods: contains: cached_methods: contains: items: description: List of cached methods returned: always sample: - HEAD - GET type: list quantity: description: Count of cached methods returned: always sample: 2 type: int description: Methods cached by the cache behavior returned: always type: complex items: description: List of methods allowed by the cache behavior returned: always sample: - HEAD - GET type: list quantity: description: Count of methods allowed by the cache behavior returned: always sample: 2 type: int description: Methods allowed by the cache behavior returned: always type: complex compress: description: Whether compression is turned on for the cache behavior returned: always sample: false type: bool default_ttl: description: Default Time to Live of the cache behavior returned: always sample: 86400 type: int forwarded_values: contains: cookies: contains: forward: description: Which cookies to forward to the origin for this cache behavior returned: always sample: none type: str whitelisted_names: contains: items: description: List of cookies to forward returned: when list is not empty sample: my_cookie type: list quantity: description: Count of cookies to forward returned: always sample: 1 type: int description: The names of the cookies to forward to the origin for this cache behavior returned: when I(forward) is C(whitelist) type: complex description: Cookies to forward to the origin returned: always type: complex headers: contains: items: description: List of headers to vary on returned: when list is not empty sample: - Host type: list quantity: description: Count of headers to vary on returned: always sample: 1 type: int description: Which headers are used to vary on cache retrievals returned: always type: complex query_string: description: Whether the query string is used in cache lookups returned: always sample: false type: bool query_string_cache_keys: contains: items: description: List of query string cache keys to use in cache lookups returned: when list is not empty sample: null type: list quantity: description: Count of query string cache keys to use in cache lookups returned: always sample: 1 type: int description: Which query string keys to use in cache lookups returned: always type: complex description: Values forwarded to the origin for this cache behavior returned: always type: complex lambda_function_associations: contains: items: description: List of lambda function associations returned: when list is not empty sample: - event_type: viewer-response lambda_function_arn: arn:aws:lambda:123456789012:us-east-1/lambda/lambda-function type: list quantity: description: Count of lambda function associations returned: always sample: 1 type: int description: Lambda function associations for a cache behavior returned: always type: complex max_ttl: description: Maximum Time to Live returned: always sample: 31536000 type: int min_ttl: description: Minimum Time to Live returned: always sample: 0 type: int path_pattern: description: Path pattern that determines this cache behavior returned: always sample: /path/to/files/* type: str smooth_streaming: description: Whether smooth streaming is enabled returned: always sample: false type: bool target_origin_id: description: Id of origin reference by this cache behavior returned: always sample: origin_abcd type: str trusted_signers: contains: enabled: description: Whether trusted signers are enabled for this cache behavior returned: always sample: false type: bool quantity: description: Count of trusted signers returned: always sample: 1 type: int description: Trusted signers returned: always type: complex viewer_protocol_policy: description: Policy of how to handle http/https returned: always sample: redirect-to-https type: str description: List of cache behaviors returned: always type: complex quantity: description: Count of cache behaviors returned: always sample: 1 type: int description: Cloudfront cache behaviors returned: always type: complex caller_reference: description: Idempotency reference given when creating cloudfront distribution returned: always sample: '1484796016700' type: str comment: description: Any comments you want to include about the distribution returned: always sample: my first cloudfront distribution type: str custom_error_responses: contains: items: contains: error_caching_min_ttl: description: Minimum time to cache this error response returned: always sample: 300 type: int error_code: description: Origin response code that triggers this error response returned: always sample: 500 type: int response_code: description: Response code to return to the requester returned: always sample: '500' type: str response_page_path: description: Path that contains the error page to display returned: always sample: /errors/5xx.html type: str description: List of custom error responses returned: always type: complex quantity: description: Count of custom error response items returned: always sample: 1 type: int description: Custom error responses to use for error handling returned: always type: complex default_cache_behavior: contains: allowed_methods: contains: cached_methods: contains: items: description: List of cached methods returned: always sample: - HEAD - GET type: list quantity: description: Count of cached methods returned: always sample: 2 type: int description: Methods cached by the cache behavior returned: always type: complex items: description: List of methods allowed by the cache behavior returned: always sample: - HEAD - GET type: list quantity: description: Count of methods allowed by the cache behavior returned: always sample: 2 type: int description: Methods allowed by the cache behavior returned: always type: complex compress: description: Whether compression is turned on for the cache behavior returned: always sample: false type: bool default_ttl: description: Default Time to Live of the cache behavior returned: always sample: 86400 type: int forwarded_values: contains: cookies: contains: forward: description: Which cookies to forward to the origin for this cache behavior returned: always sample: none type: str whitelisted_names: contains: items: description: List of cookies to forward returned: when list is not empty sample: my_cookie type: list quantity: description: Count of cookies to forward returned: always sample: 1 type: int description: The names of the cookies to forward to the origin for this cache behavior returned: when I(forward) is C(whitelist) type: complex description: Cookies to forward to the origin returned: always type: complex headers: contains: items: description: List of headers to vary on returned: when list is not empty sample: - Host type: list quantity: description: Count of headers to vary on returned: always sample: 1 type: int description: Which headers are used to vary on cache retrievals returned: always type: complex query_string: description: Whether the query string is used in cache lookups returned: always sample: false type: bool query_string_cache_keys: contains: items: description: List of query string cache keys to use in cache lookups returned: when list is not empty sample: null type: list quantity: description: Count of query string cache keys to use in cache lookups returned: always sample: 1 type: int description: Which query string keys to use in cache lookups returned: always type: complex description: Values forwarded to the origin for this cache behavior returned: always type: complex lambda_function_associations: contains: items: description: List of lambda function associations returned: when list is not empty sample: - event_type: viewer-response lambda_function_arn: arn:aws:lambda:123456789012:us-east-1/lambda/lambda-function type: list quantity: description: Count of lambda function associations returned: always sample: 1 type: int description: Lambda function associations for a cache behavior returned: always type: complex max_ttl: description: Maximum Time to Live returned: always sample: 31536000 type: int min_ttl: description: Minimum Time to Live returned: always sample: 0 type: int path_pattern: description: Path pattern that determines this cache behavior returned: always sample: /path/to/files/* type: str smooth_streaming: description: Whether smooth streaming is enabled returned: always sample: false type: bool target_origin_id: description: Id of origin reference by this cache behavior returned: always sample: origin_abcd type: str trusted_signers: contains: enabled: description: Whether trusted signers are enabled for this cache behavior returned: always sample: false type: bool quantity: description: Count of trusted signers returned: always sample: 1 type: int description: Trusted signers returned: always type: complex viewer_protocol_policy: description: Policy of how to handle http/https returned: always sample: redirect-to-https type: str description: Default cache behavior returned: always type: complex default_root_object: description: 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 returned: always sample: '' type: str diff: description: Difference between previous configuration and new configuration returned: always sample: {} type: dict domain_name: description: Domain name of cloudfront distribution returned: always sample: d1vz8pzgurxosf.cloudfront.net type: str enabled: description: Whether the cloudfront distribution is enabled or not returned: always sample: true type: bool http_version: description: Version of HTTP supported by the distribution returned: always sample: http2 type: str id: description: Cloudfront distribution ID returned: always sample: E123456ABCDEFG type: str in_progress_invalidation_batches: description: The number of invalidation batches currently in progress returned: always sample: 0 type: int is_ipv6_enabled: description: Whether IPv6 is enabled returned: always sample: true type: bool last_modified_time: description: Date and time distribution was last modified returned: always sample: '2017-10-13T01:51:12.656000+00:00' type: str logging: contains: bucket: description: S3 bucket logging destination returned: always sample: logs-example-com.s3.amazonaws.com type: str enabled: description: Whether logging is enabled returned: always sample: true type: bool include_cookies: description: Whether to log cookies returned: always sample: false type: bool prefix: description: Prefix added to logging object names returned: always sample: cloudfront/test type: str description: Logging information returned: always type: complex origins: contains: items: contains: custom_headers: contains: quantity: description: Count of headers returned: always sample: 1 type: int description: Custom headers passed to the origin returned: always type: complex custom_origin_config: contains: http_port: description: Port on which HTTP is listening returned: always sample: 80 type: int https_port: description: Port on which HTTPS is listening returned: always sample: 443 type: int origin_keepalive_timeout: description: Keep-alive timeout returned: always sample: 5 type: int origin_protocol_policy: description: Policy of which protocols are supported returned: always sample: https-only type: str origin_read_timeout: description: Timeout for reads to the origin returned: always sample: 30 type: int origin_ssl_protocols: contains: items: description: List of SSL protocols returned: always sample: - TLSv1 - TLSv1.1 - TLSv1.2 type: list quantity: description: Count of SSL protocols returned: always sample: 3 type: int description: SSL protocols allowed by the origin returned: always type: complex description: Configuration of the origin returned: always type: complex domain_name: description: Domain name of the origin returned: always sample: test-origin.example.com type: str id: description: ID of the origin returned: always sample: test-origin.example.com type: str origin_path: description: Subdirectory to prefix the request from the S3 or HTTP origin returned: always sample: '' type: str description: List of origins returned: always type: complex quantity: description: Count of origins returned: always sample: 1 type: int description: Origins in the cloudfront distribution returned: always type: complex price_class: description: Price class of cloudfront distribution returned: always sample: PriceClass_All type: str restrictions: contains: geo_restriction: contains: items: description: List of country codes allowed or disallowed returned: always sample: xy type: list quantity: description: Count of restrictions returned: always sample: 1 type: int restriction_type: description: Type of restriction returned: always sample: blacklist type: str description: Controls the countries in which your content is distributed. returned: always type: complex description: Restrictions in use by Cloudfront returned: always type: complex status: description: Status of the cloudfront distribution returned: always sample: InProgress type: str tags: description: Distribution tags returned: always sample: Hello: World type: dict viewer_certificate: contains: acm_certificate_arn: description: ARN of ACM certificate returned: when certificate comes from ACM sample: arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456abcdef type: str certificate: description: Reference to certificate returned: always sample: arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-1234-1234-abcd-123456abcdef type: str certificate_source: description: Where certificate comes from returned: always sample: acm type: str minimum_protocol_version: description: Minimum SSL/TLS protocol supported by this distribution returned: always sample: TLSv1 type: str ssl_support_method: description: Support for pre-SNI browsers or not returned: always sample: sni-only type: str description: Certificate used by cloudfront distribution returned: always type: complex web_acl_id: description: ID of Web Access Control List (from WAF service) returned: always sample: abcd1234-1234-abcd-abcd-abcd12345678 type: str