Skip to content

Commit 990c6d6

Browse files
authored
Merge branch 'main' into docs/marketplace
2 parents 9588585 + 4da896b commit 990c6d6

145 files changed

Lines changed: 1309 additions & 178 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/fetch-telemetry.yml‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,17 @@
11
name: Fetch Telemetry Data
22

33
on:
4-
# Keep this as a manual telemetry-only backfill path. The monthly OSS Health
5-
# refresh intentionally does not update telemetry while /api/overview differs
6-
# from the Grafana-backed source of truth.
4+
# Runs on the 3rd so the month it publishes is closed and the server has a
5+
# final snapshot of it. This stays its own workflow rather than joining the
6+
# monthly OSS Health job: those datasets come from public APIs, this one from
7+
# our own telemetry server, and a failure there should not hold back the rest.
8+
#
9+
# The /api/overview undercount that kept this manual is fixed — the server
10+
# counts over the period window instead of at an instant (telemetry-server
11+
# 43617cc, 2026-06-30), and its numbers now match what was published by hand
12+
# from Grafana for June.
13+
schedule:
14+
- cron: '0 5 3 * *'
715
workflow_dispatch:
816

917
permissions:
@@ -28,7 +36,22 @@ jobs:
2836
with:
2937
python-version: '3.12'
3038

39+
# Always the previous month: the current one is still open, and the
40+
# server marks a snapshot final only once the month has closed.
41+
- name: Resolve the month to publish
42+
id: period
43+
run: |
44+
# The day before the 1st of this month, rather than "last month":
45+
# that phrasing resolves to the same day number and silently skips a
46+
# month when run on a 29th, 30th or 31st.
47+
previous=$(date -u -d "$(date -u +%Y-%m-01) -1 day" +%Y-%m)
48+
echo "year=${previous%-*}" >> "$GITHUB_OUTPUT"
49+
echo "month=${previous#*-}" >> "$GITHUB_OUTPUT"
50+
3151
- name: Fetch and transform telemetry data
52+
env:
53+
TELEMETRY_YEAR: ${{ steps.period.outputs.year }}
54+
TELEMETRY_MONTH: ${{ steps.period.outputs.month }}
3255
run: python3 hack/fetch_telemetry.py
3356

