From ed1624cfa35cc6e9a5fdad2f88d4b841b4a2a83b Mon Sep 17 00:00:00 2001 From: Andrei Kvapil Date: Wed, 12 Aug 2026 18:16:19 +0200 Subject: [PATCH 1/5] docs(governance): state which shipped components the project does not govern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cozystack vendors software it does not own, which is ordinary, but the boundary was nowhere written down. Two of those components are maintained by someone who is also a Cozystack maintainer — from outside, that is indistinguishable from project code parked in a personal account, and a reader has to guess. Records the rule and names those two cases, with what makes them upstreams rather than components: their own identity and licence, a problem that exists outside this project, and absence from a default installation. Assisted-By: Claude Signed-off-by: Andrei Kvapil --- GOVERNANCE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 3fa813173..02f2db688 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -21,6 +21,24 @@ maintained under the `cozystack` namespace: * **[talos-bootstrap](https://github.com/cozystack/talos-bootstrap):** An interactive Talos Linux installer * **[talos-meta-tool](https://github.com/cozystack/talos-meta-tool):** Tool for writing network metadata into META partition +## Third-party Dependencies + +Cozystack packages and ships software it does not govern. Such components remain +under their upstream owner's namespace, are vendored by digest, and are neither +released by this project nor mirrored under `ghcr.io/cozystack`. + +Two of them are maintained by an individual who is also a Cozystack maintainer. +They are named here so that the distinction is documented rather than inferred: + +* **[kuberture](https://github.com/lexfrei/kuberture):** EndpointSlice-to-DNS controller, BSD-3-Clause. Vendored as `packages/system/kuberture`; installed only when explicitly listed in `bundles.enabledPackages`. +* **[ouroboros](https://github.com/lexfrei/ouroboros):** hairpin-NAT fix for Ingress behind PROXY-protocol, BSD-3-Clause. Vendored as `packages/system/ouroboros`; installed only when `publishing.proxyProtocol` is enabled, or as an opt-in tenant cluster addon. + +Both are independent upstreams rather than Cozystack components: each carries its +own identity and licence, addresses a problem that exists outside this project, +and is absent from a default installation. Their charts and images are pinned by +digest, and each package documents how operators should mirror them for +air-gapped installations. + ## Community Roles * **Users:** Members that engage with the Cozystack community via any medium, including Slack, Telegram, GitHub, and mailing lists. From a2f7b7956cf0263a159f1d23e3e8cdce72796bbc Mon Sep 17 00:00:00 2001 From: Andrei Kvapil Date: Wed, 12 Aug 2026 18:25:52 +0200 Subject: [PATCH 2/5] docs(governance): link the licenses page from the dependency section The section states the rule; the licenses page is where the components it covers are actually enumerated, so point at it rather than restating a list that would drift. Assisted-By: Claude Signed-off-by: Andrei Kvapil --- GOVERNANCE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 02f2db688..2feabe1c8 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -25,7 +25,9 @@ maintained under the `cozystack` namespace: Cozystack packages and ships software it does not govern. Such components remain under their upstream owner's namespace, are vendored by digest, and are neither -released by this project nor mirrored under `ghcr.io/cozystack`. +released by this project nor mirrored under `ghcr.io/cozystack`. Those components +are enumerated, with their licences, on the +[Licenses](https://cozystack.io/docs/v1.6/operations/configuration/licenses/) page. Two of them are maintained by an individual who is also a Cozystack maintainer. They are named here so that the distinction is documented rather than inferred: From 95e84fc1852f3fe14af9c754029e04650bef2973 Mon Sep 17 00:00:00 2001 From: Andrei Kvapil Date: Wed, 12 Aug 2026 18:32:14 +0200 Subject: [PATCH 3/5] docs(governance): keep the dependency list in one place MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The section named two of the upstreams it describes, which put a list here and another on the Licenses page, with nothing keeping the two in step — the drift the link was meant to avoid. States the rule and the test for applying it; the components it covers stay enumerated where they already are. Assisted-By: Claude Signed-off-by: Andrei Kvapil --- GOVERNANCE.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 2feabe1c8..8ecc7a63b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -25,21 +25,18 @@ maintained under the `cozystack` namespace: Cozystack packages and ships software it does not govern. Such components remain under their upstream owner's namespace, are vendored by digest, and are neither -released by this project nor mirrored under `ghcr.io/cozystack`. Those components -are enumerated, with their licences, on the -[Licenses](https://cozystack.io/docs/v1.6/operations/configuration/licenses/) page. +released by this project nor mirrored under `ghcr.io/cozystack`. They are +enumerated, with their licences, on the +[Licenses](https://cozystack.io/docs/v1.6/operations/configuration/licenses/) +page, which by construction lists upstreams only: what this project maintains is +Apache-2.0 and is not listed there individually. -Two of them are maintained by an individual who is also a Cozystack maintainer. -They are named here so that the distinction is documented rather than inferred: - -* **[kuberture](https://github.com/lexfrei/kuberture):** EndpointSlice-to-DNS controller, BSD-3-Clause. Vendored as `packages/system/kuberture`; installed only when explicitly listed in `bundles.enabledPackages`. -* **[ouroboros](https://github.com/lexfrei/ouroboros):** hairpin-NAT fix for Ingress behind PROXY-protocol, BSD-3-Clause. Vendored as `packages/system/ouroboros`; installed only when `publishing.proxyProtocol` is enabled, or as an opt-in tenant cluster addon. - -Both are independent upstreams rather than Cozystack components: each carries its -own identity and licence, addresses a problem that exists outside this project, -and is absent from a default installation. Their charts and images are pinned by -digest, and each package documents how operators should mirror them for -air-gapped installations. +Some of those upstreams are maintained by individuals rather than organisations, +and such an individual may also hold a role in this project. Neither fact makes +the software a Cozystack component. The test is governance: a dependency keeps +its own identity, licence and release process, and addresses a problem that +exists outside Cozystack; a component is released under this project's +governance and carries its licence. ## Community Roles From 910a9171152c9957ddb3abb9c70115769b3376d6 Mon Sep 17 00:00:00 2001 From: Andrei Kvapil Date: Wed, 12 Aug 2026 18:35:22 +0200 Subject: [PATCH 4/5] docs(governance): cut the dependency section to what it has to say The second paragraph argued that an upstream maintained by an individual is still an upstream. Nobody had disputed it, and a governance document that defends an unraised objection invites the question instead of settling it. What remains is the arrangement itself and where the components are listed. Assisted-By: Claude Signed-off-by: Andrei Kvapil --- GOVERNANCE.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 8ecc7a63b..340efc612 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -25,18 +25,12 @@ maintained under the `cozystack` namespace: Cozystack packages and ships software it does not govern. Such components remain under their upstream owner's namespace, are vendored by digest, and are neither -released by this project nor mirrored under `ghcr.io/cozystack`. They are -enumerated, with their licences, on the -[Licenses](https://cozystack.io/docs/v1.6/operations/configuration/licenses/) -page, which by construction lists upstreams only: what this project maintains is -Apache-2.0 and is not listed there individually. +released by this project nor mirrored under `ghcr.io/cozystack`. -Some of those upstreams are maintained by individuals rather than organisations, -and such an individual may also hold a role in this project. Neither fact makes -the software a Cozystack component. The test is governance: a dependency keeps -its own identity, licence and release process, and addresses a problem that -exists outside Cozystack; a component is released under this project's -governance and carries its licence. +They are enumerated, with their licences, on the +[Licenses](https://cozystack.io/docs/v1.6/operations/configuration/licenses/) +page. That page lists upstreams only: what this project maintains is Apache-2.0 +and is not listed there individually. ## Community Roles From 0feca20e26573233da3d717ba01f622cb43771a0 Mon Sep 17 00:00:00 2001 From: Andrei Kvapil Date: Wed, 12 Aug 2026 22:55:01 +0200 Subject: [PATCH 5/5] docs(governance): describe the sub-projects and what each contributes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Code Repositories list named seven repositories and was wrong in both directions: five of the six sub-projects whose code ships in the distribution were missing from it, while talos-bootstrap and talos-meta-tool were listed although an adopter installs neither. Nothing said what being on the list meant, which is why it drifted. It is replaced by a section organised around the distinction that actually matters — whether a repository's output reaches the artifact an adopter installs. Packaged sub-projects get a table naming what each contributes, its stability and its owners; independent tooling, project infrastructure and upstream forks are described in a line each as out of that scope. Three things an evaluator will find anyway are stated rather than left to be discovered: that one fork (apimachinery) is compiled into the product and why, that four repositories are private and none of them ships, and that telemetry is received by a component adopters do not install. Assisted-By: Claude Signed-off-by: Andrei Kvapil --- GOVERNANCE.md | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 340efc612..404667b49 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -8,18 +8,36 @@ This document defines the governance structure of the Cozystack community, outli to building an open, inclusive, productive, and self-governing open source community focused on building a high-quality open source PaaS and framework for building clouds. -## Code Repositories +## Sub-projects -The following code repositories are governed by the Cozystack community and -maintained under the `cozystack` namespace: +Cozystack is developed across several repositories in the `cozystack` GitHub organisation. They do not all carry the same weight, and the distinction that matters is whether a repository's output reaches the artifact an adopter installs. -* **[Cozystack](https://github.com/cozystack/cozystack):** Main Cozystack codebase -* **[website](https://github.com/cozystack/website):** Cozystack website and documentation sources -* **[Talm](https://github.com/cozystack/talm):** Tool for managing Talos Linux the GitOps way -* **[cozy-proxy](https://github.com/cozystack/cozy-proxy):** A simple kube-proxy addon for 1:1 NAT services in Kubernetes with NFT backend -* **[cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server):** Cozystack telemetry -* **[talos-bootstrap](https://github.com/cozystack/talos-bootstrap):** An interactive Talos Linux installer -* **[talos-meta-tool](https://github.com/cozystack/talos-meta-tool):** Tool for writing network metadata into META partition +**Packaged sub-projects** are built or vendored into the Cozystack distribution: install Cozystack and you run their code. They are governed by this project, released under Apache-2.0, and are in scope for the same licence, security, release and maintainership expectations as the main repository. + +| Sub-project | What it contributes to the distribution | Status | Owners | +|---|---|---|---| +| [etcd-operator](https://github.com/cozystack/etcd-operator) | Operator image, CRDs and the `etcd-migrate` tool, for etcd clusters backing tenant control planes | Stable | @lllamnyp, @androndo, @sircthulhu | +| [cozy-proxy](https://github.com/cozystack/cozy-proxy) | kube-proxy addon for 1:1 NAT services, with an NFT backend; chart vendored into the platform | Stable | @kvaps, @mattia-eleuteri | +| [keycloak-kms-proxy](https://github.com/cozystack/keycloak-kms-proxy) | PostgreSQL wire-protocol proxy that encrypts Keycloak PII columns, keeping the key in a KMS outside the database | Stable | @sircthulhu, @kvaps | +| [local-ccm](https://github.com/cozystack/local-ccm) | Cloud-controller manager for bare-metal clusters; chart and image | Stable | @kvaps, @IvanHunters | +| [cozystack-scheduler](https://github.com/cozystack/cozystack-scheduler) | kube-scheduler extension with SchedulingClass-aware placement; also a compiled dependency of the main repository | Stable | @lllamnyp | +| [ingress-nginx-with-protobuf-exporter](https://github.com/cozystack/ingress-nginx-with-protobuf-exporter) | Ingress-NGINX controller build carrying the protobuf metrics exporter | Stable | @kvaps | + +The Cozystack maintainers are maintainers of every sub-project by default (see [MAINTAINERS.md](./MAINTAINERS.md)). The owners named above are the people whose review is requested on changes in each repository; the same lists are recorded in each repository's `CODEOWNERS`. + +**Independent tooling** is governed by this project but is not part of the distribution — an adopter installs Cozystack without it, and chooses these separately: [talm](https://github.com/cozystack/talm) (managing Talos Linux the GitOps way), [cozyhr](https://github.com/cozystack/cozyhr) (a Helm and Flux CD wrapper for local development), [cozyvalues-gen](https://github.com/cozystack/cozyvalues-gen) (schema and README generation for Helm charts), [terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack), [ansible-cozystack](https://github.com/cozystack/ansible-cozystack), [boot-to-talos](https://github.com/cozystack/boot-to-talos), [talos-bootstrap](https://github.com/cozystack/talos-bootstrap), [talos-meta-tool](https://github.com/cozystack/talos-meta-tool) and [blockstor](https://github.com/cozystack/blockstor) (a software-defined storage system, developed independently of the platform). + +**Project infrastructure** carries no shipped code: [website](https://github.com/cozystack/website), [community](https://github.com/cozystack/community) (design proposals and meeting notes), [external-apps-example](https://github.com/cozystack/external-apps-example) (the reference third-party application catalogues are built from), [ccp](https://github.com/cozystack/ccp), [.github](https://github.com/cozystack/.github) and [.project](https://github.com/cozystack/.project) (CNCF project metadata). + +**Forks of upstream projects** are held for contributing changes back, or were held for that purpose and have since been archived. One is load-bearing and is called out below; the rest are not built into the distribution, which takes those components from their upstreams directly. + +Three things about this organisation are worth stating plainly rather than leaving to be discovered. + +**One fork is compiled into the product.** [cozystack/apimachinery](https://github.com/cozystack/apimachinery) is a fork of `kubernetes/apimachinery` carrying a single 34-line patch to `pkg/runtime/scheme.go` on top of the released `v0.35.0` tree, applied through a `replace` directive in `go.mod`. The same fix is proposed upstream as [kubernetes/kubernetes#135537](https://github.com/kubernetes/kubernetes/pull/135537); the fork exists only until that merges, and is pinned to a branch tracking the upstream release rather than to the fork's own trunk. + +**Four repositories are private**, and none of them contributes to the distribution: `security-scanner` (automated CVE monitoring, private because it holds pre-disclosure vulnerability state), `infrastructure` (the organisation's own CI infrastructure-as-code, private because it holds cloud credentials and account topology), one GitHub-created security-advisory workspace, and `talos-preboot-iso`, an archived prototype. Nothing an adopter installs is built from a repository they cannot read. + +**Telemetry is received by a component adopters do not install.** [cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server) runs as project infrastructure, but clusters report to it by default, so it is named here rather than omitted as out-of-scope. What is collected, why, and how to turn it off is documented on the [Telemetry](https://cozystack.io/docs/operations/configuration/telemetry/) page. ## Third-party Dependencies