第 3 章 ClusterCatalog [olm.operatorframework.io/v1]

availabilityMode

string

availabilityMode 允许用户定义如何将 ClusterCatalog 提供给集群中的客户端。AvailabilityMode 是可选的。

允许的值是 "Available" 和 "Unavailable" 并省略。

如果省略时，默认值为 "Available"。

当设置为 "Available" 时，目录内容将被解包并通过目录内容 HTTP 服务器提供。将 availabilityMode 设置为 "Available" 会告知客户端应将此 ClusterCatalog 及其内容视为可用。

当设置为 "Unavailable" 时，目录内容将不再通过目录内容 HTTP 服务器提供。当设置为这个 availabilityMode 时，它应该被解释与 ClusterCatalog not existing 相同。当用户不想删除所有 ClusterCatalog 时，将 availabilityMode 设置为 "Unavailable" 会很有用，但仍希望将其视为不存在。

priority

整数

优先级允许用户为 ClusterCatalog. 优先级定义优先级是可选的。

ClusterCatalog 的优先级供客户端用作满足客户端要求的 ClusterCatalogs 间的 tie-breaker。数值越高，优先级越高。

客户最多可以决定如何处理多个具有相同优先级的 ClusterCatalogs 满足其要求的情况。当决定如何在这种情况中中断绑定时，建议客户端提示用户输入。

省略时，默认优先级为 0，因为这是整数的零值。

负数可用于指定低于默认值的优先级。正数可用于指定高于默认值的优先级。

最低可能的值是 -2147483648。最高的可能值为 2147483647。

source

object

Source 允许用户定义目录的来源。"目录"包含有关可在集群中安装的内容的信息。提供目录源可让目录发现和使用其他集群组件。这些集群组件可能会执行此信息的各种操作，如在 GUI 仪表板中显示内容，或者从集群中的目录安装内容。目录源必须包含基于文件的目录(FBC)格式的目录元数据。有关 FBC 的更多信息，请参阅 https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs。源是一个必填字段。

以下是从镜像提供目录的 ClusterCatalogSpec 的最小示例：

source: type: Image image: ref: quay.io/operatorhubio/catalog:latest

image

object

镜像用于配置如何从 OCI 镜像提供目录内容。当类型为 Image 时，需要此字段，否则禁止此字段。

type

string

type 是对目录的来源类型的引用。需要键入目录。

唯一允许的值是 "Image"。

当设置为 "Image" 时，ClusterCatalog 内容将从 OCI 镜像提供。在使用镜像源时，必须设置 image 字段，且必须是为此类型定义的唯一字段。

pollIntervalMinutes

整数

pollIntervalMinutes 允许用户设置间隔，以分钟为单位，镜像源应针对新内容轮询。pollIntervalMinutes 是可选的。当 ref 是基于摘要的参考时，无法指定 pollIntervalMinutes。

如果省略时，不会为新内容轮询镜像。

ref

string

ref 允许用户定义包含目录内容的容器镜像的引用。需要 ref。ref 不能超过 1000 个字符。

引用可以分为 3 个部分 - 域、名称和标识符。

域通常是镜像所在的 registry。它必须是由 "." 字符分开的字母数字字符（小写和大写）。允许使用 Hyphenation，但域必须以字母数字字符开头和结尾。也可以通过添加 ":" 字符后跟数字值来指定要使用的端口。port 必须是域中的最后一个值。一些有效域值示例为 "registry.mydomain.io", "quay.io", "my-registry.io:8080"。

该名称通常是镜像所在的 registry 中的存储库。它必须包含由 ".", "_", "\_", "-" 字符分隔的小写字母数字字符。多个名称可以与 "/" 字符连接。域和名称使用"/"字符合并。一些有效名称值示例为 "operatorhubio/catalog", "catalog", "my-catalog.prod"。组合引用的 domain 和 name 部分的示例为 "quay.io/operatorhubio/catalog"。

标识符通常是镜像引用的标签或摘要，并在引用结束时存在。它以分隔符字符开头，用于区分名称的末尾和标识符的开头。对于基于摘要的参考，"@"字符是分隔符。对于基于标签的参考，":" 字符是分隔符。引用中需要一个标识符。

