私有注册表配置

可以将 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 部分定义了注册表的名称和端点，例如

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

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

重定向

如果私有注册表用作另一个注册表的镜像（例如，在配置 拉取通过缓存 时），则镜像拉取将透明地重定向到列出的端点。原始注册表名称通过 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。

重写

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

例如，以下配置将透明地拉取镜像 docker.io/rancher/mirrored-pause:3.6，如同 registry.example.com:5000/mirrorproject/rancher-images/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"
   rewrites:
     "^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 日志，以获取有关故障根本原因的详细信息。

将镜像添加到私有注册表

将镜像镜像到私有注册表需要一台具有 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