- Contributor License Agreements
- Finding Things That Need Help
- Versioning
- Branches
- Contributing a Patch
- Documentation changes
- Releases
- Proposal process (CAEP)
- Triaging E2E test failures
- Reviewing a Patch
- Features and bugs
- Experiments
- Breaking Changes
- Dependency Licence Management
- API conventions
- Google Doc Viewing Permissions
- Issue and Pull Request Management
- Contributors Ladder
Read the following guide if you're interested in contributing to cluster-api.
Contributors who are not used to working in the Kubernetes ecosystem should also take a look at the Kubernetes New Contributor Course.
We'd love to accept your patches! Before we can take them, we have to jump a couple of legal hurdles.
Please fill out either the individual or corporate Contributor License Agreement (CLA). More information about the CLA and instructions for signing it can be found here.
NOTE: Only original source code from you and other people that have signed the CLA can be accepted into the *repository.
If you're new to the project and want to help, but don't know where to start, we have a semi-curated list of issues that should not need deep knowledge of the system. Have a look and see if anything sounds interesting. Before starting to work on the issue, make sure that it doesn't have a lifecycle/active label. If the issue has been assigned, reach out to the assignee. Alternatively, read some docs on other controllers and try to write your own, file and fix any/all issues that come up, including gaps in documentation!
If you're a more experienced contributor, looking at unassigned issues in the next release milestone is a good way to find work that has been prioritized. For example, if the latest minor release is v1.0, the next release milestone is v1.1.
Help and contributions are very welcome in the form of code contributions but also in helping to moderate office hours, triaging issues, fixing/investigating flaky tests, being part of the release team, helping new contributors with their questions, reviewing proposals, etc.
⚠ The project does not follow Go Modules guidelines for compatibility requirements for 1.x semver releases.
Cluster API follows upstream Kubernetes semantic versioning. With the v1 release of our codebase, we guarantee the following:
-
A (minor) release CAN include:
- Introduction of new API versions, or new Kinds.
- Compatible API changes like field additions, deprecation notices, etc.
- Breaking API changes for deprecated APIs, fields, or code.
- Features, promotion or removal of feature gates.
- And more!
-
A (patch) release SHOULD only include backwards compatible set of bugfixes.
These guarantees extend to all code exposed in our Go Module, including types from dependencies in public APIs. Types and functions not in public APIs are not considered part of the guarantee. The test module, clusterctl, and experiments do not provide any backward compatible guarantees.
We generally do not accept PRs directly against release branches, while we might accept backports of fixes/changes already merged into the main branch.
Any backport MUST not be breaking for either API or behavioral changes.
We generally allow backports of following changes to all supported branches:
- Critical bugs fixes, security issue fixes, or fixes for bugs without easy workarounds.
- Dependency bumps for CVE (usually limited to CVE resolution; backports of non-CVE related version bumps are considered exceptions to be evaluated case by case)
- Cert-manager version bumps (to avoid having releases with cert-manager versions that are out of support, when possible)
- Changes required to support new Kubernetes versions, when possible. See supported Kubernetes versions for more details.
- Changes to use the latest Go patch version to build controller images.
- Changes to bump the Go minor version used to build controller images, if the Go minor version of a supported branch goes out of support (e.g. to pick up bug and CVE fixes).
This has no impact on folks importing Cluster API as we won't modify the version in
go.modand the version in theMakefiledoes not affect them.
We generally allow backports of following changes only to the latest supported branch:
- Improvements to existing docs (the latest supported branch hosts the current version of the book)
- Improvements to CI signal
- Improvements to the test framework
While we recommend to target following type of changes to the next minor release, CAPI maintainers will also consider exceptions for backport of following changes only to the latest supported branch:
- Enhancements or additions to experimental Cluster API features, with the goal of allowing faster adoption and iteration; Please note that stability of the branch will always be top priority while evaluating those PRs, and thus approval requires /lgtm from at least two maintainers that, on top of checking that the backport is not introducing any breaking change for either API or behavior, will evaluate if the impact of those backport is limited and well-scoped e.g. by checking that those changes should not touch non-experimental code paths like utils and/or by applying other considerations depending on the specific PR.
Like any other activity in the project, backporting a fix/change is a community-driven effort and requires that someone volunteers to own the task. In most cases, the cherry-pick bot can (and should) be used to automate opening a cherry-pick PR.
We generally do not accept backports to Cluster API release branches that are out of support.
API versioning and guarantees are inspired by the Kubernetes deprecation policy and API change guidelines. We follow the API guidelines as much as possible adapting them if necessary and on a case-by-case basis to CustomResourceDefinition.
Any command line interface in Cluster API (e.g. clusterctl) share the same versioning schema of the codebase. CLI guarantees are inspired by Kubernetes deprecation policy for CLI, however we allow breaking changes after 8 months or 2 releases (whichever is longer) from deprecation.
Cluster API has two types of branches: the main branch and release-X branches.
The main branch is where development happens. All the latest and greatest code, including breaking changes, happens on main.
The release-X branches contain stable, backwards compatible code. On every major or minor release, a new branch is created. It is from these branches that minor and patch releases are tagged. In some cases, it may be necessary to open PRs for bugfixes directly against stable branches, but this should generally not be the case.
Cluster API maintains the most recent release/releases for all supported API and contract versions. Support for this section refers to the ability to backport and release patch versions; backport policy is defined above.
- The API version is determined from the GroupVersion defined in the top-level
api/package. - The EOL date of each API Version is determined from the last release available once a new API version is published.
| API Version | Supported Until |
|---|---|
| v1beta1 | TBD (current stable) |
- For the current stable API version (v1beta1) we support the two most recent minor releases; older minor releases are immediately unsupported when a new major/minor release is available.
- For older API versions we only support the most recent minor release until the API version reaches EOL.
- We will maintain test coverage for all supported minor releases and for one additional release for the current stable API version in case we have to do an emergency patch release. For example, if v1.2 and v1.3 are currently supported, we will also maintain test coverage for v1.1 for one additional release cycle. When v1.4 is released, tests for v1.1 will be removed.
| Minor Release | API Version | Supported Until |
|---|---|---|
| v1.7.x | v1beta1 | when v1.9.0 will be released |
| v1.6.x | v1beta1 | when v1.8.0 will be released |
| v1.5.x | v1beta1 | when v1.7.0 will be released |
| v1.4.x | v1beta1 | EOL since 2023-12-05 - v1.6.0 release date |
| v1.3.x | v1beta1 | EOL since 2023-07-25 - v1.5.0 release date |
| v1.2.x | v1beta1 | EOL since 2023-03-28 - v1.4.0 release date |
| v1.1.x | v1beta1 | EOL since 2022-07-18 - v1.2.0 release date (*) |
| v1.0.x | v1beta1 | EOL since 2022-02-02 - v1.1.0 release date (*) |
| v0.4.x | v1alpha4 | EOL since 2022-04-06 - API version EOL |
| v0.3.x | v1alpha3 | EOL since 2022-02-23 - API version EOL |
(*) Previous support policy applies, older minor releases were immediately unsupported when a new major/minor release was available
- Exceptions can be filed with maintainers and taken into consideration on a case-by-case basis.
Both v1alpha3 and v1alpha4 have been removed from Cluster API as of release 1.7.
For more details and latest information please see the following issue: Removing v1alpha3 & v1alpha4 apiVersions.
Note: Removal of a deprecated APIVersion in Kubernetes can cause issues with garbage collection by the kube-controller-manager This means that some objects which rely on garbage collection for cleanup - e.g. MachineSets and their descendent objects, like Machines and InfrastructureMachines, may not be cleaned up properly if those objects were created with an APIVersion which is no longer served. To avoid these issues it's advised to ensure a restart to the kube-controller-manager is done after upgrading to a version of Cluster API which drops support for an APIVersion - e.g. v1.5 and v1.6. This can be accomplished with any Kubernetes control-plane rollout, including a Kubernetes version upgrade, or by manually stopping and restarting the kube-controller-manager.
- If you haven't already done so, sign a Contributor License Agreement (see details above).
- If working on an issue, signal other contributors that you are actively working on it using
/lifecycle active. - Fork the desired repo, develop and test your code changes.
- Submit a pull request.
- All code PR must be labeled with one of
⚠️ (:warning:, major or breaking changes)- ✨ (
:sparkles:, feature additions) - 🐛 (
:bug:, patch and bugfixes) - 📖 (
:book:, documentation or proposals) - 🌱 (
:seedling:, minor or other)
- All code PR must be labeled with one of
- If your PR has multiple commits, you must squash them into a single commit before merging your PR.
Individual commits should not be tagged separately, but will generally be assumed to match the PR. For instance, if you have a bugfix in with a breaking change, it's generally encouraged to submit the bugfix separately, but if you must put them in one PR, mark the commit separately.
All changes must be code reviewed. Coding conventions and standards are explained in the official developer docs. Expect reviewers to request that you avoid common go style mistakes in your PRs.
The documentation is published in form of a book at:
- Current stable release
- Tip of the main branch
- v1alpha4 release branch
- v1alpha3 release branch
- v1alpha2 release branch
The source for the book is this folder containing markdown files and we use mdBook to build it into a static website.
After making changes locally you can run make serve-book which will build the HTML version
and start a web server, so you can preview if the changes render correctly at
https://localhost:3000; the preview auto-updates when changes are detected.
Note: you don't need to have mdBook installed, make serve-book will ensure
appropriate binaries for mdBook and any used plugins are downloaded into
hack/tools/bin/ directory.
When submitting the PR remember to label it with the 📖 (:book:) icon.
Cluster API release process is described in this document.
The Cluster API Enhancement Proposal is the process this project uses to adopt new features, changes to the APIs, changes to contracts between components, or changes to CLI interfaces.
The template, and accepted proposals live under docs/proposals.
- Proposals or requests for enhancements (RFEs) MUST be associated with an issue.
- Issues can be placed on the roadmap during planning if there is one or more folks that can dedicate time to writing a CAEP and/or implementing it after approval.
- A proposal SHOULD be introduced and discussed during the weekly community meetings or on the
Kubernetes SIG Cluster Lifecycle mailing list.
- Submit and discuss proposals using a collaborative writing platform, preferably Google Docs, share documents with edit permissions with the Kubernetes SIG Cluster Lifecycle mailing list.
- A proposal in a Google Doc MUST turn into a Pull Request.
- Proposals MUST be merged and in
implementablestate to be considered part of a major or minor release.
When you submit a change to the Cluster API repository as set of validation jobs is automatically executed by prow and the results report is added to a comment at the end of your PR.
Some jobs run linters or unit test, and in case of failures, you can repeat the same operation locally using make test lint [etc..]
in order to investigate and potential issues. Prow logs usually provide hints about the make target you should use
(there might be more than one command that needs to be run).
End-to-end (E2E) jobs create real Kubernetes clusters by building Cluster API artifacts with the latest changes. In case of E2E test failures, usually it's required to access the "Artifacts" link on the top of the prow logs page to triage the problem.
The artifact folder contains:
- A folder with the clusterctl local repository used for the test, where you can find components yaml and cluster templates.
- A folder with logs for all the clusters created during the test. Following logs/info are available:
- Controller logs (only if the cluster is a management cluster).
- Dump of the Cluster API resources (only if the cluster is a management cluster).
- Machine logs (only if the cluster is a workload cluster)
In case you want to run E2E test locally, please refer to the Testing guide. An overview over our e2e test jobs (and also all our other jobs) can be found in Jobs.
Parts of the following content have been adapted from https://google.github.io/eng-practices/review.
Any Kubernetes organization member can leave reviews and /lgtm a pull request.
Code reviews should generally look at:
- Design: Is the code well-designed and consistent with the rest of the system?
- Functionality: Does the code behave as the author (or linked issue) intended? Is the way the code behaves good for its users?
- Complexity: Could the code be made simpler? Would another developer be able to easily understand and use this code when they come across it in the future?
- Tests: Does the code have correct and well-designed tests?
- Naming: Did the developer choose clear names for variable, types, methods, functions, etc.?
- Comments: Are the comments clear and useful? Do they explain why rather than what?
- Documentation: Did the developer also update relevant documentation?
See Code Review in Cluster API for a more focused list of review items.
Please see the Kubernetes community document on pull requests for more information about the merge process.
- A PR is approved by one of the project maintainers and owners after reviews.
- Approvals should be the very last action a maintainer takes on a pull request.
Open issues to report bugs, or discuss minor feature implementation.
Each new issue will be automatically labeled as needs-triage; after being triaged by the maintainers the label
will be removed and replaced by one of the following:
triage/accepted: Indicates an issue or PR is ready to be actively worked on.triage/duplicate: Indicates an issue is a duplicate of another open issu