terraform-aws-cloudfront

A project that provides an AWS (Amazon Web Services) CloudFront Terraform module.

Usage

Simple CDN with S3 Bucket:

module "simple-cdn-with-s3" {
  source = "../../"
  # myapp is merely a placeholder. Replace it with actual name.
  name = "myapp.nurdsoft.co"
  tags = {
    cloud            = "aws"
    environment      = "dev"
    region           = "use1"
    application_name = "myapp"
  }
}

Simple CDN with Custom S3 Bucket Policy:

locals {
  bucket_name = "myapp.nurdsoft.co"
}

data "aws_iam_policy_document" "bucket_policy" {
  statement {
    actions = [
      "s3:ListBucket",
    ]

    resources = [
      "arn:aws:s3:::${local.bucket_name}/*",
    ]
  }
}

module "simple-cdn-with-custom-s3-policy" {
  source = "../../"
  name             = local.bucket_name
  s3_custom_policy = data.aws_iam_policy_document.bucket_policy.json
  tags = {
    cloud            = "aws"
    environment      = "dev"
    region           = "use1"
    application_name = "myapp"
  }
}

Assumptions

The module assumes the following:

• A basic understanding of Git.
• Git version >= 2.33.0.
• An existing AWS IAM user or role with access to create/update/delete resources defined in main.tf.
• An existing AWS Route53 Zone.
  • Important Note: This module relies on an existing Route 53 Hosted Zone matching for certificate validation. It will not create a new zone if one is not found; the lookup will simply fail.
• A basic understanding of Terraform.
• Terraform version >= 1.0.2.
• (Optional - for local testing) A basic understanding of Make.
  • Make version >= GNU Make 3.81.
  • Important Note: This project includes a Makefile to speed up local development in Terraform. The make targets act as a wrapper around Terraform commands. As such, make has only been tested/verified on Linux/Mac OS. Though, it is possible to install make using Chocolatey, we do not guarantee this approach as it has not been tested/verified. You may use the commands in the Makefile as a guide to run each Terraform command locally on Windows.

Contributions

Contributions are always welcome. As such, this project uses the main branch as the source of truth to track changes.

Step 1. Clone this project.

# Using Git
$ git clone [email protected]:nurdsoft/terraform-aws-cloudfront.git

# Using HTTPS
$ git clone https://github.com/nurdsoft/terraform-aws-cloudfront.git

Step 2. Checkout a feature branch: git checkout -b feature/abc.

Step 3. Validate the change/s locally by executing the steps defined under Test.

Step 4. If testing is successful, commit and push the new change/s to the remote.

$ git add file1 file2 ...

$ git commit -m "Adding some change"

$ git push --set-upstream origin feature/abc

Step 5. Once pushed, create a PR and assign it to a member for review.

• Important Note: It can be helpful to attach the terraform plan output in the PR.

Step 6. A team member reviews/approves/merges the change/s.

Step 7. Once merged, deploy the required changes as needed.

Step 8. Once deployed, verify that the changes have been deployed.

Test

Important Note: This project includes a Makefile to speed up local development in Terraform. The make targets act as a wrapper around Terraform commands. As such, make has only been tested/verified on Linux/Mac OS. Though, it is possible to install make using Chocolatey, we do not guarantee this approach as it has not been tested/verified. You may use the commands in the Makefile as a guide to run each Terraform command locally on Windows.

# Perform a dry-run on the infrastructure
$ make plan
# Create the infrastructure
$ make apply
# Perform a dry-run on a destroy
$ make plan-destroy
# Destroy the infrastructure
$ make destroy

Requirements

Name	Version
terraform	>= 1.0.2
aws	~> 3.68

Providers

Name	Version
aws	~> 3.68
aws.cert	~> 3.68
random	n/a

Modules

Name	Source	Version
aws_s3_bucket	[email protected]:nurdsoft/terraform-aws-modules-s3	v0.5.0

Resources

Name	Type
aws_acm_certificate.cloudfront	resource
aws_acm_certificate_validation.cert	resource
aws_cloudfront_distribution.cloudfront	resource
aws_cloudfront_origin_access_identity.origin_access_identity	resource
aws_iam_policy.cloudfront_read	resource
aws_iam_policy.cloudfront_write	resource
aws_iam_role.cloudfront	resource
aws_iam_role_policy_attachment.cloudfront_read	resource
aws_iam_role_policy_attachment.cloudfront_write	resource
aws_route53_record.cert_validation	resource
aws_route53_record.cloudfront	resource
aws_waf_web_acl.cloudfront	resource
random_string.external_id	resource
aws_caller_identity.current	data source
aws_iam_policy_document.assume_role	data source
aws_iam_policy_document.cloudfront	data source
aws_iam_policy_document.cloudfront_read	data source
aws_iam_policy_document.cloudfront_write	data source
aws_route53_zone.cloudfront	data source

Inputs

