Skip to content

Use a private image registry⚓

Pull custom Locust images from private container registries like Docker Hub, GitHub Container Registry, or AWS ECR.

Prerequisites⚓

  • Registry credentials (username/password or access token)
  • Custom Locust image pushed to private registry

Create image pull secret⚓

Store registry credentials in a Kubernetes secret:

kubectl create secret docker-registry my-registry-secret \
  --docker-server=ghcr.io \
  --docker-username=myusername \
  --docker-password=ghp_myPersonalAccessToken

For specific registries:

kubectl create secret docker-registry ghcr-secret \
  --docker-server=ghcr.io \
  --docker-username=myusername \
  --docker-password=ghp_myPersonalAccessToken

kubectl create secret docker-registry dockerhub-secret \
  --docker-server=docker.io \
  --docker-username=myusername \
  --docker-password=myAccessToken

# Get ECR login token (expires after 12 hours)
ECR_TOKEN=$(aws ecr get-login-password --region <region>)
kubectl create secret docker-registry ecr-secret \
  --docker-server=<account-id>.dkr.ecr.<region>.amazonaws.com \
  --docker-username=AWS \
  --docker-password="${ECR_TOKEN}"

# Use JSON key file
kubectl create secret docker-registry gcr-secret \
  --docker-server=gcr.io \
  --docker-username=_json_key \
  --docker-password="$(cat key.json)"

Namespace

The image pull secret must be created in the same namespace as the LocustTest CR that references it.

Verify the secret exists:

kubectl get secret my-registry-secret

Reference secret in LocustTest⚓

Add imagePullSecrets to your LocustTest CR:

apiVersion: locust.io/v2
kind: LocustTest
metadata:
  name: private-registry-test
spec:
  image: ghcr.io/mycompany/locust-custom:v1.2.3  # Private image
  imagePullSecrets:  # Reference the secret
    - name: my-registry-secret
  testFiles:
    configMapRef: my-test
  master:
    command: "--locustfile /lotest/src/test.py --host https://api.example.com"
  worker:
    command: "--locustfile /lotest/src/test.py"
    replicas: 3

Apply the CR:

kubectl apply -f locusttest-private.yaml

Configure image pull policy⚓

Control when Kubernetes pulls the image:

apiVersion: locust.io/v2
kind: LocustTest
metadata:
  name: pull-policy-test
spec:
  image: ghcr.io/mycompany/locust-custom:latest
  imagePullPolicy: Always  # Pull image every time
  imagePullSecrets:
    - name: my-registry-secret
  testFiles:
    configMapRef: my-test
  master:
    command: "--locustfile /lotest/src/test.py --host https://api.example.com"
  worker:
    command: "--locustfile /lotest/src/test.py"
    replicas: 3

Pull policy options:

PolicyBehaviorWhen to use
AlwaysPull image on every pod creationDevelopment with :latest tag or frequently updated images
IfNotPresentPull only if not cached locallyStable versioned images (default for non-:latest tags)
NeverNever pull, use cached image onlyPre-loaded images or air-gapped environments

Recommendation: Use Always with :latest tags. Use IfNotPresent or omit (default) with version tags like v1.2.3.

Verify image pull⚓

Check that pods successfully pulled the image:

# Get pod status
kubectl get pods -l performance-test-name=private-registry-test

# Check image field
kubectl get pod -l performance-test-pod-name=private-registry-test-master -o jsonpath='{.items[0].spec.containers[0].image}'

Expected output:

ghcr.io/mycompany/locust-custom:v1.2.3

Verify pull policy:

kubectl get pod -l performance-test-pod-name=private-registry-test-master -o jsonpath='{.items[0].spec.containers[0].imagePullPolicy}'

Troubleshoot ImagePullBackOff⚓

If pods fail with ImagePullBackOff:

# Check pod events
kubectl describe pod -l performance-test-name=private-registry-test | grep -A 10 "Events:"

Common issues:

Authentication failed:

Failed to pull image: unauthorized: authentication required

Fix: Verify secret credentials are correct. Recreate the secret if needed.

Image not found:

Failed to pull image: manifest unknown: manifest unknown

Fix: Verify image name, tag, and registry URL. Check the image exists:

# For Docker Hub
docker pull ghcr.io/mycompany/locust-custom:v1.2.3

# For AWS ECR
aws ecr describe-images --repository-name locust-custom --region us-east-1

Wrong secret referenced:

Couldn't find key .dockerconfigjson in Secret

Fix: Verify secret name in imagePullSecrets matches the created secret:

kubectl get secrets | grep registry

Network policy blocking registry:

Failed to pull image: dial tcp: i/o timeout

Fix: Check network policies allow egress to the registry:

kubectl get networkpolicies

What's next⚓