📝 docs(hive): document the hive-route-reader RBAC requirement - #6527
Open
clubanderson wants to merge 1 commit into
Open
📝 docs(hive): document the hive-route-reader RBAC requirement#6527clubanderson wants to merge 1 commit into
clubanderson wants to merge 1 commit into
Conversation
The hosted-spoke provisioning template in kubestellar/hive gained a namespace-scoped read-only hive-route-reader Role + RoleBinding (hive#3846). This page is a fork of that repo's v2/docs/manual-provisioning.md and does not auto-sync, so it still described the pre-change object set. Without the Role the spoke cannot read its own Route/Ingress, so it falls back to synthesising "<hiveID>.<hub host>" — correct only for spokes fronted by the hub's own wildcard domain, and a guaranteed 503 anywhere else, because the wildcard hands the name to the HUB's router, which has no backend for a hive on another cluster. DNS resolves, so it looks healthy. Live outage on vllm-d. - A.3: the automated path emits it, so it is not deleted as unused. - B.2: the Role + RoleBinding YAML in the existing inline-flow-mapping style, the rationale, and the read-only / namespace-scoped security argument. - Fix the object inventory, which said "two Roles ... three RoleBindings". - Gotcha: derive the ServiceAccount from the hive Deployment. The subject is NOT uniform — SCC spokes bind hive-sa, others bind default. Measured live: hive-oke 22x default; vllm-d 2x default + 41x hive-sa; a-ks-wec2 5x hive-sa. An empty serviceAccountName means "default", not the empty string. - Gotcha: pre-existing namespaces need it retroactively; new ones get it free. - Failure-mode table: the 503 dashboard-link row. Surgical RBAC-only insert. The two copies have intentionally diverged elsewhere (image tag, placeholder app_id prose) and those are left alone. Signed-off-by: Andrew Anderson <andy@clubanderson.com>
kubestellar-prow
Bot
added
the
dco-signoff: yes
✅ Deploy Preview for kubestellar-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
kubestellar-prow
Bot
added
the
size/L
github-actions
Bot
added
the
documentation
Contributor
📖 Preview LinksThe following documentation pages were changed in this PR:
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Hive manual provisioning documentation to include and justify the new namespace-scoped read-only hive-route-reader Role/RoleBinding required for spokes to discover and report their served Route/Ingress hostname (preventing incorrect dashboard links and branded 503s).
Changes:
- Adds an “A.3” section explaining that the provisioning template emits
hive-route-reader, why it’s required, and when retrofits are needed. - Updates the manual provisioning RBAC inventory and includes the
hive-route-readerRole + RoleBinding YAML plus operational gotchas. - Extends the failure-mode reference with a 503/dashboard-link symptom tied to missing
hive-route-readerRBAC.
Suppressed comments (1)
docs/content/hive/manual-provisioning.md:754
- This failure-mode row says the hub falls back, but in the detailed section below the spoke is described as performing the fallback when it can't read Route/Ingress. Make the wording consistent so operators know where to look when debugging.
| Hive online, but **My Hives → Dashboard** returns a branded **503**; the link reads `<hive-id>.<hub-host>` instead of the spoke cluster's own domain | Missing `hive-route-reader` RBAC, so the spoke can't read its own Route/Ingress and the hub falls back to the hub-wildcard host, which has no backend for a hive on another cluster | Apply the `hive-route-reader` Role + RoleBinding, binding the SA the hive Deployment actually uses (see [B.2](#hive-route-reader--why-the-dashboard-link-503s-without-it)), then `rollout restart deploy/hive` |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| It is **not** unused. The spoke reads its own Route/Ingress through it to learn | ||
| the hostname it actually serves, and reports that to the hub as `dashboard_url`. | ||
| Remove it and the hub falls back to synthesising `<hiveID>.<hub host>`, which |
Comment on lines
+263
to
+264
| #### `hive-route-reader` — why the dashboard link 503s without it | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to kubestellar/hive#3849. Documents the namespace-scoped read-only
hive-route-readerRole + RoleBinding added to the hosted-spoke provisioning template by kubestellar/hive#3846 (3aa8d8f7).Where this went, and why
docs/content/hive/manual-provisioning.md— the only page in this repo that enumerates spoke-namespace RBAC, and the only place documenting spoke provisioning at all. It is a fork ofv2/docs/manual-provisioning.mdinkubestellar/hiveand does not auto-sync, so it still described the pre-change object set. This is not an ambiguous placement: the page already lists the exact Roles and RoleBindings to apply, and that list was incomplete.It is registered in nav at
src/app/docs/page-map.ts:348under Operations, which needs no change.Note the two copies have intentionally diverged elsewhere — this one pins
ghcr.io/kubestellar/hive:stablewhere upstream usesv2-latest, and upstream carries extra placeholder-app_idprose. I did a surgical RBAC-only insert rather than re-syncing the file, so those divergences are untouched.Why it matters
Without the Role the spoke cannot read its own Route/Ingress, so it falls back to synthesising
<hiveID>.<hub host>. That is correct only for spokes fronted by the hub's own wildcard domain, and a guaranteed 503 anywhere else — the wildcard resolves, so DNS looks healthy, but it hands the name to the hub's router, which has no backend for a hive on another cluster. This was a live user-visible outage on the vllm-d pool.Strictly read-only and namespace-scoped, so a compromised spoke learns only its own hostname — which it already advertises — and can neither create nor retarget routing.
The subject is not uniform
The part most likely to be got wrong by hand. The template binds
hive-saon OpenShift (SCC) clusters anddefaultelsewhere. Measured live, read-only:defaultdefaultand 41×hive-sahive-savllm-d alone needs both. The page now says to derive it from the hive Deployment rather than assume, and notes an empty
serviceAccountNamemeansdefault, not the empty string. Binding the wrong subject fails silently — the pod runs, the read is denied, you get the 503 fallback with no obvious error.Changes
Existing namespaces provisioned before this change need it applied retroactively (in progress across the fleet). New provisions get it automatically.
Verification
Read the template and
SpokeServedHostin the hive repo rather than working from a summary; the code matched. Live state confirmed read-only — no cluster writes.