docs(gcp): tested GKE install guide for agent-relay-2026.11.1
What
docs/gcp-install/: a customer-neutral GKE install guide for agent-relay-2026.11.1, in the same format as the public AWS EKS guide (numbered copy-paste steps, each with a Done when check). It is meant to become a public gist once approved.
| File | |
|---|---|
0-START-HERE.md | 15 steps: files + checksums → gcloud/cluster checks → Terraform examples/gcp → Artifact Registry mirror → static IP + DNS → settings → cloud-sql-setup.sh pre → values → secrets → Helm → migrations → post → managed cert + checks → first sign-in |
1-BRING-YOUR-OWN.md | exact specs for Cloud SQL (PG17, private IP, GOOGLE_MANAGED_CAS_CA, private DNS for verify-full), GCS, Memorystore, Pub/Sub + DLQ, search, Google-managed certs; managed-values-byo.sh |
2-SERVICE-ACCOUNTS.md | Workload Identity (direct KSA principals, resource-level grants only) + optional create-workload-identity.sh |
| secrets (step 10) | kubectl, helm-secrets/SOPS (e.g. Cloud KMS), vals with Google Secret Manager (helm-secrets-prepare.sh) |
NOT-QUALIFIED.md | what 2026.11.1 does not qualify on GKE |
How it was tested
A full dry run on a private regional GKE cluster (1.35, Workload Identity, IAP-only control plane) in a new namespace with its own Cloud SQL, bucket, Memorystore, Pub/Sub and hostnames. It used the verified 2026.11.1 release assets (chart tgz, release-images.values.yaml with an Artifact Registry mirror root).
- Timings: Terraform 4m22s (27 resources); mirror ~1 min from inside GCP (30+ min from a laptop);
pre~2 min;helm install18s; migrations 96s;post18s; restart + indexer bootstrap ~10 min; ManagedCertificateActive~25 min after the Ingress. verify-agent-relay.sh --require-native-history: PASS 18/18. Public checks:api ok,cast ok,dashboard 200,history 401, http→https 301.- e2e driver (
--history-profile pipeline): bootstrap and messaging pass. Upload → GCS → Pub/Sub → indexer works, but canonical reads 501 (see below). - Secrets: kubectl ✔; SOPS path renders Secrets byte-identical to kubectl ✔; vals + Secret Manager stores and references 19 values ✔ (resolution needs ADC; pending).
create-workload-identity.shis idempotent against the Terraform grants ✔.managed-values-byo.shoutput is identical to Terraformchart_values✔.settings.shresolves every value from Terraform outputs ✔. Shellcheck clean.- Grep for customer/internal names: none.
Not qualified at the tag (top items; full list in NOT-QUALIFIED.md)
- GCP
/turns(canonical reads) 501 on 2026.11.1. The services image stampssession_index.storage_provider = 's3'for GCS objects (relayhistory-pipeline src/session-ingest/publication-image.ts). The read API on GCS rejects those pointers (turns_canonical_pointer_invalid,message_id_canonical_pointer_invalid). Routed to the Sessions owner for 2026.11.2. - The release image overlay and install pack exist only for the
eksprofile (used on GKE here; the images are cloud-neutral). agent-relay-upgrade.sh --first-installis EKS-only.values-gcp.yamlat the tag pins 2026.11.0 images; only the overlay brings 2026.11.1.- The OpenSearch backend is SigV4-only, so the
gcp/searchmodule can't serve native search; the guide uses the Postgres backend. cloud-sql-setup.shdefects, fixed in #276 (the guide bundles the fixed copy).
Depends on #276 for the repository copy of cloud-sql-setup.sh (the bundled copy in this PR is identical to #276's head).
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
Adds a customer-neutral GKE install guide for agent-relay-2026.11.1, the GCP counterpart of the AWS EKS guide, validated end to end with a dry run on a private regional GKE cluster.
- 15 numbered copy-paste steps with a Done when check each, covering Terraform
examples/gcp, Artifact Registry mirroring, database and secrets setup, Helm install, migrations, and the Google-managed certificate. - Bring-your-own specs for Cloud SQL, GCS, Memorystore, Pub/Sub, and Workload Identity grants, with helper scripts that produce output identical to the Terraform path.
- Three secret flows: plain kubectl, helm-secrets with SOPS, and vals with Google Secret Manager.
NOT-QUALIFIED.mdlists what 2026.11.1 does not qualify on GKE; the headline item is/turns(transcript reads) returning 501 on GCS, fixed in 2026.11.2.- Bundles the
cloud-sql-setup.shfixes from #276; this PR depends on #276 for the repository copy. - Step 1 fetches the guide files from
origin/mainsince the tag predates them, then checks out the tag for Terraform and release assets. - Adds a failure note for the vals path: after a failed first run, delete the stale
secrets.yaml.decbefore retrying, or empty Secrets get installed.