docs(deploy): round-4 deploy-via-tailscale review fixes

- Gemini HIGH (design line 82): switch NODES_RAFT_MAP example to full
  MagicDNS FQDNs so it matches the runbook; bare hostnames resolve
  differently per node.
- Gemini Medium (design line 45): fix YAML — on/workflow_dispatch/inputs
  must be nested, not on a single line, and the fence is labelled yaml.
- Gemini Medium (runbook §3, design §2.3): retract devices:core — not a
  valid Tailscale OAuth scope; note devices:write as the standard one.
- Gemini Medium (runbook §6, line 153-156): correct the cancelled-job
  log pattern to what the script actually emits (`==> [<id>@<host>]
  start`, scripts/rolling-update.sh:398), not the fictitious
  `[rolling-update] rolling n<id>: ...`.
- Gemini Medium (runbook §6, line 156-160): clarify that docker run
  stdout/stderr is redirected to /dev/null, so operators reconstruct
  the invocation from the step-level env log, not from the docker-run
  argv.
- Codex P2 (runbook §8 approval troubleshooting): clarify that both
  dry-run and non-dry-run runs pause for approval in v1 because
  `environment: production` is unconditional; reference §4 for the
  second-environment upgrade path.

Author: bootjp

docs/deploy_via_tailscale_runbook.md

@@ -58,9 +58,12 @@ Admin console → Settings → OAuth clients → New client:
 
 - Description: `elastickv GitHub Actions deploy`
 - Scopes: `auth_keys` (write). Recent `tailscale/github-action` versions
-  may additionally require `devices:core` (write); enable that if the
-  join step fails with an authorization error. The action's README is
-  the definitive source for current scope requirements.
+  may additionally require `devices:write` (to register and clean up
+  the ephemeral node); enable that if the join step fails with an
+  authorization error. The action's README is the definitive source
+  for current scope requirements. `devices:core` is NOT a valid
+  Tailscale OAuth scope — earlier drafts of this runbook named it and
+  would have produced an auth failure.
 - Tags: `tag:ci-deploy`
 
 Copy the client ID and secret; they go into GitHub in the next step.
@@ -147,14 +150,20 @@ Re-run the workflow with `image_tag` set to the previous-known-good sha. The
 GitHub cancelling the job between node steps is the one operational
 hazard that needs manual cleanup.
 
-1. **Look at the last log line from the `Roll cluster` step.** The script
-   logs `[rolling-update] rolling n<id>: docker stop/rm/run ...` before
-   each node recreate. Whatever `n<id>` appears last is the one in
+1. **Look at the last log line from the `Roll cluster` step.** The
+   script emits `==> [<raft-id>@<host>] start` at the beginning of
+   each per-node recreate (see `scripts/rolling-update.sh:398`).
+   Whichever `<raft-id>` appears in the last such line is the one in
    flight when the cancel signal landed.
 2. **SSH into that node** over Tailscale and run `docker ps`. If the
-   container is absent or `Exited`, finish the recreate by hand with the
-   docker run arguments the script emitted (which you can see in the
-   workflow log, step `Roll cluster`).
+   container is absent or `Exited`, finish the recreate by hand. The
+   `docker run` invocation itself is redirected to `/dev/null` by the
+   script, so the workflow log does NOT contain the full argv. Use
+   the resolved env instead: the step logs `NODES_RAFT_MAP`,
+   `EXTRA_ENV`, `GOMEMLIMIT`, `CONTAINER_MEMORY_LIMIT`, `IMAGE`, and
+   `DATA_DIR` before invoking the script — those are sufficient to
+   reconstruct the same `docker run` you would see if you re-ran with
+   the same inputs.
 3. **Confirm the new leader via `raftadmin` or metrics** before re-running
    the workflow with `nodes:` scoped to the remaining untouched IDs. Do
    NOT re-run the full rollout if the partial one is still in flight —
