Skip to content

Latest commit

 

History

History
119 lines (88 loc) · 4.02 KB

CONTRIBUTING.md

File metadata and controls

119 lines (88 loc) · 4.02 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 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-Terraform, and 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, 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 the following permissions:
    • Project Creator access on a defined folder
    • Billing account Admin on a billing account
    • Logging Admin on the organisation
    • Logging Admin on a defined folder
    • Organisation Admin on the organisation These permissions seem quite broad, but are needed to be able to test the organisational logging sink exports.
  • The project where this service-account resides needs to have the following APIs enabled:
    • bigquery.googleapis.com
    • bigquerystorage.googleapis.com
    • cloudapis.googleapis.com
    • cloudbilling.googleapis.com
    • cloudresourcemanager.googleapis.com
    • iam.googleapis.com
    • iamcredentials.googleapis.com
    • servicemanagement.googleapis.com
    • serviceusage.googleapis.com
    • storage-api.googleapis.com
    • storage-component.googleapis.com
  • No organisational policies in place that prevent things, such as:
    • No location restrictions
    • No enforcement of bucket policy only
    • No disabling of the creation of the default network. For these policies it is ok if you 'undo' them at the defined folder.

Export the Service Account credentials to your environment like so:

export SERVICE_ACCOUNT_JSON=$(< credentials.json)

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.

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

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

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

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