Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

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

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

5.4.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.4.2. 允许 CRD 升级更改
复制链接

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

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

5.4.3. 禁用 CRD 升级安全 preflight 检查
复制链接

您可以禁用自定义资源定义(CRD)升级安全 preflight 检查。在提供 CRD 的 ClusterExtension 对象中，将 install.preflight.crdUpgradeSafety.enforcement 字段设置为 None。

警告

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

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

注意

如果您在 Operator Lifecycle Manager (OLM) v1 中禁用 CRD 升级安全 preflight 检查，Kubernetes API 服务器仍然会阻止以下操作：

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

先决条件

  • 已安装集群扩展。

流程

  1. 编辑 CRD 的 ClusterExtension 对象： 

    $ oc edit clusterextension <clusterextension_name>
    Copy to Clipboard Toggle word wrap

  2. 将 install.preflight.crdUpgradeSafety.enforcement 字段设置为 None ：

    ClusterExtension 对象示例

    apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: clusterextension-sample
spec:
  namespace: default
  serviceAccount:
    name: sa-example
  source:
    sourceType: "Catalog"
    catalog:
      packageName: argocd-operator
      version: 0.6.0
  install:
    preflight:
      crdUpgradeSafety:
        enforcement: None
    Copy to Clipboard Toggle word wrap

5.4.4. 不安全的 CRD 更改示例
复制链接

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

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

例 5.19. 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: {}
Copy to Clipboard Toggle word wrap

5.4.4.1. 范围更改
复制链接

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

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

    spec:
      group: test.example.com
      names:
        kind: Sample
        listKind: SampleList
        plural: samples
        singular: sample
      scope: Cluster
      versions:
      - name: v1alpha1
Copy to Clipboard Toggle word wrap

例 5.21. 错误输出示例

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"
Copy to Clipboard Toggle word wrap

5.4.4.2. 删除存储的版本
复制链接

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

例 5.22. 在 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
Copy to Clipboard Toggle word wrap

例 5.23. 错误输出示例

validating upgrade for CRD "test.example.com" failed: CustomResourceDefinition test.example.com failed upgrade safety validation. "NoStoredVersionRemoved" validation failed: stored version "v1alpha1" removed
Copy to Clipboard Toggle word wrap

5.4.4.3. 删除现有字段
复制链接

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

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

      versions:
      - name: v1alpha1
        schema:
          openAPIV3Schema:
            properties:
              apiVersion:
                type: string
              kind:
                type: string
              metadata:
                type: object
              spec:
                type: object
              status:
                type: object
            type: object
Copy to Clipboard Toggle word wrap

例 5.25. 错误输出示例

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
Copy to Clipboard Toggle word wrap

5.4.4.4. 添加必填字段
复制链接

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

例 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
            required:
            - pollInterval
Copy to Clipboard Toggle word wrap

例 5.27. 错误输出示例

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]
Copy to Clipboard Toggle word wrap
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat