Locust on Kubernetes: Scale Distributed Load Testing (2026)

Locust on Kubernetes allows you to distribute your load testing across multiple pods, bypassing the single-machine limitations of traditional load testing tools.

Here’s how you can set it up and run a distributed load test:

Setting Up Locust on Kubernetes

First, you’ll need a Kubernetes cluster. You can use a managed service like GKE, EKS, or AKS, or set up your own. You’ll also need kubectl configured to communicate with your cluster.

1. Create a Docker Image for Locust:

You need a Docker image that contains your Locust test script.

# Dockerfile
FROM python:3.9-slim

WORKDIR /mnt/locust

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY locustfile.py .

CMD ["locust", "-f", "locustfile.py", "--master"]

requirements.txt would simply contain locust. locustfile.py is your Locust test script.

Build and push this image to a container registry (e.g., Docker Hub, GCR, ECR).

2. Kubernetes Deployment for the Locust Master:

This deployment will run the Locust master process, which coordinates the workers.

# locust-master-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: locust-master
spec:
  replicas: 1
  selector:
    matchLabels:
      app: locust
      role: master
  template:
    metadata:
      labels:
        app: locust
        role: master
    spec:
      containers:
      - name: locust-master
        image: your-docker-registry/locust-master:latest # Replace with your image
        ports:
        - containerPort: 5557 # Master web UI and communication
          name: web
        - containerPort: 5558 # Master communication
          name: comm
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

3. Kubernetes Service for the Locust Master:

This service exposes the Locust master’s web UI and communication ports.

# locust-master-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: locust-master
spec:
  selector:
    app: locust
    role: master
  ports:
  - name: web
    port: 8089 # Port you'll access the UI on
    targetPort: 5557
  - name: comm
    port: 5558
    targetPort: 5558
  type: LoadBalancer # Or NodePort, ClusterIP depending on your needs

4. Kubernetes Deployment for Locust Workers:

These deployments will run the Locust worker processes. We’ll use a Deployment and then scale it to create multiple worker pods.

# locust-worker-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: locust-worker
spec:
  replicas: 3 # Start with 3 workers, you can scale this later
  selector:
    matchLabels:
      app: locust
      role: worker
  template:
    metadata:
      labels:
        app: locust
        role: worker
    spec:
      containers:
      - name: locust-worker
        image: your-docker-registry/locust-master:latest # Use the same image, but override the command
        command: ["locust", "-f", "/mnt/locust/locustfile.py", "--worker", "--master-host", "locust-master"]
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

Notice the command override for the workers. They need to be told to run as workers and point to the locust-master service.

Applying the Configurations

Use kubectl to apply these YAML files to your cluster:

kubectl apply -f locust-master-deployment.yaml
kubectl apply -f locust-master-service.yaml
kubectl apply -f locust-worker-deployment.yaml

Running the Load Test

Get the Master Service IP/Hostname: If you used LoadBalancer, get the external IP:
```
kubectl get services locust-master
```
Look for the EXTERNAL-IP.
Access the Locust Web UI: Open your browser to http://<EXTERNAL-IP>:8089.
Start the Test: In the Locust web UI, you’ll see fields for the number of users, spawn rate, and host. Enter your target host and click "Start swarming." The master will communicate with the workers, and they will start executing the load test against your target.

Scaling the Load Test

To increase the load, you can scale the locust-worker deployment:

kubectl scale deployment locust-worker --replicas=10

This command will create 10 worker pods, and they will automatically connect to the Locust master. You can then monitor the increased load in the Locust web UI.

Important Considerations

Resource Limits: Ensure your Locust master and worker pods have sufficient CPU and memory requests and limits. Load testing can be resource-intensive.
Network: The workers need to be able to reach the master on ports 5557 and 5558. Kubernetes services handle this communication within the cluster.
Target Host: The host field in the Locust UI is the URL your Locust workers will target. Make sure your application is accessible from the Kubernetes cluster where the workers are running.
Image Updates: If you update your locustfile.py, you’ll need to rebuild your Docker image, push it, and then update the image field in both the master and worker deployments. You might want to use image tags other than latest for better version control.

This setup allows you to generate massive amounts of load by leveraging the distributed nature of Kubernetes, overcoming the limitations of running Locust on a single machine. The next step is to integrate this into your CI/CD pipeline for automated performance testing.