kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
community/contributors/devel/development.md

12 KiB
Raw Blame History

Development Guide

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.

Pre submit flight checks

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).

Is this just a simple bug fix?

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!

Is this an architecture improvement?

Some examples of "Architecture" improvements include:

  • Adding a new feature or making a feature more configurable or modular.
  • Improving test coverage.
  • Decoupling logic or creation of new utilities.
  • Making code more resilient (sleeps, backoffs, reducing flakiness, etc.).

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.

Is this a performance improvement ?

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):

  • We should be doing X instead of Y because it might lead to better performance.
  • Doing X instead of Y would reduce calls to Z.

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):

  • Improving a caching implementation.
  • Reducing calls to functions which are O(n^2)
  • Reducing dependence on API server requests.
  • Changing the value of default parameters for processes, or making those values 'smarter'.
  • Parallelizing a calculation that needs to run on a large set of node/pod objects.

These issues should always be submitted with (in decreasing order of value):

  • A golang Benchmark test.
  • A visual depiction of reduced metric load on a cluster (measurable using metrics/ endpoints and grafana).
  • A hand-instrumented timing test (i.e. adding some logs into the controller manager).

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.

Building Kubernetes with Docker

Official releases are built using Docker containers. To build Kubernetes using Docker please follow these instructions.

Building Kubernetes on a local OS/shell environment

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.

Developers with Windows machines have two choices available to run the needed tools:

  1. If you're using Windows 10 20h1, then you may install WSL2 and your distro of choice
  2. If you're using a previous version of Windows, then set up a Linux VM with at least 8GB of memory and 60GB of disk space.

In either case, the same Linux development tools and Kubernetes source code are needed. Start your WSL2 distro or connect to your Linux VM and follow the steps below to install the required tools.

make

Kubernetes local build system requires make command to be present in your corresponding development platform.

To install make command:

  • OS X
    • xcode-select --install (Following command will install CLI Tools to your local development environment)
  • Linux
    • sudo apt-get install build-essential (Following command will install essential commands like gcc, make etc.)

Docker

Kubernetes Development requires some of the verification tests which are ran through Docker. Hence, you will need Docker Pre-Installed on your development environment.

rsync

Kubernetes build system requires rsync command present in the development platform.

jq

Kube-apiserver requires jq to be installed to successfully build in your local environment. The jq installation guide provides detailed instructions for supported platforms.

Go

Kubernetes is written in Go. If you don't have a Go development environment, please set one up.

Kubernetes requires Go
1.0 - 1.2 1.4.2
1.3, 1.4 1.6
1.5, 1.6 1.7 - 1.7.5
1.7 1.8.1
1.8 1.8.3
1.9 1.9.1
1.10 1.9.1
1.11 1.10.2
1.12 1.10.4
1.13 1.11.13
1.14 - 1.16 1.12.9
1.17+ 1.13.4

Ensure your GOPATH and PATH have been configured in accordance with the Go environment instructions.

Upgrading Go

Upgrading Go requires specific modification of some scripts and container images.

PyYAML

Some Kubernetes verification tests use PyYAML and it therefore needs to be installed to successfully run all verification tests in your local environment. You can use the PyYAML documentation to find the installation instructions.

Quick Start

The following section is a quick start on how to build Kubernetes locally, for more detailed information you can see kubernetes/build. Before you start you will need to clone a local Kubernetes code base, refer to GitHub workflow for details on how to set this up.

The best way to validate your current setup is to build a small part of Kubernetes. This way you can address issues without waiting for the full build to complete. To build a specific part of Kubernetes use the WHAT environment variable to let the build scripts know you want to build only a certain package/executable.

make WHAT=cmd/{$package_you_want}

Note: This applies to all top level folders under kubernetes/cmd.

So for the cli, you can run:

make WHAT=cmd/kubectl

If everything checks out you will have an executable in the _output/bin directory to play around with.

Note: If you are using CDPATH, you must either start it with a leading colon, or unset the variable. The make rules and scripts to build require the current directory to come first on the CD search path in order to properly navigate between directories.

To build everything:

cd $working_dir/kubernetes

# This is equivalent to calling 'make all'
make

To remove the limit on the number of errors the Go compiler reports (default limit is 10 errors):

make GOGCFLAGS="-e"

To build with optimizations disabled (enables use of source debug tools):

make GOGCFLAGS="-N -l"

To build binaries for all platforms:

make cross

To build binaries for a specific platform, add KUBE_BUILD_PLATFORMS=<os>/<arch>. For example:

make cross KUBE_BUILD_PLATFORMS=windows/amd64

Install etcd

cd $working_dir/kubernetes

# Installs in ./third_party/etcd
hack/install-etcd.sh

# Add to PATH
echo export PATH="\$PATH:$working_dir/kubernetes/third_party/etcd" >> ~/.profile

Test

cd $working_dir/kubernetes

# Run all the presubmission verification. Then, run a specific update script (hack/update-*.sh)
# for each failed verification. For example:
#   hack/update-gofmt.sh (to make sure all files are correctly formatted, usually needed when you add new files)
#   hack/update-bazel.sh (to update bazel build related files, usually needed when you add or remove imports)
make verify

# Alternatively, run all update scripts to avoid fixing verification failures one by one.
make update

# Run every unit test
make test

# Run package tests verbosely
make test WHAT=./pkg/apis/core/helper GOFLAGS=-v

# Run integration tests, requires etcd
# For more info, visit https://git.k8s.io/community/contributors/devel/sig-testing/testing.md#integration-tests
make test-integration

# Run e2e tests by building test binaries, turn up a test cluster, run all tests, and tear the cluster down
# Note: running all e2e tests takes a LONG time! To run specific e2e tests, visit:
# ./e2e-tests.md#building-kubernetes-and-running-the-tests
make test-e2e

See the testing guide and end-to-end tests for additional information and scenarios.

Run make help for additional information on these make targets.

Dependency management

Kubernetes uses go modules to manage dependencies.

Developers who need to manage dependencies in the vendor/ tree should read the docs on using go modules to manage dependencies.

Build with Bazel/Gazel

Building with Bazel is currently experimental. For more information, see Build with Bazel.

GitHub workflow

To check out code to work on, please refer to this guide.