docs: complete the Knative migration guide (PR 2 of REORG-PLAN) by pdettori · Pull Request #489 · rossoctl/moca

pdettori · 2026-10-12T12:45:51Z

Complete the Knative/KEDA migration guide (PR 2 of the docs reorg)

Extends docs/migrating-from-knative.md, the single deprecation/migration page from #485. Docs only. Independent of the docs-hygiene PR (#488); it touches only this file.

Added

Cron row in the mapping table (it was folded into the async row). The P6 spec names a supervisor timer as the intended replacement but puts scheduled dispatch out of scope for round one.
"If you depend on async fan-out or the CronJob": states what ADR-0041/ADR-0034/the P6 spec say (no P6 equivalent yet, no design or tracking issue referenced), tells those users to stay on the deprecated path and report it in the discussion, and notes that interactive turns can move first. The mixed setup is marked unverified since the smoke tests don't cover it. No workaround is invented.
Configuration table: Knative service.yaml variables mapped to the P6 templates (deploy/vm/env/*.env.example), limited to what is verified; SH_MODEL is called out as unmapped.
mocactl guidance: point clients at the control plane (discovery), install command, device-flow login, and that the Knative quick start is deprecated.
Rollback (a client repoint until Bring-up step 4) and a status log.

Please check

The async/cron wording matches your intent for Q5 in docs/REORG-PLAN.md.
Whether SH_SESSION_TOKEN_PUBLIC_KEYS and SH_CONTROL_PLANE_URL also need setting on the VM supervisor; I only verified the three systemd-credential secrets.
The rollback claim that P6-written sessions resume on Knative rests on the guide's own statement that both paths share the session schema.

Verification

Prettier run; relative links in the file resolve. make lint not run (worktree without node_modules).

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

Update after review

Rebased onto main; this PR now touches only docs/migrating-from-knative.md and is independent of docs: hygiene pass after ADR-0041 (PR 1 of REORG-PLAN) #488.
The guide's three feedback links point at the pinned tracking issue Knative/KEDA deprecation: tell us when you have migrated (or what blocks you) #490 (Discussions are disabled on this repo).

ingpaolodettori-dev

Docs-only follow-up to #485. The new sections (async/cron, the configuration table, mocactl, rollback) check out against the code at d283a64: the Knative service.yaml variable list, the VM env templates, setup-vm.sh's three systemd-credential secrets, the install script (Node 22+, MOCACTL_VERSION/MOCACTL_INSTALL_DIR), GET /v1/discovery, the mocactl-quickstart make target, the P6 spec's §2.2 table and §8 scope line, and ADR-0034/0041's "no P6 equivalent yet" wording. The rollback claim holds: both paths reach Redis through @moca/harness → @moca/session-backend. Approving with a few accuracy suggestions inline.

Stacking: the body says this is independent of #488, but this branch includes #488's commit (abcf143 is ee68e35 rebased onto main; git range-diff shows =). I reviewed only d283a64. Merge #488 first, or this PR merges #488's changes along with it.

Answers to "Please check":

SH_SESSION_TOKEN_PUBLIC_KEYS / SH_CONTROL_PLANE_URL on the VM supervisor: both are already handled. supervisor.env.example ships SH_CONTROL_PLANE_URL=http://127.0.0.1:8090 (loopback to the control plane), and setup-vm.sh writes SH_SESSION_TOKEN_PUBLIC_KEYS on the run that generates the keypair. Neither needs operator action, and the row could say so.
SH_MODEL does carry over: see the inline comment.

Author: pdettori (MEMBER, maintainer). 2 commits, both DCO signed off. All 14 checks pass.

ingpaolodettori-dev · 2026-10-12T13:58:38Z

+What that means for you:
+
+- **Stay on the deprecated path for those workloads** until a P6 equivalent is announced, and say
+  so in the [migration discussion](https://github.com/rossoctl/moca/discussions): removal waits for


suggestion — This is a third link to GitHub Discussions, which are still disabled on rossoctl/moca (has_discussions: false). We raised this on #485 for lines 9 and 182, and #485 merged with them unchanged. Removal is gated on users saying they've moved or that they depend on A/C, so this is the guide's only feedback channel and it currently 404s. Either enable Discussions, or point all three links at a pinned tracking issue.

ingpaolodettori-dev · 2026-10-12T13:58:38Z

+  remaining users to migrate, and a dependency on A or C is exactly the case that moves the date.
+- **Interactive turns can move first.** The two deployments share only Redis and the session
+  schema is the same, so running P6 for `/turn` traffic while async and cron stay on Knative is the
+  intended shape of "bring the P6 side up in parallel" above. The repo's smoke tests do not


nit — "bring the P6 side up in parallel" is in Bring-up step 1, which is below this section (line ~166), not above. The same goes for "step 4 of Bring-up" in Rolling back.

ingpaolodettori-dev · 2026-10-12T13:58:38Z

+| `REDIS_URL`                                                                                    | Unchanged (`supervisor.env.example`: "inherited unchanged"). Point it at the same Redis to keep sessions.                                                                                                                                                  |
+| `KAGENTI_SANDBOX_POD`                                                                          | Not used by the supervisor template. Sandboxes are discovered from relay records: `SH_SANDBOX_DISCOVERY=records` and `SH_REMOTE_SANDBOX=1`.                                                                                                                |
+| `KAGENTI_SANDBOX_POOL_SELECTOR`                                                                | Still present in the supervisor template (`app=sandbox`), together with `KAGENTI_SANDBOX_CAP`.                                                                                                                                                             |
+| `SH_REQUIRE_AUTH`, `SH_EXCHANGE_TOKEN`, `SH_SESSION_TOKEN_PUBLIC_KEYS`, `SH_CONTROL_PLANE_URL` | Same names. On a VM, `setup-vm.sh` generates the secrets (`SH_SESSION_TOKEN_PRIVATE_KEY`, `SH_CREDENTIAL_KEK`, `SH_EXCHANGE_TOKEN`) as systemd credentials; setting one in the env file as well makes the control plane refuse to boot.                    |


nit — Two small precision points. (1) For the supervisor, the boot refusal comes from the workers: supervisor.env.example says setting SH_EXCHANGE_TOKEN there "makes the workers refuse to boot", while the control plane refuses for its own env file. (2) On the VM, SH_SESSION_TOKEN_PUBLIC_KEYS is written by setup-vm.sh and SH_CONTROL_PLANE_URL is preset to loopback in the template, so operators don't carry these two over by hand. That also answers the PR's open question.

ingpaolodettori-dev · 2026-10-12T13:58:38Z

+| `KAGENTI_SANDBOX_POD`                                                                          | Not used by the supervisor template. Sandboxes are discovered from relay records: `SH_SANDBOX_DISCOVERY=records` and `SH_REMOTE_SANDBOX=1`.                                                                                                                |
+| `KAGENTI_SANDBOX_POOL_SELECTOR`                                                                | Still present in the supervisor template (`app=sandbox`), together with `KAGENTI_SANDBOX_CAP`.                                                                                                                                                             |
+| `SH_REQUIRE_AUTH`, `SH_EXCHANGE_TOKEN`, `SH_SESSION_TOKEN_PUBLIC_KEYS`, `SH_CONTROL_PLANE_URL` | Same names. On a VM, `setup-vm.sh` generates the secrets (`SH_SESSION_TOKEN_PRIVATE_KEY`, `SH_CREDENTIAL_KEK`, `SH_EXCHANGE_TOKEN`) as systemd credentials; setting one in the env file as well makes the control plane refuse to boot.                    |
+| `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`                              | Inference credentials are per user, issued by the control plane. An operator-wide key is opt-in: `SH_ALLOW_OPERATOR_FALLBACK=true` with `SH_DEFAULT_INFERENCE_ENDPOINT` (`control-plane.env.example`; `deploy/vm/README.md`, "The operator-key fallback"). |


suggestion — This row doesn't say where the operator's actual key goes, and that's what someone migrating an ANTHROPIC_API_KEY most needs. Per deploy/vm/README.md ("The operator-key fallback"), it becomes the operator-inference-token credential file (SH_OPERATOR_INFERENCE_TOKEN, 0600, loaded via LoadCredential=), never an env line. An Anthropic API key also needs SH_DEFAULT_INFERENCE_ENDPOINT=https://api.anthropic.com plus SH_OPERATOR_INFERENCE_HEADER=x-api-key, or the control plane refuses to boot. ANTHROPIC_BASE_URL has no single equivalent: it maps to SH_DEFAULT_INFERENCE_ENDPOINT for the fallback, and to per-user endpoints otherwise.

ingpaolodettori-dev · 2026-10-12T13:58:38Z

+| `SH_REQUIRE_AUTH`, `SH_EXCHANGE_TOKEN`, `SH_SESSION_TOKEN_PUBLIC_KEYS`, `SH_CONTROL_PLANE_URL` | Same names. On a VM, `setup-vm.sh` generates the secrets (`SH_SESSION_TOKEN_PRIVATE_KEY`, `SH_CREDENTIAL_KEK`, `SH_EXCHANGE_TOKEN`) as systemd credentials; setting one in the env file as well makes the control plane refuse to boot.                    |
+| `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`                              | Inference credentials are per user, issued by the control plane. An operator-wide key is opt-in: `SH_ALLOW_OPERATOR_FALLBACK=true` with `SH_DEFAULT_INFERENCE_ENDPOINT` (`control-plane.env.example`; `deploy/vm/README.md`, "The operator-key fallback"). |
+| `LEAF_RESULT_TTL_SECONDS`                                                                      | Read only by the async entrypoints (`server.ts`, `leaf-job.ts`); no P6 counterpart while async has no P6 equivalent.                                                                                                                                       |
+| _(none)_                                                                                       | New and required on VM: `SH_TURNS_PER_WORKER` (no default), `SH_RELAY_ADDR`, `SH_RELAY_TOKEN`, `MOCA_RELAY_EXEC_TOKEN`, `SH_GITHUB_CLIENT_ID`, `SH_PUBLIC_HARNESS_URL`. Optional: `SH_WORKERS`, `SH_ROUTING_POLICY`.                                       |


nit — MOCA_RELAY_EXEC_TOKEN is required, but setup-vm.sh generates it into both relay.env and supervisor.env when it's absent, so it isn't something the operator sets. Also, SH_RELAY_TOKEN lives in relay.env and must match each worker's SANDBOX_TOKEN. Naming the file for each variable would help.

ingpaolodettori-dev · 2026-10-12T13:58:38Z

+| `LEAF_RESULT_TTL_SECONDS`                                                                      | Read only by the async entrypoints (`server.ts`, `leaf-job.ts`); no P6 counterpart while async has no P6 equivalent.                                                                                                                                       |
+| _(none)_                                                                                       | New and required on VM: `SH_TURNS_PER_WORKER` (no default), `SH_RELAY_ADDR`, `SH_RELAY_TOKEN`, `MOCA_RELAY_EXEC_TOKEN`, `SH_GITHUB_CLIENT_ID`, `SH_PUBLIC_HARNESS_URL`. Optional: `SH_WORKERS`, `SH_ROUTING_POLICY`.                                       |
+
+`SH_MODEL` has no mapping verified here; check the destination README before assuming it carries over.


suggestion — SH_MODEL does carry over. harness/src/run-turn.ts:356 reads config?.model ?? env.SH_MODEL ?? 'claude-opus-4-8' in the P6 workers. Compose passes it to the supervisor (docker-compose.yml, covered by compose.test.sh), and the kind-ci overlay sets it on the supervisor. Suggest moving it into the table as "Same name, set on the supervisor (a session's config bundle overrides it)". The same applies to the SH_MODEL_* family.

ingpaolodettori-dev · 2026-10-12T13:58:38Z

+  deprecated along with the rest of `deploy/knative/`. The P6 equivalents are the Compose and VM
+  READMEs above.
+
+## Rolling back


nit — Rolling back and Status log sit between "What carries over" and Bring-up, so readers meet rollback steps before the bring-up steps they refer to. Consider moving Rolling back after Bring-up / During the window, and the Status log to the end of the page.

Add what docs/migrating-from-knative.md lacked: a cron row in the mapping table, a section for users who depend on async fan-out or the CronJob (no P6 equivalent yet; stated as such, no workaround invented), a configuration mapping limited to verified variables, mocactl guidance, rollback steps and a status log. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>

- Name the operator-key path (credential file, endpoint, header) and the file each required relay/supervisor/control-plane variable lives in. - Note which secrets and URLs setup-vm.sh sets for you, and that workers refuse to boot on SH_EXCHANGE_TOKEN in supervisor.env. - Map SH_MODEL and SH_MODEL_PROVIDER (same names, set on the supervisor). - Order sections Bring-up, Rolling back, During the window, Status log, and link the forward/backward references. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>

GitHub Discussions are disabled on this repo, so the three feedback links in the migration guide 404ed. Repoint them at the pinned tracking issue. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>

pdettori requested a review from cwiklik as a code owner October 12, 2026 12:45

pdettori added the ready-for-ai-review label Oct 12, 2026

ingpaolodettori-dev approved these changes Oct 12, 2026

View reviewed changes

pdettori added 2 commits October 12, 2026 10:19

pdettori force-pushed the docs/migration-guide-pr2 branch from d283a64 to 8c8cb53 Compare October 12, 2026 14:20

pdettori merged commit 708aa05 into rossoctl:main Oct 12, 2026
13 checks passed

pdettori mentioned this pull request Oct 12, 2026

docs: docs index, install chooser, style guide and link check (PR 3 of REORG-PLAN) #491

Merged

Navigation Menu

Repository navigation

docs: complete the Knative migration guide (PR 2 of REORG-PLAN) - #489

docs: complete the Knative migration guide (PR 2 of REORG-PLAN)#489
pdettori merged 3 commits into
rossoctl:mainfrom
pdettori:docs/migration-guide-pr2

pdettori commented Oct 12, 2026 •

edited

Loading

Uh oh!

ingpaolodettori-dev left a comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

pdettori commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Complete the Knative/KEDA migration guide (PR 2 of the docs reorg)

Added

Please check

Verification

Update after review

Uh oh!

ingpaolodettori-dev left a comment

Choose a reason for hiding this comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

ingpaolodettori-dev Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pdettori commented Oct 12, 2026 •

edited

Loading