@@ -185,9 +194,14 @@ each node in turn regardless of whether it was touched before.
 ## 8. Troubleshooting
 
 ### Job pauses indefinitely at "Waiting for approval"
-Expected for non-dry-run deploys — a reviewer from the `production` environment
-must click Approve. Check the "Required reviewers" list in the environment
-settings.
+Expected for **every** run in v1 — `.github/workflows/rolling-update.yml`
+sets `environment: production` unconditionally, so both dry-run and
+non-dry-run executions pause for approval. A reviewer from the
+`production` environment must click Approve. Check the "Required
+reviewers" list in the environment settings. See §4 "GitHub
+environment" for the dry-run-approval alternatives (approach 2: add a
+second `production-dry-run` environment without required reviewers)
+if the friction becomes intolerable.
 
 ### `tailscale ping` fails for a node
 The node may not be running `tailscaled`, not tagged `tag:elastickv-node`, or

docs/design/2026_04_24_proposed_deploy_via_tailscale.md

@@ -40,14 +40,15 @@ logged in on every node, with SSH access enabled over the tailnet.
 
 ### 2.1 Workflow shape
 
-```
+```yaml
 name: Rolling update
-on: workflow_dispatch:
-  inputs:
-    ref:           # git sha/tag of the image to deploy
-    image_tag:     # defaults to $ref; override only for rollbacks
-    nodes:         # subset of raft IDs; empty = full roll
-    dry_run:       # bool, default TRUE — renders plan but doesn't roll
+on:
+  workflow_dispatch:
+    inputs:
+      ref:           # git sha/tag of the image to deploy
+      image_tag:     # defaults to $ref; override only for rollbacks
+      nodes:         # subset of raft IDs; empty = full roll
+      dry_run:       # bool, default TRUE — renders plan but doesn't roll
 
 jobs:
   deploy:
@@ -79,10 +80,13 @@ Stored in a GitHub `production` environment (not repo-wide):
   entries. Prevents the first-connect TOFU prompt.
 
 **Variables (non-secret):**
-- `NODES_RAFT_MAP` — `n1=kv01,n2=kv02,...` (advertised hostnames as seen
-  from inside the tailnet; the script appends `RAFT_PORT` automatically,
-  so do NOT include a port here).
-- `SSH_TARGETS_MAP` — `n1=kv01.tailnet.ts.net,...` (MagicDNS).
+- `NODES_RAFT_MAP` — `n1=kv01.tailnet.ts.net,n2=kv02.tailnet.ts.net,...`
+  (full MagicDNS FQDNs; bare short names can resolve differently
+  depending on each node's search-domain configuration). The script
+  appends `RAFT_PORT` automatically, so do NOT include a port here.
+  The runbook (`docs/deploy_via_tailscale_runbook.md`) carries the
+  same FQDN convention; keep the two in sync if either changes.
+- `SSH_TARGETS_MAP` — `n1=kv01.tailnet.ts.net,...` (MagicDNS FQDN).
 - `IMAGE_BASE` — `ghcr.io/bootjp/elastickv` (tag is appended from the input).
 - `SSH_USER` — e.g., `bootjp`.
 
@@ -93,8 +97,11 @@ Use OAuth ephemeral nodes (not a long-lived auth key):
 - Create an OAuth client in Tailscale admin console with scope
   `auth_keys` (write) on tag `tag:ci-deploy`. (`tailscale/github-action`
   uses the OAuth client to mint a short-lived auth key on each run;
-  recent action versions may also require `devices:core` — consult the
-  action's README for the current scope list.)
+  recent action versions may also require `devices:write` so the
+  ephemeral node can register and be cleaned up — consult the action's
+  README for the current scope list. Earlier drafts of this doc named
+  `devices:core`, which is not a supported Tailscale OAuth scope and
+  would fail authentication.)
 - Store client ID + secret in GitHub env secrets.
 - `tailscale/github-action@v3` joins the tailnet for the duration of the job
   as an ephemeral tagged node; disconnects automatically on job exit.