docs(gcp-install): close the guide gaps from a clean-project install (#492)
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
- Ingress address delay (
0-START-HERE.mdstep 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 ingressevents), names theTranslation failed ... no BackendConfig for service port existswarning 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.mdhas no Ingress check of its own (it points at step 6 and 14), so it is unchanged. - Chart from a checkout (step 1). New short note:
helm dependency buildforcharts/sessions-pipelinebeforecharts/agent-relay, and why (without it the read API and workers are not rendered). managed-values.jsoncan crash-loop relay-control (step 4,terraform/examples/gcp). Two parts:- Guide. The guide told readers to uncomment
desktop_feed_bucket_namefrom 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)'onmanaged-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, defaulttrue). Withfalse,chart_values["relay-control"]has noextraEnvanddesktop_feed.envis empty; the bucket, the service account and the annotations are unchanged. Terraform cannot see the signer (it isrelay-control.desktopFeed.signingKeysin 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 istrueso that an existing install with a signer renders exactly the same: defaulting tofalsewould drop the storage env from such an install on its nextterraform outputand break it the other way round (signer without storage). The existing test now asserts the three entries by value, and a new run coversfalse.
- Guide. The guide told readers to uncomment
- Release pins (step 7). The pins are not changed. The step now says that
SERVICES_IMAGE,PSQL_IMAGEandagent-relay-0.7.54.tgzbelong 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.tgzname), and for a checkout fromreleases/<tag>/pins.jsonand thesessions-pipelinechart values. The repo has no check that compares the guide's pins with release metadata (the release workflows only carry a manual checklist line fordocs/gcp-install/), so there was nothing to keep passing. first-admin.sh(and step 15). OptionalAPI_HOST(defaultapi.<app hostname>, so current callers are unaffected), validated with the same rule as the app hostname; theOriginheader stays the app hostname. OptionalPASSWORD_FILE: the password goes to a new local file (mode 0600, created withnoclobber, refused if it exists) instead of Secret Manager, andgcloudis 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 testscripts/selfhost/tests/gcp-first-admin-test.sh, run fromrun-tests.sh(which also syntax-checks and shellchecks the script now).- Edge-deny backend (step 14). One bullet: paths routed to the
...-cast-edge-denyService (/internaland 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](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.