基于摘要的引用必须包含在 "@" 分隔符后的算法引用。算法引用必须后跟 ":" 字符和编码的字符串。该算法必须以大写或小写字符开头，后跟字母数字字符，并且可以包含"-"、"_"、"+"和"+"字符。一些有效算法值示例为 "sha256", "sha256+b64u", "multihash+base58"。算法后编码的字符串必须是十六进制数字(a-f、A-F、0-9)，且必须至少为 32 个字符。

基于标签的参考必须以单词字符（字母数字 + "\_"）开头，后跟单词字符或"-"字符。该标签不能超过 127 个字符。

有效的基于摘要的镜像引用的示例为 "quay.io/operatorhubio/catalog@sha256:200d4ddb2a73594b91358fe6397424e975205bfbe44614f5846033cad64b3f05" 的示例是 "quay.io/operatorhubio/catalog:latest"

conditions

数组

条件是此 ClusterCatalog 的当前状态表示。

当前条件类型是 Serving 和 Progressing。

Serving 条件用于表示目录的内容是否通过 HTTP (S) Web 服务器提供。当它的状态为 True 且值为 Available 的原因时，目录的内容会被提供。当它的状态为 False 且原因为 Unavailable 时，目录的内容将不会被提供，因为内容还不可用。当它的状态为 False 且是 UserSpecifiedUnavailable 的原因时，目录的内容不会被提供，因为目录被有意标记为不可用。

Progressing 条件用于表示 ClusterCatalog 正在进行，还是准备好进入新状态。当状态为 True 且 Retrying 原因时，ClusterCatalog 的进度会出现错误，这些错误可以在后续协调尝试中解决。当它的状态为 True 且是 Succeeded 的原因时，ClusterCatalog 已成功进入了新的状态，准备继续进行。当它的状态为 False 和 Blocked 的原因时，ClusterCatalog 的进度会出现错误，这需要手动干预以进行恢复。

如果 Serving 条件为 True，原因为 Available 和 Progressing is True，原因为 True，则之前获取的目录内容仍然通过 HTTP (S) web 服务器提供，同时我们继续提供目录内容的新版本。当我们最初从此目录的来源获取最新内容时，并在轮询更改确定内容更新时会出现这种情况。

conditions[]

object

condition 包含此 API 资源当前状态的一个方面的详细信息。

lastUnpacked

string

lastUnpacked 代表从其源格式中提取目录内容最后一次的时间。例如，在使用镜像源时，将拉取 OCI 镜像，并将镜像层写入文件系统支持的缓存中。我们把这个源格式提取的行动称为"unpacking"。

resolvedSource

object

resolvedSource 包含有关基于源类型的解析源的信息。

urls

object

URL 包含可用于访问目录的 URL。

lastTransitionTime

字符串

lastTransitionTime 是条件从一个状态转换到另一个状态最后一次的时间。这应该是底层条件变化的时间。如果为未知，则使用 API 字段更改的时间是可以接受的。

message

字符串

Message 是人类可读的消息，指示有关转换的详细信息。这可能是一个空字符串。

observedGeneration

整数

observedGeneration 代表 .metadata.generation，这是条件设置所基于的条件。例如，如果 .metadata.generation 目前为 12，但 .status.conditions[x].observedGeneration 是 9，则代表条件与实例的当前状态已不匹配。

reason

字符串

reason 包含程序标识符，指示条件最后一次转换的原因。特定条件类型的制作者可能会定义预期的值和此字段的含义，以及这些值是否被视为有保证的 API。该值应该是 CamelCase 字符串。此字段可能不是空的。

status

字符串

条件的状态，True, False, Unknown 之一。

type

字符串

CamelCase 或 foo.example.com/CamelCase 中的条件类型。

image

object

image 是包含从镜像提供目录源的目录源的解析信息的字段。当类型为 Image 时，必须设置此字段，否则禁止。

type

string

type 是对目录的来源类型的引用。需要键入目录。

唯一允许的值是 "Image"。

当设置为 "Image" 时，会在 'image' 字段中设置解析的镜像源的信息。

ref

string

ref 包含基于解析的镜像摘要的引用。使用摘要格式，以便用户可以使用其他工具获取用于提取目录内容的确切 OCI 清单。

base

string

Base 是一个集群内部 URL，提供用于访问目录内容的端点。

客户端预期附加他们想要访问的端点的路径。

目前，只有一个端点，可在路径 /api/v1 上访问。

为 v1 API 提供的端点有： - /all - 此端点返回 FBC 格式的目录内容的整个内容

随着用户和客户端发展的需求，可能会添加新的端点。