Skip to content

Developer's Guide

For basic guidelines around contributing, see the CONTRIBUTING document.

Prerequisites

  • Go 1.25+ (see go.mod for the exact version)
  • Docker (builds run inside containers by default)
  • Make

Building

All dependencies are managed as Go modules. To build:

make kube-router

By default, builds run inside Docker for consistency. To build locally:

BUILD_IN_DOCKER=false make kube-router

(Adding BUILD_IN_DOCKER=false will work for most other steps that utilize docker as well)

Building a Docker Image

make container

This compiles kube-router and builds a Docker image tagged with the current branch and architecture.

Pushing a Docker Image

make push

By default this pushes to the official cloudnativelabs/kube-router Docker Hub repository which most users will likely not have access to. Push to a different registry by setting image options:

make container IMG_FQDN=quay.io IMG_NAMESPACE=youruser IMG_TAG=custom

Multi-Architecture Builds

Specify the target architecture with GOARCH:

GOARCH=arm64 make kube-router
GOARCH=s390x make container

Supported architectures: amd64 (default), arm64, arm, s390x, ppc64le, riscv64.

Testing

Run the full test suite:

make test

Or with formatted output (easier to understand for humans, uses gotestsum):

make test-pretty

Linting and Formatting

Check formatting:

make gofmt

Auto-fix formatting:

make gofmt-fix

Run all linters (golangci-lint + markdownlint):

make lint

Mock Generation

When modifying interfaces that have associated mocks, regenerate them:

make gomoqs

Or regenerate a specific mock:

make pkg/controllers/proxy/linux_networking_moq.go

Commit Messages

This project uses Conventional Commits. Every commit message should follow the format <type>(<scope>): <description>.

Common types: feat, fix, doc, test, build, chore, fact (refactor).

The following scope abbreviations are used for the main controllers:

  • NSC -- Network Services Controller (pkg/controllers/proxy/)
  • NRC -- Network Routes Controller (pkg/controllers/routing/)
  • NPC -- Network Policy Controller (pkg/controllers/netpol/)

Examples:

feat(gobgp): add kube_router_bgp_peer_info metric
fix(aws.go): load region before attempting to assume a role
test(NSC): add comprehensive TCPMSS unit tests

Development Workflow

git checkout -b feature_x

# Make changes...

make clean
make gofmt-fix
make

Run make help for a full list of available targets.

Release Workflow

See RELEASE.md for more information.

Dependency Management

kube-router uses Go modules. See the upstream documentation for more information.