私有Docker镜像Helm部署遇Init:ErrImagePull问题求助

Alright, let's break down why you're hitting that Init:ErrImagePull status with your private Docker repo and Helm setup. I’ve run into this exact headache a few times, so here are the most common fixes to walk through:

1. Verify Helm is properly creating an ImagePullSecret #

First up, make sure your Helm chart is actually using the imageCredentials from your values.yaml to generate a valid Kubernetes ImagePullSecret.

Check your chart's templates for a Secret definition that looks like this (it might live in a file like templates/image-pull-secret.yaml):

apiVersion: v1
kind: Secret
metadata:
  name: {{ .Values.imageCredentials.secretName | default "private-registry-secret" }}
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: {{ printf "{\"auths\":{\"%s\":{\"username\":\"%s\",\"password\":\"%s\"}}}" .Values.imageCredentials.registry .Values.imageCredentials.username .Values.imageCredentials.password | b64enc }}

Then confirm your pod template references this secret in the imagePullSecrets section:

spec:
  imagePullSecrets:
    - name: {{ .Values.imageCredentials.secretName | default "private-registry-secret" }}

If either piece is missing from your chart, Helm won't set up the credentials needed to pull from your private repo. You can manually check if the secret exists after install with:

kubectl get secrets

2. Test your credentials directly #

Don’t assume your username/password is correct—double-check by logging into the repo manually from your local machine (or a K8s node):

docker login <your-repo-url> -u <username> -p <password>

If this fails, you’ve found your issue: fix the credentials in values.yaml and re-run helm upgrade.

3. Confirm the image tag exists in your private repo #

A typo in the tag field is super easy to miss. Verify the tag you specified in values.yaml actually exists in your repo. Test pulling the image locally (after logging in) to confirm:

docker pull <your-repo-url>:<your-version-tag>

If this returns a "manifest not found" error, you either pushed the wrong tag or haven’t pushed the image to the repo at all.

4. Check network connectivity from K8s nodes to your repo #

Sometimes the problem isn’t credentials—it’s that your K8s nodes can’t reach the private repo. On any cluster node, run:

telnet <your-repo-url> 443  # For HTTPS repos
# Or
curl -I <your-repo-url>

If you get a connection timeout or refused error, fix your network rules (firewall, VPN, etc.) to let nodes communicate with the repo.

5. Dig into the exact error from kubectl describe #

You mentioned running kubectl describe pods—pay close attention to the Events section at the bottom. It’ll give you specific error messages like:

• authentication required: Credentials are invalid or the secret isn’t attached to the pod.
• manifest unknown: The image/tag doesn’t exist in the repo.
• connection refused: Node can’t reach the repo.

These messages are your fastest path to fixing the issue.

内容的提问来源于stack exchange，提问作者Jayp