Lỗi ErrImagePull là gì? Nguyên nhân và cách khắc phục lỗi chi tiết

ErrImagePull là một trạng thái lỗi thường gặp trong Kubernetes, xuất hiện khi kubelet không thể kéo (pull) container image được khai báo trong Pod từ container registry về node. Bài viết này được mình đúc kết từ quá trình trực tiếp xử lý nhiều sự cố image pull trên các cluster Kubernetes, giúp bạn nắm rõ nguyên nhân phổ biến của ErrImagePull và áp dụng quy trình xác định, khắc phục chi tiết để đảm bảo workload triển khai ổn định.

Những điểm chính

• Quan điểm của mình: Với các hệ thống triển khai bằng Kubernetes, việc hiểu rõ cách vận hành cơ chế kéo image và đọc đúng các trạng thái ErrImagePull/ImagePullBackOff sẽ quyết định bạn xử lý sự cố nhanh hay bị “kẹt” hàng giờ chỉ vì thiếu thông tin.
• Khái niệm: Hiểu rõ ErrImagePull là trạng thái lỗi ban đầu, giúp bạn nhanh chóng xác định sự cố xảy ra ở khâu kéo ảnh container từ registry.
• Nguyên nhân gây lỗi: Nắm vững các nguyên nhân phổ biến từ sai tên image đến lỗi xác thực, giúp bạn có một danh sách kiểm tra hiệu quả để khoanh vùng và chẩn đoán sự cố.
• Cách thức hoạt động: Hiểu rõ cách Kubernetes kéo image, giúp bạn nhận biết các bước tiềm ẩn có thể gây ra lỗi trong quá trình này.
• Mối liên hệ: Phân biệt rõ ràng mối quan hệ giữa ErrImagePull (lỗi ban đầu) và ImagePullBackOff (trạng thái thử lại), giúp bạn đọc hiểu chính xác các thông báo sự kiện (events) trong Kubernetes.
• Cách khắc phục: Nắm vững quy trình xử lý 4 bước, giúp bạn có một lộ trình rõ ràng để chẩn đoán và giải quyết triệt để sự cố.
• Cách phòng tránh: Nắm được các phương pháp hay nhất trong việc quản lý image và cấu hình, giúp bạn chủ động phòng tránh sự cố và đảm bảo quy trình triển khai ổn định.
• Giới thiệu Vietnix: Nhận biết Vietnix là nhà cung cấp Enterprise Cloud, giúp bạn có một nền tảng hạ tầng vững chắc để tối ưu hóa quy trình DevOps và giảm thiểu các lỗi như ErrImagePull.
• Câu hỏi thường gặp: Giải đáp các thắc mắc liên quan đến lỗi ErrImagePull.

Lỗi ErrImagePull trong Kubernetes là gì?

ErrImagePull là trạng thái lỗi xuất hiện khi kubelet không thể kéo container image được khai báo trong Pod từ container registry về node. Khi bước image pull thất bại, Pod không thể khởi tạo container và không chuyển sang trạng thái Running. Trong nhiều trường hợp, ErrImagePull là lỗi ban đầu, sau đó Kubernetes có thể chuyển Pod sang trạng thái ImagePullBackOff khi tiếp tục retry theo cơ chế backoff.

Sai tên image, repository hoặc tag

Một trong những nguyên nhân phổ biến nhất gây ErrImagePull là khai báo sai tên image, repository hoặc tag trong manifest Kubernetes hoặc cấu hình dịch vụ. Khi kubelet dùng thông tin này để truy vấn registry, registry không tìm thấy repository hoặc tag tương ứng và trả về lỗi như “repository does not exist” hoặc “manifest unknown”. Tình huống này cũng xuất hiện trên Tencent CloudBase Run nếu cấu hình image của service trỏ đến một image hoặc tag không tồn tại trong Tencent Container Registry hay registry bên ngoài.

Image không tồn tại hoặc không public trong registry

Trong nhiều trường hợp, đường dẫn image đúng cú pháp nhưng image thực tế đã bị xóa, chưa được push hoặc đang ở trạng thái private trong registry. Khi kubelet gửi yêu cầu kéo image, registry trả về lỗi không tìm thấy manifest hoặc từ chối truy cập, dẫn đến Pod nhận trạng thái ErrImagePull. Việc triển khai dịch vụ trên CloudBase Run cũng có thể gặp ErrImagePull nếu image chưa được publish đúng project/namespace registry hoặc người dùng không có quyền đọc image đó.

Lỗi xác thực hoặc thiếu thông tin đăng nhập registry

Nếu registry yêu cầu xác thực nhưng cluster không cung cấp thông tin đăng nhập hợp lệ, kubelet không thể lấy image và trả về ErrImagePull kèm thông báo như “unauthorized” hoặc “authentication required”. Nguyên nhân thường đến từ cấu hình sai imagePullSecret, secret hết hạn token hoặc không gán secret đúng cách cho Pod hay ServiceAccount. Trên Tencent CloudBase Run, việc cấu hình chưa đúng credential để truy cập Tencent Container Registry hoặc registry bên ngoài cũng dẫn đến lỗi ErrImagePull do không vượt qua bước xác thực.

