Deploy on Google Cloud

Overview

Use this guide to evaluate PIG on an existing GKE cluster and have Terraform create its dedicated infrastructure. The example creates a Cloud SQL for PostgreSQL instance, a Cloud Storage trace bucket, and a Google service account for the analyzer’s workload identity. You then continue with the common Helm installation. If you already have these resources, go directly to that guide.

The guide reuses your cluster and network. It creates no cluster and installs no ingress controller, and it works with your existing secret-delivery and certificate-management systems. After installation, Terraform keeps ownership of the cloud infrastructure, and PIG maintains its own application releases.

Before you begin

Complete deployment planning, including your Promptless registration, Instruction Hub, and model access.
Have Terraform 1.11 or later, the gcloud CLI, Helm, and kubectl. The 0.3.6 example requires Terraform >= 1.11.0, < 2.0.0.
Prepare an existing project with the Cloud SQL, IAM, and Cloud Storage APIs enabled. Its VPC needs private services access with an allocated IP range for Cloud SQL.
Enable Workload Identity Federation for GKE on the cluster. On GKE Standard, enable the GKE metadata server on the node pool that runs the analyzer.
Have permission to provision the dedicated database, trace storage, and workload identity in that network.
Choose database capacity, availability, backup retention, trace retention, and encryption settings for your recovery requirements.

To hand the infrastructure work to a coding agent, copy this prompt. Set up PIG with a coding agent covers the whole setup.

Prepare Google Cloud infrastructure for the PIG trace analyzer on our existing
GKE cluster with the versioned Terraform example. Follow
https://promptless.ai/docs/governance/deploy-the-worker/deploy-on-gcp.md
and phase 5 of https://promptless.ai/docs/governance/agent-setup-guide.md

Outcome: an applied Terraform plan and the saved deployment_configuration
output.
Google Cloud support is experimental; confirm with me before you continue.
Inputs (discover these before you ask me):
- Project and region: [for example, acme-prod, us-central1]
- GKE cluster: [cluster name and kubectl context]
- VPC network: [name, or "discover it"]
- PIG release: [release tag, or "latest published release"]
- Terraform state backend: [our backend, or where our Terraform lives]

Show me the plan summary and wait for my approval before `terraform apply`.
Report the resources created and the next step.

1. Get the versioned Terraform example

Download and verify the release files as described in Select and verify a release. In the same shell, from that release directory, extract the Terraform example from the verified archive:

cd "$PIG_RELEASE_DIR"
tar -xzf "pig-deploy-${PIG_VERSION}.tar.gz"
cd "pig-deploy-${PIG_VERSION}/examples/gcp"

The example references the Google Cloud module in the same archive, so the module matches the release. The example also includes its provider lock file. Keep -lockfile=readonly in the commands below so Terraform uses those reviewed provider checksums.

2. Configure and apply infrastructure

Confirm your account and cluster.

gcloud config list project
kubectl config current-context

Copy the example inputs.
Terminal window
```
cp terraform.tfvars.example terraform.tfvars
```
Set project_id, region, the cluster’s workload_identity_pool, the existing network_id and its private services access allocated_ip_range, and a globally unique trace_bucket_name. Keep namespace = "pig" and service_account_name = "pig-analyzer", which the module binds to the Google service account, and set a dedicated trace_prefix such as acme/traces.

The defaults create regional high-availability PostgreSQL 16 on db-custom-2-7680, with 2 vCPUs and 7.5 GiB of memory. Storage is 100 GiB of SSD, with 14 daily backups and 7 days of point-in-time recovery. The trace bucket uses versioning and 90 days of soft delete.

