This doc explains how to setup a development environment so you can get started
contributing to Knative Eventing.
Also take a look at:
Once you meet these requirements, you can start the eventing-controller.
ℹ️ If you intend to use event sinks based on Knative Services as described in some of our examples, consider installing Knative Serving. A few Knative Sandbox projects also have a dependency on Serving.
Before submitting a PR, see also contribution guidelines.
You must install these tools:
go: The languageKnative Eventingis developed with (version 1.15 or higher)git: For source controlko: For building and deploying container images to Kubernetes in a single command.kubectl: For managing development environments.bashv4 or higher. On macOS the default bash is too old, you can use Homebrew to install a later version. For running some automations, such as dependencies updates and code generators.
- Set up a kubernetes cluster
- Follow an install guide up through "Creating a Kubernetes Cluster"
- You do not need to install Istio or Knative using the instructions in the guide. Simply create the cluster and come back here.
- If you did install Istio/Knative following those instructions, that's fine too, you'll just redeploy over them, below.
- Set up a Linux Container repository for pushing images. You can use any container image registry by adjusting the authentication methods and repository paths mentioned in the sections below.
ℹ️ You'll need to be authenticated with your
KO_DOCKER_REPObefore pushing images. Rungcloud auth configure-dockerif you are using Google Container Registry ordocker loginif you are using Docker Hub.
To start your environment you'll need to set these environment variables (we
recommend adding them to your .bashrc):
GOPATH: If you don't have one, simply pick a directory and addexport GOPATH=...$GOPATH/binonPATH: This is so that tooling installed viago getwill work properly.KO_DOCKER_REPO: The docker repository to which developer images should be pushed (e.g.gcr.io/[gcloud-project]).
ℹ️ If you are using Docker Hub to store your images, your
KO_DOCKER_REPOvariable should have the formatdocker.io/<username>. Currently, Docker Hub doesn't let you create subdirs under your username (e.g.<username>/knative).
.bashrc example:
export GOPATH="$HOME/go"
export PATH="${PATH}:${GOPATH}/bin"
export KO_DOCKER_REPO='gcr.io/my-gcloud-project-id'The Go tools require that you clone the repository to the
src/knative.dev/eventing directory in your
GOPATH.
To check out this repository:
- Create your own fork of this repo
- Clone it to your machine:
mkdir -p ${GOPATH}/src/knative.dev
cd ${GOPATH}/src/knative.dev
git clone [email protected]:${YOUR_GITHUB_USERNAME}/eventing.git
cd eventing
git remote add upstream https://github.com/knative/eventing.git
git remote set-url --push upstream no_pushAdding the upstream remote sets you up nicely for regularly
syncing your fork.
Once you reach this point you are ready to do a full build and deploy as follows.
Once you've setup your development environment, stand up
Knative Eventing with:
ko apply -f config/You can see things running with:
$ kubectl -n knative-eventing get pods
NAME READY STATUS RESTARTS AGE
eventing-controller-59f7969778-4dt7l 1/1 Running 0 2hYou can access the Eventing Controller's logs with:
kubectl -n knative-eventing logs $(kubectl -n knative-eventing get pods -l app=eventing-controller -o name)Install the In-Memory-Channel since this is the default channel.
ko apply -f config/channels/in-memory-channel/Depending on your needs you might want to install other channel implementations.
Install the
MT Channel Broker
or any of the other Brokers available inside the config/brokers/ directory.
ko apply -f config/brokers/mt-channel-broker/Depending on your needs you might want to install other Broker implementations.
If you are running e2e tests that leverage the Sugar Controller, you will need to explicitly enable it.
ko apply -f test/config/sugar.yamlAs you make changes to the code-base, there are two special cases to be aware of:
- If you change a type definition (pkg/apis/), then you must
run
./hack/update-codegen.sh. - If you change a package's deps (including adding external dep), then you
must run
./hack/update-deps.sh.
These are both idempotent, and we expect that running these at HEAD to have no
diffs.
Once the codegen and dependency information is correct, redeploying the controller is simply:
ko apply -f config/controller.yamlOr you can clean it up completely and start again.
Running tests as you make changes to the code-base is pretty simple. See the test docs.
Please check contribution guidelines.
You can delete Knative Eventing with:
ko delete -f config/To access Telemetry see:
While debugging an Eventing component, it could be useful to perform packet sniffing on a container to analyze the traffic.
Note: this debugging method should not be used in production.
In order to do packet sniffing, you need:
koto deploy Eventingkubectl sniffto deploy and collecttcpdump- (Optional) Wireshark to analyze the
tcpdumpoutput
After you installed all these tools, change the base image ko uses to build
Eventing component images changing the .ko.yaml. You need an image
that has the tar tool installed, for example:
defaultBaseImage: docker.io/debian:latestNow redeploy with ko the component you want to sniff as explained in the above
paragraphs.
When the container is running, run:
kubectl sniff <POD_NAME> -n knative-eventing -o out.dump
Changing <POD_NAME> with the pod name of the component you wish to test, for
example imc-dispatcher-85797b44c8-gllnx. This command will dump the tcpdump
output with all the sniffed packets to out.dump. Then, you can open this file
with Wireshark using:
wireshark out.dump
If you run kubectl sniff without the output file name, it will open directly
Wireshark:
kubectl sniff <POD_NAME> -n knative-eventing
Telepresence can be leveraged to debug Knative controllers, webhooks and similar components.
Telepresence allows you to use your local process, IDE, debugger, etc. but Kubernetes service calls get redirected to the process on your local. Similarly the calls on the local process goes to actual services that are running in Kubernetes.
-
Install Telepresence
-
Deploy Knative Eventing on your Kubernetes cluster.
-
Install EnvFile plugin to your Intellij
-
Run following command to swap the controller with the controller that we will start later.
telepresence --namespace knative-eventing --swap-deployment eventing-controller --env-json eventing-controller-local-env.json
For debugging applications that receive traffic, such as webhooks, you also need
to pass --expose parameter.
For example:
telepresence --swap-deployment kafka-controller-manager --namespace knative-eventing --env-json kafka-controller-manager.json --expose 8443
This will replace the eventing-controller deployment on the cluster with a
proxy.
It will also create a eventing-controller-local-env.json file which we will
use later on. Content of this envfile looks like this:
{
"CONFIG_LOGGING_NAME": "config-logging",
"EVENTING_WEBHOOK_PORT": "tcp://10.105.47.10:443",
"EVENTING_WEBHOOK_PORT_443_TCP": "tcp://10.105.47.10:443",
"EVENTING_WEBHOOK_PORT_443_TCP_ADDR": "10.105.47.10",
...
}
We need to pass these environment variables when we are starting our controller.
- Create a run configuration in Intellij for
cmd/controller/main.go:
- Use the
envfile:
Now, use the run configuration and start the local controller in debug mode. You will see that the execution will pause in your breakpoints.
- Clean up is easy. Just kill your local controller process and then hit
Ctrl+Con the terminal windows that you ran Telepresence initially. Telepresence will delete the proxy. It will also revert the deployment on the cluster back to its original state.
Notes:
- Networking works fine, but volumes (i.e. being able to access Kubernetes volumes from local controller) are not tested
- This method can also be used in production, but proceed with caution.