从私有仓库拉取镜像

此页面展示了如何创建一个 Pod，该 Pod 使用 Secret 从私有容器镜像仓库中拉取镜像。有许多私有仓库正在使用。本任务以 Docker Hub 作为示例仓库。

🛇 此项链接到不属于 Kubernetes 本身第三方项目或产品。更多信息

准备工作

你需要拥有一个 Kubernetes 集群，并且 kubectl 命令行工具已配置为与你的集群通信。建议你在至少有两个非控制平面主机的节点组成的集群上运行本教程。如果你还没有集群，你可以使用 minikube 创建一个，或者你可以使用这些 Kubernetes 操场中的一个
要完成此练习，你需要 docker 命令行工具，以及你知道密码的 Docker ID。
如果你使用的是其他私有容器镜像仓库，则需要该仓库的命令行工具以及任何登录信息。

登录 Docker Hub

在你的笔记本电脑上，你必须向仓库进行身份验证才能拉取私有镜像。

使用 docker 工具登录 Docker Hub。有关更多信息，请参阅 Docker ID 账户的“登录”部分。

docker login

出现提示时，输入你的 Docker ID，然后输入你要使用的凭据（访问令牌，或你的 Docker ID 密码）。

登录过程会创建或更新一个包含授权令牌的 config.json 文件。请查看 Kubernetes 如何解释此文件。

查看 config.json 文件

cat ~/.docker/config.json

输出包含与此类似的部分

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "c3R...zE2"
        }
    }
}

注意

如果你使用 Docker 凭证存储，你将不会看到 auth 条目，而是看到一个 credsStore 条目，其值为存储的名称。在这种情况下，你可以直接创建 Secret。请参阅通过在命令行提供凭证来创建 Secret。

基于现有凭证创建 Secret

Kubernetes 集群使用 kubernetes.io/dockerconfigjson 类型的 Secret 来向容器仓库进行身份验证，以拉取私有镜像。

如果你已经运行了 docker login，你可以将该凭证复制到 Kubernetes

kubectl create secret generic regcred \
    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    --type=kubernetes.io/dockerconfigjson

如果你需要更多控制（例如，为新的 Secret 设置命名空间或标签），那么你可以在存储 Secret 之前对其进行自定义。请确保

将数据项的名称设置为 .dockerconfigjson
对 Docker 配置文件进行 base64 编码，然后将该字符串作为字段 data[".dockerconfigjson"] 的值粘贴，不得中断
将 type 设置为 kubernetes.io/dockerconfigjson

示例

apiVersion: v1
kind: Secret
metadata:
  name: myregistrykey
  namespace: awesomeapps
data:
  .dockerconfigjson: UmVhbGx5IHJlYWxseSByZWVlZWVlZWVlZWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGxsbGx5eXl5eXl5eXl5eXl5eXl5eXl5eSBsbGxsbGxsbGxsbGxsbG9vb29vb29vb29vb29vb29vb29vb29vb29vb25ubm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg==
type: kubernetes.io/dockerconfigjson

如果你收到错误消息 error: no objects passed to create，则可能意味着 base64 编码的字符串无效。如果你收到类似 Secret "myregistrykey" is invalid: data[.dockerconfigjson]: invalid value ... 的错误消息，则意味着数据中 base64 编码的字符串已成功解码，但无法解析为 .docker/config.json 文件。

通过在命令行提供凭证来创建 Secret

创建此 Secret，命名为 regcred

kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>

其中

<your-registry-server> 是你的私有 Docker 仓库的完全限定域名。对于 DockerHub，请使用 https://index.docker.io/v1/。
<your-name> 是你的 Docker 用户名。
<your-pword> 是你的 Docker 密码。
<your-email> 是你的 Docker 电子邮件。

你已成功将你的 Docker 凭证设置为名为 regcred 的 Secret。

注意

在命令行上输入 Secret 可能会以未受保护的方式将它们存储在你的 shell 历史记录中，并且在 kubectl 运行时，这些 Secret 也可能对你电脑上的其他用户可见。

检查 Secret `regcred`

要了解你创建的 regcred Secret 的内容，首先以 YAML 格式查看 Secret

kubectl get secret regcred --output=yaml

输出类似于：

apiVersion: v1
kind: Secret
metadata:
  ...
  name: regcred
  ...
