admin/cozystack
1
0 Fork 0
mirror of https://github.com/cozystack/cozystack.git synced 2026-11-09 05:25:14 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs(governance): describe sub-projects and third-party dependencies (#3784)

Browse Source 
## What this PR does

Brings `GOVERNANCE.md` in line with the organisation it describes: what
the project governs, and what it ships but does not.

### Sub-projects

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 — `etcd-operator`,
`keycloak-kms-proxy`, `local-ccm`, `cozystack-scheduler` and
`ingress-nginx-with-protobuf-exporter` — while `talos-bootstrap` and
`talos-meta-tool` were listed although an adopter installs neither.
Nothing stated what being on the list meant, which is why it drifted.

It is replaced by a section organised around the distinction that
decides scope: whether a repository's output reaches the artifact an
adopter installs. Packaged sub-projects get a table naming what each one
contributes, its stability, and its owners — the same handles each
repository's `CODEOWNERS` already carries. Independent tooling, project
infrastructure and upstream forks are described in a line each, as
explicitly outside that scope.

Three things an evaluator finds anyway are stated rather than left to be
discovered: that one fork (`apimachinery`) is compiled into the product,
why, and that the fix is proposed upstream as
kubernetes/kubernetes#135537; that four repositories are private, with
the reason for each, and that none of them contributes to the
distribution; and that telemetry is received by a component adopters do
not install, with a link to the opt-out.

### Third-party Dependencies

Writes down which shipped components the project does not govern.
Cozystack vendors software it does not own, which is ordinary and needs
no defence — but the boundary was nowhere stated. This is a Required
item on the Incubation checklist ("All project metadata and resources
are vendor-neutral"), and an evaluator currently has nothing in the
governance document to read it off.

The section says two things: what the arrangement is, and where the
components are listed. It names nothing itself. The
[Licenses](https://cozystack.io/docs/v1.6/operations/configuration/licenses/)
page carries the list, and by its own framing carries upstreams only —
Cozystack-maintained components are Apache-2.0 and are not listed there
individually. Appearing on that page is therefore already the
classification, so a second list here would only drift from it.

Two components that belong on that page were missing from it despite
shipping since v1.3.4 and v1.4.3; cozystack/website#649 adds them.

Nothing moves, nothing is relicensed, no mirroring changes. This
documents the existing arrangement, which each package's `values.yaml`
already describes at its own level.

### Downstream repositories

Walked the trigger map in `docs/agents/contributing.md` against the
diff. It touches `GOVERNANCE.md` only, and no trigger concerns
governance documents — the website triggers are package additions,
platform values, variants, components, release assets,
`ApplicationDefinition` semantics, the Talos pin and developer tooling.
The website PR linked above is a companion, not a consequence of this
diff: it fixes a pre-existing gap on the Licenses page that stands on
its own.

- [x] No downstream repository is affected by this change

### Release note

```release-note
NONE
```


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Added governance guidance for project sub-components, including
ownership, licensing, maintenance, and repository classifications.
* Documented project infrastructure, upstream forks, private
repositories, and telemetry services.
* Clarified how third-party software is sourced, governed, mirrored, and
versioned.
* Linked to a license inventory listing third-party components and their
applicable licenses.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Andrei Kvapil authored and GitHub committed 2026-08-20 13:04:20 +02:00
2 parents adc9c568fd 0feca20e26
commit bd4939ac5e
1 file changed
+39 -10
Download Patch File Download Diff File Expand all files Collapse all files
GOVERNANCE.md
+39 -10
View File
@@ -8,18 +8,47 @@ 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
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. That page lists upstreams only: what this project maintains is Apache-2.0
and is not listed there individually.
## Community Roles