大网数据广告活动
Kubernetes 部署与运维

从私有仓库拉取镜像

· 52CE 我爱测

本文介绍如何使用 从私有的镜像仓库或代码仓库拉取镜像来创建 Pod。 有很多私有镜像仓库正在使用中。这个任务使用的镜像仓库是 Docker Hub。

本文介绍如何使用 从私有的镜像仓库或代码仓库拉取镜像来创建 Pod。 有很多私有镜像仓库正在使用中。这个任务使用的镜像仓库是 Docker Hub。

  • 要进行此练习,你需要 docker 命令行工具和一个知道密码的 Docker ID。
  • 如果你要使用不同的私有的镜像仓库,你需要有对应镜像仓库的命令行工具和登录信息。

登录 Docker 镜像仓库 {#log-in-to-docker-hub}

在个人电脑上,要想拉取私有镜像必须在镜像仓库上进行身份验证。

使用 docker 命令工具来登录到 Docker Hub。 更多详细信息,请查阅 Docker ID accounts 中的 log in 部分。

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 {#registry-secret-existing-credentials}

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 之前对它进行自定义。 请务必:

  • 将 data 项中的名称设置为 .dockerconfigjson
  • 使用 base64 编码方法对 Docker 配置文件进行编码,然后粘贴该字符串的内容,作为字段 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 {#create-a-secret-by-providing-credentials-on-the-command-line}

创建 Secret,命名为 regcred:

kubectl create secret docker-registry regcred \
  --docker-server=<你的镜像仓库服务器> \
  --docker-username=<你的用户名> \
  --docker-password=<你的密码> \
  --docker-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 {#inspecting-the-secret-regcred}

要了解你创建的 regcred Secret 的内容,可以用 YAML 格式进行查看:

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 {#create-a-pod-that-uses-your-secret}

下面是一个 Pod 配置清单示例,该示例中 Pod 需要访问你的 Docker 凭据 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,并检查它是否正常运行:

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,每个 imagePullSecrets 可以包含多个凭证。

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

来源:Kubernetes 文档贡献者 · 作者与贡献记录 · CC BY 4.0。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
Kubernetes 文档贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。