This document defines the governance structure of the Cozystack community, outlining how members collaborate to achieve shared goals.
Cozystack, a Cloud Native Computing Foundation (CNCF) project, is committed 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.
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.
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 | Operator image, CRDs and the etcd-migrate tool, for etcd clusters backing tenant control planes |
Stable | @lllamnyp, @androndo, @sircthulhu |
| 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 | PostgreSQL wire-protocol proxy that encrypts Keycloak PII columns, keeping the key in a KMS outside the database | Stable | @sircthulhu, @kvaps |
| local-ccm | Cloud-controller manager for bare-metal clusters; chart and image | Stable | @kvaps, @IvanHunters |
| cozystack-scheduler | kube-scheduler extension with SchedulingClass-aware placement; also a compiled dependency of the main repository | Stable | @lllamnyp |
| 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). 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 (managing Talos Linux the GitOps way), cozyhr (a Helm and Flux CD wrapper for local development), cozyvalues-gen (schema and README generation for Helm charts), terraform-provider-cozystack, ansible-cozystack, boot-to-talos, talos-bootstrap, talos-meta-tool and blockstor (a software-defined storage system, developed independently of the platform).
Project infrastructure carries no shipped code: website, community (design proposals and meeting notes), external-apps-example (the reference third-party application catalogues are built from), ccp, .github and .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. None is built into the distribution, which takes those components from their upstreams directly.
Two things about this organisation are worth stating plainly rather than leaving to be discovered.
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 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 page.
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 page. That page lists upstreams only: what this project maintains is Apache-2.0 and is not listed there individually.
- Users: Members that engage with the Cozystack community via any medium, including Slack, Telegram, GitHub, and mailing lists.
- Contributors: Members contributing to the projects by contributing and reviewing code, writing documentation, responding to issues, participating in proposal discussions, and so on.
- Maintainers: Technical project leaders.
Cozystack is for everyone. Anyone can become a Cozystack contributor simply by contributing to the project, whether through code, documentation, blog posts, community management, or other means. As with all Cozystack community members, contributors are expected to follow the Cozystack Code of Conduct.
All contributions to Cozystack code, documentation, or other components in the Cozystack GitHub organisation must follow the contributing guidelines. Whether these contributions are merged into the project is the prerogative of the maintainers.
Maintainers have the right to merge code into the project. Anyone can become a Cozystack maintainer (see "Becoming a maintainer" below).
Cozystack maintainers are expected to:
- Review pull requests, triage issues, and fix bugs in their areas of expertise, ensuring that all changes go through the project's code review and integration processes.
- Monitor cncf-cozystack-* emails, the Cozystack Slack channels in Kubernetes and CNCF Slack workspaces, Telegram groups, and help out when possible.
- Rapidly respond to any time-sensitive security release processes.
- Attend Cozystack community meetings.
- Be familiar with the Linux Foundation guidance on OFAC sanctions and open source and raise any related questions privately with the other maintainers.
If a maintainer is no longer interested in or cannot perform the duties listed above, they should move themselves to emeritus status. If necessary, this can also occur through the decision-making process outlined below.
A first contribution is often the moment someone decides whether to stay. When a new contributor opens an issue or a pull request:
- Aim to respond within two working days, even if only to say who will review it and when.
- Point to the contributing guide and help with the mechanics. If the DCO check fails, explain how to fix it:
git commit --amend --signofffor the last commit, orgit rebase --signoff mainfor several. - Before approving a CI run for an external contributor, read the diff and make sure it does not touch workflows, secrets or release tooling in a way that could run untrusted code with project credentials. This applies to every approval, not only the first one.
- Review against the same standards as any other change, and explain the reason behind each requested change. If the change is not going to be accepted, say so early and say why, rather than leaving it open.
- Suggest a good next step: a
good first issue, a related bug, or a documentation gap.
Anyone can become a Cozystack maintainer. Maintainers should be extremely proficient in cloud native technologies and/or Go; have relevant domain expertise; have the time and ability to meet the maintainer's expectations above; and demonstrate the ability to work with the existing maintainers and project processes.
To become a maintainer, start by expressing interest to existing maintainers. Existing maintainers will then ask you to demonstrate the qualifications above by contributing PRs, doing code reviews, and other such tasks under their guidance. After several months of working together, maintainers will decide whether to grant maintainer status.
Ideally, all project decisions are resolved by consensus of the maintainers. If this is not possible, a vote will be called. The voting process is a simple majority in which each maintainer receives one vote.