Migrate to README.yaml format (#19)

* Migrate to README.yaml format

* Fix descriptions

.gitignore

@@ -5,4 +5,7 @@
 # Module directory
 .idea
 *.iml
-**/.terraform
+**/.terraform
+
+.build-harness
+build-harness

Makefile

@@ -1,6 +1,10 @@
 SHELL := /bin/bash
 
+# List of targets the `readme` target should call before generating the readme
+export README_DEPS ?= docs/targets.md docs/terraform.md
+
 -include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
 
+## Lint terraform code
 lint:
-	$(SELF) terraform:install terraform:get-modules terraform:get-plugins terraform:lint terraform:validate
+	$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate

README.yaml

@@ -0,0 +1,96 @@
+---
+#
+# This is the canonical configuration for the `README.md`
+# Run `make readme` to rebuild the `README.md`
+#
+
+# Name of this project
+name: terraform-aws-cloudfront-s3-cdn
+
+# Logo for this project
+#logo: docs/logo.png
+
+# License of this project
+license: "APACHE2"
+
+# Canonical GitHub repo
+github_repo: cloudposse/terraform-aws-cloudfront-s3-cdn
+
+# Badges to display
+badges:
+  - name: "Build Status"
+    image: "https://travis-ci.org/cloudposse/terraform-aws-cloudfront-s3-cdn.svg?branch=master"
+    url: "https://travis-ci.org/cloudposse/terraform-aws-cloudfront-s3-cdn"
+  - name: "Latest Release"
+    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-cloudfront-s3-cdn.svg"
+    url: "https://travis-ci.org/cloudposse/terraform-aws-cloudfront-s3-cdn/releases"
+  - name: "Slack Community"
+    image: "https://slack.cloudposse.com/badge.svg"
+    url: "https://slack.cloudposse.com"
+
+related:
+  - name: "terraform-aws-cloudfront-cdn"
+    description: "Terraform Module that implements a CloudFront Distribution (CDN) for a custom origin."
+    url: "https://github.com/cloudposse/terraform-aws-cloudfront-cdn"
+  - name: "terraform-aws-s3-log-storage"
+    description: "S3 bucket with built in IAM policy to allow CloudTrail logs"
+    url: "https://github.com/cloudposse/terraform-aws-s3-log-storage"
+
+# Short description of this project
+description: |-
+  Terraform module to easily provision an AWS CloudFront CDN with an S3 or custom origin.
+
+# How to use this project
+usage: |-
+  ```hcl
+  module "cdn" {
+    source           = "git::https://github.com/cloudposse/terraform-aws-cloudfront-s3-cdn.git?ref=master"
+    namespace        = "${var.namespace}"
+    stage            = "${var.stage}"
+    name             = "${var.name}"
+    aliases          = "${var.hostname}"
+    parent_zone_name = "${var.parent_zone_name}"
+  }
+  ```
+
+  Full working example can be found in [example](./example) folder.
+
+  ### Generating ACM Certificate
+
+  Use the AWS cli to [request new ACM certifiates](http://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request.html) (requires email validation)
+  ```
+  aws acm request-certificate --domain-name example.com --subject-alternative-names a.example.com b.example.com *.c.example.com
+  ```
+
+
+
+  __NOTE__:
+
+  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.
+
+  https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-and-https-requirements.html
+  > 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.
+
+  https://docs.aws.amazon.com/acm/latest/userguide/acm-regions.html
+  > 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.
+
+  This is a fundamental requirement of CloudFront, and you will need to request the certificate in `us-east-1` region.
+
+  If there are warnings around the outputs when destroying using this module.
+  Then you can use this method for supressing the superfluous errors.
+  `TF_WARN_OUTPUT_ERRORS=1 terraform destroy`
+
+include:
+  - "docs/targets.md"
+  - "docs/terraform.md"
+
+# Contributors to this project
+contributors:
+  - name: "Erik Osterman"
+    github: "osterman"
+  - name: "Andriy Knysh"
+    github: "aknysh"
+  - name: "Jamie Nelson"
+    github: "Jamie-BitFlight"
+  - name: "Clive Zagno"
+    github: "cliveza"

docs/targets.md

@@ -0,0 +1,9 @@
+## Makefile Targets
+```
+Available targets:
+
+  help                                This help screen
+  help/all                            Display help for all targets
+  lint                                Lint terraform code
+
+```

docs/terraform.md

@@ -0,0 +1,62 @@
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| acm_certificate_arn | Existing ACM Certificate ARN | string | `` | no |
+| aliases | List of FQDN's - Used to set the Alternate Domain Names (CNAMEs) setting on Cloudfront | list | `<list>` | no |
+| allowed_methods | List of allowed methods (e.g. GET, PUT, POST, DELETE, HEAD) for AWS CloudFront | list | `<list>` | no |
+| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
+| bucket_domain_format | Format of bucket domain name | string | `%s.s3.amazonaws.com` | no |
+| cached_methods | List of cached methods (e.g. GET, PUT, POST, DELETE, HEAD) | list | `<list>` | no |
+| comment | Comment for the origin access identity | string | `Managed by Terraform` | no |
+| compress | Compress content for web requests that include Accept-Encoding: gzip in the request header | string | `false` | no |
+| cors_allowed_headers | List of allowed headers for S3 bucket | list | `<list>` | no |
+| cors_allowed_methods | List of allowed methods (e.g. GET, PUT, POST, DELETE, HEAD) for S3 bucket | list | `<list>` | no |
+| cors_allowed_origins | List of allowed origins (e.g. example.com, test.com) for S3 bucket | list | `<list>` | no |
+| cors_expose_headers | List of expose header in the response for S3 bucket | list | `<list>` | no |
+| cors_max_age_seconds | Time in seconds that browser can cache the response for S3 bucket | string | `3600` | no |
+| default_root_object | Object that CloudFront return when requests the root URL | string | `index.html` | no |
+| default_ttl | Default amount of time (in seconds) that an object is in a CloudFront cache | string | `60` | no |
+| delimiter | Delimiter to be used between `name`, `namespace`, `stage`, etc. | string | `-` | no |
+| 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 |
+| forward_cookies | Time in seconds that browser can cache the response for S3 bucket | string | `none` | no |
+| forward_query_string | Forward query strings to the origin that is associated with this cache behavior | string | `false` | no |
+| geo_restriction_locations | List of country codes for which  CloudFront either to distribute content (whitelist) or not distribute your content (blacklist) | list | `<list>` | no |
+| geo_restriction_type | Method that use to restrict distribution of your content by country: `none`, `whitelist`, or `blacklist` | string | `none` | no |
+| is_ipv6_enabled | State of CloudFront IPv6 | string | `true` | no |
+| log_expiration_days | Number of days after which to expunge the objects | string | `90` | no |
+| log_glacier_transition_days | Number of days after which to move the data to the glacier storage tier | string | `60` | no |
+| log_include_cookies | Include cookies in access logs | string | `false` | no |
+| log_prefix | Path of logs in S3 bucket | string | `` | no |
+| log_standard_transition_days | Number of days to persist in the standard storage tier before moving to the glacier tier | string | `30` | no |
+| max_ttl | Maximum amount of time (in seconds) that an object is in a CloudFront cache | string | `31536000` | no |
+| min_ttl | Minimum amount of time that you want objects to stay in CloudFront caches | string | `0` | no |
+| name | Name  (e.g. `bastion` or `db`) | string | - | yes |
+| namespace | Namespace (e.g. `cp` or `cloudposse`) | string | - | yes |
+| null | an empty string | string | `` | no |
+| origin_bucket | Name of S3 bucket | string | `` | no |
+| 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 |
+| 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 |
+| parent_zone_id | ID of the hosted zone to contain this record  (or specify `parent_zone_name`) | string | `` | no |
+| parent_zone_name | Name of the hosted zone to contain this record (or specify `parent_zone_id`) | string | `` | no |
+| price_class | Price class for this distribution: `PriceClass_All`, `PriceClass_200`, `PriceClass_100` | string | `PriceClass_100` | no |
+| stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
+| 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 |
+| tags | Additional tags (e.g. map('BusinessUnit`,`XYZ`) | map | `<map>` | no |
+| 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 |
+| viewer_protocol_policy | allow-all, redirect-to-https | string | `redirect-to-https` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| cf_arn | ARN of AWS CloudFront distribution |
+| cf_domain_name | Domain name corresponding to the distribution |
+| cf_etag | Current version of the distribution's information |
+| cf_hosted_zone_id | CloudFront Route 53 zone ID |
+| cf_id | ID of AWS CloudFront distribution |
+| cf_status | Current status of the distribution |
+| s3_bucket | Name of S3 bucket |
+| s3_bucket_domain_name | Domain of S3 bucket |
+

outputs.tf

@@ -1,31 +1,39 @@
 output "cf_id" {
-  value = "${aws_cloudfront_distribution.default.id}"
+  value       = "${aws_cloudfront_distribution.default.id}"
+  description = "ID of AWS CloudFront distribution"
 }
 
 output "cf_arn" {
-  value = "${aws_cloudfront_distribution.default.arn}"
+  value       = "${aws_cloudfront_distribution.default.arn}"
+  description = "ARN of AWS CloudFront distribution"
 }
 
 output "cf_status" {
-  value = "${aws_cloudfront_distribution.default.status}"
+  value       = "${aws_cloudfront_distribution.default.status}"
+  description = "Current status of the distribution"
 }
 
 output "cf_domain_name" {
-  value = "${aws_cloudfront_distribution.default.domain_name}"
+  value       = "${aws_cloudfront_distribution.default.domain_name}"
+  description = "Domain name corresponding to the distribution"
 }
 
 output "cf_etag" {
-  value = "${aws_cloudfront_distribution.default.etag}"
+  value       = "${aws_cloudfront_distribution.default.etag}"
+  description = "Current version of the distribution's information"
 }
 
 output "cf_hosted_zone_id" {
-  value = "${aws_cloudfront_distribution.default.hosted_zone_id}"
+  value       = "${aws_cloudfront_distribution.default.hosted_zone_id}"
+  description = "CloudFront Route 53 zone ID"
 }
 
 output "s3_bucket" {
-  value = "${local.bucket}"
+  value       = "${local.bucket}"
+  description = "Name of S3 bucket"
 }
 
 output "s3_bucket_domain_name" {
-  value = "${local.bucket_domain_name}"
+  value       = "${local.bucket_domain_name}"
+  description = "Domain of S3 bucket"
 }