Skip to content

Commit f8ab489

Browse files
vadim-gleifosterman
vadim-gleif
authored and
osterman
committed
Migrate to README.yaml format (#19)
* Migrate to README.yaml format * Fix descriptions
1 parent 3e299e3 commit f8ab489

File tree

8 files changed

+462
-106
lines changed

8 files changed

+462
-106
lines changed

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,7 @@
55
# Module directory
66
.idea
77
*.iml
8-
**/.terraform
8+
**/.terraform
9+
10+
.build-harness
11+
build-harness

‎Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
SHELL := /bin/bash
22

3+
# List of targets the `readme` target should call before generating the readme
4+
export README_DEPS ?= docs/targets.md docs/terraform.md
5+
36
-include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
47

8+
## Lint terraform code
59
lint:
6-
$(SELF) terraform:install terraform:get-modules terraform:get-plugins terraform:lint terraform:validate
10+
$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate

‎README.md‎

Lines changed: 210 additions & 63 deletions
Large diffs are not rendered by default.

‎README.yaml‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
#
3+
# This is the canonical configuration for the `README.md`
4+
# Run `make readme` to rebuild the `README.md`
5+
#
6+
7+
# Name of this project
8+
name: terraform-aws-cloudfront-s3-cdn
9+
10+
# Logo for this project
11+
#logo: docs/logo.png
12+
13+
# License of this project
14+
license: "APACHE2"
15+
16+
# Canonical GitHub repo
17+
github_repo: cloudposse/terraform-aws-cloudfront-s3-cdn
18+
19+
# Badges to display
20+
badges:
21+
- name: "Build Status"
22+
image: "https://travis-ci.org/cloudposse/terraform-aws-cloudfront-s3-cdn.svg?branch=master"
23+
url: "https://travis-ci.org/cloudposse/terraform-aws-cloudfront-s3-cdn"
24+
- name: "Latest Release"
25+
image: "https://img.shields.io/github/release/cloudposse/terraform-aws-cloudfront-s3-cdn.svg"
26+
url: "https://travis-ci.org/cloudposse/terraform-aws-cloudfront-s3-cdn/releases"
27+
- name: "Slack Community"
28+
image: "https://slack.cloudposse.com/badge.svg"
29+
url: "https://slack.cloudposse.com"
30+
31+
related:
32+
- name: "terraform-aws-cloudfront-cdn"
33+
description: "Terraform Module that implements a CloudFront Distribution (CDN) for a custom origin."
34+
url: "https://github.com/cloudposse/terraform-aws-cloudfront-cdn"
35+
- name: "terraform-aws-s3-log-storage"
36+
description: "S3 bucket with built in IAM policy to allow CloudTrail logs"
37+
url: "https://github.com/cloudposse/terraform-aws-s3-log-storage"
38+
39+
# Short description of this project
40+
description: |-
41+
Terraform module to easily provision an AWS CloudFront CDN with an S3 or custom origin.
42+
43+
# How to use this project
44+
usage: |-
45+
```hcl
46+
module "cdn" {
47+
source = "git::https://github.com/cloudposse/terraform-aws-cloudfront-s3-cdn.git?ref=master"
48+
namespace = "${var.namespace}"
49+
stage = "${var.stage}"
50+
name = "${var.name}"
51+
aliases = "${var.hostname}"
52+
parent_zone_name = "${var.parent_zone_name}"
53+
}
54+
```
55+
56+
Full working example can be found in [example](./example) folder.
57+
58+
### Generating ACM Certificate
59+
60+
Use the AWS cli to [request new ACM certifiates](http://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request.html) (requires email validation)
61+
```
62+
aws acm request-certificate --domain-name example.com --subject-alternative-names a.example.com b.example.com *.c.example.com
63+
```
64+
65+
66+
67+
__NOTE__:
68+
69+
Although AWS Certificate Manager is supported in many AWS regions, to use an SSL certificate with CloudFront, it should be requested only in US East (N. Virginia) region.
70+
71+
https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-and-https-requirements.html
72+
> If you want to require HTTPS between viewers and CloudFront, you must change the AWS region to US East (N. Virginia) in the AWS Certificate Manager console before you request or import a certificate.
73+
74+
https://docs.aws.amazon.com/acm/latest/userguide/acm-regions.html
75+
> To use an ACM Certificate with Amazon CloudFront, you must request or import the certificate in the US East (N. Virginia) region. ACM Certificates in this region that are associated with a CloudFront distribution are distributed to all the geographic locations configured for that distribution.
76+
77+
This is a fundamental requirement of CloudFront, and you will need to request the certificate in `us-east-1` region.
78+
79+
If there are warnings around the outputs when destroying using this module.
80+
Then you can use this method for supressing the superfluous errors.
81+
`TF_WARN_OUTPUT_ERRORS=1 terraform destroy`
82+
83+
include:
84+
- "docs/targets.md"
85+
- "docs/terraform.md"
86+
87+
# Contributors to this project
88+
contributors:
89+
- name: "Erik Osterman"
90+
github: "osterman"
91+
- name: "Andriy Knysh"
92+
github: "aknysh"
93+
- name: "Jamie Nelson"
94+
github: "Jamie-BitFlight"
95+
- name: "Clive Zagno"
96+
github: "cliveza"

‎docs/targets.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Makefile Targets
2+
```
3+
Available targets:
4+
5+
help This help screen
6+
help/all Display help for all targets
7+
lint Lint terraform code
8+
9+
```

‎docs/terraform.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
2+
## Inputs
3+
4+
| Name | Description | Type | Default | Required |
5+
|------|-------------|:----:|:-----:|:-----:|
6+
| acm_certificate_arn | Existing ACM Certificate ARN | string | `` | no |
7+
| aliases | List of FQDN's - Used to set the Alternate Domain Names (CNAMEs) setting on Cloudfront | list | `<list>` | no |
8+
| allowed_methods | List of allowed methods (e.g. GET, PUT, POST, DELETE, HEAD) for AWS CloudFront | list | `<list>` | no |
9+
| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
10+
| bucket_domain_format | Format of bucket domain name | string | `%s.s3.amazonaws.com` | no |
11+
| cached_methods | List of cached methods (e.g. GET, PUT, POST, DELETE, HEAD) | list | `<list>` | no |
12+
| comment | Comment for the origin access identity | string | `Managed by Terraform` | no |
13+
| compress | Compress content for web requests that include Accept-Encoding: gzip in the request header | string | `false` | no |
14+
| cors_allowed_headers | List of allowed headers for S3 bucket | list | `<list>` | no |
15+
| cors_allowed_methods | List of allowed methods (e.g. GET, PUT, POST, DELETE, HEAD) for S3 bucket | list | `<list>` | no |
16+
| cors_allowed_origins | List of allowed origins (e.g. example.com, test.com) for S3 bucket | list | `<list>` | no |
17+
| cors_expose_headers | List of expose header in the response for S3 bucket | list | `<list>` | no |
18+
| cors_max_age_seconds | Time in seconds that browser can cache the response for S3 bucket | string | `3600` | no |
19+
| default_root_object | Object that CloudFront return when requests the root URL | string | `index.html` | no |
20+
| default_ttl | Default amount of time (in seconds) that an object is in a CloudFront cache | string | `60` | no |
21+
| delimiter | Delimiter to be used between `name`, `namespace`, `stage`, etc. | string | `-` | no |
22+
| enabled | Select Enabled if you want CloudFront to begin processing requests as soon as the distribution is created, or select Disabled if you do not want CloudFront to begin processing requests after the distribution is created. | string | `true` | no |
23+
| forward_cookies | Time in seconds that browser can cache the response for S3 bucket | string | `none` | no |
24+
| forward_query_string | Forward query strings to the origin that is associated with this cache behavior | string | `false` | no |
25+
| geo_restriction_locations | List of country codes for which CloudFront either to distribute content (whitelist) or not distribute your content (blacklist) | list | `<list>` | no |
26+
| geo_restriction_type | Method that use to restrict distribution of your content by country: `none`, `whitelist`, or `blacklist` | string | `none` | no |
27+
| is_ipv6_enabled | State of CloudFront IPv6 | string | `true` | no |
28+
| log_expiration_days | Number of days after which to expunge the objects | string | `90` | no |
29+
| log_glacier_transition_days | Number of days after which to move the data to the glacier storage tier | string | `60` | no |
30+
| log_include_cookies | Include cookies in access logs | string | `false` | no |
31+
| log_prefix | Path of logs in S3 bucket | string | `` | no |
32+
| log_standard_transition_days | Number of days to persist in the standard storage tier before moving to the glacier tier | string | `30` | no |
33+
| max_ttl | Maximum amount of time (in seconds) that an object is in a CloudFront cache | string | `31536000` | no |
34+
| min_ttl | Minimum amount of time that you want objects to stay in CloudFront caches | string | `0` | no |
35+
| name | Name (e.g. `bastion` or `db`) | string | - | yes |
36+
| namespace | Namespace (e.g. `cp` or `cloudposse`) | string | - | yes |
37+
| null | an empty string | string | `` | no |
38+
| origin_bucket | Name of S3 bucket | string | `` | no |
39+
| origin_force_destroy | Delete all objects from the bucket so that the bucket can be destroyed without error (e.g. `true` or `false`) | string | `false` | no |
40+
| origin_path | (Optional) - An optional element that causes CloudFront to request your content from a directory in your Amazon S3 bucket or your custom origin. It must begin with a /. Do not add a / at the end of the path. | string | `` | no |
41+
| parent_zone_id | ID of the hosted zone to contain this record (or specify `parent_zone_name`) | string | `` | no |
42+
| parent_zone_name | Name of the hosted zone to contain this record (or specify `parent_zone_id`) | string | `` | no |
43+
| price_class | Price class for this distribution: `PriceClass_All`, `PriceClass_200`, `PriceClass_100` | string | `PriceClass_100` | no |
44+
| stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
45+
| static_s3_bucket | aws-cli is a bucket owned by amazon that will perminantly exist It allows for the data source to be called during the destruction process without failing. It doesn't get used for anything else, this is a safe workaround for handling the fact that if a data source like the one `aws_s3_bucket.selected` gets an error, you can't continue the terraform process which also includes the 'destroy' command, where is doesn't even need this data source! Don't change this bucket name, its a variable so that we can provide this description. And this works around a problem that is an edge case. | string | `aws-cli` | no |
46+
| tags | Additional tags (e.g. map('BusinessUnit`,`XYZ`) | map | `<map>` | no |
47+
| use_regional_s3_endpoint | When set to 'true' the s3 origin_bucket will use the regional endpoint address instead of the global endpoint address | string | `false` | no |
48+
| viewer_protocol_policy | allow-all, redirect-to-https | string | `redirect-to-https` | no |
49+
50+
## Outputs
51+
52+
| Name | Description |
53+
|------|-------------|
54+
| cf_arn | ARN of AWS CloudFront distribution |
55+
| cf_domain_name | Domain name corresponding to the distribution |
56+
| cf_etag | Current version of the distribution's information |
57+
| cf_hosted_zone_id | CloudFront Route 53 zone ID |
58+
| cf_id | ID of AWS CloudFront distribution |
59+
| cf_status | Current status of the distribution |
60+
| s3_bucket | Name of S3 bucket |
61+
| s3_bucket_domain_name | Domain of S3 bucket |
62+

‎outputs.tf‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,39 @@
11
output "cf_id" {
2-
value = "${aws_cloudfront_distribution.default.id}"
2+
value = "${aws_cloudfront_distribution.default.id}"
3+
description = "ID of AWS CloudFront distribution"
34
}
45

56
output "cf_arn" {
6-
value = "${aws_cloudfront_distribution.default.arn}"
7+
value = "${aws_cloudfront_distribution.default.arn}"
8+
description = "ARN of AWS CloudFront distribution"
79
}
810

911
output "cf_status" {
10-
value = "${aws_cloudfront_distribution.default.status}"
12+
value = "${aws_cloudfront_distribution.default.status}"
13+
description = "Current status of the distribution"
1114
}
1215

1316
output "cf_domain_name" {
14-
value = "${aws_cloudfront_distribution.default.domain_name}"
17+
value = "${aws_cloudfront_distribution.default.domain_name}"
18+
description = "Domain name corresponding to the distribution"
1519
}
1620

1721
output "cf_etag" {
18-
value = "${aws_cloudfront_distribution.default.etag}"
22+
value = "${aws_cloudfront_distribution.default.etag}"
23+
description = "Current version of the distribution's information"
1924
}
2025

2126
output "cf_hosted_zone_id" {
22-
value = "${aws_cloudfront_distribution.default.hosted_zone_id}"
27+
value = "${aws_cloudfront_distribution.default.hosted_zone_id}"
28+
description = "CloudFront Route 53 zone ID"
2329
}
2430

2531
output "s3_bucket" {
26-
value = "${local.bucket}"
32+
value = "${local.bucket}"
33+
description = "Name of S3 bucket"
2734
}
2835

2936
output "s3_bucket_domain_name" {
30-
value = "${local.bucket_domain_name}"
37+
value = "${local.bucket_domain_name}"
38+
description = "Domain of S3 bucket"
3139
}

0 commit comments

Comments
 (0)