docs + examples

.travis.yml

@@ -1,16 +1,19 @@
-sudo: required
+language: bash
+sudo: false
 dist: trusty
-language: generic
-services:
-  - docker
+
 install:
-  - env
   - wget -t 10 -O terraform.zip https://releases.hashicorp.com/terraform/0.11.7/terraform_0.11.7_linux_amd64.zip
   - unzip terraform.zip
   - mv terraform ~/bin/
   - chmod +x ~/bin/terraform
+  - wget -t 10 -O terraform-docs https://github.com/segmentio/terraform-docs/releases/download/v0.3.0/terraform-docs_linux_amd64
+  - mv terraform-docs ~/bin/terraform-docs
+  - chmod +x ~/bin/terraform-docs
 
 jobs:
   include:
     - stage: check
-      script: make lint
+      script: make lint
+    - stage: check
+      script: make check-docs

Makefile

@@ -12,6 +12,13 @@ lint:
 docs:
 	@for m in $(MODULES); do \
 		pushd $$m; \
-		../scripts/update-readme.sh; \
+		../scripts/update-readme.sh update; \
 		popd; \
-	done; \
+	done;
+
+check-docs:
+	@for m in $(MODULES); do \
+		cd $$m; \
+		../scripts/update-readme.sh check || exit $$?; \
+		cd ..; \
+	done;

README.md

@@ -1 +1,75 @@
-# cztack
+# CZtack
+
+Cztack (pronounced "stack") is CZI's collection of Terraform modules. We use these as way to scale our infrastructure work.
+
+## Design Principles
+
+TODO
+
+## Modules
+
+### AWS IAM ECS Task Role
+
+This creates a role for use with an ECS task, you bring your own policy and we create the role for you.
+
+[Read More](aws-iam-ecs-task-role/README.md)
+
+### AWS IAM Group assume-role
+
+This module with create and IAM group, add users to it and grant the grouop permission to assume a role. This is commonly used for cross-account access control.
+
+[Read More](aws-iam-group-assume-role/README.md)
+
+### AWS IAM Group console-login
+
+This will create a group, add users to it, and grant permission to log into the AWS console and manage one's own credentials.
+
+[Read More](aws-iam-group-console-login/README.md)
+
+### AWS IAM password policy
+
+This module will create a good password policy for your AWS account.
+
+[Read More](aws-iam-password-policy/README.md)
+
+### AWS IAM cloudwatch logs policy
+
+This will create a policy that allow writing to cloudwatch logs.
+
+[Read More](aws-iam-policy-cwlogs/README.md)
+
+### AWS IAM poweruser role
+
+This will create a poweruser role, based off the AWS-managed "poweruser" policy, but with a few additions that we find useful.
+
+[Read More](aws-iam-poweruser/README.md)
+
+### AWS IAM Role Cloudfront poweruser
+
+This will create a role that gives "poweruser" level access to cloudfront.
+
+[Read More](aws-iam-role-cloudfront-poweruser/README.md)
+
+### AWS IAM Role ECS poweruser
+
+This will create a role that gives "poweruser" level access to ECS.
+
+[Read More](aws-iam-role-ecs-poweruser/README.md)
+
+### AWS IAM Role infraci
+
+This is a role we find useful for running CI jobs for terraform code. It is based on the AWS-managed policy for readonly, but includes a few additions, like the ability to read secrets.
+
+[Read More](aws-iam-role-infraci/README.md)
+
+### AWS IAM role readonly
+
+This creates a readonly role, based off the AWS-managed readonly policy, but with a few changes.
+
+[Read More](aws-iam-role-readonly/README.md)
+
+### AWS IAM role security-audit
+
+This creates a security-audit role, based off the AWS-managed policy, but with a few changes.
+
+[Read More](aws-iam-role-security-audit/README.md)

aws-iam-ecs-task-role/README.md

@@ -1,17 +1,37 @@
 # AWs IAM Role for ECS Tasks
 
-This will create a role for attaching to an ECS task, using `var.policy`.
+This will create a role for attaching to an ECS task, using `policy`.
+
+## Example
+
+```hcl
+module "ecs-role" {
+  source = "github.com/chanzuckerberg/cztack/aws-iam-ecs-task-role?ref=master" # FIXME
+  
+  policy = "..."
+
+  project = "..."
+  env     = "..."
+  service = "..."
+  owner   = "..."
+}
+
+output "ecs-role-arn" {
+  value = "${module.ecs-role.arn}"
+}
+```
+
 <!-- START -->
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|:----:|:-----:|:-----:|
-| env | Computing environment, for example dev, staging or prod. | string | - | yes |
-| owner | Email address of the owner. Can be a group. | string | - | yes |
+| env | Environment name. For example– dev, staging or prod. | string | - | yes |
+| owner | Email address of the owner. Can be a group address. | string | - | yes |
 | policy | IAM policy to grant to this role. | string | - | yes |
-| project | High-level project, should be unique across CZI | string | - | yes |
-| service | Name of this thing we're running.  | string | - | yes |
+| project | High-level project, should be unique across the organization. | string | - | yes |
+| service | Name of this thing we're running. | string | - | yes |
 
 ## Outputs
 

aws-iam-ecs-task-role/variables.tf

