Skip to content

Latest commit

 

History

History
85 lines (52 loc) · 4.04 KB

user_guide.md

File metadata and controls

85 lines (52 loc) · 4.04 KB
Raw

User Guide

Basic setup

These instructions assume you have a working set of terraform files and have already installed Terraform Validator and have an organizational policy library available on the same filesystem.

Terraform Validator takes terraform plan JSON as its input. You can generate this file by running the following in your terraform directory:

terraform plan -out=tfplan.tfplan
terraform show -json ./tfplan.tfplan > ./tfplan.json

Auth

terraform-validator supports the same environment variables for authentication used by the google provider for terraform.

In particular, you can use the following environment variables (in order of precedence) to provide a service account key file:

  • GOOGLE_CREDENTIALS
  • GOOGLE_CLOUD_KEYFILE_JSON
  • GOOGLE_KEYFILE_JSON

Using Terraform-Validator-specific service accounts is the recommended practice when using Terraform Validator.

You can also authenticate using an OAuth 2.0 access token, which can be provided via the GOOGLE_OAUTH_ACCESS_TOKEN environment variable.

For local development, you can also use Google Application Default Credentials by providing the path to your application default credentials file via the GOOGLE_APPLICATION_CREDENTIALS environment variable.

gcloud auth application-default login  # local development only
GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/application_default_credentials.json

Service account impersonation

You can specify a service account to impersonate for all Google API calls with the GOOGLE_IMPERSONATE_SERVICE_ACCOUNT environment variable.

Required permissions

The GCP account being used for validation must have the following permissions:

  • getIamPolicy permissions for any IAM members and bindings that are being validated.
    • Terraform Validator needs to get full IAM policies and merge them with members and bindings to get an accurate end state to validate.
  • resourcemanager.projects.get for any projects that validated resources are related to.
    • Terraform Validator needs to get project ancestry from the API in order to accurately construct a full CAI Asset Name for validation.

terraform-validator validate

This command allows you to validate your terraform plan JSON against a specific policy library.

Basic usage:

terraform-validator validate tfplan.json --policy-path=${POLICY_PATH}

Flags

--policy-path=${POLICY_PATH}

The policy-path flag is set to the local clone of your Git repository that contains your organizational constraints and templates.

--project=my-project (optional)

Terraform Validator accepts an optional --project flag. This will be used as the default project when building ancestry paths for any resource that doesn't have an explicit project set.

Return value

If violations are found, terraform-validator will return exit code 2 and display a list of violations:

Found Violations:

Constraint iam_domain_restriction on resource //cloudresourcemanager.googleapis.com/projects/12345678: IAM policy for //cloudresourcemanager.googleapis.com/projects/12345678 contains member from unexpected domain: user:foo@example.com

Constraint iam_domain_restriction on resource //cloudresourcemanager.googleapis.com/projects/12345678: IAM policy for //cloudresourcemanager.googleapis.com/projects/12345678 contains member from unexpected domain: group:bar@example.com

If all constraints are validated, the command will return exit code 0 and display "No violations found."