2.2. Operator Framework 打包格式

olm.package 模式为 Operator 定义软件包级别的元数据。这包括其名称、描述、默认频道和图标。

#Package: {
  schema: "olm.package"

  // Package name
  name: string & !=""

  // A description of the package
  description?: string

  // The package's default channel
  defaultChannel: string & !=""

  // An optional icon
  icon?: {
    base64data: string
    mediatype:  string
  }
}

olm.channel 模式在软件包中定义频道、属于频道成员的捆绑包条目，以及这些捆绑包的升级边缘。

捆绑包可作为条目包含在多个 olm.channel blob 中，但它每个频道只能有一个条目。

它对条目的 replaces 值有效，以引用无法在此目录或其他目录中找到的另一捆绑包名称。但是，所有其他频道变量都必须为 true，比如频道没有多个磁头。

#Channel: {
  schema: "olm.channel"
  package: string & !=""
  name: string & !=""
  entries: [...#ChannelEntry]
}

#ChannelEntry: {
  // name is required. It is the name of an `olm.bundle` that
  // is present in the channel.
  name: string & !=""

  // replaces is optional. It is the name of bundle that is replaced
  // by this entry. It does not have to be present in the entry list.
  replaces?: string & !=""

  // skips is optional. It is a list of bundle names that are skipped by
  // this entry. The skipped bundles do not have to be present in the
  // entry list.
  skips?: [...string & !=""]

  // skipRange is optional. It is the semver range of bundle versions
  // that are skipped by this entry.
  skipRange?: string & !=""
}

olm.package 属性定义软件包名称和版本。这是捆绑包上的必要属性，必须正好有一个这些属性。packageName 字段必须与捆绑包的 first-class package 字段匹配，并且 version 字段必须是有效的语义版本。

#PropertyPackage: {
  type: "olm.package"
  value: {
    packageName: string & !=""
    version: string & !=""
  }
}

olm.gvk 属性定义此捆绑包提供的 Kubernetes API 的 group/version/kind (GVK)。OLM 使用此属性解析捆绑包，作为列出与所需 API 相同的 GVK 的其他捆绑包的依赖项。GVK 必须遵循 Kubernetes GVK 验证。

#PropertyGVK: {
  type: "olm.gvk"
  value: {
    group: string & !=""
    version: string & !=""
    kind: string & !=""
  }
}

olm.package.required 属性定义此捆绑包需要的另一软件包的软件包名称和版本范围。对于捆绑包列表的每个所需软件包属性，OLM 确保集群中为列出的软件包和所需版本范围安装了一个 Operator。versionRange 字段必须是有效的语义版本（模拟）范围。

#PropertyPackageRequired: {
  type: "olm.package.required"
  value: {
    packageName: string & !=""
    versionRange: string & !=""
  }
}

olm.gvk.required 属性定义此捆绑包需要的 Kubernetes API 的 group/version/kind (GVK)。对于捆绑包列表的每个必需的 GVK 属性，OLM 确保集群中安装了提供它的 Operator。GVK 必须遵循 Kubernetes GVK 验证。

#PropertyGVKRequired: {
  type: "olm.gvk.required"
  value: {
    group: string & !=""
    version: string & !=""
    kind: string & !=""
  }
}

Operator Lifecycle Manager (OLM) 的常规建议是捆绑包镜像及其元数据应视为不可变。

如果一个错误的捆绑包被推送到目录，您必须假设至少有一个用户已升级到该捆绑包。基于这种假设，您必须从损坏的捆绑包中发布另一个带有升级边缘的捆绑包，以确保安装了有问题的捆绑包的用户收到升级。如果目录中更新了该捆绑包的内容，OLM 将不会重新安装已安装的捆绑包。

然而，在某些情况下首选更改目录元数据：

目录元数据应存储在源控制中，并被视为事实来源。目录镜像的更新应包括以下步骤：

