From c8525f28b567190da0c066b20bc771dbf88b6020 Mon Sep 17 00:00:00 2001 From: Yoriyasu Yano <430092+yorinasub17@users.noreply.github.com> Date: Thu, 2 May 2019 15:57:12 -0700 Subject: [PATCH 1/2] Prep repo for open source --- CONTRIBUTING.md | 86 ++++++++++++++++++++ LICENSE.txt | 205 ++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 103 +++++++++--------------- 3 files changed, 322 insertions(+), 72 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..46f17e5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contribution Guidelines + +Contributions to this Module are very welcome! We follow a fairly standard [pull request +process](https://help.github.com/articles/about-pull-requests/) for contributions, subject to the following guidelines: + +1. [File a GitHub issue](#file-a-github-issue) +1. [Update the documentation](#update-the-documentation) +1. [Update the tests](#update-the-tests) +1. [Update the code](#update-the-code) +1. [Create a pull request](#create-a-pull-request) +1. [Merge and release](#merge-and-release) + +## File a GitHub issue + +Before starting any work, we recommend filing a GitHub issue in this repo. This is your chance to ask questions and +get feedback from the maintainers and the community before you sink a lot of time into writing (possibly the wrong) +code. If there is anything you're unsure about, just ask! + +## Update the documentation + +We recommend updating the documentation *before* updating any code (see [Readme Driven +Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)). This ensures the documentation +stays up to date and allows you to think through the problem at a high level before you get lost in the weeds of +coding. + +## Update the tests + +We also recommend updating the automated tests *before* updating any code (see [Test Driven +Development](https://en.wikipedia.org/wiki/Test-driven_development)). That means you add or update a test case, +verify that it's failing with a clear error message, and *then* make the code changes to get that test to pass. This +ensures the tests stay up to date and verify all the functionality in this Module, including whatever new +functionality you're adding in your contribution. Check out the [tests](/test) folder for instructions on running the +automated tests. + +## Update the code + +At this point, make your code changes and use your new test case to verify that everything is working. As you work, +keep in mind two things: + +1. Backwards compatibility +1. Downtime + +### Backwards compatibility + +Please make every effort to avoid unnecessary backwards incompatible changes. With Terraform code, this means: + +1. Do not delete, rename, or change the type of input variables. +1. If you add an input variable, it should have a `default`. +1. Do not delete, rename, or change the type of output variables. +1. Do not delete or rename a module in the `modules` folder. + +If a backwards incompatible change cannot be avoided, please make sure to call that out when you submit a pull request, +explaining why the change is absolutely necessary. + +### Downtime + +Bear in mind that the Terraform code in this Module is used by real companies to run real infrastructure in +production, and certain types of changes could cause downtime. For example, consider the following: + +1. If you rename a resource (e.g. `aws_instance "foo"` -> `aws_instance "bar"`), Terraform will see that as deleting + the old resource and creating a new one. +1. If you change certain attributes of a resource (e.g. the `name` of an `aws_elb`), the cloud provider (e.g. AWS) may + treat that as an instruction to delete the old resource and a create a new one. + +Deleting certain types of resources (e.g. virtual servers, load balancers) can cause downtime, so when making code +changes, think carefully about how to avoid that. For example, can you avoid downtime by using +[create_before_destroy](https://www.terraform.io/docs/configuration/resources.html#create_before_destroy)? Or via +the `terraform state` command? If so, make sure to note this in our pull request. If downtime cannot be avoided, +please make sure to call that out when you submit a pull request. + +## Create a pull request + +[Create a pull request](https://help.github.com/articles/creating-a-pull-request/) with your changes. Please make sure +to include the following: + +1. A description of the change, including a link to your GitHub issue. +1. The output of your automated test run, preferably in a [GitHub Gist](https://gist.github.com/). We cannot run + automated tests for pull requests automatically due to [security + concerns](https://circleci.com/docs/fork-pr-builds/#security-implications), so we need you to manually provide this + test output so we can verify that everything is working. +1. Any notes on backwards incompatibility or downtime. + +## Merge and release + +The maintainers for this repo will review your code and provide feedback. If everything looks good, they will merge the +code and release a new version, which you'll be able to find in the [releases page](../../releases). diff --git a/LICENSE.txt b/LICENSE.txt index f4e3d9b..796e219 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,7 +1,202 @@ -Gruntwork License -Copyright (c) 2016 Gruntwork, LLC + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ -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. \ No newline at end of file + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2019 Gruntwork, Inc + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index a252bb4..219bf18 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,21 @@ +[![Maintained by Gruntwork.io](https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg)](https://gruntwork.io/?ref=repo_kubergrunt) + # Terraform Utility Modules -This repo contains miscellaneous utility and helper modules for use with Terraform. +This repo contains miscellaneous utility and helper modules for use with Terraform. + +## What is in this repo + +This repo provides a Gruntwork IaC Package and has the following folder structure: -The modules are: +* [modules](/modules): This folder contains the main implementation code for this repository, broken down into multiple + standalone modules. +* [examples](/examples): This folder contains examples of how to use the modules. +* [test](/test): Automated tests for the modules and examples. -* [intermediate-variable](/modules/intermediate-variable): A simple module that returns as output the exact variables +The following modules are available: + +* [intermediate-variable](/modules/intermediate-variable): A simple module that returns as output the exact variables you pass to it as inputs. This gives you a way to store intermediate values that contain interpolations. * [join-path](/modules/join-path): This module can be used to join a list of given path parts into a single path that is platform/operating system aware. **(This module requires Python)** @@ -19,89 +30,47 @@ The modules are: and runs them as an local-exec provisioner on a null_resource. PEX files are python executables that contain all the requirements necessary to run the script. **(This module requires Python)** -Click on each module above to see its documentation. Head over to the [examples](/examples) folder for examples. +Click on each module above to see its documentation. Head over to the [examples](/examples) folder for example usage. ## 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::git@github.com: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: +A Module is a canonical, reusable, best-practices definition for how to run a single piece of infrastructure, such as a +database or server cluster. Each Module is written using a combination of Terraform and scripts (mostly bash) and +include automated tests, documentation, and examples. It is maintained both by the open source community and companies +that provide commercial support. -```bash -gruntwork-install --module-name "ecs-scripts" --repo "https://github.com/gruntwork-io/module-ecs" --tag "0.0.1" -``` +Instead of figuring out the details of how to run a piece of infrastructure from scratch, you can reuse existing code +that has been proven in production. And instead of maintaining all that infrastructure code yourself, you can leverage +the work of the Module community to pick up infrastructure improvements through a version number bump. -See the docs for each script & binary for detailed instructions on how to use them. +## Who maintains this Module? +This Module is maintained by [Gruntwork](http://www.gruntwork.io/). If you're looking for help or commercial +support, send an email to [modules@gruntwork.io](mailto:modules@gruntwork.io?Subject=Terraform%20Utilities%20Module). +Gruntwork can help with: -## Developing a module +* Setup, customization, and support for this Module. +* Modules for other types of infrastructure, such as VPCs, Docker clusters, databases, and continuous integration. +* Modules that meet compliance requirements, such as HIPAA. +* Consulting & Training on AWS, Terraform, and DevOps. -### 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. +## How is this Module versioned? +This Module follows the principles of [Semantic Versioning](http://semver.org/). You can find each new release, +along with the changelog, in the [Releases Page](../../releases). -### Tests +During initial development, the major version will be 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 make every effort to maintain a backwards compatible API and use the MAJOR, +MINOR, and PATCH versions on each release to indicate any incompatibilities. -See the [test](/test) folder for details. From e49a3d08d0d0f36b5e2f796c220a62cb59597eaf Mon Sep 17 00:00:00 2001 From: Yoriyasu Yano <430092+yorinasub17@users.noreply.github.com> Date: Thu, 2 May 2019 15:59:02 -0700 Subject: [PATCH 2/2] Add NOTICE --- NOTICE | 4 ++++ README.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 NOTICE diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..9722345 --- /dev/null +++ b/NOTICE @@ -0,0 +1,4 @@ +package-terraform-utilities +Copyright 2019 Gruntwork, Inc. + +This product includes software developed at Gruntwork (https://www.gruntwork.io/). diff --git a/README.md b/README.md index 219bf18..ab4023b 100644 --- a/README.md +++ b/README.md @@ -77,4 +77,4 @@ MINOR, and PATCH versions on each release to indicate any incompatibilities. ## License -Please see [LICENSE.txt](/LICENSE.txt) for details on how the code in this repo is licensed. +Please see [LICENSE.txt](/LICENSE.txt) and [NOTICE](/NOTICE) for details on how the code in this repo is licensed.