从私有注册表拉取镜像

此页面展示了如何创建一个使用 Secret 从私有容器镜像注册表或存储库中拉取镜像的 Pod。许多私有注册表正在使用中。此任务使用 Docker Hub 作为示例注册表。

🛇 此项链接到第三方项目或产品，这些项目或产品不是 Kubernetes 本身的一部分。更多信息

开始之前

您需要拥有一个 Kubernetes 集群，并且 kubectl 命令行工具必须配置为与您的集群通信。建议在至少有两个节点的集群上运行本教程，这些节点不充当控制平面主机。如果您还没有集群，可以使用 minikube 创建一个，或者可以使用以下 Kubernetes 游乐场之一
- Killercoda
- 使用 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 注册表 FQDN。对于 DockerHub，请使用 https://index.docker.io/v1/。
<your-name> 是您的 Docker 用户名。
<your-pword> 是您的 Docker 密码。
<your-email> 是您的 Docker 电子邮件。

您已成功将 Docker 凭据设置为名为 regcred 的 Secret，位于集群中。

注意

在命令行上键入 Secret 可能会将它们存储在您的 shell 历史记录中，而没有保护，并且这些 Secret 在 kubectl 运行期间也可能对您 PC 上的其他用户可见。

检查 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":"[email protected]","auth":"c3R...zE2"}}}

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

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

输出（用户名和密码用 : 连接）类似于以下内容

janedoe:xxxxxxxxxxx

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

您已成功将 Docker 凭据设置为名为 regcred 的 Secret，位于集群中。

创建一个使用您的 Secret 的 Pod

这是一个示例 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（或部署，或使用您正在使用的 Pod 模板的其他对象）使用镜像拉取 Secret，您需要确保相应的 Secret 存在于正确的命名空间中。要使用的命名空间与您定义 Pod 的命名空间相同。

此外，如果 Pod 无法启动，状态为 ImagePullBackOff，请查看 Pod 事件

kubectl describe pod private-reg

如果您随后看到一个原因设置为 FailedToRetrieveImagePullSecret 的事件，则 Kubernetes 找不到名为（在本例中为 regcred）的 Secret。如果您指定 Pod 需要镜像拉取凭据，则 kubelet 会在尝试拉取镜像之前检查它是否可以访问该 Secret。

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

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

下一步

详细了解 Secret
- 或阅读 Secret 的 API 参考
详细了解使用私有注册表。
详细了解将镜像拉取 Secret 添加到服务帐户。
请参阅 kubectl create secret docker-registry。
请参阅 Pod 的容器定义中的 imagePullSecrets 字段

此页面上的项目引用了提供 Kubernetes 所需功能的第三方产品或项目。Kubernetes 项目作者不对这些第三方产品或项目负责。有关更多详细信息，请参阅 CNCF 网站指南。

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

上次修改时间：2023 年 12 月 24 日下午 9:00 PST：修复错别字 (d536e46dbd)

从私有注册表拉取镜像

开始之前

登录 Docker Hub

注意

基于现有凭据创建 Secret

通过在命令行上提供凭据创建 Secret

注意

检查 Secret regcred

创建一个使用您的 Secret 的 Pod

注意

下一步

反馈

检查 Secret `regcred`