Browse the Repo

file-type-icon.circleci
file-type-icon.github
file-type-icon.patcher
file-type-icon_docs
file-type-iconcodegen
file-type-iconexamples
file-type-iconhooks
file-type-iconmodules
file-type-iconrfcs
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconCONTRIBUTING.md
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
file-type-iconrenovate.json
file-type-iconsetup.cfg
file-type-iconterraform-cloud-enterprise-private-module-...

Browse the Repo

file-type-icon.circleci
file-type-icon.github
file-type-icon.patcher
file-type-icon_docs
file-type-iconcodegen
file-type-iconexamples
file-type-iconhooks
file-type-iconmodules
file-type-iconrfcs
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconCONTRIBUTING.md
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
file-type-iconrenovate.json
file-type-iconsetup.cfg
file-type-iconterraform-cloud-enterprise-private-module-...
CIS Foundations Benchmark

CIS Foundations Benchmark

Modules and utilities certified by Gruntwork and CIS to comply with the CIS AWS Foundations Benchmark

Code Preview

Preview the Code

mobile file icon

CONTRIBUTING.md

down

Contribution Guidelines

Contributions to this repository are very welcome! We follow a fairly standard pull request process for contributions, subject to the following guidelines:

  1. File a GitHub issue
  2. Update the documentation
  3. Update the tests
  4. Update the code
  5. Create a pull request
  6. Merge and release

Please also see Auto-update for how dependencies are managed and updated in this repo.

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). 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). 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 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
  2. 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.
  2. If you add an input variable, it should have a default.
  3. Do not delete, rename, or change the type of output variables.
  4. 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.
  2. 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? 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.

Formatting and pre-commit hooks

You must run terraform fmt on the terraform code and go fmt on the go code before committing. You can configure your computer to do this automatically using pre-commit hooks managed using pre-commit:

  1. Install pre-commit. E.g.: brew install pre-commit.
  2. Install the hooks: pre-commit install.
  3. Install the required hook binaries: pip install yapf

That's it! Now just write your code, and every time you commit, terraform fmt and yapf will be run on the files you're committing.

Create a pull request

Create 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.
  2. The output of your automated test run, preferably in a GitHub Gist. We cannot run automated tests for pull requests automatically due to security concerns, so we need you to manually provide this test output so we can verify that everything is working.
  3. 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.

Auto-update

This repo has been configured with support for automatic updates using Patcher, plus an experimental Gruntwork Registry endpoint. Here's how it works:

  1. Any time a dependency of this repo releases an update, Patcher will automatically update the code in this repo to use the new version and open up a PR with the changes.

  2. To get the list of available versions, we are using an experimental Gruntwork Registry endpoint:

    1. The code for this endpoint lives in the gruntwork-registry module in the Gruntwork prototypes repo.

    2. This endpoint is NOT ready for production use with all customers and could break at any time. If Patcher works well for us with this repo, we'll work to productionize this endpoint and roll out Patcher to all customers.

    3. We are using a few weird hacks / workaronds. For example, all the regex managers in set the datasourceTemplate to terraform-module, even for non Terraform code. This is largely because we haven't figured out the right data source to use for all dependency types with our experimental endpoint, and pretending everything is a Terraform module works OK for now. Also, there are some TODOs in the code for dependencies we don't know how to update automatically, such as the Jenkins or Terraform version that gets installed (what endpoint do we get that info from?).

    4. In the meantime, if you have questions or issues related to Patcher, contact Jim.

  3. Some auto-update conventions used in this repo:

    1. All Terraform and Terragrunt source = <URL>?ref=XXX dependencies get updated automatically.

    2. For certain file types, if you put patcher auto-update: <REPO NAME> above a variable declaration that specifies a version number, the version number will be automatically updated whenever <REPO NAME> has a new release. For example, in Bash scripts (.sh files):

      # patcher auto-update: terraform-aws-eks
      readonly DEFAULT_TERRAFORM_AWS_EKS_VERSION="v0.1.2"
      

      Any time there's a new release of the terraform-aws-eks repo, Patcher will submit a PR updating the version number in this Bash script.

Questions? Ask away.

We're here to talk about our services, answer any questions, give advice, or just to chat.

Ready to hand off the Gruntwork?