Onboarding: Google Cloud¶

An Engineer or Admin can configure the Google Cloud connector from the guided setup without a human handoff. Workload Identity Federation is the default and creates no exported service-account key. See Docs authority & product state.

Access boundary¶

The module creates a service account with read access to the selected project or billing dataset:

roles/bigquery.dataViewer for billing-export data.
roles/monitoring.viewer for Vertex AI and Cloud Monitoring metrics.
roles/logging.viewer for non-private metadata logs.
roles/serviceusage.serviceUsageConsumer for quota-consuming reads; it cannot enable or disable APIs.

Set billing_dataset_only = true to replace the project-wide BigQuery grant with the named dataset grant. Private Data Access logs are excluded by default. Content-bearing request and response fields are discarded and never persisted.

Steps¶

1. Generate configuration¶

Role: Engineer or Admin in Venturi; Google Cloud principal with Workload Identity Pool and service-account creation permission for the apply.

Select Google Cloud in guided setup. The tenant flow generates the exact issuer, allowed subjects, connector ID, and pinned Terraform artifact in-product.

Terraform

project_id            = "my-prod-project"
service_account_id    = "venturi-readonly"
use_workload_identity = true
wif_pool_id           = "venturi-pool"
wif_provider_id       = "venturi-provider"
wif_issuer_uri        = "<generated in guided setup>"
wif_allowed_subjects  = ["<generated exact subject>"]
billing_dataset_id    = "billing_export"
billing_dataset_only  = true

Wildcards are rejected. Keep every subject exact.

2. Deploy and prove the boundary¶

Bash

cd infra/gcp/onboarding
gcloud auth application-default login
gcloud config set project <project_id>
terraform init
terraform plan
terraform apply
./scripts/verify.sh

The local script confirms the service account has no user-managed keys, checks the role allowlist, and proves a write is denied. Connector activation performs the positive BigQuery, Logging, and Monitoring reads through federation.

3. Register outputs and validate¶

Enter the service-account email, project number, Workload Identity Pool and provider resource names, and billing dataset in the connector step. Automated credential validation checks the issuer, exact subject, federation exchange, positive reads, and write denial.

4. Inspect evidence¶

Open the readiness result and the quality feed. Review coverage, unknown ownership or billing dimensions, and source freshness.

Success evidence¶

terraform apply succeeds with no service-account key resource.
verify.sh exits 0 and the connector’s positive read probes pass.
Automated credential validation shows the exact issuer and subject accepted.
The 1st Google Cloud-backed AttributionRecord appears in the quality feed.

Recovery¶

Failure	Action
`unauthorized_client` or subject rejection	Compare the exact generated issuer and subject; remove wildcard or whitespace drift and reapply.
Billing query is empty	Confirm the export dataset, project, location, and dataset-scoped binding.
Vertex evidence is missing	Inspect Logging exclusions and confirm the expected metadata log exists.
Positive read is denied	Add only the named missing read role at the narrowest scope, then rerun validation.
Freshness becomes stale	Check the latest billing-export partition and readiness probe timestamp.

Support is an optional escalation path after the validation evidence is available.

Rotate or revoke¶

Generate a new exact federation subject in connector settings. Add it to wif_allowed_subjects, apply, validate the new subject, then remove the old subject and apply again. Do not use wildcards to bridge rotation.

To revoke access, disable the connector in-product, then run: