Skip to content

Latest commit

 

History

History
147 lines (105 loc) · 5.33 KB

CONTRIBUTING.md

File metadata and controls

147 lines (105 loc) · 5.33 KB
Raw

Contributing

This document provides guidelines for contributing to the module.

Dependencies

The following dependencies must be installed on the development system:

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 behavior 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-Terraform, and InSpec. These tools are packaged within a Docker image for convenience.

The general strategy for these tests is to verify the behavior of the example modules, 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 directory.

To use this setup, you need a service account with these permissions (on a Folder or Organization):

The project that the service account belongs to must have the following APIs enabled (the setup won't create any resources on the service account's project):

Use service account impersonation if your identity doesn't have the necessary roles

gcloud config set auth/impersonate_service_account ${IMPERSONATION_SA}
export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)

You will also need to set a few environment variables:

export TF_VAR_org_id="your_org_id"
export TF_VAR_folder_id="your_folder_id"
export TF_VAR_billing_account="your_billing_account_id"
export TF_VAR_project_trusted_analytics="your_analytics_project_id"
export TF_VAR_project_trusted_data="your_data_project_id"
export TF_VAR_project_trusted_kms="your_kms_project_id"
export TF_VAR_default_policy_id = ${TF_VAR_org_id}  # access policy only accepts org_id
export TF_VAR_vpc_perimeter_ip_subnetworks = "your_subnet_for_vpc_perimeter"
export TF_VAR_confidential_groups = '["group:[email protected]", "group:[email protected]"]'
export TF_VAR_trusted_scientists = '["user:[email protected]", "user:[email protected]"]'

With these settings in place, you can prepare a test project using Docker. This creates the following in your test environment based on the test/setup directory:

  • BigQuery dataset and table with sample PII data
  • Test service account
  • VPC network and subnet
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_test_prepare to prepare the environment and the testing Docker container in interactive mode.

  2. Run make docker_run to start the testing Docker container in interactive mode.

  3. Run kitchen_do create <EXAMPLE_NAME> to initialize the working directory for an example module.

  4. Run kitchen_do converge <EXAMPLE_NAME> to apply the example module.

  5. Run kitchen_do verify <EXAMPLE_NAME> to test the example module.

  6. 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.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Community Guidelines

This project follows Google's Open Source Community Guidelines.