Sự cố mạng, DNS hoặc firewall tới container registry

ErrImagePull cũng có thể xuất hiện khi node không thể kết nối được tới địa chỉ registry do sự cố mạng, phân giải DNS sai hoặc firewall chặn traffic ra ngoài. Trong trường hợp này, kubelet gửi yêu cầu nhưng không nhận được phản hồi thích hợp, gây ra các lỗi như timeout, TLS handshake failure hoặc connection refused và kết quả cuối cùng là ErrImagePull. Với các môi trường managed như CloudBase Run, cấu hình network, VPC, router hoặc security group không cho phép truy cập registry cũng là nguyên nhân khiến dịch vụ báo lỗi ErrImagePull ngay khi khởi động.

Cách Kubernetes kéo image và lý do sinh ra ErrImagePull

Khi một Pod được tạo, kubelet trên node sẽ đọc spec của Pod để lấy thông tin container image, sau đó phân giải tên image thành các thành phần như registry (nếu được chỉ định), repository và tag. Nếu không chỉ rõ registry, kubelet dùng registry mặc định (ví dụ Docker Hub) và sử dụng tag latest khi không có tag, rồi chuẩn bị kết nối tới endpoint tương ứng của registry.

Tiếp theo, kubelet gửi yêu cầu tới registry để lấy manifest và các layer của image, có thể kèm thông tin xác thực nếu registry yêu cầu login. Registry kiểm tra quyền truy cập, tìm manifest và trả về metadata, sau đó node lần lượt tải về các layer để lưu vào local image cache. Khi toàn bộ manifest và layer được tải thành công, image sẵn sàng cho container runtime sử dụng để khởi tạo container.

ErrImagePull phát sinh khi một trong các bước trên thất bại, ví dụ không phân giải được image (sai tên, sai tag), không truy cập được registry (lỗi mạng hoặc DNS) hoặc bị từ chối bởi registry (lỗi xác thực, thiếu quyền). Trong trường hợp này, kubelet ghi nhận lỗi ở sự kiện Pod và trạng thái container chuyển sang ErrImagePull thay vì Pulled/Running. Nếu lỗi tiếp tục lặp lại trong các lần retry, Kubernetes có thể chuyển sang trạng thái ImagePullBackOff, thể hiện cơ chế backoff tăng dần thời gian chờ giữa các lần kéo image.

Quy trình chẩn đoán và xử lý lỗi ErrImagePull

Bước 1: Kiểm tra thông tin lỗi với kubectl describe pod và log nền tảng

Trước tiên, bạn cần lấy đầy đủ thông tin lỗi mà kubelet ghi lại cho Pod gặp ErrImagePull. Sử dụng kubectl describe pod để xem phần Events, nơi thường hiển thị các thông báo như “repository not found”, “manifest unknown”, “unauthorized”, “TLS handshake timeout” hoặc các lỗi kết nối khác liên quan tới việc kéo image. Nếu triển khai trên Tencent CloudBase Run, bạn cần đồng thời kiểm tra log và chi tiết lỗi trong giao diện console của dịch vụ để nắm được thông báo ErrImagePull và các mã lỗi đi kèm do nền tảng cung cấp.

kubectl describe pod <ten-pod> -n <namespace>

Bước 2: Sửa lỗi liên quan đến image, repository và tag

Sau khi nắm được lỗi, bước tiếp theo là kiểm tra lại phần image được khai báo trong YAML hoặc cấu hình dịch vụ. Bạn cần đối chiếu tên image, repository và tag trong manifest với thực tế trên registry đang sử dụng (Docker Hub, private registry, Tencent Container Registry,…) để xác nhận sự tồn tại và tính chính xác. Tiếp đó, bạn nên thực hiện docker pull, podman pull hoặc ctr images pull từ một môi trường tương đương node để kiểm chứng việc kéo image có thành công hay không, từ đó loại trừ trường hợp image chưa được push hoặc đã bị xóa.

docker pull <registry>/<repo>:<tag>
# hoặc
podman pull <registry>/<repo>:<tag>

Nếu phát hiện tên image hoặc tag sai, cần cập nhật lại manifest Kubernetes hoặc cấu hình CloudBase Run với đường dẫn image và tag chính xác, đồng thời nên hạn chế sử dụng tag latest để tránh nhầm lẫn giữa các phiên bản image.

Bước 3: Khắc phục vấn đề mạng và kết nối tới registry

Khi tên image đã đúng nhưng vẫn gặp ErrImagePull với thông điệp liên quan đến timeout, TLS hoặc không thể kết nối, bạn cần tập trung kiểm tra đường truyền tới registry. Từ node hoặc môi trường chạy workload, có thể dùng các công cụ như ping, curl, telnet hoặc tương đương để kiểm tra khả năng kết nối tới hostname của registry (bao gồm cả cổng sử dụng). Đồng thời, bạn rà soát cấu hình DNS, proxy, firewall, security group hoặc ACL trên mạng/VPC để xác định có thành phần nào đang chặn hoặc chuyển hướng traffic ra/vào registry.

