如何将本地Docker镜像部署为K3s Pod并解决ImagePullBackOff错误

Hey there! Let's work through this ImagePullBackOff issue step by step—since you're using K3s with Docker as the runtime, there are a few specific checks and fixes to try:

1. Verify the Local Image Exists on the Target K3s Node #

K3s can only use a local Docker image if that image is present on the node where the Pod gets scheduled.

• SSH into the K3s node (control plane or worker, depending on your scheduling) and run:

  docker images
  

• Double-check that your custom image's name and tag match exactly what's in your Pod definition. For example, if your image is my-custom-app:latest, your Pod's image field must use that exact string.
• If you're running a multi-node K3s cluster, the image needs to exist on every node that might schedule the Pod, or you'll need to share it via a local registry (more on that later).

2. Adjust the Image Pull Policy in Your Pod Definition #

By default, Kubernetes (and K3s) tries to pull images from a remote registry even if a local copy exists. Fix this by setting the imagePullPolicy:

• Use imagePullPolicy: Never to force K3s to only use the local image (no remote pull attempts)
• Or use imagePullPolicy: IfNotPresent to use the local image if it exists, otherwise pull from remote
• Example Pod YAML:

  apiVersion: v1
  kind: Pod
  metadata:
    name: my-app-pod
  spec:
    containers:
    - name: app-container
      image: my-custom-app:latest
      imagePullPolicy: Never  # Critical for local-only images
  

3. Dig Into Detailed Error Logs #

The ImagePullBackOff status is a generic indicator—get specific details to narrow down the issue:

• Run this command to view the Pod's events and error messages:

  kubectl describe pod <your-pod-name>
  

  Look for the Events section—you might see messages like ErrImagePull: image not found or pull access denied, which tell you exactly what's wrong.
• Check Docker logs on the node for more context:

  journalctl -u docker
  

4. Confirm K3s is Actually Using Docker as the Runtime #

Even if you configured K3s to use Docker, it's worth verifying:

• Check the K3s config file at /etc/rancher/k3s/config.yaml—it should include docker: true
• Or verify the node's runtime version with:

  kubectl get nodes -o wide
  

  The Runtime Version column should show something like docker://24.0.6

5. For Multi-Node Clusters: Share the Image Across Nodes #

If you have multiple K3s nodes, you can't just have the image on your local machine. Two options:

• Copy the image directly:
  1. Export the image on your local node:

     docker save -o my-app.tar my-custom-app:latest
     

  2. Transfer the .tar file to other nodes (via scp, for example)
  3. Import the image on each target node:

     docker load -i my-app.tar
     

• Set up a local private registry: Run a Docker Registry container on one of your nodes, push your custom image to it, then update your Pod's image field to point to the local registry (e.g., 192.168.1.100:5000/my-custom-app:latest)

Start with the first three steps—most ImagePullBackOff issues with local images boil down to missing images on the node or incorrect pull policies. Let me know if you hit a specific error message we can dive deeper into!

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