containerd中文翻译系列(九)主机

注册表配置 - 简介

containerd v1.5 为 ctr 客户端（用于管理员/开发人员的 containerd 工具）、containerd 镜像服务客户端和 CRI 客户端如kubectl和 crictl，提供了新的额外注册表主机配置支持。

为这些客户端配置注册表的方法是，在一个配置文件中为每个所需的注册表主机指定（可选）一个 hosts.toml 文件来完成。注意： 该目录下的更新不需要重启 containerd 守护进程。

注册 API 支持

所有已配置的注册表主机都应遵守OCI 分配规范。不符合标准或实施非标准行为的注册表将无法保证支持，并可能在不同版本之间意外中断。

目前支持的 OCI Distribution 版本： v1.0.0

使用 CTR 的主机命名空间配置

通过 ctr 拉取容器映像时，使用 --hosts-dir 选项会告诉 ctr会查找并使用指定路径下的主机配置文件：

ctr images pull --hosts-dir "/etc/containerd/certs.d" myregistry.io:5000/image_name:tag

CRI

用于指定注册表镜像和注册表配置的旧 CRI 配置模式已被删除。你现在应该将注册表 config_path 指向你的 hosts.toml 文件所在的路径。文件所在的路径。

按如下方式修改您的 config.toml（默认位置: /etc/containerd/config.toml）：

version = 2

[plugins."io.containerd.grpc.v1.cri".registry]
   config_path = "/etc/containerd/certs.d"

支持 Docker 的证书文件模式

