本文档采用自动化机器翻译技术翻译。 尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。 若出现任何内容不一致情况，请以原始 英文 版本为准，且原始英文版本为权威文本。

私有注册表配置

Containerd 可以配置为连接到私有注册表，并根据 kubelet 的需要使用它们来拉取镜像。

在启动时，K3s 将检查 /etc/rancher/k3s/registries.yaml 是否存在。如果存在，则在生成 containerd 配置时将使用此配置文件中包含的注册表配置。

  • 如果您想将私有注册表用作公共注册表（如 docker.io）的镜像，则需要在每个希望使用该镜像的节点上配置 registries.yaml。

  • 如果您的私有注册表需要身份验证、使用自定义 TLS 证书或不使用 TLS，则需要在每个将从您的注册表拉取镜像的节点上配置 registries.yaml。

请注意，服务器节点默认是可调度的。如果您没有标记服务器节点并且将在其上运行工作负载，请确保在每个服务器上也创建 registries.yaml 配置文件。

默认端点回退

Containerd 对所有注册表都有一个隐式的 "默认端点"。 即使在 registries.yaml 中列出了该注册表的其他端点，默认端点也始终作为最后的手段进行尝试。 重写不会应用于对默认端点的拉取。 例如，当拉取 registry.example.com:5000/rancher/mirrored-pause:3.6 时，containerd 将使用默认端点 https://registry.example.com:5000/v2。

  • docker.io 的默认端点是 https://index.docker.io/v2。

  • 所有其他注册表的默认端点是 https://<REGISTRY>/v2，其中 <REGISTRY> 是注册表主机名和可选端口。

为了被识别为注册表，镜像名称的第一个组件必须包含至少一个句点或冒号。 出于历史原因，名称中未指定注册表的镜像被隐式识别为来自 docker.io。

版本门控

--disable-default-registry-endpoint 选项自 2024 年 1 月发布以来可用：v1.26.13+k3s1，v1.27.10+k3s1，v1.28.6+k3s1，v1.29.1+k3s1

节点可以使用 --disable-default-registry-endpoint 选项启动。 当设置此选项时，containerd 将不会回退到默认的注册表端点，而只会从已配置的镜像端点拉取镜像；如果启用了分布式注册表，也会从中拉取镜像。

如果您的集群处于真正的隔离环境中，上游注册表不可用， 或者如果您希望只有某些节点从上游注册表拉取，这可能是所需的。

禁用默认注册表端点仅适用于通过 registries.yaml 配置的注册表。 如果注册表未通过 registries.yaml 中的镜像条目显式配置，则仍将使用默认回退行为。

注册表配置文件

该文件由两个顶级键组成，每个注册表都有子键：

mirrors:
  <REGISTRY>:
    endpoint:
      - https://<REGISTRY>/v2
configs:
  <REGISTRY>:
    auth:
      username: <BASIC AUTH USERNAME>
      password: <BASIC AUTH PASSWORD>
      token: <BEARER TOKEN>
    tls:
      ca_file: <PATH TO SERVER CA>
      cert_file: <PATH TO CLIENT CERT>
      key_file: <PATH TO CLIENT KEY>
      insecure_skip_verify: <SKIP TLS CERT VERIFICATION BOOLEAN>

镜像

镜像部分定义了注册表的名称和端点，例如：

mirrors:
  registry.example.com:
    endpoint:
      - "https://registry.example.com:5000"

每个镜像必须有一个名称和一组端点。从注册表拉取镜像时，containerd 将尝试这些端点，以及默认端点，并使用第一个可用的端点。

重定向

如果私有注册表用作另一个注册表的镜像，例如在配置 拉取缓存 时，镜像拉取操作会透明地重定向到列出的端点。原始注册表名称通过 ns 查询参数传递给镜像端点。

例如，如果您为 docker.io 配置了一个镜像：

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"

那么拉取 docker.io/rancher/mirrored-pause:3.6 将透明地拉取镜像作为 registry.example.com:5000/rancher/mirrored-pause:3.6。

重写

每个镜像可以有一组重写，这些重写使用正则表达式在从镜像拉取时匹配和转换镜像的名称。 如果私有注册表中的组织/项目结构与其镜像的注册表不同，这很有用。 重写仅匹配和转换镜像名称，而不匹配标签。

例如，以下配置会透明地以 registry.example.com:5000/mirrorproject/rancher-images/mirrored-pause:3.6 的形式拉取镜像 docker.io/rancher/mirrored-pause:3.6：

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
    rewrite:
      "^rancher/(.*)": "mirrorproject/rancher-images/$1"
版本门控

自2024年1月的版本发布以来，重写不再应用于 默认端点：v1.26.13+k3s1，v1.27.10+k3s1，v1.28.6+k3s1，v1.29.1+k3s1。 在这些版本发布之前，重写也适用于默认端点，这会阻止 K3s 从上游注册表拉取，如果图像无法从镜像端点拉取，并且在上游中没有以修改后的名称提供该图像。

