How To Contribute

Clone and Provision Environment

  1. Make sure you have a GitHub account

  2. Fork the Cilium repository to your GitHub user or organization.

  3. Turn off GitHub actions for your fork as described in the GitHub Docs. This is recommended to avoid unnecessary CI notification failures on the fork.

  4. Clone your ${YOUR_GITHUB_USERNAME_OR_ORG}/cilium fork into your GOPATH, and setup the base repository as upstream remote:

    mkdir -p "${GOPATH}/src/github.com/cilium"
    cd "${GOPATH}/src/github.com/cilium"
    git clone https://github.com/${YOUR_GITHUB_USERNAME_OR_ORG}/cilium.git
    cd cilium
    git remote add upstream https://github.com/cilium/cilium.git
    
  5. Set up your Development Setup.

  6. Check the GitHub issues for good tasks to get started.

  7. Follow the steps in Making Changes to start contributing :)

Submitting a pull request

Contributions must be submitted in the form of pull requests against the upstream GitHub repository at https://github.com/cilium/cilium.

  1. Fork the Cilium repository.

  2. Push your changes to the topic branch in your fork of the repository.

  3. Submit a pull request on https://github.com/cilium/cilium.

Before hitting the submit button, please make sure that the following requirements have been met:

  1. Take some time to describe your change in the PR description! A well-written description about the motivation of the change and choices you made during the implementation can go a long way to help the reviewers understand why you’ve made the change and why it’s a good way to solve your problem. If it helps you to explain something, use pictures or Mermaid diagrams.

  2. Each commit must compile and be functional on its own to allow for bisecting of commits in the event of a bug affecting the tree.

  3. All code is covered by unit and/or runtime tests where feasible.

  4. All changes have been tested and checked for regressions by running the existing testsuite against your changes. See the End-To-End Testing Framework section for additional details.

  5. All commits contain a well written commit description including a title, description and a Fixes: #XXX line if the commit addresses a particular GitHub issue. Note that the GitHub issue will be automatically closed when the commit is merged.

    apipanic: Log stack at debug level
    
    Previously, it was difficult to debug issues when the API panicked
    because only a single line like the following was printed:
    
    level=warning msg="Cilium API handler panicked" client=@ method=GET
    panic_message="write unix /var/run/cilium/cilium.sock->@: write: broken
    pipe"
    
    This patch logs the stack at this point at debug level so that it can at
    least be determined in developer environments.
    
    Fixes: #4191
    
    Signed-off-by: Joe Stringer <joe@cilium.io>
    

    Note

    Make sure to include a blank line in between commit title and commit description.

  6. If any of the commits fixes a particular commit already in the tree, that commit is referenced in the commit message of the bugfix. This ensures that whoever performs a backport will pull in all required fixes:

    daemon: use endpoint RLock in HandleEndpoint
    
    Fixes: a804c7c7dd9a ("daemon: wait for endpoint to be in ready state if specified via EndpointChangeRequest")
    
    Signed-off-by: André Martins <andre@cilium.io>
    

    Note

    The proper format for the Fixes: tag referring to commits is to use the first 12 characters of the git SHA followed by the full commit title as seen above without breaking the line.

  7. If you change CLI arguments of any binaries in this repo, the CI will reject your PR if you don’t also update the command reference docs. To do so, make sure to run the postcheck make target.

    $ make postcheck
    $ git add Documentation/cmdref
    $ git commit
    
  8. All commits are signed off. See the section Developer’s Certificate of Origin.

    Note

    Passing the -s option to git commit will add the Signed-off-by: line to your commit message automatically.

  9. Document any user-facing or breaking changes in Documentation/operations/upgrade.rst.

  10. (optional) Pick the appropriate milestone for which this PR is being targeted, e.g. 1.6, 1.7. This is in particular important in the time frame between the feature freeze and final release date.

  11. If you have permissions to do so, pick the right release-note label. These labels will be used to generate the release notes which will primarily be read by users.

    Labels

    When to set

    release-note/bug

    This is a non-trivial bugfix and is a user-facing bug

    release-note/major

    This is a major feature addition, e.g. Add MongoDB support

    release-note/minor

    This is a minor feature addition, e.g. Add support for a Kubernetes version

    release-note/misc

    This is a not user-facing change , e.g. Refactor endpoint package, a bug fix of a non-released feature

    release-note/ci

    This is a CI feature of bug fix.

  12. Verify the release note text. If not explicitly changed, the title of the PR will be used for the release notes. If you want to change this, you can add a special section to the description of the PR. These release notes are primarily going to be read by users so it is important that release notes for bugs, major and minor features do not contain internal details of Cilium functionality which sometimes are irrelevant for users.

    Example of a bad release note

    ```release-note
    Fix concurrent access in k8s watchers structures
    ```
    

    Example of a good release note

    ```release-note
    Fix panic when Cilium received an invalid Cilium Network Policy from Kubernetes
    ```
    

    Note

    If multiple lines are provided, then the first line serves as the high level bullet point item and any additional line will be added as a sub item to the first line.

  13. If you have permissions, pick the right labels for your PR:

    Labels

    When to set

    kind/bug

    This is a bugfix worth mentioning in the release notes

    kind/enhancement

    This enhances existing functionality in Cilium

    kind/feature

    This is a feature

    release-blocker/X.Y

    This PR should block the next X.Y release

    needs-backport/X.Y

    PR needs to be backported to these stable releases

    backport/X.Y

    This is backport PR, may only be set as part of Backporting process

    upgrade-impact

    The code changes have a potential upgrade impact

    area/* (Optional)

    Code area this PR covers

    Note

    If you do not have permissions to set labels on your pull request. Leave a comment and a core team member will add the labels for you. Most reviewers will do this automatically without prior request.

  14. Open a draft pull request. GitHub provides the ability to create a Pull Request in “draft” mode. On the “New Pull Request” page, below the pull request description box there is a button for creating the pull request. Click the arrow and choose “Create draft pull request”. If your PR is still a work in progress, please select this mode. You will still be able to run the CI against it. Once the PR is ready for review you can click in “Ready for review” button at the bottom of the page” and reviewers will start reviewing. When you are actively changing your PR, set it back to draft PR mode to signal that reviewers do not need to spend time reviewing the PR right now. When it is ready for review again, mark it as such.

https://i1.wp.com/user-images.githubusercontent.com/3477155/52671177-5d0e0100-2ee8-11e9-8645-bdd923b7d93b.gif

Getting a pull request merged

  1. As you submit the pull request as described in the section Submitting a pull request. One of the reviewers will start a CI run by replying with a comment /test as described in CI Failure Triage. If you are a core team member, you may trigger the CI run yourself. CI consists of:

    1. Static code analysis by Github Actions and Travis CI. Golang linter suggestions are added in-line on PRs. For other failed jobs, please refer to build log for required action (e.g. Please run go mod tidy && go mod vendor and submit your changes, etc).

    2. CI / Jenkins: Will run a series of tests:

      1. Unit tests

      2. Single node runtime tests

      3. Multi node Kubernetes tests

      If a CI test fails which seems unrelated to your PR, it may be a flaky test. Follow the process described in CI Failure Triage.

  2. As part of the submission, GitHub will have requested a review from the respective code owners according to the CODEOWNERS file in the repository.

    1. Address any feedback received from the reviewers

    2. You can push individual commits to address feedback and then rebase your branch at the end before merging.

    3. Once you have addressed the feedback, re-request a review from the reviewers that provided feedback by clicking on the button next to their name in the list of reviewers. This ensures that the reviewers are notified again that your PR is ready for subsequent review.

  3. Owners of the repository will automatically adjust the labels on the pull request to track its state and progress towards merging.

  4. Once the PR has been reviewed and the CI tests have passed, the PR will be merged by one of the repository owners. In case this does not happen, ping us on Slack in the #development channel.

Handling large pull requests

If the PR is considerably large (e.g. with more than 200 lines changed and/or more than 6 commits), consider whether there is a good way to split the PR into smaller PRs that can be merged more incrementally. Reviewers are often more hesitant to review large PRs due to the level of complexity involved in understanding the changes and the amount of time required to provide constructive review comments. By making smaller logical PRs, this makes it easier for the reviewer to provide comments and to engage in dialogue on the PR, and also means there should be fewer overall pieces of feedback that you need to address as a contributor. Tighter feedback cycles like this then make it easier to get your contributions into the tree, which also helps with reducing conflicts with other contributions. Good candidates for smaller PRs may be individual bugfixes, or self-contained refactoring that adjusts the code in order to make it easier to build subsequent functionality on top.

While handling review on larger PRs, consider creating a new commit to address feedback from each review that you receive on your PR. This will make the review process smoother as GitHub has limitations that prevents reviewers from only seeing the new changes added since the last time they have reviewed a PR. Once all reviews are addressed those commits should be squashed against the commit that introduced those changes. This can be accomplished by the usage of git rebase -i upstream/master and in that windows, move these new commits below the commit that introduced the changes and replace the work pick with fixup. In the following example, commit d2cb02265 will be combined into 9c62e62d8 and commit 146829b59 will be combined into 9400fed20.

pick 9c62e62d8 docs: updating contribution guide process
fixup d2cb02265 joe + paul + chris changes
pick 9400fed20 docs: fixing typo
fixup 146829b59 Quentin and Maciej reviews

Once this is done you can perform push force into your branch and request for your PR to be merged.

Pull requests review process for committers

Every committer in the committers team belongs to one or more other teams in the Cilium organization If you would like to be added or removed from any team, please contact any of the maintainers.

Once a PR is opened by a contributor, GitHub will automatically pick which teams should review the PR using the CODEOWNERS file. Each committer can see the PRs they need to review by filtering by reviews requested. A good filter is provided in this link so make sure to bookmark it.

Reviewers are expected to focus their review on the areas of the code where GitHub requested their review. For small PRs, it may make sense to simply review the entire PR. However, if the PR is quite large then it can help to narrow the area of focus to one particular aspect of the code. When leaving a review, share which areas you focused on and which areas you think that other reviewers should look into. This will help others to focus on aspects of review that have not been covered as deeply.

Belonging to a team does not mean that a committer should know every single line of code the team is maintaining. For this reason it is recommended that once you have reviewed a PR, if you feel that another pair of eyes is needed, you should re-request a review from the appropriate team. In the example below, the committer belonging to the CI team is re-requesting a review for other team members to review the PR. This allows other team members belonging to the CI team to see the PR as part of the PRs that require review in the filter.

../../../_images/re-request-review.png

When all review objectives for all CODEOWNERS are met, all required CI tests have passed and a proper release label as been set, you may set the ready-to-merge label to indicate that all criteria have been met. Maintainer’s little helper might set this label automatically if the previous requirements were met.

Labels

When to set

ready-to-merge

PR is ready to be merged

Code Owners

Code owners are used by the Cilium community to consolidate common knowledge into teams that can provide consistent and actionable feedback to contributors. This section will describe groups of teams and suggestions about the focus areas for review.

The primary motivation for these teams is to provide structure around review processes to ensure that contributors know how to reach out to community members to conduct discussions, ensure contributions meet the expectations of the community, and align on the direction of proposed changes. Furthermore, while these teams are primarily drawn upon to provide review on specific pull requests, they are also encouraged to self-organize around how to make improvements to their areas of the Cilium project over time.

Any committer may self-nominate to code owner teams. Reach out to the core team on the #committers channel in Slack to coordinate. Committers do not require expert knowledge in an area in order to join a code owner team, only a willingness to engage in discussions and learn about the area.

Project-wide

These code owners may provide feedback for Pull Requests submitted to any repository in the Cilium project:

  • @cilium/api: Ensure the backwards-compatibility of Cilium REST and gRPC APIs, including for Hubble flow export.

  • @cilium/build: Provide feedback on languages and scripting used for build and packaging system: Make, Shell, Docker.

  • @cilium/cli: Provide user experience feedback on changes to Command-Line Interfaces. These owners are a stand-in for the user community to bring a user perspective to the review process. Consider how information is presented, consistency of flags and options.

  • @cilium/ci-structure: Provide guidance around the best use of Cilium project continuous integration and testing infrastructure, including GitHub actions, VM helpers, testing frameworks, etc.

  • @cilium/contributing: Encourage practices that ensure an inclusive contributor community. Review tooling and scripts used by contributors.

  • @cilium/docs-structure: Ensure the consistency and layout of documentation. General feedback on the use of Sphinx, how to communicate content clearly to the community. This code owner is not expected to validate the technical correctness of submissions. Correctness is typically handled by another code owner group which is also assigned to any given piece of documentation.

  • @cilium/github-sec: Responsible for maintaining the security of repositories in the Cilium project by maintaining best practices for workflow usage, for instance preventing malicious use of GitHub actions.

  • @cilium/helm: Provide input on the way that Helm can be used to configure features. These owners are a stand-in for the user community to bring a user perspective to the review process. Ensure that Helm changes are defined in manners that will be forward-compatible for upgrade and follow best practices for deployment (for example, being GitOps-friendly).

  • @cilium/metrics: Provide recommendations about the types, names and labels for metrics to follow best practices. This includes considering the cardinality impact of metrics being added or extended.

  • @cilium/tophat: Top Hat duties rotate between the committer group from week to week, and they may assist in maintenance, triage and backporting duties across different Cilium repositories. Catch-all for code not otherwise owned by a team.

  • @cilium/vendor: Review vendor updates for software dependencies to check for any potential upstream breakages / incompatibilities. Discourage the use of unofficial forks of upstream libraries if they are actively maintained.

Repository Owners

The following code owners are responsible for a range of general feedback for contributions to specific repositories:

  • @cilium/sig-hubble: Review all Cilium and Hubble code related to observing system events, exporting those via gRPC protocols outside the node and outside the cluster. those event channels, for example via TLS.

  • @cilium/hubble-ui: Maintain the Hubble UI graphical interface.

  • @cilium/tetragon: Review of all Tetragon code, both for Go and C (for eBPF).

The teams above are responsible for reviewing the majority of contributions to the corresponding repositories. Additionally, there are “maintainer” teams listed below which may not be responsible for overall code review for a repository, but they have administrator access to the repositories and so they can assist with configuring GitHub repository settings, secrets, and related processes. For the full codeowners for individual repositories, see the CODEOWNERS file in the corresponding repository.

Cloud Integrations

The following codeowner groups provide insight into the integrations with specific cloud providers:

Cilium Internals

The following codeowner groups cover more specific knowledge about Cilium Agent internals or the way that particular Cilium features interact with external software and protocols:

  • @cilium/docker: Maintain the deprecated docker-plugin.

  • @cilium/endpoint: Provide background on how the Cilium Endpoint package fits into the overall agent architecture, relationship with generation of policy / datapath constructs, serialization and restore from disk.

  • @cilium/health: Review any contributions that impact cluster-wide health probing via periodic in-agent probes; bootstrapping of the simulated health ‘endpoint’ that provides an IP and HTTP endpoint for network health probing.

  • @cilium/ipcache: Provide background on how the userspace IPCache structure fits into the overall agent architecture, ordering constraints with respect to network policies and encryption. Handle the relationship between Kubernetes state and datapath state as it pertains to remote peers.

  • @cilium/kvstore: Review Cilium interactions with key-value stores, particularly etcd. Understand the client libraries used by Cilium for sharing state between nodes and clusters.

  • @cilium/loader: Maintain the tooling that allows eBPF programs to be loaded into the kernel: LLVM, bpftool, use of cilium/ebpf for loading programs in the agent, ELF templating, etc.

  • @cilium/operator: Review operations that occur once per cluster via the Cilium Operator component. Take care of the corresponding garbage collection and leader election logic.

  • @cilium/proxy: Review low-level implementations used to redirect and process traffic at Layer 7, including via the Cilium DNS proxy and Envoy. Maintain the configurations for Envoy via xDS protocols as well as the extensible proxylib framework for Go-based layer 7 filters.

  • @cilium/sig-agent: Provide Cilium (agent) general Go review. Internal architecture, core data structures and daemon startup.

  • @cilium/sig-clustermesh: Ensure the reliability of state sharing between clusters to ensure that each cluster maintains a separate fault domain.

  • @cilium/sig-datapath: Provide feedback on all eBPF code changes, use of the kernel APIs for configuring the networking and socket layers. Coordination of kernel subsystems such as xfrm (IPsec), iptables / nftables, tc. Maintain the control plane layers that populate most eBPF maps; account for endianness and system architecture impacts on the datapath code.

  • @cilium/sig-hubble: Review all Cilium and Hubble code related to observing system events, exporting those via gRPC protocols outside the node and outside the cluster. Ensure the security of those event channels, for example via TLS.

  • @cilium/sig-ipam: Coordinate the implementation between all of the IP Address Management modes, provide awareness/insight into IP resource exhaustion and garbage collection concerns.

  • @cilium/sig-k8s: Provide input on all interactions with Kubernetes, both for standard resources and CRDs. Ensure best practices are followed for the coordination of clusterwide state in order to minimize memory usage.

  • @cilium/sig-lb: Maintain the layers necessary to coordinate all load balancing configurations within the agent control plane, including Services, ClusterIP, NodePorts, Maglev, BGP export, local redirect policies, and NAT46/NAT64.

  • @cilium/sig-policy: Ensure consistency of semantics for all network policy representations. Responsible for all policy logic from Kubernetes down to eBPF policymap entries, including all intermediate layers such as the Policy Repository, SelectorCache, PolicyCache, CachedSelectorPolicy, EndpointPolicy, etc.

  • @cilium/sig-servicemesh: Provide input on the way that Service Mesh constructs such as Gateway API are converted into lower-level constructs backed by eBPF or Envoy configurations. Maintain the CRDs necessary for Service Mesh functionality.

  • @cilium/wireguard: Maintain the kernel WireGuard configuration and datapath impacts related to ensuring traffic is encrypted correctly when WireGuard mode is enabled.

Weekly duties

Some members of the committers team will have rotational duties that change every week. The following steps describe how to perform those duties. Please submit changes to these steps if you have found a better way to perform each duty.

Pull request review process

Note

These instructions assume that whoever is reviewing is a member of the Cilium GitHub organization or has the status of a committer. This is required to obtain the privileges to modify GitHub labels on the pull request.

Dedicated expectation time for review duties: Follow the next steps 1 to 2 times per day.

  1. Review all PRs needing a review from you;

  2. If this PR was opened by a non-committer (e.g. external contributor) please assign yourself to that PR and make sure to keep track the PR gets reviewed and merged. This may extend beyond your assigned week for Janitor duty.

    If the contributor is a Cilium committer, then they are responsible for getting the PR in a ready to be merged state by adding the ready-to-merge label, once all reviews have been addressed and CI checks are successful, so that the janitor can merge it (see below).

    If this PR is a backport PR (e.g. with the label kind/backport) and no-one else has reviewed the PR, review the changes as a sanity check. If any individual commits deviate from the original patch, request review from the original author to validate that the backport was correctly applied.

  3. Review overall correctness of the PR according to the rules specified in the section Submitting a pull request.

    Set the labels accordingly, a bot called maintainer’s little helper might automatically help you with this.

    Labels

    When to set

    dont-merge/needs-sign-off

    Some commits are not signed off

    needs-rebase

    PR is outdated and needs to be rebased

  4. Validate that bugfixes are marked with kind/bug and validate whether the assessment of backport requirements as requested by the submitter conforms to the Backport Criteria.

    Labels

    When to set

    needs-backport/X.Y

    PR needs to be backported to these stable releases

  5. If the PR is subject to backport, validate that the PR does not mix bugfix and refactoring of code as it will heavily complicate the backport process. Demand for the PR to be split.

  6. Validate the release-note/* label and check the PR title for release note suitability. Put yourself into the perspective of a future release notes reader with lack of context and ensure the title is precise but brief.

    Labels

    When to set

    dont-merge/needs-release-note

    Do NOT merge PR, needs a release note

    release-note/bug

    This is a non-trivial bugfix and is a user-facing bug

    release-note/major

    This is a major feature addition, e.g. Add MongoDB support

    release-note/minor

    This is a minor feature addition, e.g. Add support for a Kubernetes version

    release-note/misc

    This is a not user-facing change , e.g. Refactor endpoint package, a bug fix of a non-released feature

    release-note/ci

    This is a CI feature of bug fix.

  7. Check for upgrade compatibility impact and if in doubt, set the label upgrade-impact and discuss in the Slack channel or in the weekly meeting.

    Labels

    When to set

    upgrade-impact

    The code changes have a potential upgrade impact

  8. When all review objectives for all CODEOWNERS are met, all CI tests have passed, and all reviewers have approved the requested changes, merge the PR by clicking in the “Rebase and merge” button.

  9. Merge PRs with the ready-to-merge label set here

  10. If the PR is a backport PR, update the labels of cherry-picked PRs with the command included at the end of the original post. For example:

    $ for pr in 12589 12568; do contrib/backporting/set-labels.py $pr done 1.8; done
    

Triage issues

Dedicated expectation time for triage duties: 15/30 minutes per day. Works best if done first thing in the working day.

  1. Ensure that:

    1. Issues opened by community users are tracked down:

      1. Add the label kind/community-report;

      2. If feasible, try to reproduce the issue described;

      3. Assign a member that is responsible for that code section to that GitHub issue;

      4. If it is a relevant bug to the rest of the committers, bring the issue up in the weekly meeting. For example:

        • The issue may impact an upcoming release; or

        • The resolution is unclear and assistance is needed to make progress; or

        • The issue needs additional attention from core contributors to confirm the resolution is the right path.

    2. Issues recently commented are not left out unanswered:

      1. If there is someone already assigned to that GitHub issue and that committer hasn’t provided an answer to that user for a while, ping that committer directly on Slack;

      2. If the issue cannot be solved, bring the issue up in the weekly meeting.

Backporting community PRs

Dedicated expectation time for backporting duties: 60 minutes, twice per week depending on releases that need to be performed at the moment.

Even if the next release is not imminently planned, it is still important to perform backports to keep the process smooth and to catch potential regressions in stable branches as soon as possible. If backports are delayed, this can also delay releases which is important to avoid especially if there are security-sensitive bug fixes that require an immediate release.

If you can’t backport a PR due technical constraints feel free to contact the original author of that PR directly so they can backport the PR themselves.

Follow the Backporting process guide to know how to perform this task.

Coordination

In general, the committer with the top hat should coordinate with other core team members in the #launchpad Slack channel in order to understand the status of the review, triage and backport duties. This is especially important when the top hat is rotated from one committer to another, as well as when a release is planned for the upcoming week.

An example interaction in #launchpad:

Starting backport round for v1.7 and v1.8 now

If there are many backports to be done, then splitting up the rounds can be beneficial. Typically, backporters opt to start a round in the beginning of the week and then another near the end of the week.

By the start / end of the week, if there are other backport PRs that haven’t been merged, then please coordinate with the previous / next backporter to check what the status is and establish who will work on getting the backports into the tree (for instance by investigating CI failures and addressing review feedback). Ensure that the responsibility for driving the PRs forward is clear.

Developer’s Certificate of Origin

To improve tracking of who did what, we’ve introduced a “sign-off” procedure.

The sign-off is a simple line at the end of the explanation for the commit, which certifies that you wrote it or otherwise have the right to pass it on as open-source work. The rules are pretty simple: if you can certify the below:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

then you just add a line saying:

Signed-off-by: Random J Developer <random@developer.example.org>

Use your real name (sorry, no pseudonyms or anonymous contributions.)

If you need to add your sign off to a commit you have already made, please see this article.