Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing Guidelines

Contributions are very welcome in the form of issues and pull requests but also:

Contributors who are not used to working in the Kubernetes ecosystem should also take a look at the New Contributor Course and the Contributors Cheatsheet.

Code of Conduct

Please read carefully the Community Code of Conduct.

AI Guidance

The project aligns to Kubernetes AI guidance.

Above all, as Cluster API project maintainers and reviewers we want to engage directly with you, not with a bot.

Accordingly, when you engage with maintainers and reviewers in this project:

  • When writing a comment, please keep in mind that your opinion and your concrete use cases are unique, important and valuable, while a comment generated by a bot is not.
  • When you open a PR, be aware that concise PR descriptions are usually more helpful (and welcome) than lengthy AI generated ones.
  • When responding to review comments, you must do so without relying on AI tools.
  • As a rule of thumb, assume that AI generated comments are going to be ignored.
  • If a user will repeatedly disrupt discussion threads with AI generated comments, we are going to report it.

TL;DR; Great contributors use AI wisely to amplify their impact and reputation, but if your plan is to rely on AI only, Cluster API project maintainers and reviewers would not invest time in your work (see Cluster API manifesto#community).

Office hours, Slack channel

Chat with us on the Kubernetes Slack in the #cluster-api channel.

Subscribe to the SIG Cluster Lifecycle Google Group for access to documents and calendars.

Join our Cluster API office hour meeting where we share the latest project news, demos, answer questions, discuss issues and pull requests.

Opening an issue

Carefully read the AI guidance.

Before opening a new issue, please check if there is already an existing issue about the same topic (duplicated issues will be closed).

Open a New issues to report bugs, propose new features, ask for support.

Each new issue will be automatically labeled as needs-triage, which will surface the issue to maintainers during the triage process; make sure to follow up to maintainers question during this phase.

Depending on the outcomes of the triage process needs-triage 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/needs-information: Indicates an issue needs more information in order to work on it.
  • triage/not-reproducible: Indicates an issue can not be reproduced as described.
  • triage/duplicate: Indicates an issue is a duplicate of another open issue.

For big features, API and contract changes, or complex changes you might also be required to write a Cluster API enhancement proposal as outlined below.

Code contributions (pull requests)

  • Important!

  • Unless you are working on a trivial change, make sure that there is an issue describing what you are achieving. See existing issue, Opening an issue

    • check that the issue has the triage/accepted label; if not it means that there is not yet agreement on how to address the issue and most likely your PR will be closed immediately. See triaging issues
    • signal other contributors that you are actively working on the by assigning it to yourself. See issue management.
    • If in the issue there are comments stating that additional research is required, make sure to share the outcomes of this work and to get consensus on a way forward before opening the pull request.
    • Note: We have a semi-curated list of Good first issue that should not need deep knowledge of the system; Help wanted issues instead required deeper knowledge of the system and are not recommended for newcomers.

  • Develop and test your code changes locally.

  • Submit the 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)
    • Unfinished PR should be marked with the [WIP] prefix.

  • Ensure that all the linters and the E2E tests included in the CI signal for your PR are passing, see triaging failing or flaky tests

  • All code changes must be reviewed and approved

Documentation changes

The documentation is published in form of a book at: https://cluster-api.sigs.k8s.io

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 http://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.

Issue comments, and Pull Request comments and review

Anyone may comment on issues and submit reviews for pull requests. However, in order to be assigned an issue or pull request, you must be a member of the Kubernetes SIGs GitHub organization.

In case you are not a member of the Kubernetes SIGs GitHub organization, Cluster API maintainers can assign you an issue or pull request by leaving a /assign <your Github ID> comment on the issue or pull request.

Backporting a pull request

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. It is from these branches that minor and patch releases are tagged.

If a pull requests against the main branch is backward compatible, it can be backported to a release branch using /cherry-pick prow command.

In some cases, it may be necessary to open PRs for bugfixes directly against stable branches, but this should generally not be the case.

Note: maintainers will monitor strictly backport requests to ensure stability of the release branches.

Cluster API enhancement proposal (CAEP)

Cluster API Enhancement Proposals are documents that this project uses to discuss 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 SIG Cluster Lifecycle mailing list.
    • Submit and discuss proposals using a collaborative writing platform, preferably Google Docs, share documents with edit permissions with the SIG Cluster Lifecycle mailing list.
  • A proposal in a Google Doc MUST turn into a Pull Request.
  • Proposals MUST be merged and in implementable state to be considered part of a major or minor release.

Triaging issues

Issue triage in Cluster API follows the best practices of the Kubernetes project while seeking balance with the different size of this project.

While the maintainers play an important role in the triage process described below, the help of the community is crucial to ensure that this task is performed timely and be sustainable long term.

PhaseResponsibleWhat is required to move forward
Initial triageMaintainersThe issue MUST have:
- priority/* label
- kind/* label
Triage finalizationEveryoneThere should be consensus on the way forward and enough details for the issue being actionable
Triage finalizationMaintainersThe issue MUST have:
- triage/accepted label
label, plus eventually help or good-first-issue label
ActionableEveryoneContributors volunteering time to do the work and reviewers/approvers bandwidth
The issue being fixed

Please note that:

  • Priority provides an indication to everyone looking at issues.

    • When assigning priority several factors are taken into consideration, including impact on users, relevance for the upcoming releases, maturity of the issue (consensus + completeness).
    • priority/awaiting-more-evidence is used to mark issue where there is not enough info to take a decision for one of the other priorities values.
    • Priority can change over time, and everyone is welcome to provide constructive feedback about updating an issue’s priority.
    • Applying a priority label is not a commitment to execute within a certain time frame, because implementation depends on contributors volunteering time to do the work and on reviewers/approvers bandwidth.

  • Closing inactive issues which are stuck in the “triage” phases is a crucial task for maintaining an actionable backlog. Accordingly, the following automation applies to issues in the “triage” or the “refinement” phase:

    • After 90 days of inactivity, issues will be marked with the lifecycle/stale label
    • After 30 days of inactivity from when lifecycle/stale was applied, issues will be marked with the lifecycle/rotten label
    • After 30 days of inactivity from when lifecycle/rotten was applied, issues will be closed. With this regard, it is important to notice that closed issues are and will always be a highly valuable part of the knowledge base about the Cluster API project, and they will never go away.
    • Note:
      • The automation above does not apply to issues triaged as priority/critical-urgent, priority/important-soon or priority/important-longterm
      • Maintainers could apply the lifecycle/frozen label if they want to exclude an issue from the automation above
      • Issues excluded from the automation above will be re-triaged periodically

  • If you really care about an issue stuck in the “triage” phases, you can engage with the community or try to figure out what is holding back the issue by yourself, e.g.:

    • Issue too generic or not yet actionable
    • Lack of consensus or the issue is not relevant for other contributors
    • Lack of contributors; in this case, finding ways to help and free up maintainers/other contributors time from other tasks can really help to unblock your issues.

  • Issues in the “actionable” state are not subject to the stale/rotten/closed process; however, it is required to re-assess them periodically given that the project change quickly. Accordingly, the following automation applies to issues in the “actionable” phase:

    • After 30 days of inactivity, the triage/accepted label will be removed from issues with priority/critical-urgent
    • After 90 days of inactivity the triage/accepted label will be removed from issues with priority/important-soon
    • After 1 year of inactivity the triage/accepted label will be removed from issues without priority/critical-urgent or priority/important-soon

  • If you really care about an issue stuck in the “actionable” phase, you can try to figure out what is holding back the issue implementation (usually lack of contributors), engage with the community, find ways to help and free up maintainers/other contributors time from other tasks, or /assign the issue and send a PR.

Triaging PR or periodic test failures

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.

Tests jobs are also run periodically on all the supported branches, see test-grid for latest test results.

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 Cluster API testing guide.

Contributors Ladder

The project follows the Kubernetes community membership guidelines.

New contributors are welcomed to the community by existing members, helped with PR workflow, and directed to relevant documentation and communication channels. We are also committed in helping people willing to do so in stepping up through the contributor ladder and this paragraph describes how we are trying to make this to happen.

As the project adoption increases and the codebase keeps growing, we’re trying to break down ownership into self-driven subareas of interest. Whenever you meet requisites for taking responsibilities in a subarea as a reviewer or maintainer, the following procedure should be followed:

  1. Submit a PR adding yourself to the OWNERS file.
  2. Broadcast your request at the community meeting.
  3. Get positive feedback and +1s in the PR and wait one week lazy consensus after agreement.

As of today there are following OWNERS files/Owner groups defining sub areas: