docs: make the admin guide usable by a university that is not TUM

[Mtze]

Stacked on #8. Depends on EduIDE-Helm#28 — the admin-token page documents service.adminApiTokenSecret.external, which that PR introduces.

An audit of all 16 admin pages against the current charts found the section largely describes the platform before the 2.0.0 restructure. 11 of 16 pages hardcoded a namespace that no longer exists, and roughly 70 commands would fail as written.

Two new pages — the ones an adopter needs first, and neither existed

Cluster Prerequisites. Gateway API, a Gateway controller, cert-manager with enableGatewayAPI=true (without it, HTTP-01 challenges never complete), storage, node disk budget for preloaded images, minimum Kubernetes version. Pinned commands throughout.

Certificates and DNS. Four hostnames per installation, one of them a wildcard. Why ACME cannot issue that over HTTP-01 — it's the specification, not a cert-manager limitation — and both remedies written out end to end: a DNS-01 solver, or bring your own certificate.

Verification gets its own section, because Gateway API never compares a certificate's names against the listener hostname. A wrong certificate reports Programmed=True. The only symptom is a browser warning, then the landing page silently failing its cross-origin call to its own REST service.

Two errors the docs were actively causing

• Only two of four Keycloak redirect URIs were listed. Login appears to work, then webviews fail to authenticate — surfacing days later as "previews are broken".
• ephemeralStorage was presented as an opt-in for demos. It defaults to true. A reader following that page believes student work persists when it does not.

Pages rewritten

Page	Why
provisioning.md	Stated the new truth then contradicted it on the same screen — seven deleted charts, deleted workflows, deleted directory layout. 202 lines → 60
upgrades.md	Duplicated the rollback and release-policy pages and got both wrong
intro.md	Environment table wrong in every column; never linked to the install pages
monitoring-basics.md	Built on a deleted chart and a Rancher-only stack; ServiceMonitors that are PodMonitors
garbage-collection.md	Documented as a standalone install; it is a subchart whose values are silently ignored if nested wrongly
admin-api-tokens.md	Assumed GitHub Actions; a CLI installer had no path at all

Commands that could never have worked

• kubectl logs -l app=oauth2-proxy — there is no such Deployment; it is a per-session sidecar
• kubectl get pvc --field-selector=status.phase=Released — Released is a PersistentVolume phase, so this always returns nothing
• kubectl rollout restart deployment/operator — it is operator-deployment
• Defaults stated wrongly: operator.replicas 3→1 (two pages had you paging yourself over a healthy cluster), sessionsPerUser 10→1, requestsMemory 2000M→500M

Added

Runbooks for the two newest failure surfaces — Gateway/HTTPRoute and a certificate that does not cover a hostname — and a decommissioning procedure, which was missing entirely.

Verified: structure check passes, every relative link resolves, all factual claims re-checked against charts/eduide/values.yaml directly.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5423903b-0e19-4355-b98d-2ed518da4389

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}