在 API 服务器接受 Bundle 对象后，捆绑包被视为 RukPak 系统的其余部分的不可变工件。这个行为强制捆绑包代表集群中要 source 的一些唯一静态内容。用户可以放心，特定捆绑包指向特定的清单集合，在没有创建新捆绑包的情况下无法更新。对于由嵌入式 BundleTemplate 对象创建的单机捆绑包和动态捆绑包，此属性为 true。

捆绑包的不可变性由核心 RukPak webhook 强制执行。此 webhook 监视 Bundle 对象事件，并对捆绑包的任何更新，检查现有捆绑包的 spec 字段是否与建议的捆绑包中的 spec 字段相同。如果它们不相等，则 Webhook 将拒绝更新。在捆绑包的生命周期中，其他 Bundle 对象字段（如 metadata 或 status）会更新，它只是被视为不可变的 spec 字段。

应用 Bundle 对象，然后尝试更新其 spec 会失败。例如，以下示例会创建一个捆绑包：

$ oc apply -f -<<EOF
apiVersion: core.rukpak.io/v1alpha1
kind: Bundle
metadata:
  name: combo-tag-ref
spec:
  source:
    type: git
    git:
      ref:
        tag: v0.0.2
      repository: https://github.com/operator-framework/combo
  provisionerClassName: core-rukpak-io-plain
EOF

bundle.core.rukpak.io/combo-tag-ref created

然后，修补捆绑包以指向较新的标签会返回错误：

$ oc patch bundle combo-tag-ref --type='merge' -p '{"spec":{"source":{"git":{"ref":{"tag":"v0.0.3"}}}}}'

Error from server (bundle.spec is immutable): admission webhook "vbundles.core.rukpak.io" denied the request: bundle.spec is immutable

核心 RukPak 准入 Webhook 会拒绝补丁，因为捆绑包的 spec 是不可变的。推荐的修改捆绑包内容的方法是通过创建一个新的 Bundle 对象而不是原位更新。

进一步的不可变注意事项

虽然 Bundle 对象的 spec 字段不可变，但 BundleDeployment 对象仍有可能变为较新的捆绑包内容版本，而无需更改底层 spec 字段。这个非预期的行为可能会在以下情况中出现：

如果发生这种情况，步骤 2 中的新内容会因为第 3 步而解包。捆绑包部署会检测更改，并探测到新版本的内容。

这与 pod 的行为类似，其中一个 pod 的容器镜像使用标签，标签将移到不同的摘要中，然后在将来将现有 pod 重新调度到其他节点上。此时，节点会将新镜像拉取到新摘要中，并在没有用户明确要求的情况下运行不同的镜像。

为了确定底层 Bundle spec 内容没有改变，请在创建捆绑包时使用基于摘要的镜像或 Git 提交引用。

RukPak 中的普通捆绑包是给定目录中静态、任意的 Kubernetes YAML 清单的集合。

当前实施的普通捆绑包格式是 plain+v0 格式。捆绑包格式的名称 (plain+v0) 组合了捆绑包类型 (plain) 和当前模式版本 (v0)。

例如，下面显示了 plain+v0 捆绑包中的文件树。它必须具有一个 manifests/ 目录，其中包含部署应用程序所需的 Kubernetes 资源。

manifests
├── namespace.yaml
├── cluster_role.yaml
├── role.yaml
├── serviceaccount.yaml
├── cluster_role_binding.yaml
├── role_binding.yaml
└── deployment.yaml

静态清单必须位于 manifests/ 目录中，其中至少包含一个资源，以便捆绑包是置备程序可以解包的有效 plain+v0 捆绑包。manifests/ 目录还必须是扁平的；所有清单都必须位于顶层，且无子目录。

registry 捆绑包或 registry+v1 捆绑包包含一组以旧 Operator Lifecycle Manager (OLM) 捆绑包格式组织的静态 Kubernetes YAML 清单。