Skip to content

Local Development Guide⚓

This guide describes the setup and workflow for local development on the Locust K8s Operator project. It's intended for developers who want to contribute code changes.

Development Setup⚓

Prerequisites⚓

  • Go 1.26+: Required for building the operator
  • Docker: Running Docker daemon for building images
  • kubectl: Kubernetes CLI for cluster interaction
  • Kind or Minikube: Local Kubernetes cluster for testing
  • Helm 3.x: For chart packaging and installation

Initial Setup⚓

  1. Clone the repository: 

    git clone https://github.com/AbdelrhmanHamouda/locust-k8s-operator.git
cd locust-k8s-operator

  2. Install dependencies and tools: 

    # Download Go dependencies
make tidy

# Install development tools (controller-gen, envtest, etc.)
make controller-gen
make envtest
make kustomize

Development Guidelines⚓

Common Development Commands⚓

The project uses a Makefile for common development tasks. Run make help to see all available targets.

Build & Test⚓

# Build the operator binary
make build

# Run all tests (unit + integration via envtest)
make test

# Run linter
make lint

# Run linter with auto-fix
make lint-fix

# Run all CI checks locally
make ci

Code Generation⚓

# Generate CRDs, RBAC, and webhook manifests
make manifests

# Generate DeepCopy implementations
make generate

# Format code
make fmt

# Run go vet
make vet

Running Locally⚓

# Run the operator locally against your current kubeconfig cluster
make run

# Install CRDs into the cluster
make install

# Uninstall CRDs from the cluster
make uninstall

Local Testing with Kind⚓

For local development and testing, Kind (Kubernetes in Docker) is the recommended approach.

Steps⚓

  1. Create a Kind Cluster
kind create cluster --name locust-dev
  1. Build and Load the Docker Image
# Build the Docker image
make docker-build IMG=locust-k8s-operator:dev

# Load the image into Kind
kind load docker-image locust-k8s-operator:dev --name locust-dev
  1. Deploy the Operator

Option A: Using kustomize (for development): 

# Deploy CRDs and operator
make deploy IMG=locust-k8s-operator:dev

Option B: Using Helm (for production-like testing): 

# Package the Helm chart
helm package charts/locust-k8s-operator

# Install with local image
helm install locust-operator locust-k8s-operator-*.tgz \
  --set image.repository=locust-k8s-operator \
  --set image.tag=dev \
  --set image.pullPolicy=IfNotPresent

  1. Verify the Deployment

!!! note "Development vs Production Namespaces" The make deploy command generates a namespace based on your project name. For production deployments, use the locust-system namespace as documented in the Helm Deployment Guide.

# Check pods in the generated namespace
kubectl get pods -A | grep locust

# Follow operator logs
kubectl logs -f -n <namespace> deployment/<deployment-name>
  1. Test with a Sample CR
# Create a test ConfigMap with a simple Locust script
kubectl create configmap locust-test --from-literal=locustfile.py='
from locust import HttpUser, task
class TestUser(HttpUser):
    @task
    def hello(self):
        self.client.get("/")
'

# Apply a sample LocustTest CR
kubectl apply -f config/samples/locust_v2_locusttest.yaml

# Watch the resources
kubectl get locusttests,jobs,pods -w
  1. Cleanup
# Remove the operator
make undeploy

# Delete the Kind cluster
kind delete cluster --name locust-dev

Writing Documentation⚓

All documentation is located under the docs/ directory. The documentation is hosted on GitHub Pages and updated automatically with each release. To manage and build the documentation, the project uses MkDocs & Material for MkDocs framework.

Preview Documentation Locally⚓

# Install MkDocs (if not installed)
pip install mkdocs mkdocs-material

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build --strict

During development, the CI workflow will build the documentation as part of the validation.