This document is the canonical source of truth for things like supported toolchain versions for building Kubernetes.
Please submit an issue on Github if you * Notice a requirement that this doc does not capture. * Find a different doc that specifies requirements (the doc should instead link here).
Development branch requirements will change over time, but release branch requirements are frozen.
Determine whether your issue or pull request is improving Kubernetes’ architecture or whether it’s simply fixing a bug.
If you need a diagram, add it. SEPARATE the description of the problem (e.g. Y is a critical component that is too slow for an SLA that we care about) from the solution (e.g. make X faster).
Some of these checks were less common in Kubernetes’ earlier days. Now that we have over 1000 contributors, each issue should be filed with care. No issue should take more than 5 minutes to check for sanity (even the busiest of reviewers can spare 5 minutes to review a patch that is thoughtfully justified).
Simple bug patches are easy to review since test coverage is submitted with the patch. Bug fixes don’t usually require a lot of extra testing, but please update the unit tests so they catch the bug!
Some examples of “Architecture” improvements include:
These sorts of improvements are easily evaluated, especially when they decrease lines of code without breaking functionality. That said, please explain exactly what you are ‘cleaning up’ in your Pull Request so as not to waste a reviewer’s time.
If you’re making code more resilient, include tests that demonstrate the new resilient behavior. For example: if your patch causes a controller to better handle inconsistent data, make a mock object which returns incorrect data a few times and verify the controller’s new behaviour.
Performance bug reports MUST include data that demonstrates the bug. Without data, the issue will be closed. You can measure performance using kubemark, scheduler_perf, go benchmark tests, or e2e tests on a real cluster with metric plots.
Examples of how NOT to suggest a performance bug (these lead to a long review process and waste cycles):
The above statements have no value to a reviewer because neither is backed by data. Writing issues like this lands your PR in a no-man’s-land and waste your reviewers’ time.
Examples of possible performance improvements include (remember, you MUST document the improvement with data):
These issues should always be submitted with (in decreasing order of value):
Here are some examples of properly submitted performance issues. If you are new to kubernetes and thinking about filing a performance optimization, re-read one or all of these before you get started.
Since performance improvements can be empirically measured, you should follow the “scientific method” of creating a hypothesis, collecting data, and then revising your hypothesis. The above issues do this transparently, using figures and data rather then conjecture. Notice that the problem is analyzed and a correct solution is created before a single line of code is reviewed.
Official releases are built using Docker containers. To build Kubernetes using Docker please follow these instructions.
Kubernetes development helper scripts assume an up-to-date GNU tools environment. Recent Linux distros should work out-of-the-box.
macOS ships with outdated BSD-based tools. We recommend installing macOS GNU tools.
Kubernetes maintains state in
etcd, a distributed key store.
Please install it locally to run local integration tests.
|1.0 - 1.2||1.4.2|
|1.5, 1.6||1.7 - 1.7.5|
Ensure your GOPATH and PATH have been configured in accordance with the Go environment instructions.
Upgrading Go requires specific modification of some scripts and container images.
FROMthe desired Go version.
godep to manage
Developers who need to manage dependencies in the
vendor/ tree should read
the docs on using godep to manage dependencies.
Building with Bazel is currently experimental. For more information, see Build with Bazel.
To check out code to work on, please refer to this guide.