This doc explains how to setup a development environment so you can get started
contributing
to Knative Serving
. Also take a look at:
Follow the instructions below to set up your development environment. Once you meet these requirements, you can make changes and deploy your own version of Knative Serving!
Before submitting a PR, see also CONTRIBUTING.md.
Start by creating a GitHub account, then setup GitHub access via SSH.
You must install these tools:
go
: The languageKnative Serving
is built in (1.12rc1 or later)git
: For source controldep
: For managing external Go dependencies.ko
: For development.kubectl
: For managing development environments.
- 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 docker repository for pushing images. You can use any container image registry by adjusting the authentication methods and repository paths mentioned in the sections below.
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/bin
onPATH
: This is so that tooling installed viago get
will work properly.KO_DOCKER_REPO
: The docker repository to which developer images should be pushed (e.g.gcr.io/[gcloud-project]
).
- Note: if you are using docker hub to store your images your
KO_DOCKER_REPO
variable should bedocker.io/<username>
. - Note: Currently Docker Hub doesn't let you create subdirs under your username.
.bashrc
example:
export GOPATH="$HOME/go"
export PATH="${PATH}:${GOPATH}/bin"
export KO_DOCKER_REPO='gcr.io/my-gcloud-project-name'
export DOCKER_REPO_OVERRIDE="${KO_DOCKER_REPO}"
export K8S_CLUSTER_OVERRIDE='my-k8s-cluster-name'
Make sure to configure
authentication
for your KO_DOCKER_REPO
if required. To be able to push images to
gcr.io/<project>
, you need to run this once:
gcloud auth configure-docker
For K8S_CLUSTER_OVERRIDE
, we expect that this name matches a cluster with
authentication configured with kubectl
. You can list the clusters you
currently have configured via: kubectl config get-contexts
. For the cluster
you want to target, the value in the CLUSTER column should be put in this
variable.
The Go tools require that you clone the repository to the
src/github.com/knative/serving
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/github.com/knative
cd ${GOPATH}/src/github.com/knative
git clone git@github.com:${YOUR_GITHUB_USERNAME}/serving.git
cd serving
git remote add upstream git@github.com:knative/serving.git
git remote set-url --push upstream no_push
Adding 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 described below.
Once you've setup your development environment, stand up
Knative Serving
. Note that if you already installed Knative to your cluster,
redeploying the new version should work fine, but if you run into trouble, you
can easily clean your cluster up and try again.
Your $K8S_USER_OVERRIDE
must be a cluster admin to perform the setup needed
for Knative.
The value you use depends on your cluster setup:
# When using Minikube, the K8s user is your local user.
export K8S_USER_OVERRIDE=$USER
# When using GKE, the K8s user is your GCP user.
export K8S_USER_OVERRIDE=$(gcloud config get-value core/account)
kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole=cluster-admin \
--user="${K8S_USER_OVERRIDE?}"
kubectl apply -f ./third_party/istio-1.0.2/istio-crds.yaml
while [ $(kubectl get crd gateways.networking.istio.io -o jsonpath='{.status.conditions[?(@.type=="Established")].status}') != 'True' ]; do
echo "Waiting on Istio CRDs"; sleep 1
done
kubectl apply -f ./third_party/istio-1.0.2/istio.yaml
Follow the instructions if you need to set up static IP for Ingresses in the cluster.
This step includes building Knative Serving, creating and pushing developer images and deploying them to your Kubernetes cluster.
First, edit config-network.yaml as instructed
within the file. If this file is edited and deployed after Knative Serving
installation, the changes in it will be effective only for newly created
revisions. Alternatively, if you are developing on GKE, you can skip the editing
and use the patching tool in hack/dev-patch-config-gke.sh
after deploying
knative.
Next, run:
ko apply -f config/
./hack/dev-patch-config-gke.sh my-k8s-cluster-name # optional
The above step is equivalent to applying the serving.yaml
for released
versions of Knative Serving.
You can see things running with:
kubectl -n knative-serving get pods
NAME READY STATUS RESTARTS AGE
activator-c8495dc9-z7xpz 2/2 Running 0 6d
autoscaler-66897845df-t5cwg 2/2 Running 0 6d
controller-699fb46bb5-xhlkg 1/1 Running 0 6d
webhook-76b87b8459-tzj6r 1/1 Running 0 6d
You can access the Knative Serving Controller's logs with:
kubectl -n knative-serving logs $(kubectl -n knative-serving get pods -l app=controller -o name)
If you're using a GCP project to host your Kubernetes cluster, it's good to check the Discovery & load balancing page to ensure that all services are up and running (and not blocked by a quota issue, for example).
Run:
kubectl apply -R -f config/monitoring/100-namespace.yaml \
-f third_party/config/monitoring/logging/elasticsearch \
-f config/monitoring/logging/elasticsearch \
-f third_party/config/monitoring/metrics/prometheus \
-f config/monitoring/metrics/prometheus \
-f config/monitoring/tracing/zipkin
As you make changes to the code-base, there are two special cases to be aware of:
-
If you change an input to generated code, then you must run
./hack/update-codegen.sh
. Inputs include:- API type definitions in pkg/apis/serving/v1alpha1/,
- Types definitions annotated with
// +k8s:deepcopy-gen=true
.
-
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. Code generation and dependencies are automatically checked to produce no
diffs for each pull request.
update-deps.sh runs "dep ensure" command. In some cases, if newer dependencies are required, you need to run "dep ensure -update package-name" manually.
Once the codegen and dependency information is correct, redeploying the controller is simply:
ko apply -f config/controller.yaml
Or you can clean it up completely and
completely redeploy Knative Serving
.
You can delete all of the service components with:
ko delete --ignore-not-found=true \
-f config/monitoring/100-namespace.yaml \
-f config/ \
-f ./third_party/config/build/release.yaml \
-f ./third_party/istio-1.0.2/istio.yaml \
-f ./third_party/istio-1.0.2/istio-crds.yaml
To access Telemetry see: