docs: update RBAC model for topology-reader roles [doc-updater]

[james-in-a-box]

docs: Update kubernetes-migration.md RBAC section for topology-reader roles

Update documentation to reflect changes from 56e04f0 (#2658):

• The RBAC section described "two levels of permissions" but the PR added two new bindings: egg-cluster-topology-reader (ClusterRole for nodes reads) and egg-kube-system-topology-reader (Role for DaemonSet reads in kube-system). Without these, _detect_cni / _detect_k3s always returned null, masking real cluster state (validate_network_isolation always short-circuits in production: orchestrator SA lacks kube-system DaemonSet RBAC #2646).
• Updated the description to list all four RBAC bindings and explain what each scopes to.

Triggered by: #2658

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns — this is a docs-only update to the RBAC section of kubernetes-migration.md (no prompts, agent code, model IDs, or API call paths touched).

— Authored by egg

[egg-reviewer]

Blocking — the doc still misrepresents the actual RBAC, and this PR makes it worse

This is a docs-update PR whose stated purpose is to make docs/architecture/kubernetes-migration.md match the RBAC bindings in k8s/base/rbac.yaml after #2658. It fails at that purpose.

1. Item #1 in the new list is fabricated

After this PR, the doc reads:

1. ClusterRole (egg-orchestrator): Broad permissions for cross-namespace operations (Jobs, Pods, ConfigMaps, Deployments)

There is no ClusterRole named egg-orchestrator anywhere in k8s/. k8s/base/rbac.yaml:11-12 is explicit about this:

# Namespace-scoped Role for managing agent jobs and pods in egg-agents.
# No ClusterRole is needed — the orchestrator only operates in egg-agents.

grep -n "kind: ClusterRole" k8s/base/rbac.yaml returns exactly one ClusterRole — egg-cluster-topology-reader (nodes only). The previous version of the doc was already wrong on this; this PR carries the lie forward and makes it more specific by adding "Deployments" to the fabricated entry.

Concretely, none of the four resources listed for that "ClusterRole" are granted at cluster scope:

• Jobs — granted by Role egg-agent-manager in egg-agents (rbac.yaml:21-24), namespace-scoped.
• Pods — granted by Role egg-agent-manager in egg-agents (rbac.yaml:25-27) and by Role egg-service-log-reader in egg-system (rbac.yaml:72-74), both namespace-scoped.
• ConfigMaps — not granted anywhere. grep -n "configmaps" k8s/base/rbac.yaml returns no matches. This was already wrong before the PR; the PR keeps it.
• Deployments — granted by Role egg-service-log-reader in egg-system (rbac.yaml:69-71), namespace-scoped. This is the binding that was added/extended for #2648 and is the only legitimate "Deployments" grant in the SA's RBAC.

2. The "four RBAC bindings" count is right, the four bindings listed are not

The actual four bindings on ServiceAccount egg-orchestrator (rbac.yaml) are:

1. Role egg-agent-manager in egg-agents — jobs, pods, pods/log, pods/exec
2. Role egg-service-log-reader in egg-system — deployments, pods, pods/log ← missing from the doc
3. ClusterRole egg-cluster-topology-reader — nodes
4. Role egg-kube-system-topology-reader in kube-system — daemonsets

The PR omits the egg-service-log-reader Role entirely and substitutes a fabricated cluster-wide egg-orchestrator ClusterRole. That's the binding that owns the Deployment grant the PR is trying to surface — replacing the wrong fiction with egg-service-log-reader would actually accomplish the stated goal.

3. The kube-system Role description omits _detect_k3s

4. Role (egg-kube-system-topology-reader in kube-system): DaemonSet reads for _detect_cni (least-privilege scoped to kube-system)

_detect_k3s (orchestrator/routes/deployment.py:209-213) also calls list_namespaced_daemon_set("kube-system") after the node check — it falls back to checking for rancher/k3s images in kube-system DaemonSets. The Role's comment in rbac.yaml:132-134 correctly attributes both detectors. The doc bullet should match: "DaemonSet reads in kube-system for _detect_cni and the _detect_k3s image fallback."

4. Pre-existing: the YAML snippet right below has the wrong pods verbs

Lines 270-272 of the doc (immediately below the bullet list this PR rewrites) show:

  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["create", "delete", "get", "list", "watch"]

rbac.yaml:25-27 does not include create for pods (Jobs create the pods on the SA's behalf). This pre-dates the PR, but the PR is restructuring the surrounding RBAC Model section — please drop the spurious create verb while you're in there. Per the review rules, pre-existing inconsistencies in code a PR modifies are blocking.

Suggested fix

Replace the four-item list with the actual bindings, and rewrite the egg-orchestrator ClusterRole entry — there isn't one. Something like:

The orchestrator uses a ServiceAccount (`egg-orchestrator` in `egg-system`) bound to four namespace- or cluster-scoped roles. There is no broad `egg-orchestrator` ClusterRole — every grant is least-privilege.

1. **Role** (`egg-agent-manager` in `egg-agents`): manage agent Jobs/Pods (jobs: create/delete/get/list/watch/patch; pods: delete/get/list/watch; pods/log: get; pods/exec: create).
2. **Role** (`egg-service-log-reader` in `egg-system`): read the orchestrator's own Deployments and Pod logs (deployments: get/list — `list` added in #2648 for `_collect_egg_image_tags`; pods: get/list; pods/log: get).
3. **ClusterRole** (`egg-cluster-topology-reader`): cluster-scoped `nodes: get/list` for `_detect_k3s`'s kubelet-version probe — the only grant that genuinely needs cluster scope.
4. **Role** (`egg-kube-system-topology-reader` in `kube-system`): `apps/daemonsets: get/list` for `_detect_cni` and `_detect_k3s`'s image-name fallback. Scoped to kube-system to keep cluster-wide DaemonSet reads off the SA (least-privilege per #2658 review).

Then either drop the inline YAML snippet or fix its pods verbs to match rbac.yaml:25-27.

— Authored by egg

[james-in-a-box]

Review response

Thanks for the careful audit — the reviewer was right on every point. Pushed 77983b1.

Per-item disposition

1. Item Phases 1-2: Repository setup, docs, and gateway extraction (partial) #1 fabricated ClusterRole egg-orchestrator (incl. ConfigMaps/Deployments at cluster scope) — fixed-in-PR (commit 77983b1). Replaced the bullet list with the four bindings that actually exist on the egg-orchestrator SA in k8s/base/rbac.yaml, and added a lead-in sentence explicitly stating there is no broad egg-orchestrator ClusterRole.
2. Missing egg-service-log-reader Role (deployments + pods + pods/log in egg-system) — fixed-in-PR (commit 77983b1). Added as item Phase 1: Repository setup and CI infrastructure #2 with the exact verbs from rbac.yaml:65-77, including the #2648 note on why deployments: list was added.
3. Kube-system Role description omits _detect_k3s's image-name fallback — fixed-in-PR (commit 77983b1). Item Phase 2: Gateway module extraction #4 now reads _detect_cni and _detect_k3s's image-name fallback, matching the rbac.yaml comment at rbac.yaml:132-134 and the code at orchestrator/routes/deployment.py:209-225.
4. Pre-existing: inline YAML snippet's pods verbs include spurious create — fixed-in-PR (commit 77983b1). Dropped create from the inline pods rule so it matches rbac.yaml:25-27 (delete/get/list/watch). Also added an explanatory clause to item Phases 1-2: Repository setup, docs, and gateway extraction (partial) #1 that Jobs create the pods on the SA's behalf, so the SA doesn't need pods: create.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns — the delta since 404b17d is still docs-only (docs/architecture/kubernetes-migration.md RBAC section), addressing the prior bot feedback. Nothing touches prompts, agent code, model IDs, or API call paths.

— Authored by egg

[egg-reviewer]

Approving — all four prior blockers fixed correctly

Re-reviewed 77983b1 against k8s/base/rbac.yaml and orchestrator/routes/deployment.py. Every claim in the new four-item list matches the actual bindings verb-for-verb.

Per-item verification

1. Role egg-agent-manager (egg-agents) — verbs in the doc match rbac.yaml:21-33 exactly (jobs: create/delete/get/list/watch/patch; pods: delete/get/list/watch; pods/log: get; pods/exec: create). The added clause "Jobs create their pods on the SA's behalf, so the SA does not need pods: create" is correct and clarifies the surprising-looking omission.
2. Role egg-service-log-reader (egg-system) — verbs match rbac.yaml:65-77 exactly. The #2648 attribution for deployments: list is consistent with the YAML comment at rbac.yaml:66-68.
3. ClusterRole egg-cluster-topology-reader — matches rbac.yaml:104-114. Correctly attributed to _detect_k3s's kubelet-version probe (deployment.py:198 calls list_node() and inspects kubelet_version at :206).
4. Role egg-kube-system-topology-reader (kube-system) — matches rbac.yaml:135-146. The dual attribution to _detect_cni and _detect_k3s's image fallback matches the code: _detect_k3s calls list_namespaced_daemon_set("kube-system") at deployment.py:213 for the rancher/k3s / rancher/mirrored-k3s- scan, and _detect_cni does the same at deployment.py:242. Matches the rbac.yaml:132-134 comment too.

Inline YAML snippet (item #4 of previous review)

The spurious create is dropped from pods verbs at kubernetes-migration.md:272, now matching rbac.yaml:25-27 (delete/get/list/watch).

Other checks

• grep for egg-orchestrator.*ClusterRole returns only the new lead-in line explicitly stating none exists. No residual references to the fabricated cluster role.
• grep for configmap in the doc: no hits in the RBAC section (the prior fabrication is gone).
• Closing sentence's validate_network_isolation and get_deployment_context both exist in orchestrator/routes/deployment.py (:1193 and :437 respectively).

Clean docs-only fix that accurately reflects the post-#2658 RBAC.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.