Name	Description	Type	Default	Required
acceleration_status	Set the acceleration status of an existing bucket. Options are Enabled or Suspended. NOTE: As of 10/15/19, acceleration_status in not available in the cn-north-1 or us-gov-west-1 regions.	string	"Enabled"	no
aliases	Extra CNAMEs (alternate domain names), if any, for this distribution. At this time you can specify up to 100 CNAMEs separated with commas.	list(string)	null	no
allow_cert_overwrite	Allow creation of r53 record to overwrite an existing record.	bool	true	no
attach_policy	Controls if S3 bucket should have bucket policy attached (set to true to use value of policy as bucket policy)	bool	false	no
block_public_acls	Whether Amazon S3 should block public ACLs for this bucket. Enabling this setting does not affect existing policies or ACLs. When set to true causes the following behavior: PUT Bucket acl and PUT Object acl calls will fail if the specified ACL allows public access. PUT Object calls will fail if the request includes an object ACL.	bool	true	no
block_public_policy	Whether Amazon S3 should block public bucket policies for this bucket. Enabling this setting does not affect the existing bucket policy. When set to true causes Amazon S3 to: Reject calls to PUT Bucket policy if the specified bucket policy allows public access.	bool	true	no
cache_allowed_methods	Controls which HTTP methods CloudFront processes and forwards to your Amazon S3 bucket or your custom origin.	list(string)	[ "GET", "HEAD" ]	no
cache_compress	Whether you want CloudFront to automatically compress content for web requests that include Accept-Encoding: gzip in the request header.	bool	true	no
cache_default_ttl	The default amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request in the absence of an Cache-Control max-age or Expires header.	number	3600	no
cache_max_ttl	The maximum amount of time (in seconds) that an object is in a CloudFront cache before CloudFront forwards another request to your origin to determine whether the object has been updated. Only effective in the presence of Cache-Control max-age, Cache-Control s-maxage, and Expires headers.	number	3600	no
cache_min_ttl	The minimum amount of time that you want objects to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.	number	3600	no
cache_target_origin_id	The value of ID for the origin that you want CloudFront to route requests to when a request matches the path pattern either for a cache behavior or for the default cache behavior.	string	"S3Origin"	no
cache_viewer_proto_policy	Use this element to specify the protocol that users can use to access the files in the origin specified by TargetOriginId when a request matches the path pattern in PathPattern. Options: allow-all, https-only, or redirect-to-https.	string	"redirect-to-https"	no
cached_methods	Controls whether CloudFront caches the response to requests using the specified HTTP methods.	list(string)	[ "GET", "HEAD" ]	no
cert_validation_method	The validation method for the ACM cert. Options: DNS or Email.	string	"DNS"	no
cloudfront_default_certificate	Set this to true if you want viewers to use HTTPS to request your objects and you're using the CloudFront domain name for your distribution. This should be specified in addition to acm_certificate_arn, or iam_certificate_id.	bool	false	no
comment	Any comments you want to include about the distribution.	string	null	no
create_cert_validation	Whether to create a certificate validation request. This is useful for applications that do not follow the <app_name>.disney.com convention. Should be set to true when creating a new CloudFront distribution but once available, set this to false.	bool	true	no
create_s3_bucket	Whether to create a bucket. This is useful when creating/testing multiple resources in addition to the bucket."	bool	true	no
default_name	The default name for the CloudFront distribution.	string	""	no
default_root_object	The object that you want CloudFront to return (for example, index.html) when an end user requests the root URL.	string	"index.html"	no
domain	The AWS ACM certificate name.	string	""	no
enable_acceleration	Whether to enable acceleration.	bool	false	no
enable_encryption	Whether to enable Server Side Encryption.	bool	false	no
enable_versioning	Whether to enable Versioning.	bool	false	no
enabled	Whether the distribution is enabled to accept end user requests for content.	bool	true	no
endpoint	Used to create a custom DNS record for the distribution.	string	""	no
err_cache_min_ttl	The minimum amount of time (in seconds) you want HTTP error codes to stay in CloudFront caches before CloudFront queries your origin to see whether the object has been updated.	number	10	no
err_code_one	The 4xx or 5xx HTTP status code that should be returned.	number	404	no
err_code_two	The 4xx or 5xx HTTP status code that should be returned.	number	403	no
err_resp_code_one	The HTTP status code that you want CloudFront to return with the custom error page to the viewer.	number	200	no
err_resp_code_two	The HTTP status code that you want CloudFront to return with the custom error page to the viewer.	number	200	no
err_resp_page_path	The path of the custom error page.	string	"/index.html"	no
force_destroy	A boolean that indicates all objects (including any locked objects) should be deleted from the bucket so that the bucket can be destroyed without error. These objects are not recoverable.	bool	false	no
fwd_value_cookie_fwd	Specifies whether you want CloudFront to forward cookies to the origin that is associated with this cache behavior. You can specify all, none or whitelist. If whitelist, you must include the subsequent whitelisted_names.	string	"none"	no
fwd_value_query_string	Indicates whether you want CloudFront to forward query strings to the origin that is associated with this cache behavior.	bool	true	no
generate_new	A random string to use for the External ID.	string	"something random but known"	no
http_version	The maximum HTTP version to support on the distribution. Allowed values are http1.1, http2, http2and3 and http3.	string	"http2"	no
ignore_public_acls	Whether Amazon S3 should ignore public ACLs for this bucket. Enabling this setting does not affect the persistence of any existing ACLs and doesn't prevent new public ACLs from being set. When set to true causes Amazon S3 to: Ignore public ACLs on this bucket and any objects that it contains.	bool	true	no
is_ipv6_enabled	Whether the IPv6 is enabled for the distribution.	bool	true	no
kms_master_key_id	The AWS KMS master key ID used for the SSE-KMS encryption. This can only be used when you set the value of sse_algorithm as aws:kms. The default aws/s3 AWS KMS master key is used if this element is absent while the sse_algorithm is aws:kms.	bool	false	no
logging_config	The logging configuration that controls how logs are written to your distribution (maximum one).	any	{}	no
name	The application/website name. E.g., foo in foo.bar.com.	string	""	no
origin_id	A unique identifier for the origin.	string	"S3Origin"	no
origin_path	A unique identifier for the origin path. This assumes that the directory structure is the following s3_bucket_name/current is the cloudfront origin path and /backups is the location of the tar.gz backup file for the deployment.	string	""	no
policy	(Optional) A valid list of bucket policy JSON document. Note that if the policy document is not specific enough (but still valid), Terraform may view the policy as constantly changing in a terraform plan. In this case, please make sure you use the verbose/specific version of the policy. For more information about building AWS IAM policy documents with Terraform, see the AWS IAM Policy Document Guide.	list(string)	[]	no
price_class	The price class for this distribution. Options: PriceClass_All, PriceClass_200, PriceClass_100.	string	"PriceClass_All"	no
r53_record_ttl	The TTL (time-to-live) of the record in seconds. This is required for non-alias records.	number	60	no
r53_record_type	The record type. Valid values are A, AAAA, CAA, CNAME, DS, MX, NAPTR, NS, PTR, SOA, SPF, SRV and TXT.	string	"CNAME"	no
r53_zone_private	Whether the Route53 zone is private.	bool	false	no
region	The AWS region in which services are provisioned.	string	"us-east-1"	no
restrict_public_buckets	Whether Amazon S3 should restrict public bucket policies for this bucket. Enabling this setting does not affect the previously stored bucket policy, except that public and cross-account access within the public bucket policy, including non-public delegation to specific accounts, is blocked. When set to true: Only the bucket owner and AWS Services can access this buckets if it has a public policy.	bool	true	no
restriction_type	The method that you want to use to restrict distribution of your content by country. Options: none, whitelist, or blacklist.	string	"none"	no
s3_custom_policy	An optional custom IAM policy to attach to the S3 bucket.	string	""	no
sse_algorithm	The server-side encryption algorithm to use. Options are AES256 and aws:kms.	string	"AES256"	no
tags	The default tags to add to a resource.	map(string)	{}	no
versioning_enabled	Whether to enable versioning of objects in the bucket.	bool	true	no
viewer_cert_min_proto_version	The minimum version of the SSL protocol that you want CloudFront to use for HTTPS connections. Can only be set if cloudfront_default_certificate = false. See all possible values in this table under "Security policy." Some examples include: TLSv1.2_2019 and TLSv1.2_2021. Default: TLSv1. NOTE: If you are using a custom certificate (specified with acm_certificate_arn or iam_certificate_id), and have specified sni-only in ssl_support_method, TLSv1 or later must be specified. If you have specified vip in ssl_support_method, only SSLv3 or TLSv1 can be specified. If you have specified cloudfront_default_certificate, TLSv1 must be specified.	string	"TLSv1.2_2021"	no
viewer_cert_ssl_support_method	Specifies how you want CloudFront to serve HTTPS requests. One of vip or sni-only. Required if you specify acm_certificate_arn or iam_certificate_id. NOTE: vip causes CloudFront to use a dedicated IP address and may incur extra charges.	string	"sni-only"	no
waf_acl_default_action_type	Configuration block with action that you want AWS WAF to take when a request doesn't match the criteria in any of the rules that are associated with the web ACL.	string	"ALLOW"	no
waf_acl_metric_name	The name or description for the Amazon CloudWatch metric of this web ACL."	string	"AllowAccessFromEverywhere"	no
waf_acl_name	The name or description of the web ACL.	string	"Allow access from everywhere"	no

Outputs

Name	Description
cdn_domain	The CloudFront domain autogenerated by AWS.
cdn_id	The CloudFront distribution ID.
cicd_role_arn	The ARN of the generated role.
external_id	The external ID to be passed using the --external-id flag of the aws sts assume-role command.
s3_origin_bucket	The origin bucket Cloudfront will use to get the content.