data:
  .dockerconfigjson: eyJodHRwczovL2luZGV4L ... J0QUl6RTIifX0=
type: kubernetes.io/dockerconfigjson

.dockerconfigjson 字段的值是你的 Docker 凭证的 base64 表示。

要了解 .dockerconfigjson 字段中的内容，请将 Secret 数据转换为可读格式

kubectl get secret regcred --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

输出类似于：

{"auths":{"your.private.registry.example.com":{"username":"janedoe","password":"xxxxxxxxxxx","email":"jdoe@example.com","auth":"c3R...zE2"}}}

要了解 auth 字段中的内容，请将 base64 编码的数据转换为可读格式

echo "c3R...zE2" | base64 --decode

输出是用户名和密码用 : 连接而成，类似于

janedoe:xxxxxxxxxxx

请注意，Secret 数据包含与你本地 ~/.docker/config.json 文件类似的授权令牌。

你已成功将你的 Docker 凭证设置为名为 regcred 的 Secret。

创建使用你的 Secret 的 Pod

这是一个示例 Pod 的清单，它需要访问 regcred 中的 Docker 凭证

pods/private-reg-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: private-reg
spec:
  containers:
  - name: private-reg-container
    image: <your-private-image>
  imagePullSecrets:
  - name: regcred

将上述文件下载到你的电脑上

curl -L -o my-private-reg-pod.yaml https://k8s.io/examples/pods/private-reg-pod.yaml

在文件 my-private-reg-pod.yaml 中，将 <your-private-image> 替换为私有仓库中镜像的路径，例如

your.private.registry.example.com/janedoe/jdoe-private:v1

为了从私有仓库拉取镜像，Kubernetes 需要凭证。配置文件中的 imagePullSecrets 字段指定 Kubernetes 应从名为 regcred 的 Secret 中获取凭证。

创建使用你的 Secret 的 Pod，并验证 Pod 是否正在运行

kubectl apply -f my-private-reg-pod.yaml
kubectl get pod private-reg

注意

要为 Pod（或 Deployment，或其他使用 Pod 模板的对象）使用镜像拉取 Secret，你需要确保相应的 Secret 存在于正确的命名空间中。要使用的命名空间与你定义 Pod 的命名空间相同。

此外，如果 Pod 以 ImagePullBackOff 状态启动失败，请查看 Pod 事件

kubectl describe pod private-reg

如果你看到事件的原因设置为 FailedToRetrieveImagePullSecret，则表示 Kubernetes 找不到名称为 regcred 的 Secret（在此示例中）。

确保你指定的 Secret 存在，并且其名称拼写正确。

Events:
  ...  Reason                           ...  Message
       ------                                -------
  ...  FailedToRetrieveImagePullSecret  ...  Unable to retrieve some image pull secrets (<regcred>); attempting to pull the image may not succeed.

使用来自多个仓库的镜像

一个 Pod 可以有多个容器，每个容器镜像可以来自不同的仓库。你可以为 Pod 使用多个 imagePullSecrets，每个 Secret 可以包含多个凭证。

镜像拉取将尝试使用与仓库匹配的每个凭证。如果没有凭证与仓库匹配，镜像拉取将尝试在没有授权的情况下或使用自定义运行时特定配置进行。

下一步

了解有关 Secrets 的更多信息
- 或者阅读 Secret 的 API 参考
了解有关使用私有仓库的更多信息。
了解有关向服务账户添加镜像拉取 Secret 的更多信息。
请参阅 kubectl create secret docker-registry。
请参阅 Pod 容器定义中的 imagePullSecrets 字段

本页面上的内容涉及第三方产品或项目，它们提供了 Kubernetes 所需的功能。Kubernetes 项目作者对这些第三方产品或项目不承担责任。有关更多详细信息，请参阅 CNCF 网站指南。

在提议添加额外第三方链接的更改之前，你应该阅读内容指南。

最后修改于 2024 年 11 月 20 日太平洋标准时间凌晨 12:22：澄清镜像拉取 Secret 文档 (#48718) (22030b43ef)

从私有仓库拉取镜像

准备工作

登录 Docker Hub

注意

基于现有凭证创建 Secret

通过在命令行提供凭证来创建 Secret

注意

检查 Secret regcred

创建使用你的 Secret 的 Pod

注意

使用来自多个仓库的镜像

下一步

反馈

检查 Secret `regcred`