Terraform Module Template Repo

🚀 An Awesome Template to Jumpstart Terraform Modules 🚀

---

Post-Initialization Setup

1. Review the base template files to ensure your project's needs are met. Some helpful tips:

   • If you'd like to change the .gitignore, GitHub has some awesome templates here.

   • You can also query the gitignore.io API to find a list of recommended gitignore entries to suit virtually any type of project.

     # Obtain a list of available project-type options from the gitignore.io API.
     curl -sL https://www.toptal.com/developers/gitignore/api/list | sed 's/,/\n/g' > ./gitignore_io_api_options
     
     # Review the resultant list in "./gitignore_io_api_options" to find options that fit your project.
     # You can query gitignore entries for one or more options by separating them with commas.
     # For example, if your project will contain both Terraform and Terragrunt files:
     curl -sL https://www.toptal.com/developers/gitignore/api/terraform,terragrunt >> .gitignore

2. Set up pre-commit:

   1. Ensure it's installed locally or in an executable image.
   2. Some awesome pre-commit hooks have already been added to the pre-commit config file for Terraform projects. If you're looking for more hooks to add, the pre-commit project provides a complete list of supported hooks here. Some popular hook sources:
      • "Out-of-the-Box" pre-commit Hooks
      • pre-commit Hooks from gruntwork.io
      • Some Terraform-specific pre-commit Hooks
   3. Run pre-commit install to ensure your git hooks are present.

3. Enable the Semantic-Release GitHub Action:

   1. Create a GitHub Personal Access Token. When creating the token, the minimum required scopes are:
      • repo for a private repository
      • public_repo for a public repository
   2. Add a GitHub Secret to your repo named "SEMANTIC_RELEASE_TOKEN" with the value set to the new PAT you created in the previous step.
   3. Once the secret has been added to your repo, you can delete the "check-required-secret" job in the "Release" GitHub Action workflow (it was included so you can push initialization commits without triggering a bunch of failed GH Action runs). Note that the "Release" workflow will not run unless the "Test" workflow completes successfully.
   4. (Optional) You can have GH Issues auto-assigned on release failures by adding assignees to the "@semantic-release/github" plugin in .releaserc.yaml.

4. Enable Terratest testing suite:

   1. From the tests dir, run go mod init "<MODULE_NAME>" to initialize a go module, where <MODULE_NAME> is the name of your module, typically in the format github.com/<YOUR_USERNAME>/<YOUR_REPO_NAME>.

      Example: go mod init github.com/trevor-anderson/template-terraform-module/tests.

   2. Run go mod tidy to ensure all required package dependencies are installed.

   3. The existing test can be configured using the file tests/test_params.yaml. See Testing for more info.

      Your tests will be run by the "Test" GitHub Action workflow, but you can also run them manually from the tests dir using go test -v -timeout 30m (the flags are optional).

   4. In order for Terratest to run within a CI environment, you will need to provision access to your cloud resources in the "Test" workflow. This is best accomplished by adding GitHub as an OpenID Connect Identity Provider within your cloud platform account. If you're operating within a multi-account organization, use a "Sandbox" account.

   5. Once GitHub has been added as an OIDC Identity Provider, add the relevant action for your cloud provider which initiates the OIDC auth flow to authenticate the GitHub OIDC Provider and permits access to the desired cloud resources:

      • AWS: aws-actions/configure-aws-credentials
      • Azure: azure/login
      • GCP: google-github-actions/auth
      • HashiCorp Vault: hashicorp/vault-action
      • Others: custom action using JWTs

5. Profit 💰💰💰🥳🎉 (Also, don't forget to remove this section from the README)

Need help? 🤔 Check out my new YouTube Channel with helpful guides covering how to code your cloud with Terraform, Terragrunt, Packer, Golang, CI/CD tools, and more.

---

⚙️ Module Usage

Requirements

Name	Version
terraform	1.2.2

Providers

No providers.

Modules

No modules.

Resources

No resources.

Inputs

No inputs.

Outputs

No outputs.

---

🧪 Testing

This module's test suite is powered by Terratest and can be configured via the file tests/test_params.yaml, which is used to define which assertions the test should make, and what values to use in those assertions.

Input variables to be used for testing purposes can be specified in the file tests/test.tfvars. Note that by default, this file will not be ignored by git, so sensitive values should not be included. To override this behavior, remove the entry "!tests/test.tfvars" from the .gitignore.

Currently Supported Test Params:

• expect_outputs Map the names of expected outputs to arbitrary values of any type. The test will compare these expected outputs against the module's actual outputs; the test will fail if an expected name/key is not present, or if the expected value does not match the actual output value.
• verbose_logging Increase test logging verbosity; useful for debugging purposes, or when running tests locally. May not be suitable for some CI environments.

Coming Soon: Future releases will expand the supported test params to provide additional functionality. Ideas currently in the pipeline are listed below - PRs are welcome if you've something to add.

• expect_http_response Send configurable HTTP requests to created infrastructure components in order for assertions to be made using the resultant responses.
• expect_error Make configurable error assertions.

Test Process Outline:

1. The test_params file is read into memory. If invalid test params were provided, the test will fail. If the test params are valid, they're printed to stdout.
2. Your module files are passed into Terratest, which is used to run terraform init, terraform apply, and terraform output to retrieve module outputs.
3. The provided test params are used to determine which assertions to test. For example, providing expect_outputs will cause the actual output keys and values to be compared against the expected outputs.
4. Finally, once all assertions have been tested, Terratest is used to run terraform destroy to clean up all test resources - regardless of whether the tests succeed or fail.

Example Test Failure Output

If a test fails, the output will look something like the example below. Note: if verbose_logging is not enabled, the first four lines would be omitted.

TestTerraformModule 2022-06-14T12:35:17-04:00 module_unit_test.go:98:

        [TEST] EXPECTED OUTPUT: foo_string_key = foo_string_value        ACTUAL: foo_string_value_NOPE

module_unit_test.go:91:
                Error Trace:    module_unit_test.go:91
                Error:          Not equal:
                                expected: "foo_string_value"
                                actual  : "foo_string_value_NOPE"

                                Diff:
                                --- Expected
                                +++ Actual
                                @@ -1 +1 @@
                                -foo_string_value
                                +foo_string_value_NOPE
                Test:           TestTerraformModule

📝 License

Apache 2 Licensed. See LICENSE for more information.

💬 Template Author Contact

Trevor Anderson - @TeeRevTweets - [email protected]

     

Dare Mighty Things.