docs(kubernetes): add OIDC authentication guide#596
Conversation
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>
IvanHunters
requested review from
Andrei Kvapil (kvaps) and
Timofei Larkin (lllamnyp)
as code owners
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 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.
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>
1 participant
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.