Review these defaults and deletion protection in variables.tf against your workload and recovery requirements. Keep private database access and private trace storage. Supply the database password as TF_VAR_postgres_password from your secret manager, and keep real .tfvars files out of Git. Terraform stores the password in its encrypted remote state.
Initialize and review the plan. Copy backend.tfbackend.example to backend.tfbackend and set your existing encrypted, private state backend with locking. Limit its access to infrastructure operators.
Terminal window
```
cp backend.tfbackend.example backend.tfbackend
terraform init -backend-config=backend.tfbackend -lockfile=readonly
terraform validate
terraform plan -out=pig.tfplan
```
Review the dedicated database, storage, identity, and network bindings. Stop if the plan replaces your cluster, expands shared permissions, or destroys retained storage unexpectedly. Terraform state and saved plans can contain credentials; store them as secrets even when an output is marked sensitive.
Apply the reviewed plan.
Terminal window
```
terraform apply pig.tfplan
terraform output -json deployment_configuration > "$PIG_RELEASE_DIR/deployment-configuration.json"
```
The output file sits next to the verified release files. It contains database connection metadata, the Cloud Storage block, the ServiceAccount annotation, and pod labels. It contains no credential values.

3. Connect the infrastructure to PIG

The deployment-configuration.json file in $PIG_RELEASE_DIR is the source of truth for the Kubernetes configuration in Install with Helm. Each output goes to one destination:

Output	Destination
`postgres` connection metadata	The application connection string in `pig-credentials/postgres-dsn`.
`storage`	The `gcs` block under `PIGDeployment.spec.storage`.
`service_account_annotations`	Annotations on ServiceAccount `pig/pig-analyzer`.
`pod_labels`	`PIGDeployment.spec.podLabels`. It is empty on Google Cloud.

For Google Cloud, the ServiceAccount annotation is iam.gke.io/gcp-service-account. Its value resembles pig-analyzer@REPLACE_PROJECT_ID.iam.gserviceaccount.com. Copy the identity from your output, not this illustrative value.

The module binds the Kubernetes ServiceAccount to a Google service account with object access limited to the trace prefix. The analyzer authenticates to Cloud SQL with the database password in its connection string. It connects over the instance’s private IP, so the analyzer pod needs no database proxy.

Build the connection string in your secret manager from the postgres output and the database password. Include both host, the name on the server certificate, and hostaddr, the private IP address, with sslmode=verify-full:

postgresql://USERNAME:URL_ENCODED_PASSWORD@HOST:5432/pig?hostaddr=HOSTADDR&sslmode=verify-full

Deliver the regional Cloud SQL CA bundle for your instance as ConfigMap pig-postgres-ca with key ca.pem.

On GKE Standard, add this node selector under spec in the PIGDeployment, so the analyzer and its maintenance Jobs run on nodes with the GKE metadata server. Omit it on GKE Autopilot, which rejects it.

nodeSelector:
  iam.gke.io/gke-metadata-server-enabled: "true"

Replace the S3 block in the common Helm example with this block, using the provisioned location:

gcs:
  bucket: REPLACE_TRACE_BUCKET
  prefix: acme/traces

Choose the model separately. Select a supported endpoint from model providers. The Terraform module grants no model access.

4. Bootstrap and verify

In $PIG_RELEASE_DIR, where the verified chart and deployment-configuration.json are, continue with Install with Helm from step 2. Apply the ServiceAccount annotation, Secrets, CA ConfigMap, Cloud Storage block, and any node selector from this guide before you create the PIGDeployment. For the collector Ingress, use the Ingress with a TLS Secret values with your cluster’s ingress controller and certificate.

Keep the Helm bootstrap outside Terraform reconciliation. Terraform must not manage the self-updating supervisor through a helm_release resource or import its generated workloads.

Finish with Verify your deployment. Confirm native storage writes and reads, a successful analysis, and visible Promptless Dashboard status for one exact session.

Maintain the infrastructure

Use Terraform for database resizing, IAM changes, networking, backup policy, and object retention. PIG’s stable application channel updates only the application, so review each Terraform module upgrade as its own plan.

If PIG reports a blocked release that requires an infrastructure change, apply that change through Terraform. PIG resumes once its live checks and any required release-specific confirmations pass. Keep backups and trace retention coordinated, and follow recovery guidance before replacing storage.