Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

5.4. カスタムリソース定義 (CRD) アップグレードの安全性

クラスター拡張機能によって提供されるカスタムリソース定義 (CRD) を更新すると、Operator Lifecycle Manager (OLM) v1 は CRD アップグレードの安全性事前チェックを実行し、その CRD の以前のバージョンとの下位互換性を確保します。CRD 更新は、クラスター上で変更が進行する前にその検証に合格する必要があります。

5.4.1. 禁止されている CRD アップグレード変更
リンクのコピー

既存のカスタムリソース定義 (CRD) に対する次の変更は、CRD アップグレードの安全性事前チェックによって検出され、アップグレードが妨げられます。

  • 既存の CRD バージョンに新しい必須フィールドを追加する
  • 既存の CRD バージョンから既存フィールドを削除する
  • 既存の CRD バージョンで既存のフィールドタイプを変更する
  • 以前はデフォルト値がなかったフィールドに新しいデフォルト値を追加する
  • フィールドのデフォルト値を変更する
  • フィールドの既存のデフォルト値を削除する
  • これまで列挙制限がなかった既存フィールドに新しい列挙制限を追加する
  • 既存フィールドから既存の列挙値を削除する
  • 既存バージョンで既存フィールドの最小値を増やす
  • 既存バージョンで既存フィールドの最大値を減らす
  • 以前は制約がなかったフィールドに、最小または最大のフィールド制約を追加する
注記

最小値と最大値の変更に関するルールは、minimum、minLength、minProperties、minItems、maximum、maxLength、maxProperties、および maxItems の制約に適用されます。

既存の CRD に対する次の変更は、CRD アップグレードの安全性事前チェックによって報告され、アップグレードが防止されます。ただし、操作は技術的には Kubernetes API サーバーによって処理されます。

  • スコープを Cluster から Namespace へ、または Namespace から クラスター に変更する
  • 既存の保存された CRD バージョンを削除する

CRD アップグレード安全性事前チェックで禁止されているアップグレード変更のいずれかが検出されると、CRD アップグレードで検出された禁止されている変更ごとにエラーがログに記録されます。

ヒント

CRD への変更が禁止されている変更カテゴリーのいずれにも該当せず、許可されている変更として適切に検出もされない場合、CRD アップグレードの安全性事前チェックによってアップグレードが防止され、"未知の変更" としてエラーがログに記録されます。

5.4.2. 許可された CRD アップグレード変更
リンクのコピー

既存のカスタムリソース定義 (CRD) に対する次の変更は、下位互換性の観点で安全であり、CRD アップグレードの安全性事前チェックによってアップグレードが停止されることはありません。

  • フィールドで許可された列挙値のリストに新しい列挙値を追加する
  • 既存バージョンで既存の必須フィールドをオプションフィールドに変更する
  • 既存バージョンで既存フィールドの最小値を減らす
  • 既存バージョンで既存フィールドの最大値を増やす
  • 既存バージョンを変更せずに新規 CRD バージョンを追加する

5.4.3. CRD アップグレードの安全性プリフライトチェックを無効にする
リンクのコピー

カスタムリソース定義 (CRD) アップグレードの安全性プリフライトチェックを無効にできます。CRD を提供する ClusterExtension オブジェクトで、install.preflight.crdUpgradeSafety.enforcement フィールドに None の値を設定します。

警告

CRD アップグレードの安全性事前チェックを無効にすると、保存されている CRD バージョンとの下位互換性が失われ、クラスターでその他の予期しない結果が発生する可能性があります。

個々のフィールド検証を無効にすることはできません。CRD アップグレードの安全性事前チェックを無効にすると、すべてのフィールド検証が無効になります。

注記

Operator Lifecycle Manager (OLM) v1 で CRD アップグレード安全性プリフライトチェックを無効にしても、Kubernetes API サーバーは引き続き次の操作を防止します。

  • スコープを Cluster から Namespace に、または Namespace から Cluster に変更する
  • 保存された既存の CRD バージョンを削除する

前提条件

  • クラスター拡張機能がインストールされている。

手順

  1. CRD の ClusterExtension オブジェクトを編集します。 

    $ oc edit clusterextension <clusterextension_name>

  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

5.4.4. 安全でない CRD 変更の例
リンクのコピー

次の例は、CRD アップグレードの安全性事前チェックで検出される、サンプルカスタムリソース定義 (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: {}

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

例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"

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

例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

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

例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

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

例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]
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hatトップに戻る