|
1 | | -## File structure |
2 | | -The project has the following folders and files: |
| 1 | +# Contributing |
3 | 2 |
|
4 | | -- /: root folder |
5 | | -- /examples: examples for using this module |
6 | | -- /test: Folders with files for testing the module (see Testing section on this file) |
7 | | -- /main.tf: main file for this module, contains all the resources to create |
8 | | -- /variables.tf: all the variables for the module |
9 | | -- /output.tf: the outputs of the module |
10 | | -- /README.md: this file |
| 3 | +This document provides guidelines for contributing to the module. |
11 | 4 |
|
12 | | -## Testing and documentation generation |
| 5 | +## Dependencies |
13 | 6 |
|
14 | | -### Requirements |
15 | | -- [docker](https://docker.com/) |
| 7 | +The following dependencies must be installed on the development system: |
16 | 8 |
|
17 | | -### Integration testing |
18 | | -##### Terraform integration tests |
| 9 | +- [Docker Engine][docker-engine] |
| 10 | +- [Google Cloud SDK][google-cloud-sdk] |
| 11 | +- [make] |
19 | 12 |
|
20 | | -The module's integration tests are designed to be run within a Docker |
21 | | -container containing all the dependencies required for testing. The |
22 | | -`docker_test_integration` make target wraps this behavior but requires the |
23 | | -following configuration to execute properly: |
| 13 | +## Generating Documentation for Inputs and Outputs |
24 | 14 |
|
25 | | -- Configure a service account with the roles documented above and export the JSON key to the `SERVICE_ACCOUNT_JSON` environment variable |
| 15 | +The Inputs and Outputs tables in the READMEs of the root module, |
| 16 | +submodules, and example modules are automatically generated based on |
| 17 | +the `variables` and `outputs` of the respective modules. These tables |
| 18 | +must be refreshed if the module interfaces are changed. |
26 | 19 |
|
27 | | - export SERVICE_ACCOUNT_JSON=$(< /path/to/credentials.json) |
| 20 | +### Execution |
28 | 21 |
|
29 | | -- Create `test/fixtures/shared/terraform.tfvars` and populate with the required Terraform input variables (see `test/fixtures/shared/terraform.tfvars.sample` for more information) |
| 22 | +Run `make generate_docs` to generate new Inputs and Outputs tables. |
30 | 23 |
|
31 | | -Once those steps have been completed run `make docker_test_integration` from |
32 | | -the root of the repository to execute the tests within the `project_id` |
33 | | -provided. Infrastructure from `test/fixtures/*` will be provisioned, |
34 | | -integration tests from `test/integration/*` will be executed, and the |
35 | | -infrastructure will be deprovisioned to complete the process. |
| 24 | +## Integration Testing |
36 | 25 |
|
37 | | -### Autogeneration of documentation from .tf files |
38 | | -Run |
39 | | -``` |
40 | | -make generate_docs |
41 | | -``` |
| 26 | +Integration tests are used to verify the behaviour of the root module, |
| 27 | +submodules, and example modules. Additions, changes, and fixes should |
| 28 | +be accompanied with tests. |
| 29 | + |
| 30 | +The integration tests are run using [Kitchen][kitchen], |
| 31 | +[Kitchen-Terraform][kitchen-terraform], and [InSpec][inspec]. These |
| 32 | +tools are packaged within a Docker image for convenience. |
42 | 33 |
|
43 | | -### Lint testing |
| 34 | +The general strategy for these tests is to verify the behaviour of the |
| 35 | +[example modules](./examples/), thus ensuring that the root module, |
| 36 | +submodules, and example modules are all functionally correct. |
44 | 37 |
|
45 | | -Lint testing is also performed within a Docker container containing all the |
46 | | -dependencies required for lint tests. Execute those tests by running `make |
47 | | -docker_test_lint` from the root of the repository. |
| 38 | +### Test Environment |
| 39 | +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. |
48 | 40 |
|
49 | | -Successful output looks similar to the following: |
| 41 | +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: |
| 42 | + |
| 43 | +``` |
| 44 | +export SERVICE_ACCOUNT_JSON=$(< credentials.json) |
| 45 | +``` |
50 | 46 |
|
| 47 | +You will also need to set a few environment variables: |
51 | 48 | ``` |
52 | | -Checking for trailing whitespace |
53 | | -Checking for missing newline at end of file |
54 | | -Running shellcheck |
55 | | -Checking file headers |
56 | | -Running flake8 |
57 | | -Running terraform fmt |
58 | | -terraform fmt -diff -check=true -write=false . |
59 | | -terraform fmt -diff -check=true -write=false ./codelabs/simple |
60 | | -terraform fmt -diff -check=true -write=false ./examples/delete_default_gateway_routes |
61 | | -terraform fmt -diff -check=true -write=false ./examples/multi_vpc |
62 | | -terraform fmt -diff -check=true -write=false ./examples/secondary_ranges |
63 | | -terraform fmt -diff -check=true -write=false ./examples/simple_project |
64 | | -terraform fmt -diff -check=true -write=false ./examples/simple_project_with_regional_network |
65 | | -terraform fmt -diff -check=true -write=false ./examples/submodule_firewall |
66 | | -terraform fmt -diff -check=true -write=false ./examples/submodule_svpc_access |
67 | | -terraform fmt -diff -check=true -write=false ./modules/fabric-net-firewall |
68 | | -terraform fmt -diff -check=true -write=false ./modules/fabric-net-svpc-access |
69 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/all_examples |
70 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/delete_default_gateway_routes |
71 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/multi_vpc |
72 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/secondary_ranges |
73 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/shared |
74 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/simple_project |
75 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/simple_project_with_regional_network |
76 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/simulated_ci_environment |
77 | | -terraform fmt -diff -check=true -write=false ./test/fixtures/submodule_firewall |
78 | | -Running terraform validate |
79 | | -terraform_validate . |
80 | | -Success! The configuration is valid. |
81 | | -
|
82 | | -terraform_validate ./codelabs/simple |
83 | | -Success! The configuration is valid. |
84 | | -
|
85 | | -terraform_validate ./examples/delete_default_gateway_routes |
86 | | -Success! The configuration is valid. |
87 | | -
|
88 | | -terraform_validate ./examples/multi_vpc |
89 | | -Success! The configuration is valid. |
90 | | -
|
91 | | -terraform_validate ./examples/secondary_ranges |
92 | | -Success! The configuration is valid. |
93 | | -
|
94 | | -terraform_validate ./examples/simple_project |
95 | | -Success! The configuration is valid. |
96 | | -
|
97 | | -terraform_validate ./examples/simple_project_with_regional_network |
98 | | -Success! The configuration is valid. |
99 | | -
|
100 | | -terraform_validate ./examples/submodule_firewall |
101 | | -Success! The configuration is valid. |
102 | | -
|
103 | | -terraform_validate ./examples/submodule_svpc_access |
104 | | -Success! The configuration is valid. |
105 | | -
|
106 | | -terraform_validate ./modules/fabric-net-firewall |
107 | | -Success! The configuration is valid. |
108 | | -
|
109 | | -terraform_validate ./modules/fabric-net-svpc-access |
110 | | -Success! The configuration is valid. |
111 | | -
|
112 | | -terraform_validate ./test/fixtures/all_examples |
113 | | -Success! The configuration is valid. |
114 | | -
|
115 | | -terraform_validate ./test/fixtures/delete_default_gateway_routes |
116 | | -Success! The configuration is valid. |
117 | | -
|
118 | | -terraform_validate ./test/fixtures/multi_vpc |
119 | | -Success! The configuration is valid. |
120 | | -
|
121 | | -terraform_validate ./test/fixtures/secondary_ranges |
122 | | -Success! The configuration is valid. |
123 | | -
|
124 | | -terraform_validate ./test/fixtures/simple_project |
125 | | -Success! The configuration is valid. |
126 | | -
|
127 | | -terraform_validate ./test/fixtures/simple_project_with_regional_network |
128 | | -Success! The configuration is valid. |
129 | | -
|
130 | | -terraform_validate ./test/fixtures/simulated_ci_environment |
131 | | -Success! The configuration is valid. |
132 | | -
|
133 | | -terraform_validate ./test/fixtures/submodule_firewall |
134 | | -Success! The configuration is valid. |
| 49 | +export TF_VAR_org_id="your_org_id" |
| 50 | +export TF_VAR_folder_id="your_folder_id" |
| 51 | +export TF_VAR_billing_account="your_billing_account_id" |
135 | 52 | ``` |
136 | 53 |
|
137 | | -[terraform-provider-google]: https://github.com/terraform-providers/terraform-provider-google |
| 54 | +With these settings in place, you can prepare a test project using Docker: |
| 55 | +``` |
| 56 | +make docker_test_prepare |
| 57 | +``` |
| 58 | + |
| 59 | +### Noninteractive Execution |
| 60 | + |
| 61 | +Run `make docker_test_integration` to test all of the example modules |
| 62 | +noninteractively, using the prepared test project. |
| 63 | + |
| 64 | +### Interactive Execution |
| 65 | + |
| 66 | +1. Run `make docker_run` to start the testing Docker container in |
| 67 | + interactive mode. |
| 68 | + |
| 69 | +1. Run `kitchen_do create <EXAMPLE_NAME>` to initialize the working |
| 70 | + directory for an example module. |
| 71 | + |
| 72 | +1. Run `kitchen_do converge <EXAMPLE_NAME>` to apply the example module. |
| 73 | + |
| 74 | +1. Run `kitchen_do verify <EXAMPLE_NAME>` to test the example module. |
| 75 | + |
| 76 | +1. Run `kitchen_do destroy <EXAMPLE_NAME>` to destroy the example module |
| 77 | + state. |
| 78 | + |
| 79 | +## Linting and Formatting |
| 80 | + |
| 81 | +Many of the files in the repository can be linted or formatted to |
| 82 | +maintain a standard of quality. |
| 83 | + |
| 84 | +### Execution |
| 85 | + |
| 86 | +Run `make docker_test_lint`. |
| 87 | + |
| 88 | +[docker-engine]: https://www.docker.com/products/docker-engine |
| 89 | +[flake8]: http://flake8.pycqa.org/en/latest/ |
| 90 | +[gofmt]: https://golang.org/cmd/gofmt/ |
| 91 | +[google-cloud-sdk]: https://cloud.google.com/sdk/install |
| 92 | +[hadolint]: https://github.com/hadolint/hadolint |
| 93 | +[inspec]: https://inspec.io/ |
| 94 | +[kitchen-terraform]: https://github.com/newcontext-oss/kitchen-terraform |
| 95 | +[kitchen]: https://kitchen.ci/ |
| 96 | +[make]: https://en.wikipedia.org/wiki/Make_(software) |
| 97 | +[shellcheck]: https://www.shellcheck.net/ |
| 98 | +[terraform-docs]: https://github.com/segmentio/terraform-docs |
| 99 | +[terraform]: https://terraform.io/ |
0 commit comments