Validate policies

Before you begin

Install `Google Cloud CLI`

To use gcloud beta terraform vet you must first install Google Cloud CLI:

Install Google Cloud CLI but skip the gcloud init command.

Run the following commands to install the terraform-tools component:

  gcloud 
  
 components 
  
 update 
 gcloud 
  
 components 
  
 install 
  
 terraform-tools

Verify that the gcloud CLI is installed by running the following command:

  gcloud 
  
 beta 
  
 terraform 
  
 vet 
  
 --help

Get required permissions

The Google Cloud account that you use for validation must have the following permissions:

getIamPolicy : gcloud beta terraform vet needs to get full Identity and Access Management (IAM) policies and merge them with members and bindings to get an accurate end state to validate.
resourcemanager.projects.get : gcloud beta terraform vet needs to get project ancestry from the API in order to accurately construct a full CAI Asset Name for any projects that validated resources are related to.
resourcemanager.folders.get : gcloud beta terraform vet needs to get folder ancestry from the API in order to accurately construct a full CAI Asset Name if the validated resources contain any folder-related resources.

Set up a policy library

You need to create a policy library to use this tool.

Validate policies

1. Generate a Terraform plan

gcloud beta terraform vet is compatible with Terraform 0.12+. gcloud beta terraform vet takes terraform plan JSON as its input. You can generate the JSON file by running the following commands in your Terraform directory:

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

2. Run `gcloud beta terraform vet`

gcloud beta terraform vet lets you validate your terraform plan JSON against your organization's POLICY_LIBRARY_REPO . For example:

git clone POLICY_LIBRARY_REPO 
 POLICY_LIBRARY_DIR 
gcloud beta terraform vet tfplan.json --policy-library= POLICY_LIBRARY_DIR

When you execute this command, gcloud beta terraform vet retrieves project data by using Google Cloud APIs that are necessary for an accurate validation of your plan.

Flags

--policy-library= POLICY_LIBRARY_DIR - Directory that contains a policy library.
--project= PROJECT_ID - gcloud beta terraform vet accepts an optional --project flag. This flag specifies the default project when building the ancestry (from the Google Cloud resource hierarchy) for any resource that doesn't have an explicit project set.
--format= FORMAT - The default is yaml. The supported formats are: default , json , none , text , yaml . For more details run $ gcloud topic formats .

Exit code and output

If all constraints are validated, the command returns exit code 0 and does not display violations.
If violations are found, gcloud beta terraform vet returns exit code 2, and displays a list of violations. For example, JSON output might look like:

[
  {
    "constraint": "GCPIAMAllowedPolicyMemberDomainsConstraintV2.service_accounts_only",
    "constraint_config": {
      "api_version": "constraints.gatekeeper.sh/v1alpha1",
      "kind": "GCPIAMAllowedPolicyMemberDomainsConstraintV2",
      "metadata": {
        "annotations": {
          "description": "Checks that members that have been granted IAM roles belong to allowlisted domains.",
          "validation.gcp.forsetisecurity.org/originalName": "service_accounts_only",
          "validation.gcp.forsetisecurity.org/yamlpath": "policies/constraints/iam_service_accounts_only.yaml"
        },
        "name": "service-accounts-only"
      },
      "spec": {
        "match": {
          "target": [
            "organizations/**"
          ]
        },
        "parameters": {
          "domains": [
            "gserviceaccount.com"
          ]
        },
        "severity": "high"
      }
    },
    "message": "IAM policy for //cloudresourcemanager.googleapis.com/projects/ PROJECT_ID 
contains member from unexpected domain: user:me@example.com",
    "metadata": {
      "ancestry_path": "organizations/ ORG_ID 
/projects/ PROJECT_ID 
",
      "constraint": {
        "annotations": {
          "description": "Checks that members that have been granted IAM roles belong to allowlisted domains.",
          "validation.gcp.forsetisecurity.org/originalName": "service_accounts_only",
          "validation.gcp.forsetisecurity.org/yamlpath": "policies/constraints/iam_service_accounts_only.yaml"
        },
        "labels": {},
        "parameters": {
          "domains": [
            "gserviceaccount.com"
          ]
        }
      },
      "details": {
        "member": "user:me@example.com",
        "resource": "//cloudresourcemanager.googleapis.com/projects/ PROJECT_ID 
"
      }
    },
    "resource": "//cloudresourcemanager.googleapis.com/projects/ PROJECT_ID 
",
    "severity": "high"
  }
]

CI/CD example

A bash script for using gcloud beta terraform vet in a CI/CD pipeline might look like this:

terraform  
plan  
-out = 
tfplan.tfplan
terraform  
show  
-json  
./tfplan.tfplan  
>  
./tfplan.json
git  
clone  
 POLICY_LIBRARY_REPO 
  
 POLICY_LIBRARY_DIR 
 VIOLATIONS 
 = 
 $( 
gcloud  
beta  
terraform  
vet  
tfplan.json  
--policy-library = 
 POLICY_LIBRARY_DIR 
  
--format = 
json ) 
 retVal 
 = 
 $? 
 if 
  
 [ 
  
 $retVal 
  
-eq  
 2 
  
 ] 
 ; 
  
 then 
  
 # Optional: parse the VIOLATIONS variable as json and check the severity level 
  
 echo 
  
 " 
 $VIOLATIONS 
 " 
  
 echo 
  
 "Violations found; not proceeding with terraform apply" 
  
 exit 
  
 1 
 fi 
 if 
  
 [ 
  
 $retVal 
  
-ne  
 0 
 ] 
 ; 
  
 then 
  
 echo 
  
 "Error during gcloud beta terraform vet; not proceeding with terraform apply" 
  
 exit 
  
 1 
 fi 
 echo 
  
 "No policy violations detected; proceeding with terraform apply" 
terraform  
apply

Developers can also use gcloud beta terraform vet locally to test Terraform changes prior to running your CI/CD pipeline.

Validate policies

Before you begin

Install Google Cloud CLI

Get required permissions

Set up a policy library

Validate policies

1. Generate a Terraform plan

2. Run gcloud beta terraform vet

Flags

Exit code and output

CI/CD example

Install `Google Cloud CLI`

2. Run `gcloud beta terraform vet`