docs(oidc): add self-signed certificates configuration guide#443
docs(oidc): add self-signed certificates configuration guide#443IvanHunters merged 3 commits intomainfrom
Conversation
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughTwo new documentation files added covering OIDC configuration with self-signed certificates for Kubernetes, providing step-by-step guides for both v0 and v1 implementations including certificate retrieval, control plane configuration, and kubelogin setup. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the Cozystack documentation by introducing a detailed guide for configuring OIDC authentication with self-signed certificates, a crucial feature for environments with custom CAs. Concurrently, it updates the core configuration documentation to introduce and explain the new Package-based configuration model for Cozystack v1.x, providing a clear transition path from the older ConfigMap approach and improving the overall clarity and structure of the configuration guides. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
Add documentation for configuring OIDC authentication with Keycloak when using self-signed certificates (default in Cozystack). Covers Talos machine configuration, certificate mounting, and kubelogin setup. Signed-off-by: ohotnikov.ivan <[email protected]>
…y approach Address review feedback: use --certificate-authority flag as the default approach instead of --insecure-skip-tls-verify, clarify that LetsEncrypt is the default in Cozystack (not self-signed), and document insecure skip as a temporary workaround only. Signed-off-by: ohotnikov.ivan <[email protected]>
![gemini-code-assist[bot]](proxy.php?url=https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive guide for configuring OIDC with self-signed certificates and updates existing documentation to align with the new Package-based configuration model in Cozystack v1.x. The new documentation is well-structured and the updates are necessary. My review focuses on improving the clarity and robustness of the documentation to prevent potential user errors, particularly around the usage of kubectl patch which can have unintended consequences if not explained clearly.
Note: Security Review has been skipped due to the limited scope of the PR.
| ```bash | ||
| kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{ | ||
| "spec": { | ||
| "components": { | ||
| "platform": { | ||
| "values": { | ||
| "publishing": { | ||
| "exposedServices": ["api", "dashboard", "keycloak"] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }' |
There was a problem hiding this comment.
The section title "Add Keycloak to exposed services" is misleading. The provided kubectl patch command uses --type merge, which replaces the entire exposedServices array rather than adding to it. This could cause users to unintentionally remove other essential services like vm-exportproxy and cdi-uploadproxy. Please clarify that this is a replacement operation and advise users to include all services they want to expose in the command. A better title would be "Update Exposed Services".
|
|
||
| ```bash | ||
| # Save the certificate to a file (e.g., ~/.kube/oidc-ca.pem) | ||
| cat > ~/.kube/oidc-ca.pem <<EOF |
There was a problem hiding this comment.
The command cat > ~/.kube/oidc-ca.pem will fail if the ~/.kube directory does not exist, which can happen on a new machine. To make the guide more robust for all users, it's best to ensure the directory is created before attempting to write a file into it. Please consider adding a mkdir -p ~/.kube command before this line.
| joinCIDR: "100.64.0.0/16" | ||
| publishing: | ||
| host: "example.org" | ||
| apiServerEndpoint: "https://192.168.1.10:6443" |
There was a problem hiding this comment.
The minimal configuration example uses an IP address for apiServerEndpoint. However, the installation guide (install-cozystack.md) and general best practices recommend using a fully-qualified domain name (FQDN). Using an FQDN here would improve consistency across the documentation and reduce potential user confusion.
| apiServerEndpoint: "https://192.168.1.10:6443" | |
| apiServerEndpoint: "https://api.example.org:6443" |
| ```bash | ||
| kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{ | ||
| "spec": { | ||
| "components": { | ||
| "platform": { | ||
| "values": { | ||
| "bundles": { | ||
| "disabledPackages": ["clickhouse"] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }' |
There was a problem hiding this comment.
Similar to the exposedServices patch, this command to disable a package replaces the entire disabledPackages array. If a user has already disabled other packages, running this command will re-enable them unless they are also included in the new list. Please clarify that this is a replacement operation and advise users to include all packages they wish to keep disabled in the command.
| ```bash | ||
| kubectl get package cozystack.cozystack-platform -n cozy-system \ | ||
| -o jsonpath='{.spec.components.platform.values}' | yq |
There was a problem hiding this comment.
This command relies on the yq utility to parse the YAML output. This tool is not standard on all systems and may not be installed. It would be helpful to add a note mentioning that yq is a prerequisite for this command and provide a link to its installation instructions to improve the user experience.
Move the guide from the unversioned docs/operations/oidc/ path to both v0 and v1 versioned directories, matching the existing OIDC documentation structure. Add aliases for old paths. Co-Authored-By: Claude <[email protected]> Signed-off-by: ohotnikov.ivan <[email protected]>
![coderabbitai[bot]](proxy.php?url=https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
content/en/docs/v1/getting-started/install-cozystack.md (2)
608-621:⚠️ Potential issue | 🟠 MajorThe dashboard fallback still uses the removed ConfigMap flow.
This tutorial now defines service exposure via
publishing.exposedServices, so the fallback here should patch the Package as well. As written, a user who omitteddashboardfrom the initial Package will be told to modifycm/cozystack, which no longer matches the v1.x install path.Suggested doc fix
-If you left this line in the ConfigMap, Cozystack Dashboard must be already available at this moment: +If your initial Package already includes `dashboard` in `publishing.exposedServices`, Cozystack Dashboard should already be available: -```yaml -data: - expose-services: "dashboard,api" +```yaml +spec: + components: + platform: + values: + publishing: + exposedServices: + - dashboard + - api-If the initial configmap did not have this line, patch it with the following command:
+If the initial Package did not includedashboard, patch it with the following command:-kubectl patch -n cozy-system cm cozystack --type=merge -p '{"data":{ - "expose-services": "dashboard" - }}' +kubectl patch package cozystack.cozystack-platform -n cozy-system --type=merge -p '{ + "spec": { + "components": { + "platform": { + "values": { + "publishing": { + "exposedServices": ["dashboard"] + } + } + } + } + } +}'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/docs/v1/getting-started/install-cozystack.md` around lines 608 - 621, The docs currently instruct patching the ConfigMap key `data.expose-services` but v1 uses `spec.components.platform.values.publishing.exposedServices`; update the YAML example to show spec.components.platform.values.publishing.exposedServices: ["dashboard","api"] (replacing the ConfigMap fragment) and replace the kubectl patch command to target the Package resource `cozystack.cozystack-platform` in the `cozy-system` namespace, merging a payload that sets spec.components.platform.values.publishing.exposedServices to include "dashboard"; ensure the text change says "If the initial Package did not include `dashboard`, patch it with the following command" and remove references to `cm/cozystack`.
468-476:⚠️ Potential issue | 🟠 MajorUse the Package as the source of truth for external IP exposure.
This section still patches the legacy
cozystackConfigMap and the generated ingress resource directly, but the rest of this guide has already moved to v1.x Package-based configuration. In v1.x, these instructions should updatespec.components.platform.values.publishing.externalIPsonpackage/cozystack.cozystack-platform; otherwise the change can be ignored or reconciled away later.Suggested doc direction
-First, patch the ConfigMap with IPs to expose: +First, patch the Cozystack Package with the external IPs to expose: ```bash -kubectl patch -n cozy-system configmap cozystack --type=merge -p '{ - "data": { - "expose-external-ips": "192.168.100.11,192.168.100.12,192.168.100.13" - } +kubectl patch package cozystack.cozystack-platform -n cozy-system --type=merge -p '{ + "spec": { + "components": { + "platform": { + "values": { + "publishing": { + "externalIPs": [ + "192.168.100.11", + "192.168.100.12", + "192.168.100.13" + ] + } + } + } + } + } }'
-Next, enable
ingressfor the root tenant:
+Next, enableingressfor the root tenant:
...
-Finally, add external IPs to theexternalIPslist in the Ingress configuration:-```bash
-kubectl patch -n tenant-root ingresses.apps.cozystack.io ingress --type=merge -p '{
- "spec":{
- "externalIPs": [
"192.168.100.11","192.168.100.12","192.168.100.13"- ]
- }
-}'
-```
+The Package change above is the declarative source of truth, so there should be no extra manual patch against the generated ingress resource here.</details> Also applies to: 488-499 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@content/en/docs/v1/getting-started/install-cozystack.mdaround lines 468 -
476, The docs currently patch the legacy ConfigMap named cozystack and then the
generated Ingress; instead update the Package resource package
cozystack.cozystack-platform by setting
spec.components.platform.values.publishing.externalIPs to the array of IPs
(replace the kubectl patch of ConfigMap cozystack), and remove the separate
manual patch step against the generated ingresses.apps.cozystack.io ingress
resource since the Package is the declarative source of truth.</details> </blockquote></details> </blockquote></details>🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed. Outside diff comments: In `@content/en/docs/v1/getting-started/install-cozystack.md`: - Around line 608-621: The docs currently instruct patching the ConfigMap key `data.expose-services` but v1 uses `spec.components.platform.values.publishing.exposedServices`; update the YAML example to show spec.components.platform.values.publishing.exposedServices: ["dashboard","api"] (replacing the ConfigMap fragment) and replace the kubectl patch command to target the Package resource `cozystack.cozystack-platform` in the `cozy-system` namespace, merging a payload that sets spec.components.platform.values.publishing.exposedServices to include "dashboard"; ensure the text change says "If the initial Package did not include `dashboard`, patch it with the following command" and remove references to `cm/cozystack`. - Around line 468-476: The docs currently patch the legacy ConfigMap named cozystack and then the generated Ingress; instead update the Package resource package cozystack.cozystack-platform by setting spec.components.platform.values.publishing.externalIPs to the array of IPs (replace the kubectl patch of ConfigMap cozystack), and remove the separate manual patch step against the generated ingresses.apps.cozystack.io ingress resource since the Package is the declarative source of truth.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
6cd74601-1eea-421b-b594-7af357b90db0📒 Files selected for processing (4)
content/en/docs/operations/oidc/self-signed-certificates.mdcontent/en/docs/v1/getting-started/install-cozystack.mdcontent/en/docs/v1/operations/configuration/configmap.mdcontent/en/docs/v1/operations/configuration/package.md
IvanHunters
force-pushed
the
docs/oidc-self-signed-certificates
branch
from
a7a20e4 to
11753cf
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
content/en/docs/v0/operations/oidc/self-signed-certificates.md (1)
1-6: Add aliases for backward compatibility.The v0 documentation files typically include aliases to maintain backward compatibility. Based on sibling pages like
enable_oidc.mdandusers_and_roles.md, this page should include aliases for/docs/v0/oidc/self-signed-certificates,/docs/operations/oidc/self-signed-certificates, and/docs/oidc/self-signed-certificates.📝 Proposed fix to add aliases
--- title: "Self-Signed Certificates" linkTitle: "Self-Signed Certificates" description: "How to configure OIDC with self-signed certificates" weight: 60 +aliases: + - /docs/v0/oidc/self-signed-certificates + - /docs/operations/oidc/self-signed-certificates + - /docs/oidc/self-signed-certificates ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/docs/v0/operations/oidc/self-signed-certificates.md` around lines 1 - 6, Add an "aliases" entry to the frontmatter of the Self-Signed Certificates page so it remains backward-compatible; update the frontmatter block (near title/linkTitle/description/weight) to include aliases for "/docs/v0/oidc/self-signed-certificates", "/docs/operations/oidc/self-signed-certificates", and "/docs/oidc/self-signed-certificates" using the aliases key so the page resolves from the older paths.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@content/en/docs/v0/operations/oidc/self-signed-certificates.md`:
- Line 113: Remove the unsupported "--exec-interactive-mode=IfAvailable" flag
from the kubelogin examples and explanations (specifically the kubectl config
set-credentials usage) so docs no longer suggest interactive mode; locate
occurrences of the flag string "--exec-interactive-mode" in the Markdown under
content/en/docs (including the example line shown) and delete them, and update
any surrounding text referring to interactive mode to state that interactive
mode is not supported for kubelogin.
In `@content/en/docs/v1/operations/oidc/self-signed-certificates.md`:
- Line 116: Remove the unsupported "--exec-interactive-mode=IfAvailable"
argument from the kubelogin usage example and any other occurrences in the doc;
update the kubectl config set-credentials examples that referenced kubelogin to
omit this flag entirely and add a brief note that interactive mode is not
supported for kubelogin so no --exec-interactive-mode option should be used.
---
Nitpick comments:
In `@content/en/docs/v0/operations/oidc/self-signed-certificates.md`:
- Around line 1-6: Add an "aliases" entry to the frontmatter of the Self-Signed
Certificates page so it remains backward-compatible; update the frontmatter
block (near title/linkTitle/description/weight) to include aliases for
"/docs/v0/oidc/self-signed-certificates",
"/docs/operations/oidc/self-signed-certificates", and
"/docs/oidc/self-signed-certificates" using the aliases key so the page resolves
from the older paths.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 12a75905-65dd-4950-8d16-bef3e85a0f7d
📒 Files selected for processing (2)
content/en/docs/v0/operations/oidc/self-signed-certificates.mdcontent/en/docs/v1/operations/oidc/self-signed-certificates.md
| ```bash | ||
| kubectl config set-credentials oidc \ | ||
| --exec-api-version=client.authentication.k8s.io/v1 \ | ||
| --exec-interactive-mode=IfAvailable \ |
There was a problem hiding this comment.
Remove unsupported --exec-interactive-mode flag.
The --exec-interactive-mode flag should be omitted entirely from kubelogin documentation as interactive mode is not supported. Based on learnings, when documenting kubelogin usage with kubectl config set-credentials, omit the --exec-interactive-mode option entirely. Do not include this flag in examples or explanations. If encountered in a doc, remove it and note that interactive mode is not supported. Apply this guideline to all Markdown docs under content to ensure consistent, accurate guidance.
🔧 Proposed fix to remove the flag
kubectl config set-credentials oidc \
--exec-api-version=client.authentication.k8s.io/v1 \
- --exec-interactive-mode=IfAvailable \
--exec-command=kubectl \
--exec-arg=oidc-login \📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --exec-interactive-mode=IfAvailable \ | |
| kubectl config set-credentials oidc \ | |
| --exec-api-version=client.authentication.k8s.io/v1 \ | |
| --exec-command=kubectl \ | |
| --exec-arg=oidc-login \ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@content/en/docs/v0/operations/oidc/self-signed-certificates.md` at line 113,
Remove the unsupported "--exec-interactive-mode=IfAvailable" flag from the
kubelogin examples and explanations (specifically the kubectl config
set-credentials usage) so docs no longer suggest interactive mode; locate
occurrences of the flag string "--exec-interactive-mode" in the Markdown under
content/en/docs (including the example line shown) and delete them, and update
any surrounding text referring to interactive mode to state that interactive
mode is not supported for kubelogin.
| ```bash | ||
| kubectl config set-credentials oidc \ | ||
| --exec-api-version=client.authentication.k8s.io/v1 \ | ||
| --exec-interactive-mode=IfAvailable \ |
There was a problem hiding this comment.
Remove unsupported --exec-interactive-mode flag.
The --exec-interactive-mode flag should be omitted entirely from kubelogin documentation as interactive mode is not supported. Based on learnings, when documenting kubelogin usage with kubectl config set-credentials, omit the --exec-interactive-mode option entirely. Do not include this flag in examples or explanations. If encountered in a doc, remove it and note that interactive mode is not supported. Apply this guideline to all Markdown docs under content to ensure consistent, accurate guidance.
🔧 Proposed fix to remove the flag
kubectl config set-credentials oidc \
--exec-api-version=client.authentication.k8s.io/v1 \
- --exec-interactive-mode=IfAvailable \
--exec-command=kubectl \
--exec-arg=oidc-login \📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --exec-interactive-mode=IfAvailable \ | |
| kubectl config set-credentials oidc \ | |
| --exec-api-version=client.authentication.k8s.io/v1 \ | |
| --exec-command=kubectl \ | |
| --exec-arg=oidc-login \ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@content/en/docs/v1/operations/oidc/self-signed-certificates.md` at line 116,
Remove the unsupported "--exec-interactive-mode=IfAvailable" argument from the
kubelogin usage example and any other occurrences in the doc; update the kubectl
config set-credentials examples that referenced kubelogin to omit this flag
entirely and add a brief note that interactive mode is not supported for
kubelogin so no --exec-interactive-mode option should be used.
2 participants
Summary
Test plan
Summary by CodeRabbit