如果主机目录中不存在 hosts.toml 配置，它就会退回到检查证书文件。这些证书基于Docker 证书文件模式
(CA 证书的.crt 文件和客户端证书的.cert/.key文件）。

注册表主机命名空间

注册表主机是容器镜像和工件的来源位置。 这些注册表主机可以是本地的，也可以是远程的，通常通过 http/https 使用OCI 分发规范进行访问。注册表镜像不是注册表主机，但这些镜像也可用于提取内容。注册表主机通常以其互联网域名（又称注册表主机名。例如，docker.io、 quay.io、ggr.io 和 ghcr.io。

就 containerd 注册表配置而言，注册表主机名称空间就是文件的路径，该路径由注册表主机名或 IP 地址以及可选的端口标识符指定。端口标识符。为镜像提出拉取请求时，格式通常如下:

pull [registry_host_name|IP address][:port][/v2][/org_path][:tag|@DIGEST]

注册表主机名称空间部分为[注册表主机名称|IP 地址][:端口]。示例docker.io的目录树：

$ tree /etc/containerd/certs.d
/etc/containerd/certs.d
└── docker.io
    └── hosts.toml

如果没有其他命名空间匹配，可选择使用 _default注册表主机命名空间作为备用。

上述拉取请求格式中的 /v2 部分指的是分发 api 的版本。如果不包含在拉取请求中，/v2 会默认添加到所有客户端。

如果配置的主机与注册表主机名空间不同（如镜像），那么containerd 会将注册表主机名空间作为名为 ns 的查询参数附加到请求中。

例如，当通过以下端口从名为 myregistry.io 的私有注册表中提取 image_name:tag_name 时
端口 5000：

pull myregistry.io:5000/image_name:tag_name

拉取将解析到 https://myregistry.io:5000/v2/image_name/manifests/tag_name。

同样的拉取，如果主机配置为 mymirror.io，则解析结果为
https://mymirror.io/v2/image_name/manifests/tag_name?ns=myregistry.io:5000`。

指定注册表凭据

CTR

在通过 ctr 执行镜像操作时，使用 --help 选项可获得用于指定凭证的选项列表：

ctr i pull --help
...
OPTIONS:
   --skip-verify, -k                 跳过证书校验
   --plain-http                      允许通过http连接主机
   --user value, -u value            用户[:密码] 注册用户和密码
   --refresh value                   授权服务器的刷新令牌
   --hosts-dir value                 自定义主机配置目录
   --tlscacert value                 TLS根证书路径
   --tlscert value                   TLS客户证书路径
   --tlskey value                    TLS客户私钥路径
   --http-dump                       转储与容器注册表交互时的所有 HTTP 请求/响应
   --http-trace                      启用注册表交互的 HTTP 跟踪功能
   --snapshotter value               快照器名称. 为空代表使用默认值 [$CONTAINERD_SNAPSHOTTER]
   --label value                     附加在镜像上的标签
   --platform value                  拉取特定平台内容
   --all-platforms                   拉取所有平台的内容和元数据
   --all-metadata                    拉取所有平台的元数据
   --print-chainid                   打印生成镜像的链ID
   --max-concurrent-downloads value  设置每一次拉取的并发下载数(默认值: 0)

CRI

虽然我们已经废弃了用于指定注册表镜像和注册表配置的旧 CRI 配置模式，但你仍然可以通过CRI config来指定凭据。

此外，containerd CRI 插件还实现/支持通过 CRI 拉取镜像服务请求传递的身份验证参数。例如，当 containerd 是 "Kubernetes "的容器运行时实现时，containerd CRI 插件会收到来自 kubelet 的身份验证凭据，这些凭据从
Kubernetes镜像拉取秘诀获取。

注册表配置 - 示例

Docker 的简单(默认)主机配置

下面是一个默认注册表主机配置的简单示例。
在 containerd 的 config.toml 中设置 config_path="/etc/containerd/certs.d"。在配置路径下创建一个目录树，其中包括 docker.io 作为作为要配置的主机命名空间的目录。然后在docker.io目录中添加一个hosts.toml文件。文件来配置主机命名空间。文件应该是这样的:

$ tree /etc/containerd/certs.d
/etc/containerd/certs.d
└── docker.io
    └── hosts.toml

$ cat /etc/containerd/certs.d/docker.io/hosts.toml
server = "https://docker.io"

[host."https://registry-1.docker.io"]
  capabilities = ["pull", "resolve"]

为 Docker 设置本地镜像

server = "https://registry-1.docker.io"    # 不包含此项时将不使用上行链路

[host."https://public-mirror.example.com"]
  capabilities = ["pull"]                  # 需要的信任度较低，不会解析来自该主机的摘要标签
[host."https://docker-mirror.internal"]
  capabilities = ["pull", "resolve"]
  ca = "docker-mirror.crt"                 # 或绝对路径 /etc/containerd/certs.d/docker.io/docker-mirror.crt

为所有注册表设置默认镜像

这是一个不考虑预定注册表而使用镜像的示例。
在尝试了所有已定义的主机后，将自动使用上游注册表。

$ tree /etc/containerd/certs.d
/etc/containerd/certs.d
└── _default
    └── hosts.toml

$ cat /etc/containerd/certs.d/_default/hosts.toml
[host."https://registry.example.com"]
  capabilities = ["pull", "resolve"]

如果你想确保只使用镜像而不查询上游，请将镜像设置为 server而不是主机。
如果想先使用其他镜像，仍可指定其他主机。

$ cat /etc/containerd/certs.d/_default/hosts.toml
server = "https://registry.example.com"

绕过 TLS 验证示例

绕过位于 192.168.31.250:5000 的私有注册表的 TLS 验证

在/etc/containerd/certs.d/docker.io/hosts.toml路径下创建路径和 hosts.toml 文本，内容如下或类似：

server = "https://registry-1.docker.io"

[host."http://192.168.31.250:5000"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true

hosts.toml 内容描述 - 详情

对于注册表 config_path 中的每个注册表主机命名空间目录，你都可以在其中包含 hosts.toml 配置文件。
包含一个 hosts.toml 配置文件。以下根级 toml 字段适用于注册表主机名称空间。

注意： 在 hosts.toml 文件中指定的所有路径可以是绝对路径，也可以是相对于 hosts.toml 文件的相对路径。

服务器字段

server指定此注册表主机命名空间的默认服务器。

如果指定了host(s)，将按所列顺序首先尝试这些主机。
如果所有 host(s) 都已尝试，则将使用 server 作为备用。

如果未指定 server，则将自动使用镜像的注册主机名称空间(译者注:如docker.io/library/redis:alpine中的docker.io)。

server = "https://docker.io"

能力字段

capabilities "是一个可选设置，用于指定主机能够执行的操作。
可执行的操作。只包含适用的值。

capabilities =  ["pull", "resolve", "push"]

能力（或主机能力）表示注册表主机的能力。这也代表注册表主机可信任执行的操作集。例如，推送功能只能在上游源上执行，而不能在镜像源上执行。

解析（将名称转换为摘要的过程）必须被视为受信任的操作，只能由受信任的主机（或更理想的安全进程可以证明映射的来源）。

决不能信任公共镜像进行解析操作。

注册表类型	拉	解决(resolve)	推
公共注册表	是	是	是
私有注册表	是	是	是
公共镜像	是	否	否
私有镜像	是	是	否

ca 字段

ca（证书机构认证）可设置为一个路径或路径数组，每个路径指向一个 ca 文件，用于与注册表名称空间进行身份验证。

ca = "/etc/certs/mirror.pem"

或者

ca = ["/etc/certs/test-1-ca.pem", "/etc/certs/special.pem"]

客户端字段

client证书的配置如下:
一个路径:

client = "/etc/certs/client.pem"

一个路径数组:

client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"]

一个路径对数组:

client = [["/etc/certs/client.cert", "/etc/certs/client.key"],["/etc/certs/client.pem", ""]]

skip_verify 字段

设置为 true时，将跳过对注册表证书链和主机名的验证。这只能用于测试或与其他验证连接的方法结合使用。(默认为false）。

skip_verify = false

##header字段（以 toml 表格格式表示）

[header]包含若干个键，其中每个键都是字符串或字符串数组之一，如下所示：

字符串数组如下:

[header]
  x-custom-1 = "custom header"

或者

[header]
  x-custom-1 = ["custom header part a","part b"]

亦或

[header]
  x-custom-1 = "custom header",
  x-custom-1-2 = "another custom header"

override_path 字段

override_path用于表示主机的 API 根端点是在 URL 路径中定义，而不是由 API 规范定义。这可用于缺少 /v2 前缀的不兼容 OCI 注册。
(默认为 false）。

override_path = true

host 字段(toml 表格式)

配置中的 [host]."https://namespace"和 [host]."http://namespace"条目是注册表命名空间，用于替代默认的注册表命名空间。这些主机有时被称为镜像，因为它们可能包含您试图从默认注册表中检索的容器镜像和工件的副本。每个host/mirror 命名空间的配置方式也与命名空间的配置方式与默认注册表命名空间基本相同。
值得注意的是server没有在 host描述中指定，因为它是在命名空间中指定。
下面是几个配置主机镜像命名空间的粗略的例子:

[host."https://mirror.registry"]
  capabilities = ["pull"]
  ca = "/etc/certs/mirror.pem"
  skip_verify = false
  [host."https://mirror.registry".header]
    x-custom-2 = ["value1", "value2"]

[host."https://mirror-bak.registry/us"]
  capabilities = ["pull"]
  skip_verify = true

[host."http://mirror.registry"]
  capabilities = ["pull"]

[host."https://test-1.registry"]
  capabilities = ["pull", "resolve", "push"]
  ca = ["/etc/certs/test-1-ca.pem", "/etc/certs/special.pem"]
  client = [["/etc/certs/client.cert", "/etc/certs/client.key"],["/etc/certs/client.pem", ""]]

[host."https://test-2.registry"]
  client = "/etc/certs/client.pem"

[host."https://test-3.registry"]
  client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"]

[host."https://non-compliant-mirror.registry/v2/upstream"]
  capabilities = ["pull"]
  override_path = true

注意： 在 hosts.toml 文件中指定主机镜像命名空间时不支持递归。因此不允许/不支持以下情况:

[host."http://mirror.registry"]
  capabilities = ["pull"]
  [host."http://double-mirror.registry"]
    capabilities = ["pull"]