Deploy on Google Cloud

Use Terraform to prepare Cloud SQL for PostgreSQL, Google Cloud Storage, and a workload identity for PIG on your existing GKE cluster. Then bootstrap PIG with Helm. Terraform continues to own cloud infrastructure; PIG maintains its application releases.

Before you begin

Complete deployment planning, including your Promptless registration, Instruction Hub, and model access.
Have Terraform, Git, the gcloud CLI, Helm, and kubectl available. Use the tool versions required by the selected infrastructure release.
Prepare an existing project and VPC with private services access for Cloud SQL. Enable Workload Identity Federation for GKE and the required SQL, Storage, and IAM APIs. Use node pools that support the workload identity configuration.
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.

This guide reuses your cluster and network. It does not create a new cluster or install an ingress controller. Use your existing secret-delivery and certificate-management systems.

1. Get the versioned Terraform example

Choose a release from PIG deployment releases, then check out that exact tag:

PIG_INFRA_RELEASE='vREPLACE_WITH_RELEASE'
git clone --branch "$PIG_INFRA_RELEASE" --depth 1 \
  https://github.com/Promptless/pig-deploy.git
cd pig-deploy/examples/gcp

The example pins the cloud module to the same release and declares its Terraform and provider requirements. Preserve the module pin and commit the provider lock file generated by terraform init to your infrastructure repository. Infrastructure module versions and PIG application versions are independent.

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 the project and region, GKE cluster and workload identity pool, existing VPC ID and private services access configuration. Use namespace pig, ServiceAccount pig-analyzer, database pig, and a dedicated trace prefix such as acme/traces.

Review database sizing, availability, backup retention, storage recovery, and deletion protection explicitly. Use private database access and private trace storage. Supply database credentials through your approved secrets workflow; keep secret values out of committed .tfvars files.
Initialize and review the plan. Configure an encrypted remote state backend with access control and locking using your platform’s Terraform workflow before applying.
Terminal window
```
terraform init
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 > deployment-configuration.json
```
Keep this output for the Helm configuration. It contains database connection metadata, the native storage block, ServiceAccount annotations, and any required pod labels. It contains no credential values. Deliver the database DSN through your secret manager and install the provider’s CA bundle separately.

3. Connect the infrastructure to PIG

Use the module’s deployment_configuration output as the source of truth. It maps into the common installation as follows:

Output	Destination
`postgres` connection metadata	The DSN in `pig-credentials/postgres-dsn`, with provider-appropriate TLS verification.
`storage`	The single native object-storage block under `PIGDeployment.spec.storage`.
`service_account_annotations`	Annotations on ServiceAccount `pig/pig-analyzer`.
`pod_labels`	`PIGDeployment.spec.podLabels`.

For Google Cloud, the ServiceAccount annotation is iam.gke.io/gcp-service-account. Its value resembles pig-analyzer@REPLACE_PROJECT_ID.iam.gserviceaccount.com. Use the output’s actual identity; do not copy the illustrative value.

The module binds the Kubernetes ServiceAccount to a Google service account with trace-bucket data access. Database authentication uses the PostgreSQL credential; it does not assume automatic IAM database-token refresh. This recipe uses private Cloud SQL connectivity, without requiring a database proxy in the analyzer pod.

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

gcs:
  bucket: REPLACE_TRACE_BUCKET
  prefix: acme/traces

The model is a separate choice. Select a supported endpoint from model providers; the storage backend does not select or provision it.

4. Bootstrap and verify

Continue with Install with Helm. Apply the ServiceAccount annotations, pod labels, native storage block, and database Secret from this guide before creating the PIGDeployment.

Keep the Helm bootstrap outside Terraform reconciliation. Do not add a helm_release resource for the self-updating supervisor or import its generated workloads into Terraform.

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. Review infrastructure module upgrades as separate plans; PIG’s stable application channel does not upgrade your Terraform modules.

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.

For cloud-specific identity setup, see Workload Identity Federation for GKE.