Local Development
This page covers how to set up a local development environment for working on the Control Plane.
Prerequisites
Make sure the following tools are installed before you begin. For specific version requirements and setup instructions, see the Contributing guide and the repository's CONTRIBUTING.md.
- Go — the primary language for all operators and services
- Kubebuilder — scaffolding and code generation for Kubernetes operators
- A local Kubernetes cluster — for example kind or minikube
- kubectl — configured to communicate with your local cluster
- Helm — for installing dependencies such as cert-manager
- pip + pre-commit — for running pre-commit hooks
Repository Structure
The Control Plane is organised as a monorepo. Each domain lives in its own directory with a dedicated Go module (go.mod), Makefile, and — for operators — a Kubebuilder PROJECT file. Modules reference each other through Go replace directives.
Operators
Each domain has its own Kubebuilder-scaffolded controller in a dedicated directory (for example gateway/, identity/, rover/). See the repository root for the full list of operator directories.
Services
Backend services that are not Kubernetes operators:
common-server/ · controlplane-api/ · rover-server/ · secret-manager/ · file-manager/
CLI Tools
rover-ctl/ — command-line interface for interacting with the Control Plane.
rover-ctl depends on common/ through a local replace directive (github.com/telekom/controlplane/common => ../common), like the other modules. Build it from a full repository checkout so the sibling common/ directory is present; release builds (goreleaser and ko) already do this. Remote installation with go install github.com/telekom/controlplane/rover-ctl@<version> is not supported for versions containing this local replacement: version-suffixed go install rejects it. Use a release binary or build from a checkout instead.
Libraries
| Directory | Purpose |
|---|---|
common/ | Shared operator framework (controller, handler, utility types) |
cpapi/ | Shared API types used across services and operators |
Installation
| Path | Purpose |
|---|---|
install/base/ | Shared Kustomize base (namespace and trust infrastructure) |
install/bundle/ | Core workloads without site configuration |
install/overlays/default/ | Production overlay (pulls images from GitHub Container Registry) |
install/overlays/local/ | Local development overlay (images at latest, eventing enabled) |
install/components/ | Optional composable capabilities and development services |
Tools
| Path | Purpose |
|---|---|
tools/e2e-tester/ | End-to-end test runner |
tools/route-tester/ | Route testing utility |
tools/snapshotter/ | Cluster state snapshot tool |
Code Generation
hack/ — helper scripts including local-setup.sh (full local dev environment) and boilerplate templates for code generation.
Local Installation
There are two ways to deploy the Control Plane to your local cluster.
Option A — Full Local Setup (Recommended)
The hack/local-setup.sh script creates a Kind cluster, installs all prerequisites, builds every controller image with ko, loads them into Kind, and deploys everything:
./hack/local-setup.sh
This is the fastest way to get a complete local environment. The script also supports incremental rebuilds:
# Rebuild all images and redeploy
./hack/local-setup.sh --build-only
# Rebuild a single controller
./hack/local-setup.sh --build-only --only gateway
The local overlay reads shared settings from install/overlays/local/global-config.env. Workloads then consume an optional unique <component>-env ConfigMap before explicit container environment entries; application code supplies shipped defaults. Create component ConfigMaps as top-level generators rather than merging or replacing nested generators. Eventing is selected as an atomic component: the overlay installs both Event and PubSub and enables their required global feature flag automatically. Do not duplicate that flag in global-config.env.
Option B — Manual Kustomize
If you prefer full control, apply the local overlay directly:
kubectl apply -k install/overlays/local
kubectl apply -k install/overlays/local/resources/admin
kubectl apply -k install/overlays/local/resources/org
kubectl apply -k install/overlays/local/resources/rover
Working with a Domain
To develop on a single operator, navigate into its directory and use the provided Make targets:
cd <domain>
# Generate CRDs and code
make manifests
make generate
# Install CRDs into cluster
make install
# Run the operator locally (outside the cluster)
make run
# Build the binary
make build
Running the operator locally with make run starts the controller on your machine and connects it to the cluster configured in your current kubeconfig context. This gives you fast feedback without needing to build a container image.
Running Tests
Unit Tests
make test
Uses envtest with Kubernetes 1.32.0 assets. Output is formatted with gotestfmt.
Linting and Formatting
# Run the linter
make lint
# Run the linter and auto-fix issues
make lint-fix
# Format code
make fmt
# Run go vet
make vet
Key Make Targets
Every operator directory exposes a consistent set of Make targets:
| Target | Description |
|---|---|
manifests | Generate CRDs, RBAC, and webhook manifests where configured |
generate | Generate DeepCopy methods |
fmt | Run go fmt |
vet | Run go vet |
test | Run unit tests with envtest |
lint | Run golangci-lint |
build | Build the manager binary |
run | Run the operator locally |
install | Install CRDs into the cluster |
uninstall | Remove CRDs from the cluster |
deploy | Deploy the operator to the cluster |
undeploy | Remove the operator from the cluster |
Tool Versions
The project pins the following tool versions to ensure reproducible builds:
| Tool | Version |
|---|---|
| Kustomize | v5.4.3 |
| controller-gen | v0.20.1 |
| setup-envtest | release-0.19 |
| golangci-lint | v2.11.2 |
| envtest K8s version | 1.32.0 |
Next Steps
- Contributing — learn about the contribution workflow and code standards
- Creating an Operator — scaffold a new operator from scratch