在搭建和维护ref="/tag/2020/" style="color:#E3A3CF;font-weight:bold;">Kubernetes集群时，经常会遇到需要从私有镜像仓库拉取容器镜像的情况。比如公司内部用Harbor搭建了私有仓库，或者你用了某个云厂商的私有镜像服务。这时候直接部署应用会失败，因为kubelet没有权限拉取镜像。解决这个问题的关键就是——pull secret。
什么是Pull Secret
Pull secret其实就是一个包含Docker registry认证信息的Secret资源，Kubernetes用它来完成私有镜像仓库的登录（docker login）操作。你可以把它理解为一个“通行证”，告诉集群：“我有权限下载这个镜像”。
创建Pull Secret的几种方式
最常用的方式是通过kubectl命令直接创建。假设你的镜像仓库是registry.example.com，用户名是devuser，密码是secretpass，邮箱可选，执行下面这行命令：
kubectl create secret docker-registry my-pull-secret \
--docker-server=registry.example.com \
--docker-username=devuser \
--docker-password=secretpass \
--docker-email=dev@example.com这条命令会在当前命名空间生成一个名为my-pull-secret的Secret。如果你希望所有命名空间都能用，就得在每个命名空间里单独创建一份，或者写脚本批量同步。
另一种方式是手动编写YAML文件，适合集成到CI/CD流程中：
apiVersion: v1
kind: Secret
metadata:
name: my-pull-secret
type: kubernetes.io/dockerconfigjson
data:
.dockerconfigjson: ewoiciZzZXJ2ZXIiOiAicmVnaXN0cnkuZXhhbXBsZS5jb20iLAogICJ1c2VybmFtZSI6ICJkZXZ1c2VyIiwKICAicGFzc3dvcmQiOiAic2VjcmV0cGFzcyIsCiAgImVtYWlsIjogImRldkBleGFtcGxlLmNvbSJ9Cg==注意.data部分是.dockerconfigjson的Base64编码内容，原始JSON长这样：
{
"auths": {
"registry.example.com": {
"username": "devuser",
"password": "secretpass",
"email": "dev@example.com",
"auth": "base64encodedstring="
}
}
}如何在Pod中使用Pull Secret
创建好Secret后，下一步是在Pod或Deployment中引用它。最简单的方法是在pod spec里加上imagePullSecrets字段：
apiVersion: v1
kind: Pod
metadata:
name: myapp-pod
spec:
containers:
- name: main-app
image: registry.example.com/myteam/app:v1
imagePullSecrets:
- name: my-pull-secret这样kubelet就知道用哪个凭证去拉镜像了。如果你不想每个Pod都写一遍，可以把这个pull secret设置为默认服务账户的自动挂载项：
kubectl patch serviceaccount default -p '{"imagePullSecrets":[{"name":"my-pull-secret"}]}'之后这个命名空间下的所有Pod，只要没特别指定，都会自动带上这个pull secret，省事不少。
实际使用中的小坑
有时候明明配置了pull secret，但还是拉不到镜像。常见原因有几个：一是Secret名字拼错了；二是创建在别的命名空间，当前Pod访问不到；三是.dockerconfigjson里的server地址写得不准确，比如漏了端口号；四是Base64编码出错，多编或少解了一次。
排查时可以用kubectl describe pod <pod-name>看事件记录，通常会明确提示“Failed to pull image”和“unauthorized”这类错误。再结合kubectl get secret和kubectl describe secret确认内容是否正确。
还有一种情况是多个私有仓库，可以一次性在Secret里配置多个auths条目，kubelet会自动匹配对应的仓库。
用好pull secret，私有镜像部署就顺畅多了。别再让镜像拉取失败卡住上线进度，提前把凭证配好，部署时才能一键到底。