From bfb442eed2b83a1ddc87b5233895e3d992a80296 Mon Sep 17 00:00:00 2001 From: Miya Date: Thu, 19 Nov 2026 13:14:39 +0100 Subject: [PATCH 1/2] docs(gcp-install): close the guide gaps from a clean-project install (#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.) and PASSWORD_FILE (a new 0600 file instead of Secret Manager), with tests. Co-Authored-By: Claude Fable 5.2 --- docs/gcp-install/0-START-HERE.md | 106 ++++++++++++- docs/gcp-install/first-admin.sh | 56 +++++-- .../selfhost/tests/gcp-first-admin-test.sh | 147 ++++++++++++++++++ scripts/selfhost/tests/run-tests.sh | 3 + terraform/examples/gcp/README.md | 9 +- terraform/examples/gcp/desktop-feed.tf | 13 ++ terraform/examples/gcp/outputs.tf | 26 ++-- .../examples/gcp/tests/native.tftest.hcl | 22 ++- terraform/examples/gcp/variables.tf | 6 + 9 files changed, 356 insertions(+), 32 deletions(-) create mode 100755 scripts/selfhost/tests/gcp-first-admin-test.sh diff --git a/docs/gcp-install/0-START-HERE.md b/docs/gcp-install/0-START-HERE.md index dc666c69..9ca1058c 100644 --- a/docs/gcp-install/0-START-HERE.md +++ b/docs/gcp-install/0-START-HERE.md @@ -56,6 +56,21 @@ No `gh`? Download the same assets from https://github.com/AgentWorkforce/infra/releases/tag/agent-relay-2026.11.16 into `release/`. On macOS use `shasum -a 256 -c SHA256SUMS`. +**Installing the chart from a checkout instead of the released `.tgz`?** (A +chart newer than the pinned release, or your own change.) Build the +dependencies in this order, then use `infra/charts/agent-relay` wherever the +steps name the `.tgz` or `$CHART`: + +```sh +helm dependency build infra/charts/sessions-pipeline +helm dependency build infra/charts/agent-relay +``` + +`sessions-pipeline` has dependencies of its own, so it goes first. Without it +the second command fails or packages a chart whose read API and workers are +not rendered. Step 7's image values then need the chart's own release, not +this guide's pins (see the note there). + Tools: `gcloud` (with `gke-gcloud-auth-plugin`), `terraform` ≥ 1.11 (or OpenTofu), `helm` 3, `kubectl`, `jq`, `yq`, `openssl`, and [`crane`](https://github.com/google/go-containerregistry/releases) for step 5. @@ -152,7 +167,7 @@ network_self_link = "projects//global/networks/" sessions_bucket_name = "" deletion_protection = true image_mirror_repository = "agent-relay-mirror" # step 5's registry, readable by the GKE nodes -# desktop_feed_bucket_name = "" # agent-relay-2026.11.9 or later: the desktop app's update feed +# desktop_feed_bucket_name = "" # agent-relay-2026.11.9 or later, and only once the feed's signing key exists (see below) # gke_node_service_account = "" # only if the node pool has its own service account # kms_key_name = "projects/

/locations//keyRings//cryptoKeys/" # optional CMEK labels = { app = "agent-relay" } @@ -169,7 +184,7 @@ cd - change, 0 to destroy` (5 more with `desktop_feed_bucket_name`, 2 fewer without `image_mirror_repository`), the apply completes, and `managed-values.json` exists. -From agent-relay-2026.11.9, uncomment `desktop_feed_bucket_name`. It gives the +From agent-relay-2026.11.9, `desktop_feed_bucket_name` gives the desktop app a signed update feed in your project: a private bucket, and a service account relay-control uses to write releases there and sign download links. `managed-values.json` carries its settings into step 11; if your `values.yaml` sets `relay-control.extraEnv` or @@ -178,6 +193,29 @@ settings into step 11; if your `values.yaml` sets `relay-control.extraEnv` or Terraform input nor relay-control 0.5.25, so leave it commented. Agent Relay sets up the feed's signing key with you when we build your branded desktop app. +**Uncomment it only once that signing key is in place** (the key's Secret +exists and your `values.yaml` sets `relay-control.desktopFeed.signingKeys`). +The bucket puts the feed's storage settings into `managed-values.json`, and +relay-control does not start with storage and no signer: it exits with +`SELFHOST_DESKTOP_FEED_SIGNER and SELFHOST_DESKTOP_FEED_STORAGE must be set together` +and the pod crash-loops. Adding the bucket later is this step again (5 to +add), then step 11's command. + +**Already applied with the bucket, and no signing key yet?** Keep the bucket +and take the storage settings out until the key exists: + +```sh +jq 'del(.["relay-control"].extraEnv)' managed-values.json > managed-values.tmp && mv managed-values.tmp managed-values.json +``` + +Also remove any `SELFHOST_DESKTOP_FEED_*` entries you copied into +`values.yaml`. The service account annotations can stay. When the key is in +place, write `managed-values.json` again (the `terraform output` line above) +and run step 11's command. The Terraform on `main` (after the pinned release) +does the same with `desktop_feed_has_signing_keys = false` in +`terraform.tfvars`: the output then leaves the storage settings out until you +remove that line. + **Terraform state.** The example has no `backend` block, so the state stays in a local file. To keep it in Cloud Storage, create a private, versioned bucket and add a backend before `terraform init`: @@ -292,6 +330,34 @@ source settings.sh bash -c 'source ./settings.sh; for v in DOMAIN ORG_ID ORG_NAME ADMIN_EMAIL GCP_PROJECT_ID REGION MIRROR_ROOT CLOUD_SQL_INSTANCE CLOUD_SQL_HOST CLOUD_SQL_ADMIN_USER CLOUD_SQL_ADMIN_SECRET_ID CLOUD_SQL_CA_SHA256 SESSIONS_BUCKET; do [ -n "${!v}" ] && [ "${!v}" != null ] && [[ "${!v}" != *"<"* ]] || echo "MISSING: $v"; done; echo "settings checked"' ``` +**`SERVICES_IMAGE`, `PSQL_IMAGE` and `agent-relay-0.7.54.tgz` belong to the +pinned release,** agent-relay-2026.11.16 (chart 0.7.54). Installing another +release or chart? Don't reuse these digests: the Jobs in steps 8, 13 and 16 +would run an older services image than the workloads. Read the three values +from that release's own assets in `release/` (step 1, with its tag): + +```sh +ls release/agent-relay-*.tgz +jq -r '.images[] | select(.name == "sessions-pipeline" or .name == "sessions-migration-postgresql") | "\(.name) \(.ref)"' release/release-manifest.json +``` + +`SERVICES_IMAGE` is `$MIRROR_ROOT/` followed by the `sessions-pipeline` ref, +`PSQL_IMAGE` is `$MIRROR_ROOT/` followed by the `sessions-migration-postgresql` +ref, and the `.tgz` name replaces `agent-relay-0.7.54.tgz` in steps 11, 13 and +16. + +A chart from a checkout (step 1) has no release assets. Read the same two +images from the checkout, for the release whose images you run, and mirror +them (step 5) before use: + +```sh +jq -r '.pins["sessions-pipeline"] | "\(.repository)@\(.digest)"' infra/releases//pins.json +grep -m1 -o 'ghcr.io/cloudnative-pg/postgresql[^ ]*' infra/charts/sessions-pipeline/values.yaml +``` + +The second line prints `repository:tag@sha256:...`; `PSQL_IMAGE` takes it +without the tag (`repository@sha256:...`), as step 5 mirrors by digest. + **Brought your own resources (step 3)?** Replace the six lines between `PG=` and `unset` with the values from 1-BRING-YOUR-OWN.md. @@ -564,7 +630,7 @@ with `echo $CLOUD_SQL_CA_SHA256`. kubectl -n $NAMESPACE get managedcertificate agent-relay -o jsonpath='{.status.certificateStatus}{"\n"}' ``` -Repeat until it prints `Active`. Then: +Repeat until it prints `Active` (what is normal while you wait is below). Then: ```sh curl -fsS "https://api.$DOMAIN/readyz" && echo " api ok" @@ -576,12 +642,32 @@ curl -s -o /dev/null -w "history %{http_code}\n" "https://history.$DOMAIN/v1/ses **Done when:** `Active`, then `api ok`, `cast ok`, `dashboard 200` and `history 401`. +**The Ingress can take 15 to 20 minutes to get its address** after step 11. +The certificate cannot leave `Provisioning` before that. To look: + +```sh +kubectl -n $NAMESPACE get ingress +kubectl -n $NAMESPACE describe ingress | sed -n '/^Events:/,$p' +``` + +A `Translation failed ... no BackendConfig for service port exists` warning +on the first sync is harmless when it does not repeat: the load balancer +controller read the Services before their BackendConfigs, and a later sync +heals it by itself. Worry only if the `ADDRESS` column is still empty, or the +warning still repeats, after about 20 minutes; then send us the events. + - **Stuck in `Provisioning` for over an hour:** one of the four names does not resolve to the address from step 6, or a CAA record blocks Google. Fix DNS; the certificate retries by itself. - **`FailedNotVisible`:** the same: DNS does not point at the load balancer yet. - **502 for a few minutes after `Active`:** the load balancer's health checks are still converging. Wait 5 minutes. +- **502 on `/internal` and other closed paths is not an outage.** The chart + routes paths that must not be public (for example + `https://api./internal/...`) to the `...-cast-edge-deny` Service, + which has no endpoints on purpose. Without a Cloud Armor policy the load + balancer answers those paths with 502, not 403 or 404. Only the four checks + above tell you whether the install is up. The load balancer accepts TLS 1.0 and later until it has an SSL policy. To require TLS 1.2, add Cloud Armor, or put Cloudflare in front, see @@ -619,6 +705,19 @@ hours: the script never retries, and it stops if the secret already exists. A `403 csrf_rejected` means the request lacked your dashboard's origin; it is refused before the key is read, so the key stays unused. +Two settings, both optional: + +- **The API is not at `api.`** (your own four host names): name + it with `API_HOST= bash first-admin.sh ...`. The script calls + that host and still sends the app hostname as the origin. +- **No Secret Manager** (the API is off, or you may not create secrets there): + `PASSWORD_FILE= bash first-admin.sh ...` keeps the password in that + new local file (mode 0600) instead; `` is then unused and can be + `-`. The script stops if the file exists. Hand the file to the admin over a + channel you trust, then delete it. By default the script needs + `secretmanager.googleapis.com` and permission to create a secret in the + project. + Then add users: ```sh @@ -1115,6 +1214,7 @@ gcloud artifacts repositories delete agent-relay-mirror --location $REGION - **Used `first-admin.sh` (step 15)?** Delete the password it stored, or it will refuse to run for a new install in this project: `gcloud secrets delete agent-relay-first-admin-password --project $GCP_PROJECT_ID`. + With `PASSWORD_FILE`, delete that file instead. - **Used vals with Secret Manager (step 10c)?** Delete its secrets: `gcloud secrets list --filter='name~agent-relay--' --format='value(name)' | xargs -r -n1 gcloud secrets delete --quiet`. - Delete `~/.agent-relay-install` from wherever you copied it: the database diff --git a/docs/gcp-install/first-admin.sh b/docs/gcp-install/first-admin.sh index f617176b..138a0b42 100644 --- a/docs/gcp-install/first-admin.sh +++ b/docs/gcp-install/first-admin.sh @@ -6,24 +6,41 @@ # # bash first-admin.sh [namespace] # +# Optional environment: +# API_HOST the API's host name. Default: api.. Set it when +# the API has another name. The Origin header stays the app +# hostname. +# PASSWORD_FILE keep the password in this new local file (mode 0600) instead +# of Secret Manager. gcloud is then not needed and +# is not used (pass -). The file must not exist yet. +# # It generates a password, stores it in Secret Manager as # agent-relay-first-admin-password (before using it, so it is never lost), then # posts it with the setup key from the agent-relay-secrets Secret. On 200 the # admin reads the password with # gcloud secrets versions access latest --secret agent-relay-first-admin-password --project -# and signs in at https:///login. +# and signs in at https:///login. Without PASSWORD_FILE this +# needs secretmanager.googleapis.com enabled and permission to create a secret +# in the project. # # The setup key works once, within 24 hours of the install: this script never # retries. A 403 csrf_rejected is refused before the key is read, so the key # stays unused; any other failure: read its message, fix the cause, run again. -# Needs gcloud, kubectl (on the cluster), curl, jq and openssl. +# Needs kubectl (on the cluster), curl, jq and openssl, and gcloud unless +# PASSWORD_FILE is set. set -euo pipefail -DOMAIN="${1:?usage: bash first-admin.sh [namespace]}" -PROJECT="${2:?usage: bash first-admin.sh [namespace]}" +USAGE='usage: [API_HOST=] [PASSWORD_FILE=] bash first-admin.sh [namespace]' +DOMAIN="${1:?$USAGE}" +PROJECT="${2:?$USAGE}" NAMESPACE="${3:-agent-relay}" +API_HOST="${API_HOST:-api.$DOMAIN}" +PASSWORD_FILE="${PASSWORD_FILE:-}" SECRET=agent-relay-first-admin-password case "$DOMAIN" in *[!A-Za-z0-9.-]*|"") echo "app hostname must be a bare host name, e.g. relay.example.com" >&2; exit 2 ;; esac -for tool in gcloud kubectl curl jq openssl; do +case "$API_HOST" in *[!A-Za-z0-9.-]*|"") echo "API_HOST must be a bare host name, e.g. relay-api.example.com" >&2; exit 2 ;; esac +tools="kubectl curl jq openssl" +[ -n "$PASSWORD_FILE" ] || tools="gcloud $tools" +for tool in $tools; do command -v "$tool" >/dev/null || { echo "$tool is required" >&2; exit 2; } done @@ -33,15 +50,30 @@ kubectl -n "$NAMESPACE" get secret agent-relay-secrets -o jsonpath='{.data.selfh # 2. Store the password first. An existing secret means a run already stored # one: stop rather than replace a password the admin may already use. -if gcloud secrets describe "$SECRET" --project "$PROJECT" >/dev/null 2>&1; then +if [ -n "$PASSWORD_FILE" ]; then + if [ -e "$PASSWORD_FILE" ] || [ -L "$PASSWORD_FILE" ]; then + echo "$PASSWORD_FILE already exists: the first sign-in may already be done." >&2 + echo "Sign in with that password; to start over, delete the file yourself first." >&2 + exit 1 + fi + STORED="the file $PASSWORD_FILE" +elif gcloud secrets describe "$SECRET" --project "$PROJECT" >/dev/null 2>&1; then echo "Secret Manager already holds $SECRET in $PROJECT: the first sign-in may already be done." >&2 echo "Sign in with that password; to start over, delete the secret yourself first." >&2 exit 1 +else + STORED="$SECRET" fi PW="$(openssl rand -base64 33 | tr -d '\n/+=' | cut -c1-32)" -printf '%s' "$PW" | gcloud secrets create "$SECRET" --project "$PROJECT" \ - --replication-policy automatic --labels app=agent-relay --data-file=- >/dev/null -echo "stored $SECRET in $PROJECT" +if [ -n "$PASSWORD_FILE" ]; then + # noclobber: never write through a file or link created since the check. + (umask 077; set -o noclobber; printf '%s\n' "$PW" > "$PASSWORD_FILE") + echo "stored the password in $PASSWORD_FILE (mode 0600)" +else + printf '%s' "$PW" | gcloud secrets create "$SECRET" --project "$PROJECT" \ + --replication-policy automatic --labels app=agent-relay --data-file=- >/dev/null + echo "stored $SECRET in $PROJECT" +fi # 3. Post the key and password. The Origin header is required: sign-in routes # refuse a request without the dashboard's origin (403 csrf_rejected). @@ -50,14 +82,14 @@ CODE="$(PW="$PW" KEY="$(kubectl -n "$NAMESPACE" get secret agent-relay-secrets - jq -n '{setupKey:env.KEY,password:env.PW}' | curl -sS -o "$BODY" -w '%{http_code}' -X POST \ -H 'Content-Type: application/json' -H "Origin: https://$DOMAIN" \ - --data-binary @- "https://api.$DOMAIN/api/v1/auth/password/setup-key")" || CODE="${CODE:-000}" + --data-binary @- "https://$API_HOST/api/v1/auth/password/setup-key")" || CODE="${CODE:-000}" unset PW if [ "$CODE" = 200 ]; then - echo "first admin set: sign in at https://$DOMAIN/login with the password in $SECRET" + echo "first admin set: sign in at https://$DOMAIN/login with the password in $STORED" exit 0 fi # Error bodies carry a code and a message, never the key or the password. # 000: curl could not reach the API (DNS, certificate, network); the key was not sent. echo "setup-key sign-in failed: HTTP $CODE $(jq -c '{error,message}' "$BODY" 2>/dev/null || true)" >&2 -echo "The stored password was not accepted; delete $SECRET before running again." >&2 +echo "The stored password was not accepted (API: https://$API_HOST); delete $STORED before running again." >&2 exit 1 diff --git a/scripts/selfhost/tests/gcp-first-admin-test.sh b/scripts/selfhost/tests/gcp-first-admin-test.sh new file mode 100755 index 00000000..e66fbe51 --- /dev/null +++ b/scripts/selfhost/tests/gcp-first-admin-test.sh @@ -0,0 +1,147 @@ +#!/usr/bin/env bash +# Offline behavioral tests for docs/gcp-install/first-admin.sh. gcloud, kubectl +# and curl are mocked; no network, cluster or cloud access is used. +set -euo pipefail + +TEST_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" +SCRIPT="${TEST_DIR}/../../../docs/gcp-install/first-admin.sh" +TEST_BASH="${TEST_BASH:-bash}" +ROOT="$(mktemp -d)" +trap 'rm -rf "$ROOT"' EXIT +BIN="$ROOT/bin" +mkdir -p "$BIN" + +fail() { printf 'not ok - gcp-first-admin: %s\n' "$*" >&2; exit 1; } +pass() { printf 'ok - gcp-first-admin: %s\n' "$*"; } + +cat >"$BIN/kubectl" <<'MOCK' +#!/usr/bin/env bash +printf 'kubectl %s\n' "$*" >>"$MOCK_LOG" +printf '%s' 'setup-key-value' | base64 +MOCK +# "secrets describe" fails (no secret yet) unless MOCK_SECRET_EXISTS is set; +# "secrets create" keeps what it reads on stdin. +cat >"$BIN/gcloud" <<'MOCK' +#!/usr/bin/env bash +printf 'gcloud %s\n' "$*" >>"$MOCK_LOG" +case " $* " in + *" secrets describe "*) [ -n "${MOCK_SECRET_EXISTS:-}" ] ;; + *" secrets create "*) cat >"$MOCK_DIR/secret-manager-value" ;; + *) exit 1 ;; +esac +MOCK +# Keeps the request body, logs the arguments, answers MOCK_HTTP_CODE. +cat >"$BIN/curl" <<'MOCK' +#!/usr/bin/env bash +cat >"$MOCK_DIR/curl-body" +out="" +previous="" +for arg in "$@"; do + printf 'curl-arg %s\n' "$arg" >>"$MOCK_LOG" + [ "$previous" = "-o" ] && out="$arg" + previous="$arg" +done +printf '%s' '{"error":"mock_error","message":"mock message"}' >"$out" +printf '%s' "${MOCK_HTTP_CODE:-200}" +MOCK +chmod +x "$BIN/kubectl" "$BIN/gcloud" "$BIN/curl" + +# run [VAR=value ...] --