Migrate readme yaml (#5)

.gitignore

@@ -6,3 +6,6 @@
 .terraform
 .idea
 *.iml
+
+.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,194 @@
+---
+#
+# This is the canonical configuration for the `README.md`
+# Run `make readme` to rebuild the `README.md`
+#
+
+# Name of this project
+name: terraform-aws-multi-az-subnets
+
+# Logo for this project
+#logo: docs/logo.png
+
+# License of this project
+license: "APACHE2"
+
+# Canonical GitHub repo
+github_repo: cloudposse/terraform-aws-multi-az-subnets
+
+# Badges to display
+badges:
+  - name: "Build Status"
+    image: "https://travis-ci.org/cloudposse/terraform-aws-multi-az-subnets.svg?branch=master"
+    url: "https://travis-ci.org/cloudposse/terraform-aws-multi-az-subnets"
+  - name: "Latest Release"
+    image: "https://img.shields.io/github/release/cloudposse/terraform-aws-multi-az-subnets.svg"
+    url: "https://github.com/cloudposse/terraform-aws-multi-az-subnets/releases/latest"
+  - name: "Slack Community"
+    image: "https://slack.cloudposse.com/badge.svg"
+    url: "https://slack.cloudposse.com"
+
+related:
+  - name: "terraform-aws-named-subnets"
+    description: "Terraform module for named subnets provisioning."
+    url: "https://github.com/cloudposse/terraform-aws-named-subnets"
+  - name: "terraform-aws-dynamic-subnets"
+    description: "Terraform module for public and private subnets provisioning in existing VPC"
+    url: "https://github.com/cloudposse/terraform-aws-dynamic-subnets"
+  - name: "terraform-aws-vpc"
+    description: "Terraform Module that defines a VPC with public/private subnets across multiple AZs with Internet Gateways"
+    url: "https://github.com/cloudposse/terraform-aws-vpc"
+  - name: "terraform-aws-cloudwatch-flow-logs"
+    description: "Terraform module for enabling flow logs for vpc and subnets."
+    url: "https://github.com/cloudposse/terraform-aws-cloudwatch-flow-logs"
+
+# Short description of this project
+description: |-
+  Terraform module for multi-AZ [`subnets`](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html) provisioning.
+
+  The module creates private and public subnets in the provided Availability Zones.
+
+  The public subnets are routed to the Internet Gateway specified by `var.igw_id`.
+
+  `nat_gateway_enabled` flag controls the creation of NAT Gateways in the public subnets.
+
+  The private subnets are routed to the NAT Gateways provided in the `var.az_ngw_ids` map.
+
+# How to use this project
+usage: |-
+  ```hcl
+  module "vpc" {
+    source     = "git::https://github.com/cloudposse/terraform-aws-vpc.git?ref=master"
+    namespace  = "${var.namespace}"
+    name       = "vpc"
+    stage      = "${var.stage}"
+    cidr_block = "${var.cidr_block}"
+  }
+
+  locals {
+    public_cidr_block  = "${cidrsubnet(module.vpc.vpc_cidr_block, 1, 0)}"
+    private_cidr_block = "${cidrsubnet(module.vpc.vpc_cidr_block, 1, 1)}"
+  }
+
+  module "public_subnets" {
+    source              = "git::https://github.com/cloudposse/terraform-aws-multi-az-subnets.git?ref=master"
+    namespace           = "${var.namespace}"
+    stage               = "${var.stage}"
+    name                = "${var.name}"
+    availability_zones  = ["us-east-1a", "us-east-1b", "us-east-1c"]
+    vpc_id              = "${module.vpc.vpc_id}"
+    cidr_block          = "${local.public_cidr_block}"
+    type                = "public"
+    igw_id              = "${module.vpc.igw_id}"
+    nat_gateway_enabled = "true"
+  }
+
+  module "private_subnets" {
+    source              = "git::https://github.com/cloudposse/terraform-aws-multi-az-subnets.git?ref=master"
+    namespace           = "${var.namespace}"
+    stage               = "${var.stage}"
+    name                = "${var.name}"
+    availability_zones  = ["us-east-1a", "us-east-1b", "us-east-1c"]
+    vpc_id              = "${module.vpc.vpc_id}"
+    cidr_block          = "${local.private_cidr_block}"
+    type                = "private"
+
+    # Map of AZ names to NAT Gateway IDs that was created in "public_subnets" module
+    az_ngw_ids          = "${module.public_subnets.az_ngw_ids}"
+
+    # Need to explicitly provide the count since Terraform currently can't use dynamic count on computed resources from different modules
+    # https://github.com/hashicorp/terraform/issues/10857
+    # https://github.com/hashicorp/terraform/issues/12125
+    # https://github.com/hashicorp/terraform/issues/4149
+    az_ngw_count = 3
+  }
+  ```
+examples: |-
+  Given the following configuration
+
+  ```hcl
+  module "vpc" {
+    source     = "git::https://github.com/cloudposse/terraform-aws-vpc.git?ref=master"
+    namespace  = "${var.namespace}"
+    name       = "vpc"
+    stage      = "${var.stage}"
+    cidr_block = "${var.cidr_block}"
+  }
+
+  locals {
+    public_cidr_block  = "${cidrsubnet(module.vpc.vpc_cidr_block, 1, 0)}"
+    private_cidr_block = "${cidrsubnet(module.vpc.vpc_cidr_block, 1, 1)}"
+  }
+
+  module "public_subnets" {
+    source              = "git::https://github.com/cloudposse/terraform-aws-multi-az-subnets.git?ref=master"
+    namespace           = "${var.namespace}"
+    stage               = "${var.stage}"
+    name                = "${var.name}"
+    availability_zones  = ["us-east-1a", "us-east-1b", "us-east-1c"]
+    vpc_id              = "${module.vpc.vpc_id}"
+    cidr_block          = "${local.public_cidr_block}"
+    type                = "public"
+    igw_id              = "${module.vpc.igw_id}"
+    nat_gateway_enabled = "true"
+  }
+
+  module "private_subnets" {
+    source              = "git::https://github.com/cloudposse/terraform-aws-multi-az-subnets.git?ref=master"
+    namespace           = "${var.namespace}"
+    stage               = "${var.stage}"
+    name                = "${var.name}"
+    availability_zones  = ["us-east-1a", "us-east-1b", "us-east-1c"]
+    vpc_id              = "${module.vpc.vpc_id}"
+    cidr_block          = "${local.private_cidr_block}"
+    type                = "private"
+    az_ngw_ids          = "${module.public_subnets.az_ngw_ids}"
+    az_ngw_count        = 3
+  }
+
+  output "private_az_subnet_ids" {
+    value = "${module.private_subnets.az_subnet_ids}"
+  }
+
+  output "public_az_subnet_ids" {
+    value = "${module.public_subnets.az_subnet_ids}"
+  }
+  ```
+
+  the output Maps of AZ names to subnet IDs look like these
+
+  ```hcl
+  public_az_subnet_ids = {
+    us-east-1a = subnet-ea58d78e
+    us-east-1b = subnet-556ee131
+    us-east-1c = subnet-6f54db0b
+  }
+  private_az_subnet_ids = {
+    us-east-1a = subnet-376de253
+    us-east-1b = subnet-9e53dcfa
+    us-east-1c = subnet-a86fe0cc
+  }
+  ```
+
+  and the created subnet IDs could be found by the AZ names using `map["key"]` or [`lookup(map, key, [default])`](https://www.terraform.io/docs/configuration/interpolation.html#lookup-map-key-default-),
+
+  for example:
+
+  `public_az_subnet_ids["us-east-1a"]`
+
+  `lookup(private_az_subnet_ids, "us-east-1b")`
+  <br/>
+
+screenshots:
+  - name: "terraform-aws-multi-az-subnets"
+    description: "Example of `terraform apply` outputs"
+    url: "images/terraform-aws-multi-az-subnets.png"
+
+include:
+  - "docs/targets.md"
+  - "docs/terraform.md"
+
+# Contributors to this project
+contributors:
+  - name: "Andriy Knysh"
+    github: "aknysh"

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,36 @@
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
+| availability_zones | List of Availability Zones (e.g. `['us-east-1a', 'us-east-1b', 'us-east-1c']`) | list | `<list>` | no |
+| az_ngw_count | Count of items in the `az_ngw_ids` map. Needs to be explicitly provided since Terraform currently can't use dynamic count on computed resources from different modules. https://github.com/hashicorp/terraform/issues/10857 | string | `0` | no |
+| az_ngw_ids | Only for private subnets. Map of AZ names to NAT Gateway IDs that are used as default routes when creating private subnets | map | `<map>` | no |
+| cidr_block | Base CIDR block which is divided into subnet CIDR blocks (e.g. `10.0.0.0/16`) | string | - | yes |
+| delimiter | Delimiter to be used between `namespace`, `stage`, `name` and `attributes` | string | `-` | no |
+| enabled | Set to false to prevent the module from creating any resources | string | `true` | no |
+| igw_id | Internet Gateway ID that is used as a default route when creating public subnets (e.g. `igw-9c26a123`) | string | `` | no |
+| max_subnets | Maximum number of subnets that can be created. The variable is used for CIDR blocks calculation | string | `6` | no |
+| name | Application or solution name | string | - | yes |
+| namespace | Namespace (e.g. `cp` or `cloudposse`) | string | - | yes |
+| nat_gateway_enabled | Flag to enable/disable NAT Gateways creation in public subnets | string | `true` | no |
+| private_network_acl_egress | Egress network ACL rules | list | `<list>` | no |
+| private_network_acl_id | Network ACL ID that is added to the private subnets. If empty, a new ACL will be created | string | `` | no |
+| private_network_acl_ingress | Egress network ACL rules | list | `<list>` | no |
+| public_network_acl_egress | Egress network ACL rules | list | `<list>` | no |
+| public_network_acl_id | Network ACL ID that is added to the public subnets. If empty, a new ACL will be created | string | `` | no |
+| public_network_acl_ingress | Egress network ACL rules | list | `<list>` | no |
+| stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
+| tags | Additional tags (e.g. map(`BusinessUnit`,`XYZ`) | map | `<map>` | no |
+| type | Type of subnets to create (`private` or `public`) | string | `private` | no |
+| vpc_id | VPC ID | string | - | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| az_ngw_ids | Map of AZ names to NAT Gateway IDs (only for public subnets) |
+| az_route_table_ids | Map of AZ names to Route Table IDs |
+| az_subnet_ids | Map of AZ names to subnet IDs |
+

outputs.tf

@@ -1,11 +1,14 @@
 output "az_subnet_ids" {
-  value = "${zipmap(var.availability_zones, matchkeys(coalescelist(aws_subnet.private.*.id, aws_subnet.public.*.id), coalescelist(aws_subnet.private.*.tags.AZ, aws_subnet.public.*.tags.AZ), var.availability_zones))}"
+  value       = "${zipmap(var.availability_zones, matchkeys(coalescelist(aws_subnet.private.*.id, aws_subnet.public.*.id), coalescelist(aws_subnet.private.*.tags.AZ, aws_subnet.public.*.tags.AZ), var.availability_zones))}"
+  description = "Map of AZ names to subnet IDs"
 }
 
 output "az_route_table_ids" {
-  value = "${zipmap(var.availability_zones, matchkeys(coalescelist(aws_route_table.private.*.id, aws_route_table.public.*.id), coalescelist(aws_route_table.private.*.tags.AZ, aws_route_table.public.*.tags.AZ), var.availability_zones))}"
+  value       = "${zipmap(var.availability_zones, matchkeys(coalescelist(aws_route_table.private.*.id, aws_route_table.public.*.id), coalescelist(aws_route_table.private.*.tags.AZ, aws_route_table.public.*.tags.AZ), var.availability_zones))}"
+  description = " Map of AZ names to Route Table IDs"
 }
 
 output "az_ngw_ids" {
-  value = "${zipmap(var.availability_zones, coalescelist(matchkeys(aws_nat_gateway.public.*.id, aws_nat_gateway.public.*.tags.AZ, var.availability_zones), local.dummy_az_ngw_ids))}"
+  value       = "${zipmap(var.availability_zones, coalescelist(matchkeys(aws_nat_gateway.public.*.id, aws_nat_gateway.public.*.tags.AZ, var.availability_zones), local.dummy_az_ngw_ids))}"
+  description = "Map of AZ names to NAT Gateway IDs (only for public subnets)"
 }