FAQ: How to deal with imagePullBackOff when pulling the Komodor-Agent Image

Overview

When deploying the Komodor Agent, you may encounter a Kubernetes ImagePullBackOff error. This typically happens if Kubernetes can’t authenticate or is rate-limited when pulling our container images. This FAQ walks you through three ways to solve it:

1. Authenticate to Amazon ECR Public
2. Use Docker Hub (backup registry)
3. Host a Local (private) Image Registry

1. Authenticate to Amazon ECR Public

Komodor publishes our images to Amazon ECR Public. By authenticating, you avoid Docker Hub rate limits altogether.

1. Install/Configure the AWS CLI (v2+) and ensure you have IAM permissions for ecr-public:GetLoginPassword.
2. Create a Kubernetes Secret in the namespace where your Komodor Agent runs (e.g. komodor-agent):

   # Replace <secret-name> and <namespace> as needed
   kubectl create secret docker-registry <secret-name> \
     --docker-server=public.ecr.aws/komodor-public \
     --docker-username=AWS \
     --docker-password="$(aws ecr-public get-login-password --region us-east-1)" \
     --namespace komodor-agent

3. Patch your Agent’s ServiceAccount (or Pod spec) to reference the secret:

   kubectl patch serviceaccount komodor-agent-sa \
     --namespace komodor-agent \
     -p '{"imagePullSecrets":[{"name":"<secret-name>"}]}'

4. Re-deploy the Agent:

   kubectl rollout restart deployment komodor-agent -n komodor-agent

If authentication succeeds, the Pods should start pulling images without rate-limit errors.

2. Use Docker Hub (Backup Registry)

We mirror the same Agent images on Docker Hub. If you prefer Docker Hub or lack AWS credentials, register an account there:

1. Create a Docker Hub Account at https://hub.docker.com.
2. Create a Kubernetes Secret:

   kubectl create secret docker-registry dockerhub-komodor \
     --docker-server=https://index.docker.io/v1/ \
     --docker-username=<your-dockerhub-username> \
     --docker-password=<your-dockerhub-token-or-password> \
     --namespace komodor-agent

3. Attach the Secret to your Agent’s ServiceAccount (same as above).
4. Restart the Deployment.

Note: Docker Hub enforces rate limits on anonymous or free-tier pulls. Authenticating with your account raises your pull quota.

3. Host a Local Image Registry

For full control and zero external dependencies, you can mirror the Komodor Agent images into your own registry:

1. Pull the Komodor Agent Image Locally:

   docker pull public.ecr.aws/komodor-public/komodor-agent:<version>

2. Tag & Push to Your Registry:

   docker tag public.ecr.aws/komodor-public/komodor-agent:<version> \
     my-registry.local:5000/komodor-agent:<version>
   
   docker push my-registry.local:5000/komodor-agent:<version>

3. Create a Kubernetes Secret for my-registry.local:5000 (if it’s private):

   kubectl create secret docker-registry local-registry \
     --docker-server=my-registry.local:5000 \
     --docker-username=<user> \
     --docker-password=<pass> \
     --namespace komodor-agent

4. Update Your Deployment to use your registry address:

   # In your Komodor Agent Helm values or YAML:
   image:
     repository: my-registry.local:5000/komodor-agent
     tag: <version>
   imagePullSecrets:
     - name: local-registry

5. Apply & Rollout:

   kubectl apply -f komodor-agent-deployment.yaml

Troubleshooting Tips

• Ensure Namespace Matches: Double-check that your imagePullSecrets and ServiceAccount live in the same namespace as the Agent Pods.

• Verify Secret Contents:

  kubectl get secret <secret-name> -n komodor-agent -o yaml

  Look for non-empty .data.

• Check Pod Events:

  kubectl describe pod <agent-pod-name> -n komodor-agent

  The events will show authentication or rate-limit errors.

Still Seeing ImagePullBackOff?

If none of the above resolves your issue, please reach out to Komodor Support:

• Email: support@komodor.com
• Chat: Reach out via the chat icon in the Komodor UI.
• Help Center: See our relevant docs at help.komodor.com 

We’ll be happy to help diagnose any remaining edge cases.