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

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

重要

Operator Lifecycle Manager (OLM) v1 はテクノロジープレビュー機能です。テクノロジープレビュー機能は、Red Hat 製品のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。

Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。

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

関連情報

5.3.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.3.2. 許可された CRD アップグレード変更

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

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

5.3.3. CRD アップグレードの安全性事前チェックを無効にする

カスタムリソース定義 (CRD) アップグレード安全性事前チェックは、CRD を提供する ClusterExtension オブジェクトに、preflight.crdUpgradeSafety.disabled フィールドを true の値で追加することで無効にできます。

警告

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

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

注記

次のチェックは Kubernetes API サーバーによって処理されます。

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

Operator Lifecycle Manager (OLM) v1 を介して CRD アップグレードの安全性事前チェックを無効にした後も、これら 2 つの操作は Kubernetes によって引き続き防止されます。

前提条件

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

手順

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

    $ oc edit clusterextension <clusterextension_name>

  2. 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 アップグレードの安全性事前チェックで検出される、サンプルカスタムリソース定義 (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]
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

© 2024 Red Hat, Inc.