3457
- name: Check for changes
@@ -48,7 +71,7 @@ jobs:
4871
git add static/oss-health-data/telemetry.json
4972
git branch -D update-telemetry || true
5073
git checkout -b update-telemetry
51-
git commit --signoff -m "[oss-health] Update telemetry snapshot $(date -u +'%Y-%m-%d %H:%M:%S')"
74+
git commit --signoff -m "[oss-health] Update telemetry snapshot for ${{ steps.period.outputs.year }}-${{ steps.period.outputs.month }}"
5275
git push --force --set-upstream origin update-telemetry
5376
5477
- name: Open pull request if not exists

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,7 @@ static/docs/*/cozystack-api/
2828
# Claude Code local settings
2929
.claude/
3030
.demo-build-uidir
31+
32+
# demo overlay ships a public/ with the MSW worker — keep it despite the public/ ignore
33+
!demo-src/overlay/apps/console/public/
34+
!demo-src/overlay/apps/console/public/**

‎content/de/_index.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ seo:
88
title: "Cozystack — Open-Source Private Cloud auf Kubernetes"
99
description: "Open-Source-Cloud-Plattform auf Kubernetes für Managed VMs, Datenbanken, S3-Storage und GPU-Workloads. CNCF-Sandbox-Projekt."
1010
keywords: ["private cloud", "managed kubernetes", "kubernetes plattform", "open source cloud"]
11-
source_digest: "sha256:24e38da4716b93c35dcb9eb607152d193ef3d5ad42c0e22a25063a89da9f8dde"
11+
source_digest: "sha256:e8f982c2431355bc79d3bb2133781cc539553c4c0a293d36e4c23dc54e7fcf80"
1212
translation_status: current
1313
l10n: transcreate
1414
taglines:
@@ -83,6 +83,17 @@ features:
8383
<!-- Screenshot Gallery -->
8484
{{< home/screenshot-gallery >}}
8585

86+
<!-- Live Demo -->
87+
<div class="section-live-demo">
88+
{{< blocks/lead color="primary" >}}
89+
<h2 class="section-label">Sehen Sie die Konsole, bevor Sie irgendetwas installieren</h2>
90+
91+
Das echte Dashboard von Cozystack, vollständig in Ihrem Browser — kein Cluster, keine Anmeldung, keine Einrichtung. Stöbern Sie im Marketplace, öffnen Sie Managed Services, klicken Sie sich durch die Konsole. Es ist die echte UI, nur mit Demo-Daten.
92+
93+
<a class="btn btn-lg btn-primary mt-4" href="/demo/">Live-Demo öffnen &rarr;</a>
94+
{{< /blocks/lead >}}
95+
</div>
96+
8697
<!-- Benefits & Features -->
8798

8899
{{< home/benefits >}}

‎content/en/demo/_index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: "Cozystack Live Demo"
3+
layout: "demo-app"
4+
url: "/demo/"
5+
description: "Try the real Cozystack console in your browser — marketplace, managed services, VMs — running entirely on mock data, no cluster required."
6+
body_class: "demo-embed-page"
7+
---
Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: "OIDC authentication for kubectl"
3+
linkTitle: "OIDC authentication"
4+
description: "Give tenant users per-identity kubectl access to a Managed Kubernetes cluster with per-cluster audience isolation."
5+
weight: 45
6+
---
7+
8+
Tenant Kubernetes clusters can authenticate `kubectl` users through OIDC instead of the shared static admin kubeconfig. Each user then has their own identity, per-user audit, and RBAC that can be revoked by disabling the account — not by rotating a shared certificate.
9+
10+
The identity model is deliberately **per-cluster** rather than per-tenant: each tenant Kubernetes cluster gets its own OIDC audience, and a token minted for cluster A is rejected by cluster B's apiserver. That gives you cross-cluster isolation without provisioning a Keycloak realm per tenant. The full rationale (why per-cluster audience and not per-tenant realm; how it relates to Keycloak Organizations; what BYO-OIDC looks like) is in the [design proposal](https://github.com/cozystack/community/pull/24).
11+
12+
{{% alert color="info" %}}
13+
The static `kubernetes-<cluster>-admin-kubeconfig` Secret in the tenant namespace stays available as a break-glass path regardless of whether OIDC is enabled.
14+
{{% /alert %}}
15+
16+
## Modes
17+
18+
`spec.oidc.mode` picks the identity source:
19+
20+
- **`None`** — the default. No OIDC; only the static admin kubeconfig works. Existing clusters render identically to before.
21+
- **`System`** — trust the platform `cozy` Keycloak realm via a per-cluster public client and audience binding. Users are the ones a Cozystack platform admin already provisioned in `cozy`; the tenant does not manage a directory of its own.
22+
- **`CustomConfig`** — trust a tenant-supplied issuer directly (BYO IdP: Okta, Auth0, a customer's own Keycloak). `cozy` is not in the path.
23+
24+
## Enable OIDC — `System` mode
25+
26+
```yaml
27+
apiVersion: apps.cozystack.io/v1alpha1
28+
kind: Kubernetes
29+
metadata:
30+
name: prod
31+
namespace: tenant-acme
32+
spec:
33+
oidc:
34+
mode: System
35+
users:
36+
37+
role: admin # binds to ClusterRole/cluster-admin
38+
39+
role: view # binds to ClusterRole/view
40+
# ...
41+
```
42+
43+
Cozystack provisions:
44+
45+
- A per-cluster `KeycloakClient` in the `cozy` realm, with `clientId` set to `<namespace>-kubernetes-<cluster-name>` (for the CR above: `tenant-acme-kubernetes-prod`). `public: true`, PKCE required, redirect URIs locked to `localhost:8000` and `localhost:18000` (the `kubectl oidc-login` defaults).
46+
- A per-cluster `KeycloakClientScope` whose audience mapper pins the token's `aud` claim to that same `clientId`.
47+
- A structured `AuthenticationConfiguration` (`apiserver.config.k8s.io/v1beta1`) on the tenant kube-apiserver, pointing at the `cozy` issuer and the per-cluster audience.
48+
- One `ClusterRoleBinding` inside the tenant cluster for each `users[]` entry — `admin` → `cluster-admin`, `view` → `view`. The chart uses your `users[].email` value as the `User:` subject and matches it against the token's `email` claim.
49+
50+
Removing a user from `users[]` prunes their `ClusterRoleBinding` on the next reconcile.
51+
52+
### Prerequisite
53+
54+
`System` mode requires the platform-level OIDC feature (`authentication.oidc.enabled` at the Cozystack platform values). If the flag is off, the chart hard-fails the render with a clear message. Ask a Cozystack platform admin to enable it, or use `CustomConfig`.
55+
56+
## Enable OIDC — `CustomConfig` mode
57+
58+
Bring your own issuer. Two supply paths, **mutually exclusive**:
59+
60+
```yaml
61+
spec:
62+
oidc:
63+
mode: CustomConfig
64+
customConfig:
65+
config: |
66+
apiVersion: apiserver.config.k8s.io/v1beta1
67+
kind: AuthenticationConfiguration
68+
jwt:
69+
- issuer:
70+
url: https://idp.acme.example
71+
certificateAuthority: |
72+
-----BEGIN CERTIFICATE-----
73+
...
74+
-----END CERTIFICATE-----
75+
audiences:
76+
- cozystack-prod
77+
claimMappings:
78+
username:
79+
claim: email
80+
prefix: ""
81+
groups:
82+
claim: groups
83+
prefix: ""
84+
users:
85+
86+
role: admin
87+
```
88+
89+
…or via a pre-existing Secret in the tenant namespace (you create it separately, e.g. under your own GitOps repository, so the AuthenticationConfiguration does not live inside the `Kubernetes` CR):
90+
91+
```yaml
92+
spec:
93+
oidc:
94+
mode: CustomConfig
95+
customConfig:
96+
secretRef:
97+
name: acme-byo-authn-config # Secret with a `config.yaml` key holding the AuthenticationConfiguration
98+
```
99+
100+
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 tenant-supplied issuer directly.
101+
102+
Ensure your BYO issuer emits the `email` claim in the JWT. Every conformant OIDC provider does when the client requests the `email` scope. If you distribute a hand-crafted kubeconfig instead of using the chart-generated one, remember to include `--oidc-extra-scope=email` in the `kubectl oidc-login` exec block.
103+
104+
## Get the kubeconfig
105+
106+
In `System` mode, Cozystack writes a ready-to-use kubeconfig into a `kubernetes-<cluster>-oidc-kubeconfig` Secret in the tenant namespace (the same namespace where the `Kubernetes` resource lives). It's exposed to the dashboard alongside the admin kubeconfig, and you can also fetch it directly:
107+
108+
```shell
109+
kubectl --namespace tenant-acme get secret kubernetes-prod-oidc-kubeconfig \
110+
--output=jsonpath='{.data.kubeconfig}' | base64 -d > prod.kubeconfig
111+
```
112+
113+
The file contains the tenant CA (extracted from the Kamaji-issued admin kubeconfig at reconcile time), the external apiserver URL, and a `kubectl oidc-login` exec block wired to your per-cluster client.
114+
115+
In `CustomConfig` mode no kubeconfig Secret is generated — you distribute the OIDC kubeconfig out-of-band from your own IdP configuration.
116+
117+
## Sign in
118+
119+
Install the `oidc-login` kubectl plugin once:
120+
121+
```shell
122+
kubectl krew install oidc-login
123+
```
124+
125+
Then use the OIDC kubeconfig — the first request triggers the browser flow:
126+
127+
```shell
128+
kubectl --kubeconfig prod.kubeconfig get pods --all-namespaces
129+
```
130+
131+
`kubectl oidc-login` opens Keycloak's login page on `localhost:8000` (falling back to `localhost:18000`), captures the token, and caches it locally. Subsequent calls are silent until the token expires.
132+
133+
## Toggling OIDC off
134+
135+
Setting `spec.oidc.mode` back to `None` — or deleting the `Kubernetes` resource entirely — reconciles a cleanup pass that removes the tenant apiserver's `--authentication-config` flag, deletes the chart-owned OIDC Secrets, and drops the per-cluster Keycloak client and audience scope. `ClusterRoleBindings` labelled by the release are also removed from the tenant cluster (best-effort during pre-delete, since the tenant apiserver may already be tearing down).
136+
137+
## Prerequisites and gotchas
138+
139+
- **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.
140+
- **`oidc-login` plugin required.** Without `kubectl krew install oidc-login` the exec block errors out client-side. The plugin is a documented prerequisite.
141+
- **`emailVerified: true` when provisioning Keycloak users.** Phase 1 does not add a `claimValidationRules` entry to the rendered `AuthenticationConfiguration` — so `email_verified` is not chart-enforced. Set `emailVerified: true` on the `KeycloakRealmUser` (or complete the email-verify flow through the Keycloak UI) so the identity holding a given `users[].email` is guaranteed authentic. The `cozy` realm's default `duplicateEmails: false` prevents a second account from claiming an already-registered address. If the issuer explicitly emits `email_verified: false` on a token the apiserver rejects it (k8s upstream behaviour); a missing claim is treated as verified. CEL `claimValidationRules` to make this a hard gate is a follow-up hardening path.
142+
- **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.
143+
144+
## What's out of scope for this feature
145+
146+
- **Per-tenant Keycloak realms.** Managed multi-tenant identity (a hosted directory the tenant self-administers) is a separate proposal, evaluated against Keycloak Organizations. Track it in the [community proposal](https://github.com/cozystack/community/pull/24).
147+
- **Federating an external IdP into the platform `cozy` realm.** BYO-for-Cozystack-itself is a distinct problem — this feature is BYO-for-a-managed-service.
148+
- **Cross-cluster SSO inside one tenant.** By design: each cluster has its own audience, which is the per-cluster isolation primitive.
149+
- **RFC 8693 token exchange.** Possible future optimisation; not required for the per-cluster client + audience model.

‎content/en/docs/next/networking/hairpin-proxy-protocol.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ Disabling has different shapes on the two layers, by design. The host path has a
119119
The platform refuses to render the bare flag flip when a `cozystack.ouroboros` Package CR is already on the cluster — `helm template` / `helm upgrade` fails fast with an error that points at `kubectl delete package.cozystack.io cozystack.ouroboros` (which triggers helm uninstall and the chart's pre-delete cleanup hook) and the acknowledgement field. The vendored chart carries a pre-delete hook (`charts/ouroboros/templates/coredns-cleanup-hook.yaml`) that quiesces the controller and `sed`-strips the `# === BEGIN ouroboros … END ouroboros ===` block from `kube-system/coredns` automatically when helm actually uninstalls the chart — operators do **not** need to run the manual `sed` recipe in the normal disable path. The full host disable sequence is:
120120

121121
1. Flip the upstream LB off PROXY-protocol injection (external traffic precondition).
122-
2. Remove the Package CR with `kubectl delete package.cozystack.io cozystack.ouroboros` (or add it to `bundles.disabledPackages`). This triggers helm uninstall, which fires the chart's pre-delete hook and patches `kube-system/coredns` automatically.
122+
2. Remove the Package CR with `kubectl delete package.cozystack.io cozystack.ouroboros`. This triggers helm uninstall, which fires the chart's pre-delete hook and patches `kube-system/coredns` automatically. Adding the name to `bundles.disabledPackages` is **not** a second way to get there. `disabledPackages` will not remove components that are already installed: the list only stops the platform chart from emitting the Package document, and `helm.sh/resource-policy: keep` leaves the live Package on the cluster along with the HelmRelease it owns. ouroboros keeps running, the pre-delete hook never fires, and no platform values setting reaches it.
123123
3. Set `publishing.proxyProtocol: false` in the platform values. The render guard now passes (the `lookup` for `cozystack.ouroboros` returns nil after step 2), so `publishing.proxyProtocolAcknowledgeUnclean` stays at its default `false`.
124124

125125
If the operator has reason to flip `publishing.proxyProtocol: false` BEFORE deleting the Package CR (strict GitOps where `kubectl delete` is not in-band, parallel rollbacks, etc.), set `publishing.proxyProtocolAcknowledgeUnclean: true` together with the flag flip in the same commit, then drive the Package deletion separately. Flip `proxyProtocolAcknowledgeUnclean` back to `false` once the cluster has been clean for one reconcile cycle. This is the escape valve, not the recommended path — the staged sequence above keeps the ack flag at its default and avoids the round-trip.

0 commit comments

Comments
 (0)