Validate your IaC against your Google Cloud organization's policies

This document describes how to validate your infrastructure as code (IaC) against the organization policies and Security Health Analytics detectors that you have defined in your Google Cloud organization. IaC lets you create and manage your cloud resources using languages such as Terraform so that you can deploy the resources using a development workflow.

Validating your IaC lets you determine whether your new or modified resource definitions violate the existing policies that are applied to your Google Cloud resources (for example, cluster, bucket, or instance). You can define these policies using security postures, but the IaC validation feature analyzes your code against all the policies in your Google Cloud organization. IaC validation helps your developers identify and fix any security issues in the IaC configuration of assets or resources before they are applied to your Google Cloud environment.

The IaC validation feature supports Terraform plan files. You can validate your Terraform plan using Google Cloud CLI, or you can integrate the validation process into your Jenkins or GitHub Actions developer workflow.

Before you begin

Complete these tasks to get started with IaC validation.

Activate the Security Command Center Premium tier or Enterprise tier

Verify that the Security Command Center Premium tier or Enterprise tier is activated at the organization level.

Set up permissions

  1. Make sure that you have the following role or roles on the organization: Security Posture Shift-Left Validator

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the organization.

    3. In the Principal column, find the row that has your email address.

      If your email address isn't in that column, then you do not have any roles.

    4. In the Role column for the row with your email address, check whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the organization.
    3. Click Grant access.
    4. In the New principals field, enter your email address.
    5. In the Select a role list, select a role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

For more information about IaC validation permissions, see IAM for organization-level activations.

Set up Google Cloud CLI

You can use the gcloud CLI samples on this page from either of the following development environments:

  • Cloud Shell: To use an online terminal with the gcloud CLI already set up, activate Cloud Shell.

    At the bottom of this page, a Cloud Shell session starts and displays a command-line prompt. It can take a few seconds for the session to initialize.

  • Local shell: To use the gcloud CLI in a local development environment, install and initialize the gcloud CLI.

To set up the gcloud CLI to use service account impersonation to authenticate to Google APIs, rather than your user credentials, run the following command: 

gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

For more information, see Service account impersonation.

Enable APIs

Enable the Security posture service and Security Command Center management APIs.

Enable the APIs

Define your policies

Define your organization policies and Security Health Analytics detectors. To define these policies using a security posture, complete the tasks in Create and deploy a posture.

Create your Terraform code

Use your developer workflows and tools to create a Terraform file that includes the Google Cloud assets that you want to create or modify.

Consider the following:

  • Populate the parent attribute (the project, folder, or organization) of every resource or asset in the Terraform configuration.
  • Modify assets and policies separately. The API doesn't support validation of Terraform plan files which modify both assets and policies at the same time.
  • Use supported asset types and policies only. For a list of supported asset types and policies, see Supported asset types and policies for IaC validation.
  • Review the limitations for IaC validation.
  • Don't include sensitive information such as passwords or other personally identifiable information in your Terraform plan file. If the validation feature encounters fields marked as sensitive in the resource changes, the fields are removed.

After you create your Terraform code, you can run the IaC validation report. You can use Google Cloud CLI, Jenkins, or GitHub Actions.

Use Google Cloud CLI to create an IaC validation report

To create an IaC validation report, complete the following:

  1. In gcloud CLI, run terraform init.

    Verify that you're running Terraform provider version v5.5 or later. If required, upgrade to the latest Google provider version:

    terraform init -upgrade

  2. Convert the Terraform plan file to JSON format:

    terraform plan -out TF_PLAN_FILENAME
terraform show -json TF_PLAN_FILENAME > TF_PLAN_JSON_FILENAME.json

    Replace the following:

    • TF_PLAN_FILENAME: The name for the Terraform plan file.
    • TF_PLAN_JSON_FILENAME: The name of the file that will contain the Terraform plan in JSON format.

  3. Create the IaC validation report:

    gcloud scc iac-validation-reports create PARENT \
  --tf-plan-file=TF_PLAN_JSON_FILENAME

    Replace the following:

    • PARENT: The Google Cloud organization in which to create the IaC Validation report. The format is organizations/ORGANIZATION_ID/locations/LOCATION. LOCATION is global.
    • TF_PLAN_JSON_FILENAME: The path to the JSON file that contains the IaC plan that you want to validate.

    For example, to create an IaC validation report under the organizations/3589215982/locations/global organization with an IaC plan included in planFile.json, run the following command:

    gcloud scc iac-validation-reports create organizations/3589215982/locations/global --tf-plan-file=planFile.json

    This command returns the operation details for creating the IAC validation report. To get information about the operation, see View information about a posture deployment operation.

What's next