2.2. Operator Framework 打包格式

捆绑包清单指的是一组 Kubernetes 清单，用于定义 Operator 的部署和 RBAC 模型。

捆绑包包括每个目录的一个 CSV，一般情况下，用来定义 CRD 所拥有的 API 的 CRD 位于 /manifest 目录中。

etcd
├── manifests
│   ├── etcdcluster.crd.yaml
│   └── etcdoperator.clusterserviceversion.yaml
│   └── secret.yaml
│   └── configmap.yaml
└── metadata
    └── annotations.yaml
    └── dependencies.yaml

额外支持的对象

以下对象类型也可以包括在捆绑包的 /manifests 目录中：

当捆绑包中包含这些可选对象时，Operator Lifecycle Manager（OLM）可以从捆绑包创建对象，并随 CSV 一起管理其生命周期：

捆绑包还在其 /metadata 文件夹中包含 annotations.yaml 文件。此文件定义了更高级别的聚合数据，以帮助描述有关如何将捆绑包添加到捆绑包索引中的格式和软件包信息：

annotations:
  operators.operatorframework.io.bundle.mediatype.v1: "registry+v1" 1
  operators.operatorframework.io.bundle.manifests.v1: "manifests/" 2
  operators.operatorframework.io.bundle.metadata.v1: "metadata/" 3
  operators.operatorframework.io.bundle.package.v1: "test-operator" 4
  operators.operatorframework.io.bundle.channels.v1: "beta,stable" 5
  operators.operatorframework.io.bundle.channel.default.v1: "stable" 6

Operator 的依赖项列在捆绑包的 metadata/ 目录中的 dependencies.yaml 文件中。此文件是可选的，目前仅用于指明 Operator-version 依赖项。

依赖项列表中，每个项目包含一个 type 字段，用于指定这一依赖项的类型。支持以下 Operator 依赖项：

在以下示例中，为 Prometheus Operator 和 etcd CRD 指定依赖项：

dependencies:
  - type: olm.package
    value:
      packageName: prometheus
      version: ">0.27.0"
  - type: olm.gvk
    value:
      group: etcd.database.coreos.com
      kind: EtcdCluster
      version: v1beta2

opm CLI 工具由 Operator Framework 提供,用于 Operator 捆绑格式。您可以通过此工具从与软件存储库类似的 Operator 捆绑包列表中创建和维护 Operator 目录。其结果是一个容器镜像，它可以存储在容器的 registry 中，然后安装到集群中。

目录包含一个指向 Operator 清单内容的指针数据库，可通过在运行容器镜像时提供的已包含 API 进行查询。在 OpenShift Container Platform 中，Operator Lifecycle Manager (OLM) 可以引用由 CatalogSource 对象定义的目录源中的镜像，它会定期轮询镜像，以对集群上安装的 Operator 进行更新。

基于文件的目录可从基于目录的文件系统进行存储和加载。opm CLI 通过遍历根目录并递归到子目录来加载目录。CLI 尝试加载它找到的每个文件，如果发生错误，则会失败。

可以使用 .indexignore 文件忽略非目录文件，这些文件对模式和优先级与 .gitignore 文件具有相同的规则。

# Ignore everything except non-object .json and .yaml files
**/*
!*.json
!*.yaml
**/objects/*.json
**/objects/*.yaml

目录维护人员具有选择所需的布局的灵活性，但建议将每个软件包基于文件的目录 Blob 存储在单独的子目录中。每个单独的文件可以是 JSON 或 YAML；目录中的每一文件并不需要使用相同的格式。

catalog
├── packageA
│   └── index.yaml
├── packageB
│   ├── .indexignore
│   ├── index.yaml
│   └── objects
│       └── packageB.v0.1.0.clusterserviceversion.yaml
└── packageC
    └── index.json

此推荐结构具有目录层次结构中的每个子目录都是自包含目录的属性，它使得目录组成、发现和导航简单文件系统操作。通过将目录复制到父目录的根目录，目录也可以包含在父目录中。

基于文件的目录使用基于 CUE 语言规范 的格式，该格式可使用任意模式进行扩展。以下 _Meta CUE 模式定义了所有基于文件的目录 Blob 必须遵循的格式：

_Meta: {
  // schema is required and must be a non-empty string
  schema: string & !=""

  // package is optional, but if it's defined, it must be a non-empty string
  package?: string & !=""

  // properties is optional, but if it's defined, it must be a list of 0 or more properties
  properties?: [... #Property]
}

#Property: {
  // type is required
  type: string & !=""

  // value is required, and it must not be null
  value: !=null
}

Operator Lifecycle Manager (OLM) 目录目前使用三种模式（olm.package、olm.channel 和 olm.bundle），它们对应于 OLM 的现有软件包和捆绑包概念。

目录中的每个 Operator 软件包都需要一个 olm.package blob、至少一个 olm.channel blob 以及一个或多个 olm.bundle blob。

#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
  }
}

#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 & !=""
}

#Bundle: {
  schema: "olm.bundle"
  package: string & !=""
  name: string & !=""
  image: string & !=""
  properties: [...#Property]
  relatedImages?: [...#RelatedImage]
}

#Property: {
  // type is required
  type: string & !=""

  // value is required, and it must not be null
  value: !=null
}

#RelatedImage: {
  // image is the image reference
  image: string & !=""

  // name is an optional descriptive name for an image that
  // helps identify its purpose in the context of the bundle
  name?: string & !=""
}

属性是可附加到基于文件的目录方案的任意元数据片段。type 字段是一个有效指定 value 字段语义和语法含义的字符串。该值可以是任意 JSON 或 YAML。

OLM 定义几个属性类型，再次使用保留的 olm.* 前缀。

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

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

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

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

对于基于文件的目录，目录维护人员可以专注于 Operator 策展和兼容性。由于 Operator 作者已为其 Operator 创建了特定于 Operator 的目录，因此目录维护人员可以通过将每个 Operator 目录渲染到目录根目录的子目录来构建其目录。

构建基于文件的目录的方法有很多；以下步骤概述了一个简单的方法：

在维护基于文件的目录时，请考虑以下准则。

有关使用 opm CLI 创建基于文件的目录的说明，请参阅管理自定义目录。

有关管理基于文件的目录的 opm CLI 命令的参考文档，请参阅 CLI 工具。

建议 Operator 作者和目录维护人员使用 CI/CD 工作流自动化其目录维护。目录维护人员可通过构建 GitOps 自动化以完成以下任务来进一步改进：