@@ -1,7 +1,7 @@
 variable "project" {
   type = "string"
 
-  description = "High-level project, should be unique across CZI"
+  description = "High-level project, should be unique across the organization."
 }
 
 variable "env" {

aws-iam-group-assume-role/README.md

@@ -1,6 +1,27 @@
 # AWS IAM Group for assuming a role
 
-This module will create a grouop which has the right to assume a particular IAM role.  This is commoly used for granting cross-account permissions to IAM users.
+This module will create a group which has the right to assume a particular IAM role.  This is commoly used for granting cross-account permissions to IAM users.
+
+```hcl
+module "group" {
+  source = "github.com/chanzuckerberg/cztack/aws-iam-group-assume-role?ref=master" # FIXME
+
+  group_name      = "…"
+  path            = "…"
+  target_accounts = [...]
+  target_role     = "..."
+
+  depends_on = […]
+}
+
+output "group_arn" {
+  value = "${module.group.group_arn}"
+}
+
+output "group_name" {
+  value = "${module.group.group_name}"
+}
+```
 
 <!-- START -->
 
@@ -9,11 +30,11 @@ This module will create a grouop which has the right to assume a particular IAM
 | Name | Description | Type | Default | Required |
 |------|-------------|:----:|:-----:|:-----:|
 | depends_on | Pseudo depends_on because Terraform modules do not support depends_on | list | `<list>` | no |
-| group_name |  | string | - | yes |
-| path |  | string | `/` | no |
-| target_accounts |  | list | - | yes |
-| target_role |  | string | `` | no |
-| users |  | list | `<list>` | no |
+| group_name | The name of the group this module will create. | string | - | yes |
+| iam_path | The IAM path under which the group and policies will be created. Useful for avoiding naming conflicts. | string | `/` | no |
+| target_accounts | List of accounts in which this role should be assume-able. | list | - | yes |
+| target_role | Name of the role to be assume-able. If not specified or given as empty string, then the group name will be used as the role name. | string | `` | no |
+| users | List of user's names who should be added to this group. | list | `<list>` | no |
 
 ## Outputs
 
@@ -22,4 +43,4 @@ This module will create a grouop which has the right to assume a particular IAM
 | group_arn |  |
 | group_name |  |
 
-<!-- END -->
+<!-- END -->

aws-iam-group-assume-role/variables.tf

@@ -3,19 +3,21 @@ variable "target_accounts" {
   description = "List of accounts in which this role should be assume-able."
 }
 
-variable "path" {
-  type    = "string"
-  default = "/"
+variable "iam_path" {
+  type        = "string"
+  default     = "/"
+  description = "The IAM path under which the group and policies will be created. Useful for avoiding naming conflicts."
 }
 
 variable "group_name" {
-  type = "string"
+  type        = "string"
+  description = "The name of the group this module will create."
 }
 
 variable "users" {
   type        = "list"
   default     = []
-  description = "List of users who should be added to this group."
+  description = "List of user's names who should be added to this group."
 }
 
 variable "target_role" {

aws-iam-group-console-login/README.md

@@ -2,12 +2,34 @@
 
 This module will create an IAM group and grant access for its members to log into the AWS console and manage their own credentials (and nothing more).
 
+## Example 
+
+```hcl
+module "group" {
+  source = "github.com/chanzuckerberg/cztack/aws-iam-group-console-login?ref=master" # FIXME
+
+  group_name = "…"
+  iam_path = "…"
+}
+
+output "group_name" {
+  value = "${module.group.group_name}"
+}
+```
+
 <!-- START -->
 
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| group_name | Name of the group to be created. | string | `console-login` | no |
+| iam_path | IAM path under which resources will be created. | string | `/` | no |
+
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| name |  |
+| group_name |  |
 
 <!-- END -->

aws-iam-group-console-login/outputs.tf

@@ -1,3 +1,3 @@
-output "name" {
+output "group_name" {
   value = "${aws_iam_group.login.name}"
 }

aws-iam-group-console-login/variables.tf

@@ -1,9 +1,11 @@
-variable "name" {
-  type    = "string"
-  default = "console-login"
+variable "group_name" {
+  type        = "string"
+  default     = "console-login"
+  description = "Name of the group to be created."
 }
 
-variable "path" {
-  type    = "string"
-  default = "/"
+variable "iam_path" {
+  type        = "string"
+  default     = "/"
+  description = "IAM path under which resources will be created."
 }

aws-iam-password-policy/README.md

@@ -2,5 +2,14 @@
 
 This module is useful for setting a password policy on AWS IAM.
 
+## Example
+
+```hcl
+module "password-policy" {
+  source = "github.com/chanzuckerberg/cztack/aws-iam-password-policy?ref=master" # FIXME
+}
+```
+
 <!-- START -->
+
 <!-- END -->

aws-iam-policy-cwlogs/README.md

@@ -1,4 +1,23 @@
 # AWS IAM policy  to allow cloudwatch logs
+
+This will create a policy that allows writing to cloudwatch logs and attach it to the supplied role.
+
+## Example
+
+```hcl
+module "policy" {
+  source = "github.com/chanzuckerberg/cztack/aws-iam-policy-cwlogs?ref=master" # FIXME
+
+
+  iam_path            = "…"
+  target_accounts = [...]
+  target_role     = "..."
+
+  depends_on = […]
+}
+```
+
+
 <!-- START -->
 
 ## Inputs

aws-iam-role-poweruser/README.md

@@ -0,0 +1,25 @@
+# AWS IAM role poweruser
+
+This creates a role, `role_name` which is assumable from the account `source_account_id`.
+
+## Example
+
+```hcl
+module "group" {
+  source = "github.com/chanzuckerberg/cztack/aws-iam-role-poweruser?ref=master" # FIXME
+
+  role_name         = "…" # defaults to "poweruser"
+  source_account_id = "…"
+}
+```
+
+<!-- START -->
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| role_name |  | string | `poweruser` | no |
+| source_account_id |  | string | - | yes |
+
+<!-- END -->

aws-iam-poweruser/variables.tf → aws-iam-role-poweruser/variables.tf

@@ -1,4 +1,4 @@
-variable "name" {
+variable "role_name" {
   type    = "string"
   default = "poweruser"
 }