在 Kubernetes (K8s) 中，imagePullSecrets 允许 Pod 访问私有镜像仓库，例如 Docker Hub、Harbor、阿里云镜像仓库、腾讯云 TCR 或自建的 registry.flow.cn。以下是完整的 imagePullSecrets 配置步骤：
步骤 1：创建 imagePullSecrets
Kubernetes 通过 docker-registry 类型的 Secret 存储镜像仓库的认证信息。
1.1 运行 kubectl create secret docker-registry
使用以下命令创建 imagePullSecrets，将 <username>、<password> 和 <email> 替换成你的私有仓库登录信息：
kubectl create secret docker-registry regcred \--docker-server=registry.flow.cn \--docker-username=<username> \--docker-password=<password> \--docker-email=<email> \-n <namespace>
regcred是 Secret 的名称（可以自定义）。--docker-server=registry.flow.cn指定私有仓库地址。-n <namespace>指定命名空间（如果省略，则创建在default命名空间）。--docker-username和--docker-password填写镜像仓库的登录凭据。
示例（如果仓库在 kubesphere-system 命名空间）：
kubectl create secret docker-registry regcred \--docker-server=registry.flow.cn \--docker-username=myuser \--docker-password=mypassword \--docker-email=myemail@example.com \-n kubesphere-system
步骤 2：配置 imagePullSecrets 到 Pod/Deployment
创建 imagePullSecrets 之后，需要在 Pod、Deployment、StatefulSet、DaemonSet 等工作负载的 spec 里引用它。
2.1 修改 Deployment
如果 Pod 由 Deployment 管理，执行：
kubectl edit deployment ks-apiserver -n kubesphere-system
在 spec.template.spec 下面添加：
imagePullSecrets:- name: regcred
完整示例：
apiVersion: apps/v1
kind: Deployment
metadata:name: ks-apiservernamespace: kubesphere-system
spec:replicas: 1selector:matchLabels:app: ks-apiservertemplate:metadata:labels:app: ks-apiserverspec:imagePullSecrets:- name: regcredcontainers:- name: ks-apiserverimage: registry.flow.cn/kubesphereio/ks-apiserver:v3.4.1imagePullPolicy: Always
保存后，K8s 会自动重新创建 Pod。
2.2 修改已有 Pod（适用于非 Deployment 方式）
如果 Pod 不是由 Deployment 控制，而是手动创建的 Pod，你需要：
- 删除现有 Pod
kubectl delete pod ks-apiserver-54466b5d66-p8r4m -n kubesphere-system
- 编辑 Pod YAML 文件
kubectl get pod ks-apiserver-54466b5d66-p8r4m -n kubesphere-system -o yaml > pod.yaml
修改 spec：
spec:imagePullSecrets:- name: regcred
然后重新创建：
kubectl apply -f pod.yaml
步骤 3：配置默认 imagePullSecrets（影响整个命名空间）
如果希望命名空间下的所有 Pod 默认使用 imagePullSecrets，可以修改 ServiceAccount。
执行：
kubectl edit serviceaccount default -n kubesphere-system
添加：
imagePullSecrets:
- name: regcred
这样，在 kubesphere-system 命名空间中创建的所有 Pod 默认都会使用 regcred 拉取镜像。
步骤 4：验证 imagePullSecrets 是否生效
查看 Pod 状态：
kubectl get pod -n kubesphere-system
如果 Pod 不再处于 ImagePullBackOff 或 ErrImagePull 状态，说明 imagePullSecrets 配置成功！
还可以检查具体事件：
kubectl describe pod ks-apiserver-54466b5d66-p8r4m -n kubesphere-system
如果 Events 中没有报 Failed to pull image，就说明 imagePullSecrets 已经生效。
总结
| 步骤 | 操作命令 |
|---|---|
创建 imagePullSecrets | kubectl create secret docker-registry regcred --docker-server=registry.flow.cn --docker-username=<username> --docker-password=<password> --docker-email=<email> -n kubesphere-system |
| 修改 Deployment | kubectl edit deployment ks-apiserver -n kubesphere-system，添加 imagePullSecrets |
| 修改已有 Pod | kubectl get pod -o yaml > pod.yaml，然后修改 spec.imagePullSecrets 并 kubectl apply -f pod.yaml |
| 修改默认 ServiceAccount | kubectl edit serviceaccount default -n kubesphere-system |
| 检查 Pod 状态 | kubectl get pod -n kubesphere-system |
| 查看 Pod 事件 | kubectl describe pod ks-apiserver-54466b5d66-p8r4m -n kubesphere-system |
