Skip to content

Developer's Guide

We aim to make local development and testing as straightforward as possible. For basic guidelines around contributing, see the CONTRIBUTING document.

There are a number of automation tools available to help with testing and building your changes, detailed below.

Building kube-router

Go version 1.19 or above is required to build kube-router

All the dependencies are specified as Go modules and will be fetched into your cache, so just run make kube-router or go build pkg/cmd/kube-router.go to build.

Building A Docker Image

Running make container will compile kube-router (if needed) and build a Docker image. By default the container will be tagged with the last release version, and current commit ID.

For example:

$ make container
Building for GOARCH=amd64
Verifying kube-router gobgp for ARCH=x86-64 ...
Starting kube-router container image build for amd64 on amd64
docker build -t "cloudnativelabs/kube-router-git:amd64-bug_fixes_for_v2.0.0" -f Dockerfile --build-arg ARCH="" \
        --build-arg BUILDTIME_BASE="golang:1.20.9-alpine3.18" --build-arg RUNTIME_BASE="alpine:3.18" .
Sending build context to Docker daemon  198.6MB
Step 1/19 : ARG BUILDTIME_BASE=golang:1-alpine
Step 2/19 : ARG RUNTIME_BASE=alpine:latest
Step 3/19 : FROM ${BUILDTIME_BASE} as builder
 ---> 6cbc3ac54aa3
Step 4/19 : ENV BUILD_IN_DOCKER=false
 ---> Using cache
 ---> aec11cc4a0cd

...

Removing intermediate container 371a162930f5
 ---> 1d3f742d559e
Step 19/19 : ENTRYPOINT ["/usr/local/bin/kube-router"]
 ---> Running in d5ea6fda9fe4
Removing intermediate container d5ea6fda9fe4
 ---> 17cfbc77e293
[Warning] One or more build-args [ARCH] were not consumed
Successfully built 17cfbc77e293
Successfully tagged cloudnativelabs/kube-router-git:amd64-bug_fixes_for_v2.0.0
Finished kube-router container image build.

The following describes the rest of the portions of the container naming convention

  • kube-router-git indicates that the container was built from git and not from a tag.
  • amd64 indicates that it was built for the amd64 architecture
  • bug_fixes_for_v2.0.0 indicates the branch that the user was on when it was built

Pushing A Docker Image

Running make push will push your container image to a Docker registry. The default configuration will use the Docker Hub repository for the official kube-router images, cloudnativelabs/kube-router. You can push to a different repository by changing a couple settings, as described in Image Options below.

Makefile Options

There are several variables which can be modified in the Makefile to customize your builds. They are specified after your make command like this: make OPTION=VALUE. These options can also be set in your environment variables.

For more details beyond the scope of this document, see the Makefile and run make help.

Image Options

You can configure the name and tag of the Docker image with a few variables passed to make container and make push.

Example:

$ make container IMG_FQDN=quay.io IMG_NAMESPACE=bzub IMG_TAG=custom
docker build -t "quay.io/bzub/kube-router-git:custom" .
Sending build context to Docker daemon  151.5MB
Step 1/4 : FROM alpine
 ---> a41a7446062d
Step 2/4 : RUN apk add --no-cache iptables ipset
 ---> Using cache
 ---> 30e25a7640de
Step 3/4 : COPY kube-router /
 ---> Using cache
 ---> c06f78fd02e8
Step 4/4 : ENTRYPOINT /kube-router
 ---> Using cache
 ---> 5cfcfe54623e
Successfully built 5cfcfe54623e
Successfully tagged quay.io/bzub/kube-router-git:custom
  • REGISTRY is derived from other options. Set this to something else to quickly override the Docker image registry used to tag and push images.
  • Note: This will override other variables below that make up the image name/tag.
  • IMG_FQDN should be set if you are not using Docker Hub for images. In the examples above IMG_FQDN is set to quay.io.
  • IMG_NAMESPACE is the Docker registry user or organization. It is used in URLs.
  • Example: quay.io/IMG_NAMESPACE/kube-router
  • NAME goes onto the end of the Docker registry URL that will be used.
  • Example: quay.io/cloudnativelabs/NAME
  • IMG_TAG is used to override the tag of the Docker image being built.
  • DEV_SUFFIX is appended to Docker image names that are not for release. By default these images get a name ending with -git to signify that they are for testing purposes. Example (DEV-SUFFIX=master-latest): quay.io/cloudnativelabs/kube-router-git:master-latest

Release Workflow

See Release Documentation for more information

Dependency Management

kube-router uses go modules for managing dependencies see upstream documentation for more information