Skip to main content
This guide will help you set up your development environment for contributing to KubeLB.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Go 1.25.7 or later
  • Docker for building images
  • kubectl for interacting with Kubernetes clusters
  • Git for version control
  • Make for running build commands
For macOS users, you may need gsed for some Makefile operations:
brew install gnu-sed

​
Forking the Repository

1

Fork on GitHub

Navigate to the KubeLB repository and click the “Fork” button to create your own copy.
2

Clone your fork

git clone https://github.com/YOUR_USERNAME/kubelb.git
cd kubelb
3

Add upstream remote

git remote add upstream https://github.com/kubermatic/kubelb.git
git fetch upstream

​
Building KubeLB

KubeLB consists of two main components that can be built separately or together.

​
Build All Components

make build
This builds both the manager and CCM binaries into the bin/ directory.

​
Build Individual Components

make build-kubelb
The binaries will be available at:
  • bin/kubelb - KubeLB Manager
  • bin/ccm - KubeLB Cloud Controller Manager

​
Development Workflow

​
Code Formatting and Linting

Before committing code, ensure it’s properly formatted and passes linting: 
# Format code
make fmt

# Run vet
make vet

# Run linter
make lint

​
Running Unit Tests

Run the test suite with coverage: 
make test
This uses envtest to run tests against a local control plane.

​
Generating Code

After modifying CRD types or adding kubebuilder markers, regenerate the code: 
make update-codegen
This runs the full code generation pipeline including:
  • DeepCopy methods
  • CRD manifests
  • RBAC configurations
  • Helm documentation
  • Metrics documentation

​
Running Locally

​
Prerequisites for Local Testing

  1. Generate CRDs and manifests: 
    make manifests generate
  2. Install CRDs into your cluster: 
    make install

​
Running the Manager

make run-kubelb
This starts the KubeLB Manager controller locally, connecting to the cluster specified in your ~/.kube/config.

​
Running the CCM

make run-ccm
This starts the Cloud Controller Manager locally.
When running locally, the controllers use your current kubeconfig context. Make sure you’re connected to the correct cluster.

​
Building Docker Images

To build Docker images for both components: 
make docker-image
This creates:
  • quay.io/kubermatic/kubelb-manager:<IMAGE_TAG>
  • quay.io/kubermatic/kubelb-ccm:<IMAGE_TAG>
The IMAGE_TAG is automatically generated from your git commit hash.

​
Environment Variables

KubeLB’s build system respects several environment variables:
VariableDescriptionDefault
GOPATHGo workspace path$(go env GOPATH)
CGO_ENABLEDEnable CGO0
GOPROXYGo module proxyhttps://proxy.golang.org
GOFLAGSGo build flags-mod=readonly -trimpath
GIT_TAGGit tag for versionAuto-detected
KUBELB_IMGManager image namequay.io/kubermatic/kubelb-manager
KUBELB_CCM_IMGCCM image namequay.io/kubermatic/kubelb-ccm

​
Next Steps

Now that you have your environment set up:

Architecture

Learn about KubeLB’s code organization and patterns

Testing

Write and run tests for your changes

Code Generation

Understand the code generation workflow

Contributing Guide

Read the full contribution guidelines

​
Getting Help

If you encounter issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us