Skip to content

Latest commit

 

History

History
118 lines (81 loc) · 5.4 KB

DEVELOPMENT.md

File metadata and controls

118 lines (81 loc) · 5.4 KB

Development

Dependencies

The following dependencies must be installed on the development system:

  1. Go
  2. Terraform-Docs
  3. tfsec
  4. pre-commit
  5. Packer

Pre-commit hooks must be installed to your git config:

pre-commit install --install-hooks

All code must pass the pre-commit checks to be merged. If you encounter errors running pre-commit run (particularly on OSX), ensure you are using Bash > 3.

You may need to run:

brew install bash coreutils

File Structure

The project has the following folders and files:

  • /*.tf: Terraform files that consitute the executable code within the digitalocean/github-oidc/vault Terraform module.
  • /examples: Relatively plug-and-play examples for using this module.
  • /test: Folders with files setting up an ephemeral Vault for running Terratest to test the module (see Integration Testing).
    • The /test/packer directory builds a weekly Droplet snapshot of a base Vault installation on an Ubuntu server to simplify + speed up the regular Terraform invocations during PR reviews.
    • The /test/terratest directory contains the Terratest code executed during pull request reviews.
  • /main.tf: The main file of the module, containing all of the resources that will be created.
  • /variables.tf: All of the variables for the module.
  • /outputs.tf: All of the output variables generated by the module.

Generating Documentation for Inputs and Outputs

The inputs and outputs in the READMEs of the root module and examples are automatically generated via terraform-docs.

Integration Testing

Integration tests are used to verify the behavior of the root module. Additions, changes, and fixes should be accompanied with tests.

The general strategy of the tests is to verify the correct configuration of HashiCorp Vault for this OIDC use case with GitHub, thus ensuring the root module is functionally correct.

To streamline the testing that occurs in pull requests, this repo builds a weekly Droplet snapshot made up of a base Ubuntu image with Vault pre-installed and ready for configuration. This increases stability in PRs as well. In the event of a build failure, PR reviews will continue testing against the last successfully generated snapshot.

Test Environment

Given the module binds GitHub OIDC authentication, the test environment must run on a GitHub Actions workflow. Therefore, tests are run from the .github/workflows/pr_target.yml file. To help troubleshoot any failures of those tests, the test environment is itself tested for functional correctness by the Terratest suite under /test/terratest.

The tests under /test ensure that the ephemeral Vault instance created during the GitHub Actions CI suite is properly pre-configured. It also verifies the Terraform module configures the GitHub OIDC auth backend per existing expectations. The details of this test harness can be found under test/terratest/prepare-server/ and test/terratest/configure-vault/. This module is executed in test/terratest/configure-oidc/.

The tests run by .github/workflows/pr_target.yml take an additional step from the Terratest code and attempt to access secrets from Vault through OIDC authentication during a GitHub Action workflow run. They demonstrate correct binding of OIDC auth roles, including the inability to bind to an auth role given alternate GitHub JWT bound_subjects.

To use and execute the test environment, you need a DigitalOcean API token. To run the Packer build in /test/packer, set a DIGITALOCEAN_TOKEN env var. To run the Terraform suite or Terratest tests, set the API token to the Terraform variable do_token. For example:

export DIGITALOCEAN_TOKEN="dop_v1_..."
export TF_VAR_do_token="${DIGITALOCEAN_TOKEN}"

You can then run either the Packer build or Terratest test suite.

Packer:

cd test/packer && packer build .

Terratest:

make test
# Alternatively
cd test/terratest/ && go test

You cannot use local development tools such as act due to the OIDC binding requirements of the tests run under .github/workflows/pr_target.yml. To reproduce the test steps from .github/workflows/pr.yml, it is faster to run:

make init
make fmt
make validate

than to run act or a similar tool. If you wish to use act, install with brew install act and run:

# Check Terraform syntax
act -j fmt-validate -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04

Linting and Formatting

The Terraform, Packer, and Go code can be linted and formatted to maintain a standard of quality. Run make fmt.

Releasing New Versions

This repository publishes tags and releases following semantic versioning and follows the Keep a Changelog convention for syntax within release notes.

See the Terraform documentation for more info on releasing new versions.