This is a beta release. This product might be changed in backward-incompatible ways and is not subject to any SLA or deprecation policy.

Deploy Forseti Security on Google Kubernetes Engine

This guide explains how to setup Forseti on Kubernetes. Most installation scenarios require the use of Terraform and the terraform-google-forseti module. The Forseti containers are deployed on-GKE using Helm charts. When using Terraform to deploy Forseti on-GKE, this is transparent to the user.

Install Pre-Requisites

The following tools are required:

Terraform - 0.12.x
gsutil

Deploying with Terraform

The on_gke** examples are found in the examples/ folder of the *terraform-google-forseti Terraform module. Each “on-GKE” specific example is prepended with “on_gke_”. Please understand that each of these examples are just that, examples. Each example has a main.tf file that describes how the environment will be built addressing common scenarios. Please review the examples to determine if the examples are sufficient for the environment where Forseti is deployed.

Wherever possible, the examples utilize modules developed and curated by the Cloud Foundation Toolkit team. These modules implement opinionated best practices for deploying GCP components. For example, the kubernetes-engine module applies practices found in the GKE hardening.

Re-using an Existing Forseti Deployment

If you wish to reuse an existing Forseti deployment (e.g. you deployed Forseti on GCE with either Deployment Manager or Terraform), please follow the terraform-google-forseti upgrade guide.

Service Account

Terraform uses an IAM Service Account to deploy and configure resources on behalf of the user. The Service Account and required APIs can be setup automatically with a provided script on the Forseti Terraform Github repository. Alternatively, if you are an Org Admin, you can use your own credentials to install Forseti.

git clone --branch modulerelease502 --depth 1 https://github.com/forseti-security/terraform-google-forseti.git

cd terraform-google-forseti

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

This will create a service account called cloud-foundation-forseti-<suffix>, and download the service account credentials to ${PWD}/credentials.json. Grant the following roles to the newly created service account:

roles/container.admin
roles/container.clusterAdmin
roles/container.developer
roles/iam.serviceAccountKey.Admin
roles/resourcemanager.projectIamAdmin
roles/compute.networkAdmin

Ensure the following APIs are enabled on the Forseti project:

container.googleapis.com
compute.googleapis.com

Deploy Forseti on-GKE

Create a file named main.tf in an empty directory and add the following content per one of the two scenarios below. Add the appropiate values for each of the input variables (e.g. domain, gsuite_admin_email).

New GKE Cluster

module "forseti-on-gke" {
    source                  = "terraform-google-modules/forseti/google//examples/on_gke_end_to_end"
    domain                  = ""
    gsuite_admin_email      = ""
    org_id                  = ""
    project_id              = ""
    region                  = ""
}

Existing GKE Cluster

module "forseti-on-gke" {
    source                  = "terraform-google-modules/forseti/google//examples/on_gke"
    domain                  = ""
    gsuite_admin_email      = ""
    org_id                  = ""
    project_id              = ""
    region                  = ""

    gke_cluster_name        = ""
    gke_cluster_location    = ""
}

Next Steps

Initialize the Terraform module.

terraform init

Apply the Terraform module.

terraform apply

Deploying with Helm

Deploy Forseti in an Existing GKE Cluster (Helm)

Forseti can be deployed on-GKE without the use of Terraform if the following preconditions are met.

Forseti has been deployed in a GCP project.
A GKE cluster has already been deployed in GCP under the same organization as Forseti.
The GKE credentials exist on the machine executing the deployement
The Helm binary is installed and initiallized on the machine executing the deployment.

After these preconditions are met, add the forseti-security-charts Helm repo to your Helm environment.

helm repo add forseti-security https://forseti-security-charts.storage.googleapis.com/release

Follow the chart installation instructions to install Forseti on-GKE.

Post Deployment Configuration Changes

Note: If any changes are made to the forseti_server_conf.yaml file in GCS, one of the following steps is necessary. In a future version of this feature, this will be automated.

With Terraform

terraform apply

With Helm

helm upgrade -i forseti forseti-security/forseti-security \
    --set production=true \
    --recreate-pods \
    --set-string serverConfigContents="$(gsutil cat gs://<BUCKET_NAME>/configs/forseti_conf_server.yaml | base64 -)" \
    --values=forseti-values.yaml

Deploying with config-validator on-GKE

The config-validator in Forseti on-GKE obtains policies from a policy-library in a Git repository via SSH. The pre-requisites for this are as follows.

A policy-library in a Git repository.
A generated SSH key with the private key local to the host running Terraform or Helm, and the public key uploaded to the service hosting the policy-library Git repository.

With Terraform

In any of the Terraform examples above, the following additional variables are required:

module "forseti-on-gke-with-config-validator" {
    # Other parameters/variables removed for brevity

    # Enable config-validator
    config_validator_enabled = true
    
    # Path to the private SSH key file
    git_sync_private_ssh_key_file = ""

    # SSH Git repository location, usually in the following
    # format: git@repo-host:repo-owner/repo-name.git
    policy_library_repository_url = ""
}

With Helm

In the Helm example above, the following variables are required in the user defined values.yaml file.

# configValidator sets whether or not to deploy config-validator
configValidator: true

# gitSyncPrivateSSHKey is the private OpenSSH key generated to allow the git-sync to clone the policy library repository.
gitSyncPrivateSSHKey: ""

# gitSyncSSH use SSH for git-sync operations
gitSyncSSH: true

# policyLibraryRepositoryURL is a git repository policy-library.
policyLibraryRepositoryURL: ""

Accessing Forseti from the Client VM

Forseti on-GKE is configured to accept connections from the CIDR on which the Client VM is deployed. You can access the Forseti deployment, for example to run forseti inventory create by doing the following:

SSH to the Client VM.
Change user to the ubuntu user.
Execute the desired command.