docs(gcp): tested GKE install guide for agent-relay-2026.11.1

Merged
KH
9d ago
+1677-0

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.md15 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.mdexact 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.mdWorkload 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.mdwhat 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 install 18s; migrations 96s; post 18s; restart + indexer bootstrap ~10 min; ManagedCertificate Active ~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.sh is idempotent against the Terraform grants ✔. managed-values-byo.sh output is identical to Terraform chart_values ✔. settings.sh resolves 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)

  1. GCP /turns (canonical reads) 501 on 2026.11.1. The services image stamps session_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.
  2. The release image overlay and install pack exist only for the eks profile (used on GKE here; the images are cloud-neutral).
  3. agent-relay-upgrade.sh --first-install is EKS-only.
  4. values-gcp.yaml at the tag pins 2026.11.0 images; only the overlay brings 2026.11.1.
  5. The OpenSearch backend is SigV4-only, so the gcp/search module can't serve native search; the guide uses the Postgres backend.
  6. cloud-sql-setup.sh defects, 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
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.md lists 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.sh fixes from #276; this PR depends on #276 for the repository copy.
  • Step 1 fetches the guide files from origin/main since 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.dec before retrying, or empty Secrets get installed.