docs(kubernetes): add OIDC authentication guide - #596
Conversation
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Warning Review limit reached
Next review available in: 43 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdds a new documentation page describing OIDC-based kubectl authentication for Cozystack-managed Kubernetes clusters, covering per-cluster audience isolation, OIDC modes, configuration examples, kubeconfig retrieval, sign-in flow, cleanup behavior, prerequisites, and out-of-scope items. ChangesOIDC Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation for configuring OIDC authentication for kubectl in tenant Kubernetes clusters, detailing the System, CustomConfig, and None modes. The review feedback suggests minor corrections to the documentation for accuracy, specifically clarifying that the issuer is tenant-supplied rather than operator-supplied in CustomConfig mode, and correcting the schema path reference for the certificate authority.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| name: acme-byo-authn-config # Secret with a `config.yaml` key holding the AuthenticationConfiguration | ||
| ``` | ||
|
|
||
| Setting both `config` and `secretRef.name` (or neither) fails the render. In `CustomConfig` mode no Keycloak objects are provisioned in `cozy`; the tenant apiserver trusts the operator-supplied issuer directly. |
There was a problem hiding this comment.
In CustomConfig mode, the tenant apiserver trusts the tenant-supplied (or user-supplied) issuer directly, rather than the "operator-supplied" issuer (since the operator does not provision Keycloak objects or supply the issuer in this mode). Consider updating "operator-supplied" to "tenant-supplied" for clarity.
|
|
||
| - **Don't mix with legacy `--oidc-*` flags.** The tenant kube-apiserver refuses to boot if both `--authentication-config` (injected by `spec.oidc`) and any legacy `--oidc-*` flag are set. If you previously wired OIDC by hand through `controlPlane.apiServer.extraArgs`, remove those flags before enabling `spec.oidc`. The chart fails the render with a pointer to this migration. | ||
| - **`oidc-login` plugin required.** Without `kubectl krew install oidc-login` the exec block errors out client-side. The plugin is a documented prerequisite. | ||
| - **Custom issuer with a self-signed CA.** In `CustomConfig` mode you can supply the CA inline under `issuer.certificateAuthority`. The legacy `--oidc-*` flag path could not. |
There was a problem hiding this comment.
In CustomConfig mode, the CA is supplied under certificateAuthority at the JWT authenticator level, not under issuer.certificateAuthority. Consider updating the text to refer to certificateAuthority or jwt[].certificateAuthority to match the schema.
## Summary Adds a new guide under `content/en/docs/next/operations/services/monitoring/`: **OIDC authentication for Grafana**. Documents how to enable per-user OIDC authentication on the Grafana instance shipped by every `Monitoring` release, using the new `spec.oidc` selector. Ships alongside [cozystack/cozystack#3176](cozystack/cozystack#3176), the code PR that adds the selector to the chart. The identity model is per-instance audience isolation on the flat `cozy` realm — same shape as the tenant kube-apiserver's Phase 1 ([cozystack/cozystack#3044](cozystack/cozystack#3044)); architectural rationale in [cozystack/community#24](cozystack/community#24). ## What - New page `content/en/docs/next/operations/services/monitoring/oidc-authentication.md` (`weight: 5`, positioned between `setup.md` (2) and `dashboards.md` (10)). - Covers all three modes (`None`, `System`, `CustomConfig`), the three role-mapping `KeycloakRealmGroup`s the chart owns, how a user is added via `KeycloakRealmUser`, browser login flow, and gotchas: `emailVerified` prescriptive requirement, self-signed CA under `CustomConfig.secretRef`, `admin_user` break-glass posture. - Explicit "out of scope" section (per-tenant realms, backend-logout-url, CEL `claimValidationRules`) so readers know where the boundary sits. - Only adds to `docs/next/`; version-specific pages (`v1.5`, ...) get the guide when the code PR lands in a release. ## Why - The `spec.oidc` selector on the `Monitoring` CR is a new user-facing surface — needs a user-facing guide before v1.6. - Uses the same tone and section shape as the tenant Kubernetes OIDC page (`content/en/docs/next/kubernetes/oidc-authentication.md`, #596), so operators land on a familiar layout. - Site builds cleanly in dev mode (Hugo, 1686+ pages, zero warnings); the page is reachable at `/docs/next/operations/services/monitoring/oidc-authentication/`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a comprehensive OIDC authentication guide for Monitoring Grafana, including per-instance audience isolation to prevent token reuse across instances. * Documented OIDC modes (`None`, `System`, `CustomConfig`), required Grafana `auth.generic_oauth` settings, and group-based access control via namespace-scoped authorization with `groups_attribute_path`. * Explained `System` Keycloak artifact provisioning and automated user/role syncing, plus the forced Grafana behaviors when OIDC users are configured. * Detailed `CustomConfig` validation/precedence, key gotchas (e.g., `emailVerified`), CA/tls guidance, and how switching modes affects user reconciliation. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
Guide covers spec.oidc modes (None/System/CustomConfig), kubeconfig retrieval, toggle-off cleanup, prerequisites, common gotchas, and out-of-scope items. Placed under docs/next/; ships alongside the code PR that adds the selector. Signed-off-by: IvanHunters <xorokhotnikov@gmail.com>
When `username.claim` is `email` the tenant kube-apiserver rejects tokens with `email_verified: false` (kubernetes/kubernetes#123737). Add a gotcha entry so operators provisioning cozy-realm users through KeycloakRealmUser or the Keycloak UI set `emailVerified: true` before granting cluster access, avoiding a silent "oidc: email not verified" at login. Signed-off-by: IvanHunters <xorokhotnikov@gmail.com>
The tenant kube-apiserver receives no claimValidationRules from the Phase 1 chart, so the previous wording that suggested the chart enforces email_verified overstated the guarantee. Rewrite the bullet to describe the actual layered mechanism: prescriptive emailVerified at provisioning, cozy realm's default duplicateEmails: false, k8s upstream side-effect on explicit false, and CEL claimValidationRules as a follow-up hardening path. Signed-off-by: IvanHunters <xorokhotnikov@gmail.com>
The three commits above were written against next/ in early July, when v1.6 did not exist yet. next/ is excluded from production builds, so landing them alone would merge the guide without making it reachable — the same way #597 merged the Grafana OIDC guide into next/ only and left it invisible on cozystack.io for three weeks. Copy the page into v1.6/ verbatim, so the two stay byte-identical. weight: 45 places it between the section index and GPU sharing. The modes (None, System, CustomConfig) and roles (admin, view) it documents were re-checked against packages/apps/kubernetes values.schema.json on main and still match exactly. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
In CustomConfig mode the chart provisions no Keycloak objects and does not supply the issuer, the tenant does. Calling it operator-supplied was the wrong way round. Raised by gemini-code-assist on #596 and left unaddressed there. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
865b708 to
526de66
Compare
|
IvanHunters I rebased this onto main and force-pushed, it was 143 commits behind so it would not merge as it was. Your three commits are cherry-picked unchanged, authorship and sign-offs kept. Sorry for touching your branch, tell me if you would rather own the rest of it. Two commits on top. First one copies the page into Second one applies the first gemini comment, The other gemini comment is wrong, no change made. Modes and roles rechecked against |
2 participants
Summary
Adds a new guide under
content/en/docs/next/kubernetes/: OIDC authentication for kubectl.Documents how to enable per-user OIDC authentication and RBAC on tenant Kubernetes clusters via the new
spec.oidcselector on theKubernetesresource. Covers all three modes (None,System,CustomConfig), how to retrieve and use the chart-generated kubeconfig, the toggle-off cleanup mechanic, prerequisites, gotchas (legacy--oidc-*flag collision), and what is deliberately out of scope for this feature (per-tenant realms, IdP federation intocozy, cross-cluster SSO).Ships alongside cozystack/cozystack#3044, the code PR that adds the
spec.oidcselector to theKuberneteschart. Full architectural rationale lives in cozystack/community#24.Only adds to
docs/next/; version-specific pages (v1.5, ...) get the guide when the code PR lands in that release.Test plan
HUGO_ENVIRONMENT=development hugorenders the site cleanly (1686 pages, zero warnings); page reachable at/docs/next/kubernetes/oidc-authentication/.weight: 45sits between the section index (40) andgpu-sharing.md(50); appears in the intended sidebar slot.spec.oidc.mode: System,CustomConfiginline,CustomConfigsecretRef,kubectl krew install oidc-login) verified end-to-end on a dev cluster against the code PR.docs/next/is skipped by the production build (as designed viaconfig/production/hugo.yaml); Netlify deploy-preview will show it.Summary by CodeRabbit
kubectlauthentication in Cozystack-managed Kubernetes clusters.spec.oidc.modeoptions, and provides configuration examples for platform-managed and custom identity providers.