The Terraform Forseti module can be used to quickly install and configure Forseti in a fresh cloud project.

This module is meant for use with Terraform 0.12. If you haven't upgraded and need a Terraform 0.11.x-compatible version of this module, the last released version intended for Terraform 0.11.x is 2.3.0.

Example setups are included in the examples, but you can can also get started using a Cloud Shell Tutorial.

Simple usage of the module within your own main.tf file is as follows:

    module "forseti" {
      source  = "terraform-google-modules/forseti/google"
      version = "~> 3.0"

      gsuite_admin_email = "[email protected]"
      domain             = "yourdomain.com"
      project_id         = "my-forseti-project"
      org_id             = "2313934234"
    }

The default VM size and Cloud SQL size have been increased to n1-standard-8 and db-n1-standard-4 to account for larger GCP environments.

To size the instances up or down, update the following variables in your main.tf file:

server_type = {VM SIZE}

cloudsql_type = {CLOUD SQL SIZE}

Please refer to the VM sizing guide and the Cloud SQL sizing guide to find what works best for your environment.

• Terraform 0.12
• Terraform Provider for GCP plugin v2.11
• terraform-provider-template plugin >= v2.0
• Python 3.7.x
• terraform-docs (optional) 0.6.0

In order to execute this module you must have a Service Account with the following roles assigned. There is a helpful setup script documented below which can automatically create this account for you.

For this module to work, you need the following roles enabled on the Service Account.

On the organization:

• roles/resourcemanager.organizationAdmin
• roles/securityReviewer

On the project:

• roles/owner
• roles/compute.instanceAdmin
• roles/compute.networkViewer
• roles/compute.securityAdmin
• roles/iam.serviceAccountAdmin
• roles/serviceusage.serviceUsageAdmin
• roles/iam.serviceAccountUser
• roles/storage.admin
• roles/cloudsql.admin

On the host project (when using shared VPC)

• roles/compute.securityAdmin
• roles/compute.networkAdmin

To use the IAM exploration functionality of Forseti, you will need a Super Admin on the Google Admin console. This admin's email must be passed in the gsuite_admin_email variable.

For this module to work, you need the following APIs enabled on the Forseti project.

• compute.googleapis.com
• serviceusage.googleapis.com
• cloudresourcemanager.googleapis.com

You can create the service account manually, or by running the following command:

./helpers/setup.sh -p PROJECT_ID -o ORG_ID

This will create a service account called cloud-foundation-forseti-<suffix>, give it the proper roles, and download service account credentials to ${PWD}/credentials.json. Note, that using this script assumes that you are currently authenticated as a user that can create/authorize service accounts at both the organization and project levels.

This script will also activate necessary APIs required for terraform to run.

If you are using the real time policy enforcer, you will need to generate a service account with a few extra roles. This can be enabled with the -e flag:

./helpers/setup.sh -p PROJECT_ID -o ORG_ID -e

Utilizing a shared VPC via a host project is supported with the -f flag:

./helpers/setup.sh -p PROJECT_ID -f HOST_PROJECT_ID -o ORG_ID

Be sure you have the correct Terraform version (0.12), you can choose the binary here:

• https://releases.hashicorp.com/terraform/

Additionally, you will need to export TF_WARN_OUTPUT_ERRORS=1 to work around a known issue with Terraform when running terraform destroy.

The following steps need to be performed manually/outside of this module.

To enable GSuite groups and users scanning, you must activate Domain Wide Delegation on the Service Account used for Forseti server VM: forseti-server-gcp-<number>@<project_id>.iam.gserviceaccount.com.

Please refer to the Forseti documentation for step by step directions.

To send Forseti notifications to the Cloud Security Command Center, you need to enable the Forseti add-on in the CSCC.

After activating the add-on, copy the integration's source_id and paste it into the cscc_source_id field in your Terraform configuration.

Run terraform apply again to complete the configuration.

Remember to cleanup the service account used to install Forseti either manually, or by running the command:

./scripts/cleanup.sh -p PROJECT_ID -o ORG_ID -s cloud-foundation-forseti-<suffix>

This will deprovision and delete the service account, and then delete the credentials file.

If the service account was provisioned with the roles needed for the real time policy enforcer, you can set the -e flag to clean up those roles as well:

./scripts/cleanup.sh -p PROJECT_ID -o ORG_ID -S cloud-foundation-forseti-<suffix> -e

Run

make generate_docs

• (test/README.md): Overview on howto run the test suite
• (test/integration/gcp/README.md): Detailed information about the base test suite
• (examples/simple/README.md): Overview of basic usage of the module

The project has the following folders and files:

• (/): root folder
• (/examples): examples for using this module
• (/main.tf): main file for this module, contains all the resources to create
• (/variables.tf): all the variables for the module
• (/test): all integration tests are located here
• (/README.md): this file