5.3. 自定义资源定义 (CRD) 升级安全

重要

Operator Lifecycle Manager (OLM) v1 只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。

有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。

当您更新由集群扩展提供的自定义资源定义(CRD)时，Operator Lifecycle Manager (OLM) v1 运行 CRD 升级安全 preflight 检查，以确保与 CRD 的早期版本向后兼容。在允许更改在集群中进行前，CRD 更新必须通过验证检查。

其他资源

更新集群扩展

5.3.1. 禁止 CRD 升级更改

CRD 升级安全 preflight 检查会发现对现有自定义资源定义 (CRD) 的以下更改，并阻止升级：

将新的必填字段添加到 CRD 的现有版本中
现有字段已从现有 CRD 版本中删除
在 CRD 的现有版本中更改现有字段类型
在之前没有默认值的字段中添加一个新的默认值
字段的默认值被改变
字段的现有默认值被删除
在之前没有 enum 限制的现有字段中添加了新的 enum 限制
现有字段中的现有 enum 值会被删除
现有字段的最小值会在现有版本中增加
在现有版本中现有字段的最大值会减少
在之前没有限制的字段中添加最小或最大字段限制

注意

对最小和最大值的更改规则适用于 minimum, minLength, minProperties, minItems, maximum, maxLength, maxProperties, 和 maxItems 约束。

CRD 升级安全 preflight 检查会报告对现有 CRD 的以下更改，并防止升级，尽管 Kubernetes API 服务器在技术上处理操作：

范围从 Cluster 改为 Namespace 或从 Namespace 改为 Cluster
删除现存已存储的 CRD 的现有版本

如果 CRD 升级安全 preflight 检查遇到禁止的升级更改之一，它会记录 CRD 升级过程中检测到的每个禁止更改的错误。

提示

如果对 CRD 的更改没有属于被禁止更改类别之一，但也无法正确地探测到允许的 CRD 升级安全 preflight 检查，则 CRD 升级安全 preflight 检查将阻止升级并记录"未知更改"的错误。

5.3.2. 允许 CRD 升级更改

对现有自定义资源定义 (CRD) 的以下更改可以安全地向后兼容，且不会导致 CRD 升级安全 preflight 检查停止升级：

在字段中允许枚举值列表中添加新的 enum 值
在现有版本中将现有必填字段更改为 optional
在现有版本中现有字段的最小值会减少
在现有版本中增加现有字段的最大值
在不对现有版本进行任何修改的情况下，会添加 CRD 的新版本

5.3.3. 禁用 CRD 升级安全 preflight 检查

通过在提供 CRD 的 ClusterExtension 对象中为 preflight.crdUpgradeSafety.disabled 字段添加 true 来禁用自定义资源定义 (CRD) 升级安全 preflight 检查。

警告

禁用 CRD 升级安全 preflight 检查可能会破坏与 CRD 存储版本的向后兼容性，并在集群中造成其他意外后果。

您无法禁用单个字段验证器。如果您禁用 CRD 升级安全 preflight 检查，则会禁用所有字段验证器。

注意

以下检查由 Kubernetes API 服务器处理：

范围从 Cluster 改为 Namespace 或从 Namespace 改为 Cluster
删除现存已存储的 CRD 的现有版本

在通过 Operator Lifecycle Manager (OLM) v1 禁用 CRD 升级安全 preflight 检查后，Kubernetes 仍然会阻止这两个操作。

先决条件

已安装集群扩展。

流程

编辑 CRD 的 ClusterExtension 对象：

$ oc edit clusterextension <clusterextension_name>

将 preflight.crdUpgradeSafety.disabled 字段设置为 true ：

例 5.22. ClusterExtension 对象示例

apiVersion: olm.operatorframework.io/v1alpha1
kind: ClusterExtension
metadata:
    name: clusterextension-sample
spec:
    installNamespace: default
    packageName: argocd-operator
    version: 0.6.0
    preflight:
        crdUpgradeSafety:
            disabled: true 1

1: 设置为 true。

5.3.4. 不安全的 CRD 更改示例

以下示例演示了 CRD 升级安全 preflight 检查示例自定义资源定义 (CRD) 中的具体更改。

对于以下示例，请考虑以下开始状态的 CRD 对象：

例 5.23. CRD 对象示例

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.13.0
  name: example.test.example.com
spec:
  group: test.example.com
  names:
    kind: Sample
    listKind: SampleList
    plural: samples
    singular: sample
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        properties:
          apiVersion:
            type: string
          kind:
            type: string
          metadata:
            type: object
          spec:
            type: object
          status:
            type: object
          pollInterval:
            type: string
        type: object
    served: true
    storage: true
    subresources:
      status: {}

5.3.4.1. 范围更改

在以下自定义资源定义 (CRD) 示例中，scope 字段从 Namespaced 改为 Cluster ：

例 5.24. CRD 中的范围更改示例

    spec:
      group: test.example.com
      names:
        kind: Sample
        listKind: SampleList
        plural: samples
        singular: sample
      scope: Cluster
      versions:
      - name: v1alpha1

例 5.25. 错误输出示例

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "NoScopeChange" validation failed: scope changed from "Namespaced" to "Cluster"

5.3.4.2. 删除存储的版本

在以下自定义资源定义 (CRD) 示例中，现有存储版本 v1alpha1 已被删除：

例 5.26. 在 CRD 中删除存储版本示例

      versions:
      - name: v1alpha2
        schema:
          openAPIV3Schema:
            properties:
              apiVersion:
                type: string
              kind:
                type: string
              metadata:
                type: object
              spec:
                type: object
              status:
                type: object
              pollInterval:
                type: string
            type: object

例 5.27. 错误输出示例

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "NoStoredVersionRemoved" validation failed: stored version "v1alpha1" removed

5.3.4.3. 删除现有字段

在以下自定义资源定义 (CRD) 示例中，pollInterval 属性字段已从 v1alpha1 模式中删除：

例 5.28. 在 CRD 中删除现有字段示例

      versions:
      - name: v1alpha1
        schema:
          openAPIV3Schema:
            properties:
              apiVersion:
                type: string
              kind:
                type: string
              metadata:
                type: object
              spec:
                type: object
              status:
                type: object
            type: object

例 5.29. 错误输出示例

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "NoExistingFieldRemoved" validation failed: crd/test.example.com version/v1alpha1 field/^.spec.pollInterval may not be removed

5.3.4.4. 添加必填字段

在以下自定义资源定义 (CRD) 示例中，pollInterval 属性已改为必填字段：

例 5.30. 在 CRD 中添加必填字段的示例

      versions:
      - name: v1alpha2
        schema:
          openAPIV3Schema:
            properties:
              apiVersion:
                type: string
              kind:
                type: string
              metadata:
                type: object
              spec:
                type: object
              status:
                type: object
              pollInterval:
                type: string
            type: object
            required:
            - pollInterval

例 5.31. 错误输出示例

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "ChangeValidator" validation failed: version "v1alpha1", field "^": new required fields added: [pollInterval]