ping <registry-hostname>
curl -v https://<registry-hostname>/v2/
telnet <registry-hostname> 443

Bên cạnh đó, bạn nên kiểm tra trạng thái hoạt động của registry (region, endpoint, health service) thông qua trang trạng thái dịch vụ hoặc tài liệu nhà cung cấp để loại trừ trường hợp registry đang gặp sự cố phía nhà cung cấp.

Bước 4: Xử lý sự cố xác thực và quyền truy cập registry

Nếu thông báo ErrImagePull cho thấy lỗi “unauthorized”, “authentication required” hoặc mã lỗi liên quan đến quyền, bạn cần kiểm tra lại thông tin đăng nhập sử dụng cho registry. Trong Kubernetes, thông tin này thường được lưu dưới dạng Secret dùng cho imagePullSecrets, bao gồm username/password, access token hoặc key được cung cấp bởi registry. Khi credential không còn hợp lệ hoặc cấu hình sai, bạn tạo mới hoặc cập nhật Secret, sau đó gán lại vào Pod spec hoặc ServiceAccount thông qua trường imagePullSecrets.

kubectl create secret docker-registry regcred \
  --docker-server=<registry> \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email> \
  -n <namespace>

apiVersion: v1
kind: Pod
metadata:
  name: example
  namespace: <namespace>
spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: app
      image: <registry>/<repo>:<tag>

Đối với Tencent CloudBase Run, bạn cần cấu hình lại credential truy cập Tencent Container Registry hoặc registry bên ngoài theo hướng dẫn của nền tảng (ví dụ gán quyền cho tài khoản cloud, cấu hình thông tin repository trong giao diện CloudBase Run), để dịch vụ có đủ quyền kéo image mà không phát sinh ErrImagePull.

Hạn chế ErrImagePull trong môi trường Kubernetes

Để giảm tần suất phát sinh ErrImagePull và đơn giản hóa quá trình vận hành, bạn cần thiết kế quy trình build, push và deploy image một cách chặt chẽ ngay từ đầu.

• Chuẩn hóa tên và tag image: Sử dụng quy ước đặt tên rõ ràng cho repository và tag, tránh phụ thuộc vào latest để giảm rủi ro trỏ nhầm tới phiên bản image không mong muốn.
• Kiểm tra image trước khi triển khai: Thực hiện docker/podman/ctr pull image từ môi trường tương đương node hoặc môi trường CI/CD để xác minh image tồn tại và có thể kéo được trước khi apply manifest lên cluster.
• Quản lý credential registry bằng Secret: Lưu thông tin đăng nhập registry trong Kubernetes Secret (docker-registry) hoặc cơ chế credential an toàn của nền tảng, thay vì hard-code trong manifest hoặc biến môi trường.
• Gán imagePullSecrets đúng phạm vi: Cấu hình imagePullSecrets cho Pod hoặc gắn ở cấp ServiceAccount dùng chung cho nhiều workload, bảo đảm mọi Pod cần kéo image private đều có credential hợp lệ.
• Giám sát trạng thái registry và mạng: Thiết lập giám sát kết nối tới registry, bao gồm DNS, latency, lỗi TLS, cùng với việc theo dõi trang trạng thái dịch vụ registry hoặc cloud provider để phát hiện sớm sự cố ảnh hưởng đến quá trình kéo image.
• Tối ưu quy trình deploy trên nền tảng managed: Với môi trường như Tencent CloudBase Run, định kỳ kiểm tra cấu hình image, registry, quyền truy cập và log triển khai để đảm bảo dịch vụ luôn tham chiếu đúng repository, tag và credential mới nhất.

Vietnix – Nhà cung cấp nền tảng đám mây tối ưu, hạn chế lỗi ImagePull

Để đảm bảo các cụm Kubernetes của bạn hoạt động ổn định và tránh các lỗi phiền phức như ErrImagePull, một hạ tầng đám mây với hiệu năng cao và kết nối mạng đáng tin cậy là yếu tố không thể thiếu. Vietnix cung cấp dịch vụ Enterprise Cloud hiệu suất vượt trội, được thiết kế để trở thành nền tảng vững chắc cho các cụm Kubernetes của bạn. Với kết nối mạng ổn định và băng thông mạnh mẽ, Vietnix giúp các node của bạn dễ dàng kéo image container từ mọi registry, giảm thiểu rủi ro lỗi kết nối và tối ưu hóa quy trình triển khai.

Thông tin liên hệ:

• Website: https://vietnix.vn/
• Hotline: 1800 1093
• Email: sales@vietnix.com.vn
• Địa chỉ: 265 Hồng Lạc, Phường Bảy Hiền, Thành Phố Hồ Chí Minh

Lỗi ErrImagePull là một sự cố phổ biến nhưng quan trọng trong Kubernetes, báo hiệu rằng hệ thống không thể kéo ảnh container cần thiết để khởi chạy ứng dụng. Việc thiết lập các quy trình làm việc chặt chẽ và giám sát chủ động sẽ là chìa khóa để hạn chế ErrImagePull, đảm bảo các ứng dụng được triển khai một cách liền mạch và duy trì tính sẵn sàng cho toàn bộ cụm Kubernetes.