Skip to content

Latest commit

 

History

History
307 lines (217 loc) · 9.18 KB

DEVELOPER.md

File metadata and controls

307 lines (217 loc) · 9.18 KB
Raw

Developer documentation

Hello, and welcome! If you're thinking about contributing to Kuma's code base, you came to the right place. This document serves as guide/reference for technical contributors.

Consult the Table of Contents below, and jump to the desired section.

Table of Contents

Dependencies

The following dependencies are all necessary. Please follow the installation instructions for any tools/libraries that you may be missing.

Command line tool

  • curl
  • git
  • make
  • go
  • clang-format # normally included in system's clang package with some exceptions, please check with the following command: 
    clang-format --version

For a quick start, use the official golang Docker image. It includes all the command line tools pre-installed, with exception for from clang-format.

docker run --name kuma-build -ti \
  --volume `pwd`:/go/src/github.com/kumahq/kuma \
  --workdir /go/src/github.com/kumahq/kuma \
  --env GO111MODULE=on \
  golang:1.12.12 \
  bash -c 'apt update && apt install -y unzip && export PATH=$HOME/bin:$PATH && bash'

If kuma-build container already exists, start it with

docker start --attach --interactive kuma-build

To cleanup disk space, run

docker rm kuma-build

Helper commands

Throughout this guide, we will use the make utility to run pre-defined tasks in the Makefile. Use the following command to list out all the possible commands:

make help

Installing dev tools

We packaged the remaining dependencies into one command. This is one of many commands that's listed if you run the make help command above. You can also install each tool individually if you know what you are missing. Run:

make dev/tools

to install all of the following tools at $HOME/bin:

  1. Ginkgo (BDD-style Go testing framework)
  2. Kubebuilder (Kubernetes API extension framework, comes with etcd and kube-apiserver)
  3. kustomize (Customization of kubernetes YAML configurations)
  4. kubectl (Kubernetes API client)
  5. KIND (Kubernetes IN Docker)
  6. Minikube (Kubernetes in VM)

ATTENTION: By default, development tools will be installed at $HOME/bin. Remember to include this directory into your PATH, e.g. by adding export PATH=$HOME/bin:$PATH line to the $HOME/.bashrc file.

Testing

We use Ginkgo as our testing framework. To run the existing test suite, you have several options:

For all tests, run:

make test

For integration tests, run:

make integration

And you can run tests that are specific to a part of Kuma by appending the app name as shown below:

make test/kumactl

Please make sure that all tests pass before submitting a pull request in the master branch. Thank you!

Building

After you made some changes, you will need to re-build the binaries. You can build all binaries by running:

make build

And similar to make test, you can appending the app name to the build command to build the binary of a specific app. For example, here is how you would build the binary for only kumactl:

make build/kumactl

This could help expedite your development process if you only made changes to the kumactl files.

Running Control Plane on local machine

Universal

Universal setup does not require Kubernetes to be present. It can be run in two modes.

Universal without any external dependency (in-memory storage)

  1. Run Control Plane on local machine:
make run/universal/memory

Universal with Postgres as a storage

  1. Run Postgres with initial schema using docker-compose. It will run on port 15432 with username: kuma, password: kuma and db name: kuma.
make start/postgres
  1. Run Control Plane on local machine.
make run/universal/postgres

Running a Dataplane (Envoy)

  1. Build a kumactl
make build/kumactl
export PATH=`pwd`/build/artifacts-$(go env GOOS)-$(go env GOARCH)/kumactl:$PATH
  1. Configure a kumactl with running Control Plane

Check current config

kumactl config control-planes list

ACTIVE   NAME    ADDRESS
*        local   http://localhost:5681

If active control plane points to different address than http://localhost:5681, add a new one

kumactl config control-planes add --name universal --address http://localhost:5681
  1. Apply a Dataplane descriptor
kumactl apply -f dev/examples/universal/dataplanes/example.yaml
  1. Run a Dataplane (requires envoy binary to be on your PATH)
make run/example/envoy/universal
  1. List Dataplanes connected to the Control Plane:
kumactl inspect dataplanes

MESH      NAME      TAGS                                     STATUS   LAST CONNECTED AGO   LAST UPDATED AGO   TOTAL UPDATES   TOTAL ERRORS
default   example   env=production service=web version=2.0   Online   32s                  32s                2               0
  1. Dump effective Envoy config:
make config_dump/example/envoy

Kubernetes

Local Control Plane working with Kubernetes

The following instructions are for folks who want to run Control Plane on their local machine. Local development is a viable path for people who are familiar with Kubernetes and understands trade-offs of out-off cluster deployment. If you want to run the Control Plane on Kubernetes instead, jump to the Control Plane on Kubernetes section below.

  1. Run KIND (Kubernetes IN Docker):
make kind/start

# set KUBECONFIG for use by `kumactl` and `kubectl`
export KUBECONFIG="$(kind get kubeconfig-path --name=kuma)"
  1. Run Control Plane on local machine:
make run/k8s

Running Dataplane (Envoy)

  1. Run the instructions at "Pointing Envoy at Control Plane" section, so the Dataplane descriptor is available in the Control Plane.

  2. Start Envoy on local machine (requires envoy binary to be on your PATH):

make run/example/envoy/k8s
  1. Dump effective Envoy config:
make config_dump/example/envoy

Control Plane on Kubernetes

To run the Kuma Control Plane on Kubernetes, follow these steps:

  1. Run KIND (Kubernetes IN Docker):
make kind/start

# set KUBECONFIG for use by `kubectl`
export KUBECONFIG="$(kind get kubeconfig-path --name=kuma)"
  1. Deploy Control Plane to KIND (Kubernetes IN Docker):
make kind/deploy/kuma
  1. Deploy the demo app (and get Kuma sidecar injected)
make kind/deploy/example-app
  1. Build kumactl
make build/kumactl

export PATH=`pwd`/build/artifacts/kumactl:$PATH
  1. Forward the Control Plane port to localhost:
kubectl port-forward -n kuma-system $(kubectl get pods -n kuma-system -l app=kuma-control-plane -o=jsonpath='{.items[0].metadata.name}') 15681:5681
  1. Add Control Plane to your kumactl config:
kumactl config control-planes add --name k8s --address http://localhost:15681
  1. Verify that Control Plane has been added:
kumactl config control-planes list

NAME   API SERVER
k8s    http://localhost:15681
  1. List Dataplanes connected to the Control Plane:
kumactl inspect dataplanes

MESH      NAME                        TAGS                                                                          STATUS   LAST CONNECTED AGO   LAST UPDATED AGO   TOTAL UPDATES   TOTAL ERRORS
default   demo-app-7cbbd658d5-dj9l6   app=demo-app pod-template-hash=7cbbd658d5 service=demo-app_kuma-demo_svc_80   Online   42m28s               42m28s             8               0