Forseti Terraform Module

The Forseti Terraform module is the only supported method of deploying Forseti Security. The default infrastructure for Forseti is Google Compute Engine. For more information on installing Forseti on Google Kubernetes Engine (GKE), please see the detailed guide on the Forseti Security website.

Google Cloud Shell Walkthrough

A Google Cloud Shell Walkthrough has been setup to make it easy for users who are new to Forseti and Terraform. This walkthrough provides a set of instructions to get a default installation of Forseti setup that can be used in a production environment.

If you are familiar with Terraform and would like to run Terraform from a different machine, you can skip this walkthrough and move onto the How to Deploy section.

How to Deploy

Install Terraform

Terraform version 0.12 is required for this module, which can be downloaded from the Terraform website. Terraform version 0.12.20 or greater is recommended.

Google Credentials

In order to run this module you will need to be authenticated as a user that has access to the project and can create/authorize service accounts at both the organization and project levels. To login to GCP from a shell, run:

gcloud auth login

Create a new Project

Create a new GCP project to deploy Forseti into. The Google Project Factory Terraform module can be used to provision the project with the required APIs enabled, along with a Shared VPC connection.

Create the Service Account and Enable Required APIs

The Service Account and required APIs can be setup automatically with a provided script. To perform these steps manually, review the Requirements section.

These commands will download and run the helper script. The script will create a service account called cloud-foundation-forseti-<suffix>, and assign it the proper roles. The service account credentials will be downloaded to ${PWD}/credentials.json.

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -p PROJECT_ID -o ORG_ID

Usage for a Shared VPC

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

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -f HOST_PROJECT_ID -p PROJECT_ID -o ORG_ID

Usage for GKE

Deploying Forseti on GKE is supported with the -k flag:

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -k -p PROJECT_ID -o ORG_ID

Usage for Real-time Enforcer

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:

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -e -p PROJECT_ID -o ORG_ID

Terraform Configuration

Example configurations are included in the examples directory. You can copy these examples or use the snippet below as a starting point to your own custom configuration.

The default Forseti Server VM machine type and Cloud SQL machine type have been set to n1-standard-8 and db-n1-standard-4 to account for larger GCP environments. These can be changed by providing the server_type and cloudsql_type variables.

Create a file named main.tf in an empty directory and copy the contents below into the file.

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

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

Forseti provides many optional settings for users to customize for their environment and security requirements. View the list of inputs to see all of the available options.

Run Terraform

Forseti is ready to be installed! First you will need to initialize Terraform to download the module dependencies.

terraform init

The configuration can now be applied which will determine the necessary actions to perform on the GCP project.

terraform apply

Review the Terraform plan and enter yes to perform these actions.

Cleanup

Remember to cleanup the service account used to deploy Forseti. A provided helper script will delete the service account, and delete the credentials files.

curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/cleanup.sh |
bash -s -- -p PROJECT_ID -o ORG_ID -s cloud-foundation-forseti-<suffix>

Usage for Real-Time Enforcer

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:

curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/cleanup.sh |
bash -s -- -e -p PROJECT_ID -o ORG_ID -s cloud-foundation-forseti-<suffix>

Forseti Configuration

Now that Forseti has been deployed, there are additional steps that you can follow to further configure Forseti. Some of the commonly used features are listed below:

• Enable G Suite Scanning
• Enable Cloud Security Command Center Notifications
  • After activating this integration, add the Source ID into the Terraform configuration using the cscc_source_id input and re-run the Terraform apply command.

Requirements

This section describes in detail the requirements necessary to deploy Forseti. The setup helper script automates the service account creation and enabling the APIs for you. Read through this section if you are not using the setup script.

Service Account

In order to execute this module you must have a Service Account with the following IAM roles assigned.

Organization Roles

• roles/iam.securityReviewer
• roles/resourcemanager.organizationAdmin

Project Roles

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

Host Project Roles (when using shared VPC)

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

Required APIs

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

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

Inputs

Outputs

File structure

The project has the following folders and files:

• build/: Google Cloud Build configuration
• docs/: Additional documentation
• examples/: examples for using this module
• helpers/: Helper scripts
• modules/: Private and sub-modules
• test/: All integration tests are located here
• CHANGELOG.md: A list of changes made for each release
• CONTRIBUTING.md: Information on how to contribute to this project
• LICENSE: License terms and conditions
• main.tf: Main Terraform configuration file for this module, contains all the resources to install Forseti
• README.md: This readme file
• variables.tf: All the variables for the module