docs(oidc): document private CA and staging trust - #650
Conversation
Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com> Assisted-By: Claude <noreply@anthropic.com> Assisted-By: GPT-5 <noreply@openai.com>
📝 WalkthroughWalkthroughThe OIDC documentation now covers internal Keycloak routing, private and staging certificates, wildcard issuance, cluster trust configuration, client setup, verification, CA rotation, and troubleshooting. ChangesOIDC certificate and routing documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Suggested reviewers: 🚥 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 |
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@content/en/docs/next/operations/oidc/self-signed-certificates.md`:
- Around line 272-276: The kube-apiserver inspection commands only examine the
first pod via .items[0]. Update both kubectl jsonpath expressions to iterate
over .items[*] and include each pod’s name in the output, so OIDC arguments and
ca-certificates mounts are checked across every control-plane node.
- Around line 77-96: Update the development-root-ca Certificate manifest to
explicitly disable renewal using spec.renewal.policy: Disabled when supported by
the deployed cert-manager version. If that field is unavailable, document the
existing CA overlap procedure and instruct operators to follow it before
renewal; do not rely on privateKey.rotationPolicy to control certificate
renewal.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: f16b32e4-e307-41f7-9947-5a85b9738dc6
📒 Files selected for processing (2)
content/en/docs/next/operations/oidc/enable_oidc.mdcontent/en/docs/next/operations/oidc/self-signed-certificates.md
| ```yaml | ||
| machine: | ||
| network: | ||
| extraHostEntries: | ||
| - ip: <KEYCLOAK_INGRESS_IP> | ||
| aliases: | ||
| - keycloak.example.org | ||
| files: | ||
| - content: | | ||
| -----BEGIN CERTIFICATE----- | ||
| <YOUR_CERTIFICATE_CONTENT> | ||
| -----END CERTIFICATE----- | ||
| permissions: 0o644 | ||
| path: /var/oidc-ca.crt | ||
| op: create | ||
| apiVersion: cert-manager.io/v1 | ||
| kind: Certificate | ||
| metadata: | ||
| name: development-root-ca | ||
| namespace: cozy-cert-manager | ||
| spec: | ||
| isCA: true | ||
| commonName: Cozystack development root CA | ||
| subject: | ||
| organizations: | ||
| - Cozystack development | ||
| secretName: development-root-ca | ||
| duration: 87600h | ||
| privateKey: | ||
| algorithm: ECDSA | ||
| size: 256 | ||
| issuerRef: | ||
| name: selfsigned-cluster-issuer | ||
| kind: ClusterIssuer |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
kubectl -n cozy-cert-manager get certificate development-root-ca \
-o jsonpath='{.spec.duration}{"\n"}{.spec.renewBefore}{"\n"}{.spec.renewal.policy}{"\n"}{.status.renewalTime}{"\n"}'Repository: cozystack/website
Length of output: 200
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
file="content/en/docs/next/operations/oidc/self-signed-certificates.md"
printf '%s\n' '--- target section ---'
sed -n '60,110p' "$file"
printf '%s\n' '--- rotation and renewal references ---'
rg -n -C 5 'development-root-ca|renew|rotation|overlap|281|291' "$file"
printf '%s\n' '--- repository references to cert-manager renewal fields ---'
rg -n -S 'renewBefore|renewalPolicy|renewal\.policy|rotationPolicy|privateKey:' . \
-g '*.md' -g '*.yaml' -g '*.yml' -g '*.json' || trueRepository: cozystack/website
Length of output: 5339
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
file="content/en/docs/next/operations/oidc/self-signed-certificates.md"
printf '%s\n' '--- target section ---'
sed -n '60,110p' "$file"
printf '%s\n' '--- rotation and renewal references ---'
rg -n -C 5 'development-root-ca|renew|rotation|overlap' "$file"
printf '%s\n' '--- repository references to cert-manager renewal fields ---'
rg -n -S 'renewBefore|renewalPolicy|renewal\.policy|rotationPolicy|privateKey:' . \
-g '*.md' -g '*.yaml' -g '*.yml' -g '*.json' || trueRepository: cozystack/website
Length of output: 5339
🌐 Web query:
cert-manager Certificate disable automatic renewal renewal policy self-signed CA duration renewBefore official documentation
💡 Result:
In cert-manager, you can manage and disable automatic certificate renewal using the Certificate resource's specification [1]. To disable automatic renewal for a Certificate, you can set the renewal policy to Disabled in your manifest [1]: spec: renewal: policy: Disabled This setting prevents cert-manager from automatically renewing the certificate [1]. It is often used for manually managed root or intermediate CA certificates where automatic rotation is not desired [1]. Key concepts regarding renewal and duration: Renewal Policy and Timing: cert-manager determines when to renew a certificate based on its duration and the configured renewal window [1][2]. By default, renewal occurs at 2/3 of the certificate's duration [3]. You can control this timing using: - renewBefore: Specifies the absolute duration before expiry to trigger renewal [4][2]. - renewBeforePercentage: Specifies a relative percentage of the certificate's total duration before expiry to trigger renewal [4]. Self-Signed CA Duration: When using a SelfSigned issuer to bootstrap a CA, you define the duration in the Certificate spec (e.g., spec: duration: 87600h) [1]. Note that cert-manager does not provide automatic rotation for CA certificates stored in Secrets [5]. If you use a long-lived self-signed CA, you must plan for manual rotation or replacement [5][6]. If a CA certificate is near expiry, leaf certificates signed by it will not automatically be re-issued unless you manually trigger the process or manage the rotation carefully [5]. Manual Reissue: Even when automatic renewal is disabled (via policy or other means), you can still manually trigger a certificate reissue by deleting the associated Secret or using tools like cmctl [1][7][8]. Note: Ensure your duration and renewBefore values are specified using valid Go duration strings (e.g., 8760h, 30m, 1h), avoiding unsupported suffixes like 'd' for days [2][9]. The minimum accepted renewBefore value is 5 minutes [4][2].
Citations:
- 1: https://cert-manager.io/docs/usage/certificate/
- 2: https://cert-manager.io/v1.5-docs/usage/certificate/
- 3: https://cert-manager.io/docs/faq/
- 4: https://cert-manager.io/docs/reference/api-docs/
- 5: https://cert-manager.io/docs/configuration/ca/
- 6: CA cert in Secret not updated when self-signed CA itself gets renewed. cert-manager/cert-manager#5851
- 7: feat: add annotation to disable certificate reissue cert-manager/cert-manager#8091
- 8: Feature Request: Add annotation to disable automatic certificate renewal cert-manager/cert-manager#8085
- 9: https://cert-manager.io/v1.4-docs/usage/certificate/
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
for url in \
'https://cert-manager.io/docs/usage/certificate/' \
'https://cert-manager.io/docs/configuration/ca/' \
'https://cert-manager.io/docs/reference/api-docs/' \
'https://raw.githubusercontent.com/cert-manager/cert-manager/master/deploy/crds/crd-certmanager.io_certificates.yaml'
do
printf '\n--- %s ---\n' "$url"
curl -L --fail --silent --show-error "$url" |
rg -in -C 3 'renewal policy|renewBefore|renewalPolicy|rotationPolicy|automatically renew|CA certificate|does not.*renew|isCA' |
head -n 120 || true
doneRepository: cozystack/website
Length of output: 50374
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
tmp="$(mktemp)"
trap 'rm -f "$tmp"' EXIT
curl -L --fail --silent --show-error \
'https://raw.githubusercontent.com/cert-manager/cert-manager/master/deploy/crds/crd-certmanager.io_certificates.yaml' \
>"$tmp"
printf '%s\n' '--- renewal schema ---'
python3 - "$tmp" <<'PY'
import sys, yaml
with open(sys.argv[1]) as f:
crd = yaml.safe_load(f)
schema = crd["spec"]["versions"][0]["schema"]["openAPIV3Schema"]
props = schema["properties"]["spec"]["properties"]
print(yaml.safe_dump(props.get("renewal", {}), sort_keys=False))
PY
printf '%s\n' '--- official documentation matches ---'
for url in \
'https://cert-manager.io/docs/usage/certificate/' \
'https://cert-manager.io/docs/configuration/ca/'
do
printf '\n%s\n' "$url"
curl -L --fail --silent --show-error "$url" |
tr '<' '\n' |
rg -i -m 30 -C 2 'renewal policy|renewBefore|rotation policy|CA certificates|automatically renew|root certificate|self.?signed' || true
doneRepository: cozystack/website
Length of output: 206
🌐 Web query:
site:cert-manager.io/docs/reference/api-docs CertificateRenewal RenewalPolicy Disabled RenewBefore cert-manager
💡 Result:
There is no CertificateRenewal policy option called Disabled in cert-manager [1]. The cert-manager Certificate API allows for renewal configuration through the renewal field, which supports the RenewBefore policy [1]. The renewBefore field defines an absolute duration before the certificate expiry when renewal should be attempted, while the renewBeforePercentage field allows defining this threshold as a percentage of the total certificate lifetime [1]. If renewBefore is not explicitly set, cert-manager defaults the renewal threshold to one-third of the issued certificate's lifetime [1]. There is no documented parameter to disable the automatic renewal process entirely through a policy setting [1].
Citations:
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
for url in \
'https://raw.githubusercontent.com/cert-manager/cert-manager/master/pkg/apis/certmanager/v1/types_certificate.go' \
'https://raw.githubusercontent.com/cert-manager/cert-manager/master/pkg/controller/certificates/sync.go' \
'https://raw.githubusercontent.com/cert-manager/cert-manager/master/pkg/controller/certificates/trigger/trigger_controller.go'
do
printf '\n--- %s ---\n' "$url"
curl -L --fail --silent --show-error "$url" |
rg -n -C 4 'Renewal|renewal|isCA|SelfSigned|renewBefore|nextPrivateKeySecretName' |
head -n 160 || true
doneRepository: cozystack/website
Length of output: 10471
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '--- cert-manager trigger sources ---'
curl -L --fail --silent --show-error \
'https://api.github.com/repos/cert-manager/cert-manager/contents/pkg/controller/certificates/trigger' |
jq -r '.[].download_url' |
while read -r url; do
[ "$url" = "null" ] && continue
printf '\n--- %s ---\n' "$url"
curl -L --fail --silent --show-error "$url" |
rg -n -C 5 'CertificateRenewalPolicyDisabled|Disabled|renewal policy|isCA|SelfSigned' |
head -n 120 || true
done
printf '%s\n' '--- cert-manager version references in the repository ---'
rg -n -i -S 'cert-manager|certmanager.io/v1' . \
-g '*.md' -g '*.yaml' -g '*.yml' -g '*.json' |
head -n 200 || trueRepository: cozystack/website
Length of output: 50374
Define the development root CA renewal policy.
cert-manager renews Certificate resources by default. If renewBefore is unset, renewal starts at one-third of the issued lifetime. A renewed self-signed root can replace the Secret and invalidate clients that trust the previous root. If the deployed cert-manager version supports spec.renewal.policy: Disabled, set it for this disposable root. Otherwise, document and follow the existing CA overlap procedure before renewal. privateKey.rotationPolicy does not disable certificate renewal.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@content/en/docs/next/operations/oidc/self-signed-certificates.md` around
lines 77 - 96, Update the development-root-ca Certificate manifest to explicitly
disable renewal using spec.renewal.policy: Disabled when supported by the
deployed cert-manager version. If that field is unavailable, document the
existing CA overlap procedure and instruct operators to follow it before
renewal; do not rely on privateKey.rotationPolicy to control certificate
renewal.
| kubectl get pod -n kube-system -l component=kube-apiserver \ | ||
| -o jsonpath='{range .items[0].spec.containers[0].command[*]}{.}{"\n"}{end}' | grep oidc | ||
|
|
||
| kubectl get pod -n kube-system -l component=kube-apiserver \ | ||
| -o jsonpath='{range .items[0].spec.containers[0].volumeMounts[*]}{.name}{"\t"}{.mountPath}{"\n"}{end}' | grep ca-certificates |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Inspect every kube-apiserver pod.
Both commands query .items[0]. In a multi-control-plane cluster, a missing OIDC argument or CA mount on another node remains undetected. Iterate over .items[*] and print the pod name, or run the check once per control-plane node.
</review_comment>
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@content/en/docs/next/operations/oidc/self-signed-certificates.md` around
lines 272 - 276, The kube-apiserver inspection commands only examine the first
pod via .items[0]. Update both kubectl jsonpath expressions to iterate over
.items[*] and include each pod’s name in the output, so OIDC arguments and
ca-certificates mounts are checked across every control-plane node.
1 participant
What this PR does
Replaces the self-signed leaf-pinning guide with an end-to-end OIDC trust guide for private CAs and Let's Encrypt staging. It documents wildcard certificate options, cert-manager CA bootstrap for disposable development environments, Talos
TrustedRootsConfigandStaticHostConfig, the explicit kube-apiserver CA mount, browser and kubelogin trust, Keycloak trust boundaries, bootstrap behavior, verification, troubleshooting, and safe CA rotation order.Also updates the OIDC enable page to reflect that Dashboard and LINSTOR backend requests use the internal Keycloak Service by default.
Validation
next/contenttalosctl validate --mode metal --strictgit diff --checkDownstream repositories
Not applicable: this PR changes website documentation only and does not modify a Cozystack runtime contract.
Summary by CodeRabbit