K8s拉取Harbor私有镜像全攻略

Kubernetes拉取Harbor私有镜像全攻略：生产环境落地指南

在企业级容器化场景中，Harbor作为主流的私有镜像仓库，其安全管控与Kubernetes的集成是必备技能。本文将手把手教你5种认证方案，并揭秘镜像拉取失败的6大排查技巧。

---

一、基础认证方案：Docker-registry Secret

1. 快速创建认证凭证

# 一键生成Harbor认证Secret（推荐）
kubectl create secret docker-registry harbor-creds \
  --docker-server=harbor.example.com \
  --docker-username=admin \
  --docker-password=Harbor12345 \
  --namespace=prod

2. 关联到工作负载的三种方式

方式1：Pod直接引用

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  template:
    spec:
      containers:
      - name: app
        image: harbor.example.com/prod/frontend:v1.2
      imagePullSecrets:
      - name: harbor-creds  # 关键配置

方式2：绑定默认ServiceAccount

# 将Secret添加到default服务账号
kubectl patch serviceaccount default \
  -p '{"imagePullSecrets": [{"name": "harbor-creds"}]}' \
  -n prod

方式3：自定义ServiceAccount

apiVersion: v1
kind: ServiceAccount
metadata:
  name: ci-cd-sa
  namespace: prod
imagePullSecrets:
- name: harbor-creds
secrets: []

---

二、企业级进阶方案

1. 多环境隔离配置

# 为不同环境创建独立凭证
kubectl create secret docker-registry harbor-dev-creds \
  --docker-server=harbor-dev.example.com \
  --docker-username=dev-robot \
  --docker-password=Dev@Token2023 \
  --namespace=dev

kubectl create secret docker-registry harbor-prod-creds \
  --docker-server=harbor-prod.example.com \
  --docker-username=prod-robot \
  --docker-password=Prod@Token2023 \
  --namespace=prod

2. HTTPS证书配置

# 获取Harbor的CA证书
openssl s_client -connect harbor.example.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > ca.crt

# 创建包含证书的Secret
kubectl create secret generic harbor-ca \
  --from-file=ca.crt=./ca.crt \
  --namespace=prod

# 在节点上更新Docker配置
sudo mkdir -p /etc/docker/certs.d/harbor.example.com
sudo cp ca.crt /etc/docker/certs.d/harbor.example.com/ca.crt

3. 使用Harbor机器人账户

apiVersion: v1
kind: Secret
metadata:
  name: harbor-robot
  annotations:
    harbor.example.com/robot-id: "robot$ci-system+2023"  # 审计追踪
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: >
    eyJhdXRocyI6eyJoYXJib3...（base64编码数据）

---

三、镜像地址规范详解

正确格式示例：

harbor.example.com/<项目名>/<镜像名>:<标签>

常见错误案例：

1. 缺少项目名：harbor.example.com/nginx:latest
   ✅ 修正：harbor.example.com/library/nginx:latest

2. 端口号错误：harbor.example.com:80/prod/app:v1
   ✅ 修正：harbor.example.com/prod/app:v1（默认443端口）

3. 标签缺失：harbor.example.com/prod/app
   ✅ 修正：harbor.example.com/prod/app:latest

---

四、镜像拉取失败排查指南

1. 错误现象分析

错误提示	可能原因	解决方案
ErrImagePull	凭证错误/镜像不存在	检查Secret和镜像地址
ImagePullBackOff	网络不通/证书问题	验证节点到Harbor连通性
repository does not exist	项目权限不足	检查Harbor项目访问权限
x509: certificate signed by unknown authority	未配置CA证书	部署证书到节点或容器

2. 诊断命令大全

# 查看详细拉取日志
kubectl describe pod <pod-name> | grep Events -A20

# 手动模拟镜像拉取（在节点执行）
docker login harbor.example.com
docker pull harbor.example.com/prod/app:v1

# 检查Secret内容
kubectl get secret harbor-creds -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d

# 网络连通性测试
kubectl run -it --rm debug-tools --image=nicolaka/netshoot -- ping harbor.example.com

---

五、CI/CD集成最佳实践

1. GitLab Runner配置示例

variables:
  HARBOR_URL: harbor.example.com
  HARBOR_PROJECT: ci

stages:
  - build
  - deploy

build_image:
  stage: build
  script:
    - docker login -u $HARBOR_USER -p $HARBOR_PASSWORD $HARBOR_URL
    - docker build -t $HARBOR_URL/$HARBOR_PROJECT/app:$CI_COMMIT_SHA .
    - docker push $HARBOR_URL/$HARBOR_PROJECT/app:$CI_COMMIT_SHA

deploy_k8s:
  stage: deploy
  script:
    - kubectl set image deployment/app app=$HARBOR_URL/$HARBOR_PROJECT/app:$CI_COMMIT_SHA -n prod

2. ArgoCD同步策略

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-deploy
spec:
  source:
    repoURL: git@github.com:myteam/app-manifests.git
    targetRevision: HEAD
    path: prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

---

避坑总结：

1. 生产环境务必使用机器人账户，避免个人账号密码泄露
2. 跨命名空间场景需在每个ns单独创建Secret
3. 镜像地址严格遵循仓库域名/项目名/镜像名:标签格式
4. 定期轮换凭证（建议90天）
5. 使用NetworkPolicy限制只有特定命名空间能访问Harbor服务

通过以上方案，可实现企业级安全规范的镜像拉取流程。记住：安全无小事，完善的权限控制+审计日志才是保障私有镜像仓库安全的终极防线！