Auto-generate docs for release v0.0.1 [ci skip]

Author: brikis98

LICENSE.txt

@@ -0,0 +1,12 @@
+**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/LICENSE.txt>.
+If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
+
+Gruntwork License
+
+Copyright (c) 2016 Gruntwork, LLC
+
+This code is the property of Gruntwork, LLC. In the Software Development Agreement signed by both Gruntwork and your
+company, Gruntwork grants you a limited license to use, modify, and create derivative works of this code. Please
+consult the Software Development Agreement for the complete terms under which you may use this code. 

README.md

@@ -0,0 +1,92 @@
+**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/README.md>.
+If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
+
+# Security Modules
+
+This repo contains modules for setting up best practices for managing secrets, credentials, and servers:
+
+* [kms-master-key](/modules/kms-master-key): This Terraform Module creates a new [Customer Master Key
+  (CMK)](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) in [Amazon's Key Management
+  Service (KMS)](https://aws.amazon.com/kms/) as well as a [Key
+  Policy](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key_permissions) that controls who has
+  access to the CMK. You can use a CMK to encrypt and decrypt small amounts of data and to generate [Data
+  Keys](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) that can be used to encrypt and
+  decrypt larger amounts of data.
+
+Click on each module above to see its documentation. Head over to the [examples](/examples) folder for examples.
+
+## What is a module?
+
+At [Gruntwork](http://www.gruntwork.io), we've taken the thousands of hours we spent building infrastructure on AWS and
+condensed all that experience and code into pre-built **packages** or **modules**. Each module is a battle-tested,
+best-practices definition of a piece of infrastructure, such as a VPC, ECS cluster, or an Auto Scaling Group. Modules
+are versioned using [Semantic Versioning](http://semver.org/) to allow Gruntwork clients to keep up to date with the
+latest infrastructure best practices in a systematic way.
+
+## How do you use a module?
+
+Most of our modules contain either:
+
+1. [Terraform](https://www.terraform.io/) code
+1. Scripts & binaries
+
+#### Using a Terraform Module
+
+To use a module in your Terraform templates, create a `module` resource and set its `source` field to the Git URL of
+this repo. You should also set the `ref` parameter so you're fixed to a specific version of this repo, as the `master`
+branch may have backwards incompatible changes (see [module
+sources](https://www.terraform.io/docs/modules/sources.html)).
+
+For example, to use `v1.0.8` of the ecs-cluster module, you would add the following:
+
+```hcl
+module "ecs_cluster" {
+  source = "git::[email protected]:gruntwork-io/module-ecs.git//modules/ecs-cluster?ref=v1.0.8"
+
+  // set the parameters for the ECS cluster module
+}
+```
+
+*Note: the double slash (`//`) is intentional and required. It's part of Terraform's Git syntax (see [module
+sources](https://www.terraform.io/docs/modules/sources.html)).*
+
+See the module's documentation and `vars.tf` file for all the parameters you can set. Run `terraform get -update` to
+pull the latest version of this module from this repo before runnin gthe standard  `terraform plan` and
+`terraform apply` commands.
+
+#### Using scripts & binaries
+
+You can install the scripts and binaries in the `modules` folder of any repo using the [Gruntwork
+Installer](https://github.com/gruntwork-io/gruntwork-installer). For example, if the scripts you want to install are
+in the `modules/ecs-scripts` folder of the https://github.com/gruntwork-io/module-ecs repo, you could install them
+as follows:
+
+```bash
+gruntwork-install --module-name "ecs-scripts" --repo "https://github.com/gruntwork-io/module-ecs" --tag "0.0.1"
+```
+
+See the docs for each script & binary for detailed instructions on how to use them.
+
+## Developing a module
+
+#### Versioning
+
+We are following the principles of [Semantic Versioning](http://semver.org/). During initial development, the major
+version is to 0 (e.g., `0.x.y`), which indicates the code does not yet have a stable API. Once we hit `1.0.0`, we will
+follow these rules:
+
+1. Increment the patch version for backwards-compatible bug fixes (e.g., `v1.0.8 -> v1.0.9`).
+2. Increment the minor version for new features that are backwards-compatible (e.g., `v1.0.8 -> 1.1.0`).
+3. Increment the major version for any backwards-incompatible changes (e.g. `1.0.8 -> 2.0.0`).
+
+The version is defined using Git tags.  Use GitHub to create a release, which will have the effect of adding a git tag.
+
+#### Tests
+
+See the [test](/test) folder for details.
+
+## License
+
+Please see [LICENSE.txt](/LICENSE.txt) for details on how the code in this repo is licensed.

circle.yml

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/circle.yml>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

examples/kms-master-key/README.md

@@ -0,0 +1,29 @@
+**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/examples/kms-master-key/README.md>.
+If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
+
+# KMS Master Key Example
+
+This is an example of how to create a [Customer Master
+Key (CMK)](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) in [Amazon's Key Management
+Service (KMS)](https://aws.amazon.com/kms/) using the [kms-master-key module](/modules/kms-master-key). You can use a
+CMK to encrypt and decrypt small amounts of data and to generate [Data
+Keys](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) that can be used to encrypt and
+decrypt larger amounts of data.
+
+You can use KMS via the AWS API, CLI, or, for a more streamlined experience, you can use
+[gruntkms](https://github.com/gruntwork-io/gruntkms).
+
+## Quick start
+
+**Note**: These templates create a Master Key in KMS. Each Master Key costs $1/month, even if you delete it immediately
+after. So please be aware that applying this example will cost you money!
+
+To try these templates out you must have Terraform installed (minimum version: `0.6.11`):
+
+1. Open `vars.tf`, set the environment variables specified at the top of the file, and fill in any other variables that
+   don't have a default.
+1. Run `terraform get`.
+1. Run `terraform plan`.
+1. If the plan looks good, run `terraform apply`.

examples/kms-master-key/main.tf

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/examples/kms-master-key/main.tf>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

examples/kms-master-key/outputs.tf

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/examples/kms-master-key/outputs.tf>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

examples/kms-master-key/vars.tf

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/examples/kms-master-key/vars.tf>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

modules/kms-master-key/README.md

@@ -0,0 +1,40 @@
+**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/kms-master-key/README.md>.
+If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
+
+# KMS Master Key Module
+
+This Terraform Module creates a new [Customer Master
+Key (CMK)](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) in [Amazon's Key Management
+Service (KMS)](https://aws.amazon.com/kms/) as well as a [Key
+Policy](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key_permissions) that controls who has
+access to the CMK. You can use a CMK to encrypt and decrypt small amounts of data and to generate [Data
+Keys](http://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) that can be used to encrypt and
+decrypt larger amounts of data.
+
+You can use KMS via the AWS API, CLI, or, for a more streamlined experience, you can use
+[gruntkms](https://github.com/gruntwork-io/gruntkms).
+
+## How do you use this module?
+
+* See the [root README](/README.md) for instructions on using Terraform modules.
+* See the [kms-master-key example](/examples/kms-master-key) for an example.
+* See [vars.tf](./vars.tf) for all the variables you can set on this module.
+
+**Note**: This module creates a Master Key in KMS. Each Master Key costs $1/month, even if you delete it immediately
+after. So please be aware that using this module will cost you money!
+
+## What is KMS?
+
+[Amazon's Key Management Service (KMS)](https://aws.amazon.com/kms/) is a managed service that makes it easy for you to
+create and control the encryption keys used to encrypt your data, and uses Hardware Security Modules (HSMs) to protect
+the security of your keys.
+
+## What is a Customer Master Key?
+
+A Customer Master Key (CMK) is a secret key that KMS stores and manages for you. You can use the CMK to encrypt small
+amounts of data using the AWS APIs or a tool like [gruntkms](https://github.com/gruntwork-io/gruntkms). You can also use
+a CMK to generate a Data Key that you can use in your own encryption algorithms to encrypt and decrypt large amounts of
+data. You typically store the Data Key, encrypted via the CMK, in version control, and decrypt it via the AWS API or
+gruntkms whenever you need to use it to decrypt or encrypt data.

modules/kms-master-key/main.tf

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/kms-master-key/main.tf>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

modules/kms-master-key/outputs.tf

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/kms-master-key/outputs.tf>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

modules/kms-master-key/vars.tf

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/kms-master-key/vars.tf>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

test/README.md

@@ -0,0 +1,65 @@
+**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/test/README.md>.
+If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
+
+# Tests
+
+This folder contains the tests for the modules in this repo.
+
+## Running the tests locally
+
+**Note #1**: Many of these tests create real resources in an AWS account. That means they cost money to run, especially
+if you don't clean up after yourself. Please be considerate of the resources you create and take extra care to clean
+everything up when you're done!
+
+**Note #2**: Never hit `CTRL + C` or cancel a build once tests are running or the cleanup tasks won't run!
+
+**Note #3**: We set `-timeout 45m` on all tests not because they necessarily take 45 minutes, but because Go has a
+default test timeout of 10 minutes, after which it does a `SIGQUIT`, preventing the tests from properly cleaning up
+after themselves. Therefore, we set a timeout of 45 minutes to make sure all tests have enough time to finish and
+cleanup.
+
+#### Prerequisites
+
+- Install the latest version of [Go](https://golang.org/).
+- Install [glide](https://glide.sh/) for Go dependency management. On OSX, the simplest way to install is
+  `brew update; brew install glide`.
+- Install [Terraform](https://www.terraform.io/downloads.html).
+- Add your AWS credentials as environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
+- For some of the tests, you also need to set the `GITHUB_OAUTH_TOKEN` environment variable to a valid GitHub
+  auth token with "repo" access. You can generate one here: https://github.com/settings/tokens
+
+#### Setup
+
+Download Go dependencies using glide:
+
+```
+cd test
+glide update
+```
+
+#### Run all the tests
+
+```bash
+cd test
+go test -v -timeout 45m -parallel 128
+```
+
+**Note**: The automated test for the `kms-master-key` package is disabled by default. That's because generating a KMS
+Master Key costs $1/month, even if we delete it right after, which can add up quickly if we run this test often. To
+enable the test, you need to set the `RUN_KMS_TEST` environment variable:
+
+```bash
+cd test
+RUN_KMS_TEST=true go test -v -timeout 45m -parallel 128
+```
+
+#### Run a specific test
+
+To run a specific test called `TestFoo`:
+
+```bash
+cd test
+go test -v -timeout 45m -parallel 128 -run TestFoo
+```

test/glide.lock

@@ -0,0 +1,4 @@
+# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/test/glide.yaml>.
+# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

test/glide.yaml

@@ -0,0 +1,4 @@
+// **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+// We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+// If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/test/kms_master_key_test.go>.
+// If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

test/kms_master_key_test.go

@@ -0,0 +1,4 @@
+// **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
+// We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
+// If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/test/test_helpers.go>.
+// If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!