-
Notifications
You must be signed in to change notification settings - Fork 92
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
28 changed files
with
466 additions
and
1,007 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,101 @@ | ||
# Contributing | ||
|
||
This document provides guidelines for contributing to the module. | ||
|
||
## Dependencies | ||
|
||
The following dependencies must be installed on the development system: | ||
|
||
- [Docker Engine][docker-engine] | ||
- [Google Cloud SDK][google-cloud-sdk] | ||
- [make] | ||
|
||
## Generating Documentation for Inputs and Outputs | ||
|
||
The Inputs and Outputs tables in the READMEs of the root module, | ||
submodules, and example modules are automatically generated based on | ||
the `variables` and `outputs` of the respective modules. These tables | ||
must be refreshed if the module interfaces are changed. | ||
|
||
### Execution | ||
|
||
Run `make generate_docs` to generate new Inputs and Outputs tables. | ||
|
||
## Integration Testing | ||
|
||
Integration tests are used to verify the behaviour of the root module, | ||
submodules, and example modules. Additions, changes, and fixes should | ||
be accompanied with tests. | ||
|
||
The integration tests are run using [Kitchen][kitchen], | ||
[Kitchen-Terraform][kitchen-terraform], and [InSpec][inspec]. These | ||
tools are packaged within a Docker image for convenience. | ||
|
||
The general strategy for these tests is to verify the behaviour of the | ||
[example modules](./examples/), thus ensuring that the root module, | ||
submodules, and example modules are all functionally correct. | ||
|
||
### Test Environment | ||
The easiest way to test the module is in an isolated test project. The setup for such a project is defined in [test/setup](./test/setup/) directory. | ||
|
||
To use this setup, you need a service account with Project Creator access on a folder. Export the Service Account credentials to your environment like so: | ||
|
||
``` | ||
export SERVICE_ACCOUNT_JSON=$(< credentials.json) | ||
``` | ||
|
||
You will also need to set a few environment variables: | ||
``` | ||
export TF_VAR_project_id="project_id_of_test_project" | ||
export TF_VAR_parent_resource_project="project_id_of_test_project" | ||
export TF_VAR_parent_resource_folder="folder_id_of_test_folder" | ||
export TF_VAR_parent_resource_organization="org_id_of_test_organization" | ||
export TF_VAR_parent_resource_billing_account="billing_account_id_of_test_billing_account" | ||
``` | ||
|
||
With these settings in place, you can prepare a test project using Docker: | ||
``` | ||
make docker_test_prepare | ||
``` | ||
|
||
### Noninteractive Execution | ||
|
||
Run `make docker_test_integration` to test all of the example modules | ||
noninteractively, using the prepared test project. | ||
|
||
### Interactive Execution | ||
|
||
1. Run `make docker_run` to start the testing Docker container in | ||
interactive mode. | ||
|
||
1. Run `kitchen_do create <EXAMPLE_NAME>` to initialize the working | ||
directory for an example module. | ||
|
||
1. Run `kitchen_do converge <EXAMPLE_NAME>` to apply the example module. | ||
|
||
1. Run `kitchen_do verify <EXAMPLE_NAME>` to test the example module. | ||
|
||
1. Run `kitchen_do destroy <EXAMPLE_NAME>` to destroy the example module | ||
state. | ||
|
||
## Linting and Formatting | ||
|
||
Many of the files in the repository can be linted or formatted to | ||
maintain a standard of quality. | ||
|
||
### Execution | ||
|
||
Run `make docker_test_lint`. | ||
|
||
[docker-engine]: https://www.docker.com/products/docker-engine | ||
[flake8]: http://flake8.pycqa.org/en/latest/ | ||
[gofmt]: https://golang.org/cmd/gofmt/ | ||
[google-cloud-sdk]: https://cloud.google.com/sdk/install | ||
[hadolint]: https://github.com/hadolint/hadolint | ||
[inspec]: https://inspec.io/ | ||
[kitchen-terraform]: https://github.com/newcontext-oss/kitchen-terraform | ||
[kitchen]: https://kitchen.ci/ | ||
[make]: https://en.wikipedia.org/wiki/Make_(software) | ||
[shellcheck]: https://www.shellcheck.net/ | ||
[terraform-docs]: https://github.com/segmentio/terraform-docs | ||
[terraform]: https://terraform.io/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.