Migration Guide: v1 to v2⚓

This guide helps existing users of the Locust Kubernetes Operator upgrade from v1 to v2. The v2 release is a complete rewrite in Go, bringing significant performance improvements and new features.

Overview⚓

Why We Rewrote in Go⚓

The v2 operator was rewritten from Java to Go for several key reasons:

What Changes for Users⚓

• API Version: New locust.io/v2 API with grouped configuration
• Backward Compatibility: v1 CRs continue to work via automatic conversion
• New Features: OpenTelemetry, secret injection, volume mounting, separate resource specs
• Helm Chart: Updated values structure (backward compatible)

Compatibility Guarantees⚓

• v1 API: Fully supported via conversion webhook (deprecated, will be removed in v3)
• Existing CRs: Work without modification
• Helm Values: Backward compatibility shims for common settings

Before You Begin⚓

Prerequisites⚓

• Kubernetes 1.25+
• Helm 3.x
• cert-manager v1.14+ (required for conversion webhook)

Backup Recommendations⚓

Before upgrading, back up your existing resources:

# Export all LocustTest CRs
kubectl get locusttests -A -o yaml > locusttests-backup.yaml

# Export operator Helm values
helm get values locust-operator -n <namespace> > values-backup.yaml

Step 1: Update Helm Chart⚓

Upgrade Command⚓

# Update Helm repository
helm repo update locust-k8s-operator

# Upgrade to v2 (with webhook for v1 CR compatibility)
helm upgrade locust-operator locust-k8s-operator/locust-k8s-operator \
  --namespace locust-system \
  --version 2.0.0 \
  --set webhook.enabled=true

# If you don't need v1 API compatibility, you can omit --set webhook.enabled=true

New Helm Values⚓

The v2 chart introduces a cleaner structure. Key changes:

Operator Resource Defaults⚓

The Go operator controller requires significantly fewer resources than the Java version:

resources:
  limits:
    memory: 256Mi
    cpu: 500m
  requests:
    memory: 64Mi
    cpu: 10m

Step 2: Verify Existing CRs⚓

The conversion webhook automatically converts v1 CRs to v2 format when stored. Verify your existing CRs work:

# List all LocustTests
kubectl get locusttests -A

# Check a specific CR
kubectl describe locusttest <name>

Verify Conversion⚓

You can read a v1 CR as v2 to verify conversion:

# Read as v2 (even if created as v1)
kubectl get locusttest <name> -o yaml | grep "apiVersion:"
# Should show: apiVersion: locust.io/v2

Step 3: Migrate CRs to v2 Format (Recommended)⚓

While v1 CRs continue to work, migrating to v2 format is recommended to access new features.

Field Mapping Reference⚓

Example Transformation⚓

apiVersion: locust.io/v1
kind: LocustTest
metadata:
  name: example-test
spec:
  image: locustio/locust:2.43.3
  masterCommandSeed: --locustfile /lotest/src/test.py --host https://example.com
  workerCommandSeed: --locustfile /lotest/src/test.py
  workerReplicas: 5
  configMap: test-scripts
  labels:
    master:
      team: platform
    worker:
      team: platform

apiVersion: locust.io/v2
kind: LocustTest
metadata:
  name: example-test
spec:
  image: locustio/locust:2.43.3
  master:
    command: "--locustfile /lotest/src/test.py --host https://example.com"
    labels:
      team: platform
  worker:
    command: "--locustfile /lotest/src/test.py"
    replicas: 5
    labels:
      team: platform
  testFiles:
    configMapRef: test-scripts

Lossy Conversion Details⚓

Step 4: Leverage New Features⚓

After migrating to v2, you can use new features:

OpenTelemetry Support⚓

spec:
  observability:
    openTelemetry:
      enabled: true
      endpoint: "otel-collector.monitoring:4317"
      protocol: "grpc"

Learn more about OpenTelemetry

Secret & ConfigMap Injection⚓

spec:
  env:
    secretRefs:
      - name: api-credentials
        prefix: "API_"
    configMapRefs:
      - name: app-config
    variables:
      - name: TARGET_HOST
        value: "https://api.example.com"

Learn more about Environment Injection

Volume Mounting⚓

spec:
  volumes:
    - name: test-data
      persistentVolumeClaim:
        claimName: test-data-pvc
  volumeMounts:
    - name: test-data
      mountPath: /data
      target: both  # master, worker, or both

Learn more about Volume Mounting

Separate Resource Specs⚓

spec:
  master:
    resources:
      requests:
        memory: "256Mi"
        cpu: "100m"
  worker:
    resources:
      requests:
        memory: "512Mi"
        cpu: "500m"

Learn more about Separate Resources

Troubleshooting⚓

Common Issues⚓

Conversion Webhook Not Working⚓

Symptom: v1 CRs fail with schema validation errors

Solution: Ensure cert-manager is installed and the webhook is enabled:

# Check cert-manager
kubectl get pods -n cert-manager

# Enable webhook in Helm
helm upgrade locust-operator locust-k8s-operator/locust-k8s-operator \
  --set webhook.enabled=true

Resources Not Created⚓

Symptom: LocustTest CR created but no Jobs/Services appear

Solution: Check operator logs:

kubectl logs -n locust-system -l app.kubernetes.io/name=locust-k8s-operator

Status Not Updating⚓

Symptom: LocustTest status remains empty

Solution: Verify RBAC permissions include locusttests/status:

kubectl auth can-i update locusttests/status --as=system:serviceaccount:locust-system:locust-operator

How to Get Help⚓

• GitHub Issues

Rollback Procedure⚓

If you need to revert to v1:

# Rollback Helm release
helm rollback locust-operator <previous-revision> -n locust-system

# Or reinstall v1
helm install locust-operator locust-k8s-operator/locust-k8s-operator \
  --version 1.1.1 \
  -f values-backup.yaml