Skip to main content
The GCP Cloud Account connects a Google Cloud project to Formal using Workload Identity Federation. Formal presents its AWS identity, which your project trusts through a workload identity pool, then impersonates a dedicated service account. No service account keys are created; access is entirely federated.

What Formal Discovers

Discover Cloud SQL for PostgreSQL and MySQL instances and add them as Formal resources.
Discover GKE clusters for Kubernetes access control. Clusters need a public endpoint to be discovered.
Discover Compute Engine instances for SSH access.
Forward Formal Connector logs to GCS buckets for long-term storage and compliance.
Autodiscovery for all three resource types is on by default. See Resource Autodiscovery for how discovered resources behave.

Architecture

The terraform-formal-gcp module enables the required APIs (IAM, STS, IAM Credentials, Cloud Resource Manager) and creates:
  1. Workload Identity Pool: a pool with an AWS-type provider that trusts Formal’s AWS account
  2. Attribute Condition: pins Formal’s per-integration role ARN, so only that exact role can exchange a token
  3. Service Account: the identity Formal impersonates in your project
  4. IAM Bindings: grant the service account only the roles for the capabilities you enable, such as compute.viewer, container.viewer, and cloudsql.viewer for discovery, and storage.objectCreator for log delivery
Formal derives the exact roles from the capabilities you enable and returns them for the module to grant.

Setup

1

Navigate to Cloud Accounts

2

Add Integration

Click Add Integration and choose GCP
3

Enter Details

Enter a name and the Google Cloud project ID to connect
4

Choose Discovery

Toggle autodiscovery for Compute Engine, GKE, and Cloud SQL. All are on by default.
5

Configure GCS Access

To deliver logs to Cloud Storage, enable GCS log writes. Leave the bucket list empty to allow every bucket in the project, or name specific buckets to scope access.
6

Run the Setup Command

Formal shows a command with your integration ID and security key filled in. Paste it into an authenticated Cloud Shell for that project:
It fetches the setup parameters from Formal, runs terraform apply, then reports the service account and workload identity pool provider back to Formal, which activates the integration.

Cloud Storage Log Delivery

To forward logs to GCS, the integration needs Cloud Storage access. Enable it when creating the integration with two settings: Formal grants matching IAM: a project-level roles/storage.objectCreator when the bucket list is empty, or per-bucket IAM bindings when you restrict it. Once access is granted, create a Log Integration pointing at a bucket to start forwarding logs.

Security

  • Federated, keyless: no service account keys are created or stored.
  • Pinned role: the pool’s attribute condition trusts only Formal’s exact per-integration role ARN.
  • Least privilege: the service account gets only the roles for the capabilities you enable; disabling every capability connects the project with no access.
  • Bucket scoping: restrict gcs_buckets so Formal can write only to the buckets you name.

Troubleshooting

Possible causes:
  • The Cloud Shell is not authenticated to the target project
  • The account lacks permission to enable APIs or create IAM resources
  • The integration ID or security key is wrong
Solution:
  1. Run gcloud config set project <PROJECT_ID> in the Cloud Shell
  2. Ensure the account has roles/owner or an equivalent set of IAM and Service Usage roles
  3. Copy the exact command Formal shows when you create the integration
Possible causes:
  • Autodiscovery disabled for that resource type
  • GKE cluster has no public endpoint
  • Cloud SQL instance is neither PostgreSQL nor MySQL
  • Service account missing the viewer role
Solution:
  1. Verify the discovery toggle is enabled on the Cloud Account
  2. Confirm the cluster exposes a public endpoint
  3. Re-run the setup command so the module grants the viewer roles
  4. Wait a few minutes for the initial scan
Possible causes:
  • Cloud Storage access not enabled on the integration
  • The target bucket is not in the gcs_buckets allowlist
  • Log integration not configured
Solution:
  1. Confirm allow_gcs_access is enabled on the Cloud Account
  2. Add the bucket to gcs_buckets, or leave the list empty to allow all buckets
  3. Create a Log Integration pointing to this cloud integration

Next Steps

Log Integration

Forward logs to Cloud Storage

Add Resources

Manually configure discovered resources

Terraform

Manage integrations as code

View Resources

See all autodiscovered resources