Tạo imagePullSecret bằng kubectl

Để pull image từ registry riêng, cluster Kubernetes cần một Secret kiểu kubernetes.io/dockerconfigjson chứa thông tin đăng nhập — gọi là imagePullSecret. Không có Secret này, Pod sẽ dừng ở trạng thái ImagePullBackOff và ứng dụng không khởi động được. Hướng dẫn này áp dụng cho dù bạn là developer deploy ứng dụng dùng image riêng tư, platform engineer chuẩn bị Secret cho nhiều namespace, hay pipeline CI/CD cần tạo lại Secret mỗi khi rotate thông tin đăng nhập. Sau khi hoàn thành, bạn có một Secret trong namespace của mình và workload pull được image riêng tư từ Container Registry.

Điều kiện tiên quyết

• kubectl kết nối được cluster. Kiểm tra bằng kubectl get nodes.
• Bạn có quyền tạo Secret trong namespace cần dùng. Kiểm tra bằng kubectl auth can-i create secret -n <namespace>.
• Bạn có thông tin đăng nhập Container Registry. Trên FPT Portal, vào Container Registry > Get Token.

Dùng Robot Account chỉ có quyền pull cho việc này, không dùng tài khoản cá nhân. Xem Tạo robot account.

Tạo Secret

kubectl create secret docker-registry regcred \
  --docker-server=registry.fptcloud.com \
  --docker-username='robot$my-project+ci' \
  --docker-password='Xy9!kP2$mQ' \
  --namespace=my-app

Chạy thành công trả về:

secret/regcred created

cảnh báo

Ba điểm sau thường khiến Secret có vẻ đúng nhưng vẫn không xác thực được.

• Luôn bọc password trong nháy đơn ('...'). Ký tự như $, !, hay & nếu không bọc sẽ bị shell thay đổi, khiến Secret lưu sai giá trị dù lệnh vẫn báo thành công.
• --docker-server phải khớp đúng phần host đứng đầu tên image — không kèm https://, không kèm tên project.
• --namespace phải đúng namespace nơi workload chạy. Secret không dùng chéo namespace được.

mẹo

Truyền username và password qua biến môi trường thay vì gõ trực tiếp vào lệnh, và không commit file YAML chứa .dockerconfigjson lên Git.

Xem Tham chiếu field imagePullSecret để biết đầy đủ các flag của kubectl create secret docker-registry và quy tắc đặt tên Secret.

Gắn Secret vào workload

Thêm imagePullSecrets vào Pod template:

spec:
  template:
    spec:
      imagePullSecrets:
        - name: regcred
      containers:
        - name: api
          image: registry.fptcloud.com/my-project/api:v1

kubectl apply -f deployment.yaml

Nếu nhiều workload trong cùng namespace dùng chung registry, gắn Secret vào ServiceAccount thay vì sửa từng manifest:

kubectl patch serviceaccount default -n my-app \
  -p '{"imagePullSecrets":[{"name":"regcred"}]}'

ghi chú

Patch ServiceAccount chỉ ảnh hưởng đến Pod được tạo sau khi patch. Pod đang chạy cần kubectl rollout restart để nhận thay đổi.

Kiểm tra Secret hoạt động

kubectl get pods -n my-app

Trạng thái	Nghĩa là	Cần làm gì
ContainerCreating	Đang pull.	Đợi rồi kiểm tra lại.
Running	Pull thành công.	Không cần làm gì thêm.
ErrImagePull	Lần pull đầu thất bại.	Xem Xử lý sự cố.
ImagePullBackOff	Kubernetes đã thử lại và bỏ cuộc.	Xem Xử lý sự cố.

Để xem nguyên nhân cụ thể, kiểm tra Events của Pod:

kubectl describe pod <pod-name> -n my-app | tail -20

Phần Events ở cuối output phân biệt lỗi xác thực và lỗi không tìm thấy image.

Để xem thông tin đăng nhập đã lưu trong Secret:

kubectl get secret regcred -n my-app \
  -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d

Kết quả đúng chứa khối auths với địa chỉ registry và trường auth không rỗng, và Pod chuyển sang Running.

Tạo Secret từ file cấu hình Docker

Dùng cách này khi password chứa ký tự khó escape, hoặc khi bạn đã docker login sẵn.

docker login registry.fptcloud.com

kubectl create secret docker-registry regcred \
  --from-file=$HOME/.docker/config.json \
  --namespace=my-app

Kiểm tra file trước khi dùng cách này:

cat ~/.docker/config.json

Nếu file chứa "credsStore" thay vì khối "auths" có trường "auth", Docker đang lưu thông tin đăng nhập trong keychain của hệ điều hành. Secret tạo từ file này sẽ rỗng — dùng lệnh kubectl create secret docker-registry ở phần trên thay thế.

Tạo lại hoặc dùng Secret cho nhiều namespace

Chạy lại kubectl create secret trên một Secret đã tồn tại sẽ lỗi AlreadyExists. Trong script hoặc CI/CD, pipe sang kubectl apply để lệnh an toàn khi chạy nhiều lần:

kubectl create secret docker-registry regcred \
  --docker-server=registry.fptcloud.com \
  --docker-username="$REG_USER" \
  --docker-password="$REG_PASS" \
  --namespace=my-app \
  --dry-run=client -o yaml | kubectl apply -f -

Secret không dùng chéo namespace được, nên lặp lại lệnh cho từng namespace cần dùng:

for ns in app-dev app-staging app-prod; do
  kubectl create secret docker-registry regcred \
    --docker-server=registry.fptcloud.com \
    --docker-username="$REG_USER" \
    --docker-password="$REG_PASS" \
    --namespace="$ns" \
    --dry-run=client -o yaml | kubectl apply -f -
done

Cập nhật Secret sau khi rotate thông tin đăng nhập

Pod đang chạy không tự nhận thông tin đăng nhập mới. Sau khi tạo lại hoặc cập nhật Secret với thông tin đăng nhập mới, restart workload để nó nạp lại:

kubectl rollout restart deployment/api -n my-app

Bước tiếp theo

• Quản lý repository — xem và dọn dẹp các Repository cluster của bạn đang pull từ đó.
• Xử lý sự cố — khắc phục Secret không xác thực được.