如果您希望在直接从注册表拉取时应用重写 - 当它不作为不同上游注册表的镜像使用时 - 您必须提供一个与默认端点不匹配的镜像端点。 在 registries.yaml 中与默认端点匹配的镜像端点将被忽略；如果未禁用回退，默认端点总是最后尝试且不进行重写。

例如，如果您在 https://registry.example.com/ 处有一个注册表，并希望在明确拉取 registry.example.com/rancher/mirrored-pause:3.6 时应用重写，您可以添加一个列出端口的镜像端点。 因为镜像端点与默认端点不匹配 - "https://registry.example.com:443/v2" != "https://registry.example.com/v2" - 所以该端点被接受为镜像并应用重写，尽管它实际上与默认端点相同。

mirrors:
 registry.example.com
   endpoint:
     - "https://registry.example.com:443"
   rewrite:
     "^rancher/(.*)": "mirrorproject/rancher-images/$1"

请注意，在使用镜像和重写时，图像仍将以原始名称存储。 例如，crictl image ls 将显示 docker.io/rancher/mirrored-pause:3.6 在节点上可用，即使图像是从具有不同名称的镜像拉取的。

配置

configs 部分定义了每个镜像的 TLS 和凭证配置。对于每个镜像，您可以定义 auth 和/或 tls。

tls 部分包括：

指令 说明

cert_file

将用于与注册表进行身份验证的客户端证书路径

key_file

将用于与注册表进行身份验证的客户端密钥路径

ca_file

定义用于验证注册表服务器证书文件的 CA 证书路径

insecure_skip_verify

布尔值，定义是否应跳过注册表的 TLS 验证

auth 部分由用户名/密码或身份验证令牌组成：

指令 说明

username

私有注册表基本身份验证的用户名

password

私有注册表基本身份验证的用户密码

auth

私有注册表基本身份验证的身份验证令牌

以下是使用私有注册表的不同模式的基本示例：

通配符支持

版本门控

通配符支持自2024年3月发布的版本开始提供：v1.26.15+k3s1、v1.27.12+k3s1、v1.28.8+k3s1、v1.29.3+k3s1

"*" 通配符条目可以在 mirrors 和 configs 部分中使用，以为所有注册表提供默认配置。 默认配置仅在该注册表没有特定条目时使用。请注意，星号必须用引号括起来。

在以下示例中，将为所有注册表使用本地注册表镜像。对于所有注册表，TLS 验证将被禁用，除了 docker.io。

mirrors:
  "*":
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "docker.io":
  "*":
    tls:
      insecure_skip_verify: true

使用 TLS

以下是使用 TLS 时，您如何在每个节点上配置 /etc/rancher/k3s/registries.yaml 的示例。

  • 使用身份验证

  • 不使用身份验证

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry
mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry

不使用 TLS

以下是当 不 使用 TLS 时，您如何在每个节点上配置 /etc/rancher/k3s/registries.yaml 的示例。

  • 使用身份验证

  • 不使用身份验证

mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"

如果没有 TLS 通信，您需要为端点指定 http://，否则将默认为 https。

为了使注册表更改生效，您需要在每个节点上重新启动 K3s。

故障排除镜像拉取

当 Kubernetes 在拉取镜像时遇到问题时，kubelet 显示的错误可能仅反映对默认端点的拉取尝试返回的终端错误，这使得配置的端点似乎未被使用。

检查节点上 /var/lib/rancher/k3s/agent/containerd/containerd.log 的 containerd 日志，以获取有关故障根本原因的详细信息。请注意，您必须查看调度有该 Pod 的节点上的日志。您可以通过发出 kubectl get pod -o wide -n NAMESPACE POD 并检查 NODE 列来查看您的 Pod 被调度到哪个节点。

将镜像添加到私有注册表

将镜像复制到私有注册表需要一台配备 Docker 或其他能够拉取和推送镜像的第三方工具的主机。
以下步骤假设您有一个带有 dockerd 和 docker CLI 工具的主机，并且可以访问 docker.io 和您的私有注册表。

  1. 从 GitHub 获取您正在使用的版本的 k3s-images.txt 文件。

  2. 从 docker.io 拉取 k3s-images.txt 文件中列出的每个 K3s 镜像。
    示例：docker pull docker.io/rancher/mirrored-pause:3.6

  3. 将镜像重新标记为私有注册表。
    示例：docker tag docker.io/rancher/mirrored-pause:3.6 registry.example.com:5000/rancher/mirrored-pause:3.6

  4. 将镜像推送到私有注册表。
    示例：docker push registry.example.com:5000/rancher/mirrored-pause:3.6