docs(gcp-install): close the guide gaps from a clean-project install (#492)

Merged
MI
3d ago
+370-32

Fixes #492

Six gaps found by following docs/gcp-install on a clean project. None is a regression. Docs, one guide script and the Terraform example only: no chart is touched, and the release the guide pins is unchanged.

What changed, per item

  1. Ingress address delay (0-START-HERE.md step 14). The step now says the Ingress can take 15 to 20 minutes to get its address, gives the commands to look (kubectl get ingress, kubectl describe ingress events), names the Translation failed ... no BackendConfig for service port exists warning as harmless when it does not repeat, and says when to worry (address still empty or warning still repeating after about 20 minutes). 1-BRING-YOUR-OWN.md has no Ingress check of its own (it points at step 6 and 14), so it is unchanged.
  2. Chart from a checkout (step 1). New short note: helm dependency build for charts/sessions-pipeline before charts/agent-relay, and why (without it the read API and workers are not rendered).
  3. managed-values.json can crash-loop relay-control (step 4, terraform/examples/gcp). Two parts:
    • Guide. The guide told readers to uncomment desktop_feed_bucket_name from 2026.11.9 and said the signing key comes later, which is exactly the storage-without-signer state relay-control refuses. It now says to uncomment the bucket only once the signing key is in place, quotes the exit message, and gives the recovery for an install that already applied with the bucket (jq 'del(.["relay-control"].extraEnv)' on managed-values.json). This part is needed on its own because the guide's Terraform comes from the pinned release tag, which cannot have a new input.
    • Terraform. New input desktop_feed_has_signing_keys (bool, default true). With false, chart_values["relay-control"] has no extraEnv and desktop_feed.env is empty; the bucket, the service account and the annotations are unchanged. Terraform cannot see the signer (it is relay-control.desktopFeed.signingKeys in the site values), so a plan-time check is not possible; an explicit input is the smallest thing that lets the output omit the env. The default is true so that an existing install with a signer renders exactly the same: defaulting to false would drop the storage env from such an install on its next terraform output and break it the other way round (signer without storage). The existing test now asserts the three entries by value, and a new run covers false.
  4. Release pins (step 7). The pins are not changed. The step now says that SERVICES_IMAGE, PSQL_IMAGE and agent-relay-0.7.54.tgz belong to agent-relay-2026.11.16 (chart 0.7.54), and shows how to read the three values for another release from its assets (release-manifest.json, the .tgz name), and for a checkout from releases/<tag>/pins.json and the sessions-pipeline chart values. The repo has no check that compares the guide's pins with release metadata (the release workflows only carry a manual checklist line for docs/gcp-install/), so there was nothing to keep passing.
  5. first-admin.sh (and step 15). Optional API_HOST (default api.<app hostname>, so current callers are unaffected), validated with the same rule as the app hostname; the Origin header stays the app hostname. Optional PASSWORD_FILE: the password goes to a new local file (mode 0600, created with noclobber, refused if it exists) instead of Secret Manager, and gcloud is then not required. The Secret Manager requirement of the default mode is now stated. The password and setup key are still never printed or put on a command line. New offline test scripts/selfhost/tests/gcp-first-admin-test.sh, run from run-tests.sh (which also syntax-checks and shellchecks the script now).
  6. Edge-deny backend (step 14). One bullet: paths routed to the ...-cast-edge-deny Service (/internal and other closed paths) answer 502 from the load balancer when no Cloud Armor policy is attached, by design, so it is not read as an outage.

Overlap with #487 and #493

Both authors confirmed no conflicting passages. This PR stays out of 3-EDGE-HARDENING.md, edge.tf, the edge output and modules/gcp/edge-security. In the shared files the hunks are apart: the new variable sits next to the other desktop_feed_* inputs (theirs are appended at the end), and its name sorts before desktop_feed_service_account_id so the generated README row does not land on the lines #487 adds. Whichever merges second should re-run terraform-docs for terraform/examples/gcp instead of hand-merging the table.

Verification (local)

$ shellcheck -x -S warning docs/gcp-install/first-admin.sh scripts/selfhost/tests/gcp-first-admin-test.sh
(no output, exit 0)

$ bash scripts/selfhost/tests/gcp-first-admin-test.sh      # also with TEST_BASH=/bin/bash (3.2)
ok - gcp-first-admin: default host and Secret Manager are unchanged
ok - gcp-first-admin: API_HOST replaces the API host only
ok - gcp-first-admin: host names are validated before any command
ok - gcp-first-admin: PASSWORD_FILE keeps the password in a 0600 file without gcloud
ok - gcp-first-admin: gcloud is required only for Secret Manager
ok - gcp-first-admin: an existing password stops the run
ok - gcp-first-admin: a refused sign-in reports the host and the stored password's place
All gcp-first-admin tests passed.

# terraform 1.16.7 and terraform-docs v0.24.0 (the versions terraform.yml pins), in terraform/examples/gcp
$ terraform fmt -check -recursive .            -> exit 0
$ terraform init -backend=false && terraform validate
Success! The configuration is valid.
$ terraform test
  run "desktop_feed_is_off_by_default"... pass
  run "desktop_feed_bucket_and_identity"... pass
  run "desktop_feed_without_signing_keys_has_no_storage_env"... pass
  ...
Success! 12 passed, 0 failed.
$ terraform-docs --config ../../.terraform-docs.yml --output-check .
README.md is up to date

The commands the guide now shows were run against repository data or a stand-in file: the pins.json and grep lines print the two digests the guide pins today, and the release-manifest.json filter and the jq del(...) line were run on sample JSON of the same shape.

Not fully run locally: scripts/selfhost/tests/run-tests.sh (the static job's "Self-hosted operator script tests"). On macOS it stops in agent-relay-upgrade-test.sh at an interrupted (INT) census plan succeeded, before it reaches the new test; unmodified main fails at the same line on the same machine, so this is a local platform difference and the Linux CI run is the evidence for that step. Everything before it passed, including the runner's syntax check and shellcheck of first-admin.sh and the new test. No YAML file changed, so there was nothing for yamllint. tflint and checkov were not installed locally; CI runs them. The repo has no markdown or link check in CI. Nothing was applied to any cloud project or cluster.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.