Skip to content

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

Merged
khaliqgant merged 2 commits into
mainfrom
docs/gke-guide-gaps-492
Nov 19, 2026
Merged

khaliqgant merged 2 commits into
mainfrom
docs/gke-guide-gaps-492

Conversation

@miyaontherelay

@miyaontherelay miyaontherelay commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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.

…492)

- Step 14: the Ingress can take 15 to 20 minutes to get its address; the
  first-sync "no BackendConfig for service port exists" warning is harmless
  when it does not repeat. 502 on paths routed to the edge-deny Service is
  by design, not an outage.
- Step 1: installing from a checkout needs helm dependency build for
  sessions-pipeline before agent-relay.
- Step 4 and terraform/examples/gcp: relay-control exits when the Desktop
  feed storage env is set without a signer. The guide says to set the bucket
  only once the signing key exists and how to recover; the new
  desktop_feed_has_signing_keys input (default true, so current outputs are
  unchanged) leaves the storage env out of chart_values and desktop_feed.
- Step 7: SERVICES_IMAGE, PSQL_IMAGE and the .tgz name belong to the pinned
  release; how to read them for another release or a checkout.
- first-admin.sh: optional API_HOST (default api.<app hostname>) and
  PASSWORD_FILE (a new 0600 file instead of Secret Manager), with tests.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@miyaontherelay miyaontherelay added the merge-train:hold Do not merge without Khaliq's direct OK label Nov 19, 2026
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: a0a3d4d9-e494-4f6b-8c13-048c7115fe97
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@greptile-apps

greptile-apps Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The follow-up changes appear safe to merge.

Summary

The PR fills gaps in the GCP install guide, adds first-admin options, and lets operators create Desktop feed storage before signing keys are ready.

  • Terraform can prepare the feed bucket before its signing key is ready.
  • The first-admin script can use another API host or a local password file.
  • Checkout installs build chart dependencies before packaging the main chart.
  • Each install release uses its own image and chart pins.
  • The guide shows when a slow Ingress is still starting normally.
  • The guide explains why closed paths can return 502.

Both previous findings are fixed. No new actionable issues were found in the follow-up changes. The focused first-admin tests passed.

Reviews (2) · Last reviewed commit: "fix(gcp-install): isolate the first-admi..." · Reviewed by Greptile

Comment thread scripts/selfhost/tests/run-tests.sh Resolved
Comment thread terraform/examples/gcp/README.md Resolved
…nge on apply

- gcp-first-admin-test.sh brings its own openssl mock. Under run-tests.sh it
  inherited the runner's mock, which prints nothing for "rand", so the
  password was empty and the static job failed.
- desktop_feed_has_signing_keys: say that outputs are read from the state,
  so changing the input needs an apply before chart_values is saved again
  (example README, variable description, guide step 4).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@khaliqgant
khaliqgant merged commit ff9ff61 into main Nov 19, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-train:hold Do not merge without Khaliq's direct OK

Projects

None yet

2 participants