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

5.7. クラスターサービスバージョン (CSV) の定義

クラスターサービスバージョン (CSV) は、ClusterServiceVersion オブジェクトで定義され、Operator Lifecycle Manager (OLM) によるクラスターでの Operator の実行をサポートする Operator メタデータから作成される YAML マニフェストです。これは、ユーザーインターフェイスにロゴ、説明、およびバージョンなどの情報を設定するために使用される Operator コンテナーイメージに伴うメタデータです。CSV は、Operator が必要とする RBAC ルールやそれが管理したり、依存したりするカスタムリソース (CR) などの Operator の実行に必要な技術情報の情報源でもあります。

Operator SDK には、YAML マニフェストおよび Operator ソースファイルに含まれる情報を使用してカスタマイズされた現行 Operator プロジェクトの CSV を生成するための CSV ジェネレーターが含まれます。

重要

Operator プロジェクトの関連スキャフォールディングおよびテストツールなど、Red Hat がサポートするバージョンの Operator SDK CLI ツールは非推奨となり、OpenShift Container Platform の今後のリリースで削除される予定です。Red Hat は、現在のリリースライフサイクル中にこの機能のバグ修正とサポートを提供しますが、この機能は今後、機能拡張の提供はなく、OpenShift Container Platform リリースから削除されます。

新しい Operator プロジェクトを作成する場合、Red Hat がサポートするバージョンの Operator SDK は推奨されません。既存の Operator プロジェクトを使用する Operator 作成者は、OpenShift Container Platform 4.16 でリリースされるバージョンの Operator SDK CLI ツールを使用してプロジェクトを維持し、OpenShift Container Platform の新しいバージョンを対象とする Operator リリースを作成できます。

Operator プロジェクトの次の関連ベースイメージは 非推奨 ではありません。これらのベースイメージのランタイム機能と設定 API は、バグ修正と CVE への対応のために引き続きサポートされます。

  • Ansible ベースの Operator プロジェクトのベースイメージ
  • Helm ベースの Operator プロジェクトのベースイメージ

OpenShift Container Platform で非推奨となったか、削除された主な機能の最新の一覧は、OpenShift Container Platform リリースノートの 非推奨および削除された機能 セクションを参照してください。

サポートされていない、コミュニティーによって管理されているバージョンの Operator SDK は、Operator SDK (Operator Framework) を参照してください。

CSV で生成されるコマンドにより、Operator の作成者が OLM を詳しく知らなくても、Operator は OLM と対話したり、メタデータをカタログレジストリーに公開したりできます。また、Kubernetes および OLM の新機能が実装される過程で CSV 仕様が変更される可能性が高いため、Operator SDK はその後の新規 CSV 機能を処理できるように更新システムを容易に拡張できるようになっています。

5.7.1. CSV 生成の仕組み

クラスターサービスバージョン (CSV) を含む Operator バンドルマニフェストは、Operator Lifecycle Manager (OLM) でアプリケーションを表示、作成、および管理する方法を説明します。generate bundle サブコマンドによって呼び出される Operator SDK の CSV ジェネレーターは、Operator をカタログに公開し、これを OLM でデプロイする最初の手順になります。サブコマンドには、CSV マニフェストを作成するための特定の入力マニフェストが必要です。すべての入力は、コマンドが CSV ベースと共に呼び出される際に読み取られ、べき等性で CSV を生成したり、再生成したりします。

通常は、generate kustomize manifests サブコマンドが最初に実行され、generate bundle サブコマンドで使用される入力された Kustomize ベースを生成します。ただし、Operator SDK は make bundle コマンドを提供します。これは、以下のサブコマンドを順番に実行するなどの複数のタスクを自動化します。

  1. generate kustomize manifests
  2. generate bundle
  3. bundle validate

関連情報

5.7.1.1. 生成されるファイルおよびリソース

make bundle コマンドは、以下のファイルおよびディレクトリーを Operator プロジェクトに作成します。

  • ClusterServiceVersion (CSV) オブジェクトを含む bundle/manifests という名前のバンドルマニフェストディレクトリー
  • bundle/metadata という名前のバンドルメタデータディレクトリー
  • config/crd ディレクトリー内のすべてのカスタムリソース定義 (CRD)
  • Dockerfile bundle.Dockerfile

通常、以下のリソースは CSV に含まれます。

Role
namespace 内で Operator パーミッションを定義します。
ClusterRole
クラスター全体の Operator パーミッションを定義します。
デプロイメント
Operator のオペランドが Pod で実行される方法を定義します。
CustomResourceDefinition (CRD)
Operator が調整するカスタムリソースを定義します。
カスタムリソースの例
特定の CRD の仕様に従ったリソースの例。

5.7.1.2. バージョンの管理

generate bundle サブコマンドの --version フラグは、バンドルの初回作成時および既存バンドルのアップグレード時に、バンドルのセマンティックバージョンを提供します。

Makefile に VERSION 変数を設定することで、--version フラグは、generate bundle サブコマンドが make bundle コマンドによって実行される際に、値を使用して自動的に呼び出されます。CSV バージョンは Operator のバージョンと同じであり、新規 CSV は Operator バージョンのアップグレード時に生成されます。

5.7.2. 手動で定義される CSV フィールド

多くの CSV フィールドは、生成された、Operator SDK に特化していない汎用マニフェストを使用して設定することはできません。これらのフィールドは、ほとんどの場合、Operator および各種のカスタムリソース定義 (CRD) に関する人間が作成するメタデータです。

Operator 作成者はそれらのクラスターサービスバージョン (CSV) YAML ファイルを直接変更する必要があり、パーソナライズ設定されたデータを以下の必須フィールドに追加します。Operator SDK は、必須フィールドのいずれかにデータが欠落していることが検出されると、CSV 生成時に警告を送信します。

以下の表は、手動で定義された CSV フィールドのうち、必須フィールドとオプションフィールドを詳細に示しています。

表5.7 必須の CSV フィールド
フィールド説明

metadata.name

CSV の固有名。Operator バージョンは、app-operator.v0.1.1 などのように一意性を確保するために名前に含める必要があります。

metadata.capabilities

Operator の成熟度モデルに応じた機能レベル。オプションには、Basic Install、Seamless Upgrades、Full Lifecycle、Deep Insights、および Auto Pilot が含まれます。

spec.displayName

Operator を識別するためのパブリック名。

spec.description

Operator の機能に関する簡単な説明。

spec.keywords

Operator を記述するキーワード。

spec.maintainers

name および email を持つ、Operator を維持する人または組織上のエンティティー

spec.provider

name を持つ、Operator のプロバイダー (通常は組織)。

spec.labels

Operator 内部で使用されるキー/値のペア。

spec.version

Operator のセマンティクスバージョン。 例: 0.1.1。

spec.customresourcedefinitions

Operator が使用する任意の CRD。このフィールドは、CRD YAML ファイルが deploy/ にある場合に Operator SDK によって自動的に設定されます。ただし、CRD マニフェスト仕様にない複数のフィールドでは、ユーザーの入力が必要です。

  • description: description of the CRD.
  • resources: CRD によって利用される任意の Kubernetes リソース (例: Pod および StatefulSet オブジェクト)。
  • specDescriptors: Operator の入力および出力に関する UI ヒント。
表5.8 オプションの CSV フィールド
フィールド説明

spec.replaces

この CSV によって置き換えられる CSV の名前。

spec.links

それぞれが name および url を持つ、Operator および管理されているアプリケーションに関する URL (例: Web サイトおよびドキュメント)。

spec.selector

Operator がクラスターでのリソースのペアの作成に使用するセレクター。

spec.icon

mediatype で base64data フィールドに設定される、Operator に固有の base64 でエンコーディングされるアイコン。

spec.maturity

このバージョンでソフトウェアが達成した成熟度。オプションに、planning、pre-alpha、alpha、beta、stable、mature、inactive、および deprecated が含まれます。

上記の各フィールドが保持するデータの詳細は、CSV spec を参照してください。

注記

現時点で、ユーザーの介入を必要とするいくつかの YAML フィールドは、Operator コードから解析される可能性があります。

関連情報

5.7.3. Operator メタデータアノテーション

Operator 開発者は、クラスターサービスバージョン (CSV) のメタデータに特定のアノテーションを設定して、OperatorHub や Red Hat Ecosystem Catalog などのユーザーインターフェイス (UI) の機能を有効にしたり、機能を強調したりできます。Operator のメタデータのアノテーションは、CSV YAML ファイルの metadata.annotations フィールドを設定して手動で定義します。

5.7.3.1. インフラストラクチャー機能のアノテーション

features.operators.openshift.io グループのアノテーションは、Operator がサポートするインフラストラクチャー機能の詳細を表すものです。この機能は、"true" または "false" 値を設定することで指定されます。ユーザーは、Web コンソールや Red Hat Ecosystem Catalog の OperatorHub から Operator を探すときに、これらの機能を使用して表示やフィルタリングを行うことができます。これらのアノテーションは、OpenShift Container Platform 4.10 以降でサポートされています。

重要

features.operators.openshift.io のインフラストラクチャー機能のアノテーションにより、OpenShift Container Platform の以前のバージョンで使用されていた operators.openshift.io/infrastructure-features アノテーションが非推奨となりました。詳細は、「非推奨のインフラストラクチャー機能のアノテーション」を参照してください。

表5.9 インフラストラクチャー機能のアノテーション
アノテーション説明有効な値 [1]

features.operators.openshift.io/disconnected

Operator はすべての依存関係を含む非接続カタログにミラーリングされるため、インターネットへのアクセスは必要ないかどうかを指定します。Operator は、spec.relatedImages CSV フィールドを活用して、ダイジェストによって関連するイメージを参照します。

"true" または "false"

features.operators.openshift.io/fips-compliant

Operator が基盤となるプラットフォームの FIPS-140 設定を受け入れ、FIPS モードで起動したノードで動作するかどうかを指定します。このモードでは、Operator とそれが管理するすべてのワークロード (オペランド) は、FIPS-140 検証用に提出された Red Hat Enterprise Linux (RHEL) 暗号化ライブラリーのみを呼び出します。

"true" または "false"

features.operators.openshift.io/proxy-aware

標準の HTTP_PROXY および HTTPS_PROXY プロキシー環境変数を受け入れて、プロキシーの背後にあるクラスターでの実行を Operator がサポートするかどうかを指定します。該当する場合、Operator はこの情報を管理対象のワークロード (オペランド) に渡します。

"true" または "false"

features.operators.openshift.io/tls-profiles

Operator が使用する TLS 暗号スイート、および該当する場合は管理対象のワークロード (オペランド) を変更するための既知の設定項目を Operator が実装するかどうかを指定します。

"true" または "false"

features.operators.openshift.io/token-auth-aws

Cloud Credential Operator (CCO) を使用して、AWS Secure Token Service (STS) を介した AWS API によるトークン化認証の設定を Operator がサポートするかどうかを指定します。

"true" または "false"

features.operators.openshift.io/token-auth-azure

Cloud Credential Operator (CCO) を使用して、Azure マネージド ID を介した Azure API によるトークン化認証の設定を Operator がサポートするかどうかを指定します。

"true" または "false"

features.operators.openshift.io/token-auth-gcp

Cloud Credential Operator (CCO) を使用して、GCP Workload Identity Foundation (WIF) を介した Google Cloud API によるトークン化認証の設定を Operator がサポートするかどうかを指定します。

"true" または "false"

features.operators.openshift.io/cnf

Cloud-Native Network Function (CNF) Kubernetes プラグインを Operator が提供するかどうかを指定します。

"true" または "false"

features.operators.openshift.io/cni

Container Network Interface (CNI) Kubernetes プラグインを Operator が提供するかどうかを指定します。

"true" または "false"

features.operators.openshift.io/csi

Container Storage Interface (CSI) Kubernetes プラグインを Operator が提供するかどうかを指定します。

"true" または "false"

  1. Kubernetes アノテーションは文字列でなければならないため、有効な値は意図的に二重引用符で囲んで表示されています。

インフラストラクチャー機能のアノテーションを含む CSV の例

apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  annotations:
    features.operators.openshift.io/disconnected: "true"
    features.operators.openshift.io/fips-compliant: "false"
    features.operators.openshift.io/proxy-aware: "false"
    features.operators.openshift.io/tls-profiles: "false"
    features.operators.openshift.io/token-auth-aws: "false"
    features.operators.openshift.io/token-auth-azure: "false"
    features.operators.openshift.io/token-auth-gcp: "false"

関連情報

5.7.3.2. 非推奨のインフラストラクチャー機能のアノテーション

OpenShift Container Platform 4.14 以降、operators.openshift.io/infrastructure-features のアノテーションのグループが、features.operators.openshift.io namespace のアノテーションのグループによって非推奨となりました。新しいアノテーションを使用することを推奨しますが、現在は両方のグループを並行して使用できます。

これらのアノテーションは、Operator がサポートするインフラストラクチャー機能の詳細を表すものです。ユーザーは、Web コンソールや Red Hat Ecosystem Catalog の OperatorHub から Operator を探すときに、これらの機能を使用して表示やフィルタリングを行うことができます。

表5.10 非推奨の operators.openshift.io/infrastructure-features アノテーション
有効なアノテーション値説明

disconnected

Operator はすべての依存関係を含む非接続カタログにミラーリングされるため、インターネットへのアクセスは必要ありません。ミラーリングに必要なすべての関連イメージが Operator によって一覧表示されます。

cnf

Operator は Cloud-native Network Functions (CNF) Kubernetes プラグインを提供します。

cni

Operator は Container Network Interface (CNI) Kubernetes プラグインを提供します。

csi

Operator は Container Storage Interface (CSI) Kubernetes プラグインを提供します。

fips

Operator は基盤となるプラットフォームの FIPS モードを受け入れ、FIPS モードで起動したノードで動作します。

重要

FIPS モードでブートされた Red Hat Enterprise Linux (RHEL) または Red Hat Enterprise Linux CoreOS (RHCOS) を実行する場合、OpenShift Container Platform コアコンポーネントは、x86_64、ppc64le、および s390x アーキテクチャーのみで、FIPS 140-2/140-3 検証のために NIST に提出された RHEL 暗号化ライブラリーを使用します。

proxy-aware

Operator はプロキシーの背後のクラスターでの実行をサポートします。Operator は、クラスターがプロキシーを使用するように設定される際に Operator Lifecycle Manager (OLM) が Operator に自動的に提供する標準のプロキシー環境変数の HTTP_PROXY および HTTPS_PROXY を受け入れます。必要な環境変数は、管理されているワークロード用にオペランドに渡されます。

disconnected および proxy-aware サポートを含む CSV の例

apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  annotations:
    operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'

5.7.3.3. その他の任意のアノテーション

次の Operator のアノテーションは任意です。

表5.11 その他の任意のアノテーション
アノテーション説明

alm-examples

カスタムリソース定義 (CRD) テンプレートに最低限の設定セットを指定します。互換性のある UI は、ユーザーがさらにカスタマイズできるようにこのテンプレートの事前入力を行います。

operatorframework.io/initialization-resource

Operator のインストール中に、クラスターサービスバージョン (CSV) に operatorframework.io/initialization-resource アノテーションを追加することで、必要なカスタムリソースを 1 つ指定します。ユーザーは、CSV で提供されるテンプレートを使用してカスタムリソースを作成するように求められます。完全な YAML 定義が含まれるテンプレートを含める必要があります。

operatorframework.io/suggested-namespace

Operator をデプロイする必要のある推奨 namespace を設定します。

operatorframework.io/suggested-namespace-template

指定された Namespace のデフォルトのノードセレクターを使用して、namespace オブジェクトのマニフェストを設定します。

operators.openshift.io/valid-subscription

Operator を使用するために必要とされる特定のサブスクリプションをリスト表示するための自由形式の配列です。例: '["3Scale Commercial License", "Red Hat Managed Integration"]'

operators.operatorframework.io/internal-objects

ユーザーの操作を目的としていない UI の CRD を非表示にします。

OpenShift Container Platform ライセンス要件を含む CSV の例

apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  annotations:
    operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'

3scale ライセンス要件を含む CSV の例

apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  annotations:
    operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]'

関連情報

5.7.4. ネットワークが制限された環境に関する Operator の有効化

Operator の作成者は、Operator がネットワークが制限された環境、または非接続の環境で適切に実行されるよう追加要件を満たすことを確認する必要があります。

非接続モードをサポートするための Operator の要件

  • ハードコードされたイメージ参照は、環境変数に置き換えます。

  • Operator のクラスターサービスバージョン (CSV) で以下を行います。

    • Operator がそれらの機能を実行するために必要となる可能性のある 関連イメージ または他のコンテナーをリスト表示します。
    • 指定されたすべてのイメージを、タグではなくダイジェスト (SHA) で参照します。
  • Operator のすべての依存関係は、非接続モードでの実行もサポートする必要があります。
  • Operator にはクラスター外のリソースは必要ありません。

前提条件

  • CSV を含む Operator プロジェクト次の手順では、Go ベース、Ansible ベース、および Helm ベースのプロジェクトの例として Memcached Operator を使用します。

手順

  1. config/manager/manager.yamlファイルで、Operator が使用する追加のイメージ参照の環境変数を設定します。

    例5.11 config/manager/manager.yaml ファイル例

    ...
spec:
  ...
    spec:
      ...
      containers:
      - command:
        - /manager
        ...
        env:
        - name: <related_image_environment_variable> 1
          value: "<related_image_reference_with_tag>" 2
    1
    RELATED_IMAGE_MEMCACHEDなどの環境変数を定義します。
    2
    docker.io/memcached:1.4.36-alpineなどの関連するイメージ参照とタグを設定します。

  2. ハードコードされたイメージ参照は、Operator プロジェクトタイプに関連するファイルの環境変数に置き換えます。

    • Go ベースの Operator プロジェクトの場合には、次の例に示すように、環境変数を controllers/memcached_controller.go ファイルに追加します。

      例5.12 controllers/memcached_controller.go ファイルの例

        // deploymentForMemcached returns a memcached Deployment object

...

	Spec: corev1.PodSpec{
        	Containers: []corev1.Container{{
-			Image:   "memcached:1.4.36-alpine", 1
+			Image:   os.Getenv("<related_image_environment_variable>"), 2
			Name:    "memcached",
			Command: []string{"memcached", "-m=64", "-o", "modern", "-v"},
			Ports: []corev1.ContainerPort{{

...
      1
      イメージ参照とタグを削除します。
      2
      os.Getenv関数を使用して、<related_image_environment_variable>を呼び出します。
      注記

      変数が設定されていない場合、os.Getenv関数は空の文字列を返します。ファイルを変更する前に、<related_image_environment_variable>を設定してください。

    • Ansible ベースの Operator プロジェクトの場合には、次の例に示すように、環境変数をroles/memcached/tasks/main.ymlファイルに追加します。

      例5.13 roles/memcached/tasks/main.ymlファイルの例

      spec:
  containers:
  - name: memcached
    command:
    - memcached
    - -m=64
    - -o
    - modern
    - -v
-   image: "docker.io/memcached:1.4.36-alpine" 1
+   image: "{{ lookup('env', '<related_image_environment_variable>') }}" 2
    ports:
      - containerPort: 11211

...
      1
      イメージ参照とタグを削除します。
      2
      lookup 関数を使用して、<related_image_environment_variable>を呼び出します。

    • Helm ベースの Operator プロジェクトの場合、以下の例のように overrideValues フィールドを watches.yaml ファイルに追加します。

      例5.14 watches.yaml ファイルの例

      ...
- group: demo.example.com
  version: v1alpha1
  kind: Memcached
  chart: helm-charts/memcached
  overrideValues: 1
    relatedImage: ${<related_image_environment_variable>} 2
      1
      overrideValues フィールドを追加します。
      2
      <related_image_environment_variable> を使用して overrideValues フィールドを定義します (例: RELATED_IMAGE_MEMCACHED)。

      1. 以下の例のように、overrideValues フィールドの値を helm-charts/memchached/values.yaml ファイルに追加します。

        helm-charts/memchached/values.yaml ファイルの例

        ...
relatedImage: ""

      2. 以下の例のように、helm-charts/memcached/templates/deployment.yaml ファイルのチャートテンプレートを編集します。

        例5.15 helm-charts/memcached/templates/deployment.yaml ファイルの例

        containers:
  - name: {{ .Chart.Name }}
    securityContext:
      - toYaml {{ .Values.securityContext | nindent 12 }}
    image: "{{ .Values.image.pullPolicy }}
    env: 1
      - name: related_image 2
        value: "{{ .Values.relatedImage }}" 3
        1
        env フィールドを追加します。
        2
        環境変数に名前を付けます。
        3
        環境変数の値を定義します。

  3. 次の変更を加えて、BUNDLE_GEN_FLAGS変数定義をMakefileに追加します。

    Makefile の例

       BUNDLE_GEN_FLAGS ?= -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS)

   # USE_IMAGE_DIGESTS defines if images are resolved via tags or digests
   # You can enable this value if you would like to use SHA Based Digests
   # To enable set flag to true
   USE_IMAGE_DIGESTS ?= false
   ifeq ($(USE_IMAGE_DIGESTS), true)
         BUNDLE_GEN_FLAGS += --use-image-digests
   endif

...

-  $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle -q --overwrite --version $(VERSION) $(BUNDLE_METADATA_OPTS) 1
+  $(KUSTOMIZE) build config/manifests | operator-sdk generate bundle $(BUNDLE_GEN_FLAGS) 2

...

    1
    Makefileでこの行を削除します。
    2
    上記の行は、この行に置き換えます。

  4. タグではなくダイジェスト (SHA) を使用するように Operator イメージを更新するには、make bundleコマンドを実行し、USE_IMAGE_DIGESTSをtrueに設定します。 

    $ make bundle USE_IMAGE_DIGESTS=true

  5. disconnected アノテーションを追加します。これは、Operator が非接続環境で機能することを示します。 

    metadata:
  annotations:
    operators.openshift.io/infrastructure-features: '["disconnected"]'

    Operator は、このインフラストラクチャー機能によって OperatorHub でフィルターされます。

5.7.5. 複数のアーキテクチャーおよびオペレーティングシステム用の Operator の有効化

Operator Lifecycle Manager (OLM) では、すべての Operator が Linux ホストで実行されることを前提としています。ただし、Operator の作成者は、ワーカーノードが OpenShift Container Platform クラスターで利用可能な場合に、Operator が他のアーキテクチャーでのワークロードの管理をサポートするかどうかを指定できます。

Operator が AMD64 および Linux 以外のバリアントをサポートする場合、サポートされるバリアントをリスト表示するために Operator を提供するクラスターサービスバージョン (CSV) にラベルを追加できます。サポートされているアーキテクチャーとオペレーティングシステムを示すラベルは、以下で定義されます。 

labels:
    operatorframework.io/arch.<arch>: supported 1
    operatorframework.io/os.<os>: supported 2
1
<arch> をサポートされる文字列に設定します。
2
<os> をサポートされる文字列に設定します。
注記

デフォルトチャネルのチャネルヘッドにあるラベルのみが、パッケージマニフェストをラベルでフィルターする場合に考慮されます。たとえば、デフォルト以外のチャネルで Operator の追加アーキテクチャーを提供することは可能ですが、そのアーキテクチャーは PackageManifest API でのフィルターには使用できません。

CSV に os ラベルが含まれていない場合、これはデフォルトで以下の Linux サポートラベルが設定されているかのように処理されます。 

labels:
    operatorframework.io/os.linux: supported

CSV に arch ラベルが含まれていない場合、これはデフォルトで以下の AMD64 サポートラベルが設定されているかのように処理されます。 

labels:
    operatorframework.io/arch.amd64: supported

Operator が複数のノードアーキテクチャーまたはオペレーティングシステムをサポートする場合、複数のラベルを追加することもできます。

前提条件

  • CSV を含む Operator プロジェクト
  • 複数のアーキテクチャーおよびオペレーティングシステムのリスト表示をサポートするには、CSV で参照される Operator イメージはマニフェストリストイメージである必要があります。
  • Operator がネットワークが制限された環境または非接続環境で適切に機能できるようにするには、参照されるイメージは、タグではなくダイジェスト (SHA) を使用して指定される必要もあります。

手順

  • Operator がサポートするサポートされるアーキテクチャーおよびオペレーティングシステムのそれぞれについて CSV の metadata.labels にラベルを追加します。 

    labels:
  operatorframework.io/arch.s390x: supported
  operatorframework.io/os.zos: supported
  operatorframework.io/os.linux: supported 1
  operatorframework.io/arch.amd64: supported 2
    1 2
    新規のアーキテクチャーまたはオペレーティングシステムを追加したら、デフォルトの os.linux および arch.amd64 バリアントも明示的に組み込む必要があります。

関連情報

5.7.5.1. Operator のアーキテクチャーおよびオペレーティングシステムのサポート

以下の文字列は、複数のアーキテクチャーおよびオペレーティングシステムをサポートする Operator のラベル付けまたはフィルター時に OpenShift Container Platform の Operator Lifecycle Manager (OLM) でサポートされます。

表5.12 OpenShift Container Platform でサポートされるアーキテクチャー
アーキテクチャー文字列

AMD64

amd64

ARM64

arm64

IBM Power®

ppc64le

IBM Z®

s390x

表5.13 OpenShift Container Platform でサポートされるオペレーティングシステム
オペレーティングシステム文字列

Linux

linux

z/OS

zos

注記

OpenShift Container Platform およびその他の Kubernetes ベースのディストリビューションの異なるバージョンは、アーキテクチャーおよびオペレーティングシステムの異なるセットをサポートする可能性があります。

5.7.6. 推奨される namespace の設定

Operator が正しく機能するには、一部の Operator を特定の namespace にデプロイするか、特定の namespace で補助リソースと共にデプロイする必要があります。サブスクリプションから解決されている場合、Operator Lifecycle Manager (OLM) は Operator の namespace を使用したリソースをそのサブスクリプションの namespace にデフォルト設定します。

Operator の作成者は、必要なターゲット namespace をクラスターサービスバージョン (CSV) の一部として表現し、それらの Operator にインストールされるリソースの最終的な namespace の制御を維持できます。OperatorHub を使用して Operator をクラスターに追加する場合、Web コンソールはインストールプロセス時にクラスター管理者に提案される namespace を自動設定します。

手順

  • CSV で、operatorframework.io/suggested-namespace アノテーションを提案される namespace に設定します。 

    metadata:
  annotations:
    operatorframework.io/suggested-namespace: <namespace> 1
    1
    提案された namespace を設定します。

5.7.7. デフォルトのノードセレクターを使用して推奨される namespace を設定する

一部の Operator は、コントロールプレーンノードでのみ実行することを想定しています。これは、Operator 自体が Pod 仕様で nodeSelector を設定することによって実行できます。

クラスター全体のデフォルト nodeSelector が重複して競合する可能性を回避するために、Operator が実行される namespace にデフォルトのノードセレクターを設定できます。デフォルトのノードセレクターはクラスターのデフォルトよりも優先されるため、クラスターのデフォルトは Operator の namespace 内の Pod には適用されません。

OperatorHub を使用して Operator をクラスターに追加する場合、Web コンソールはインストールプロセス時にクラスター管理者に提案される namespace を自動設定します。推奨される namespace は、クラスターサービスバージョン (CSV) に含まれる YAML の namespace マニフェストを使用して作成されます。

手順

  • CSV で、namespace オブジェクトのマニフェストを使用して operatorframework.io/suggested-namespace-template を設定します。次のサンプルは、namespace のデフォルトのノードセレクターが指定された Namespace の例のマニフェストです。 

    metadata:
  annotations:
    operatorframework.io/suggested-namespace-template: 1
      {
        "apiVersion": "v1",
        "kind": "Namespace",
        "metadata": {
          "name": "vertical-pod-autoscaler-suggested-template",
          "annotations": {
            "openshift.io/node-selector": ""
          }
        }
      }
    1
    提案された namespace を設定します。
    注記

    suggested-namespace および suggested-namespace-template アノテーションの両方が CSV にある場合、suggested-namespace-template が優先されます。

5.7.8. Operator 条件の有効化

Operator Lifecycle Manager (OLM) は、Operator を管理する一方で OLM の動作に影響を与える複雑な状態を通信するためのチャネルを Operator に提供します。デフォルトで、OLM は Operator のインストール時に OperatorCondition カスタムリソース定義 (CRD) を作成します。OperatorCondition カスタムリソース (CR) に設定される条件に基づいて、OLM の動作は随時変わります。

Operator 条件をサポートするには、Operator は OLM によって作成された OperatorCondition CR を読み取ることができ、次のタスクを完了することができる必要があります。

  • 特定の条件を取得します。
  • 特定の条件のステータスを設定します。

これは、operator-lib ライブラリーを使用して実行できます。Operator の作成者は、ライブラリーがクラスター内の Operator が所有する OperatorCondition CR にアクセスできるように Operator に controller-runtime クライアント を指定できます。

ライブラリーは汎用的な Conditions インターフェイスを提供します。これには、OperatorCondition CR で conditionType の Get および Set を実行するための以下のメソッドがあります。

Get
特定の条件を取得するために、ライブラリーは controller-runtime の client.Get 機能を使用します。これには、conditionAccessor にあるタイプが types.NamespacedName の ObjectKey が必要です。
Set
特定の条件のステータスを更新するために、ライブラリーは controller-runtime の client.Update 機能を使用します。conditionType が CRD にない場合、エラーが生じます。

Operator は CR の status サブリソースのみを変更することができます。Operator は status.conditions 配列を削除したり、条件を追加できるようにこれを更新したりすることができます。条件にあるフィールドの形式および説明の詳細は、アップストリームの Condition GoDocs を参照してください。

注記

Operator SDK 1.36.1 は、operator-lib v0.11.0 をサポートしています。

前提条件

  • Operator プロジェクトが Operator SDK を使用して生成されている。

手順

Operator プロジェクトで Operator 条件を有効にするには、以下を実行します。

  1. Operator プロジェクトの go.mod ファイルで、operator-framework/operator-lib を必要なライブラリーとして追加します。 

    module github.com/example-inc/memcached-operator

go 1.19

require (
  k8s.io/apimachinery v0.26.0
  k8s.io/client-go v0.26.0
  sigs.k8s.io/controller-runtime v0.14.1
  operator-framework/operator-lib v0.11.0
)

  2. Operator ロジックに独自のコンストラクターを作成すると、次の結果が得られます。

    • controller-runtime クライアントを許可します。
    • conditionType を受け入れます。
    • 条件を更新または追加する Condition インターフェイスを返します。

    現時点で OLM は Upgradeable 状態をサポートするため、Upgradeable 条件にアクセスするためのメソッドを持つインターフェイスを作成できます。以下に例を示します。 

    import (
  ...
  apiv1 "github.com/operator-framework/api/pkg/operators/v1"
)

func NewUpgradeable(cl client.Client) (Condition, error) {
  return NewCondition(cl, "apiv1.OperatorUpgradeable")
}

cond, err := NewUpgradeable(cl);

    この例では、NewUpgradeable コンストラクターが、タイプ Condition の変数 cond を使用するためにさらに使用されます。cond 変数には、OLM の Upgradeable 条件を処理するために使用できる Get および Set メソッドが含まれます。

関連情報

5.7.9. Webhook の定義

Webhook により、リソースがオブジェクトストアに保存され、Operator コントローラーによって処理される前に、Operator の作成者はリソースのインターセプト、変更、許可、および拒否を実行することができます。Operator Lifecycle Manager (OLM) は、Operator と共に提供される際にこれらの Webhook のライフサイクルを管理できます。

Operator のクラスターサービスバージョン (CSV) リソースには、以下のタイプの Webhook を定義するために webhookdefinitions セクションを含めることができます。

  • 受付 Webhook (検証および変更用)
  • 変換 Webhook

手順

  • webhookdefinitions セクションを Operator の CSV の spec セクションに追加し、type として ValidatingAdmissionWebhook、MutatingAdmissionWebhook、または ConversionWebhook を使用して Webhook 定義を追加します。以下の例には、3 つのタイプの Webhook がすべて含まれます。

    Webhook が含まれる CSV

      apiVersion: operators.coreos.com/v1alpha1
  kind: ClusterServiceVersion
  metadata:
    name: webhook-operator.v0.0.1
  spec:
    customresourcedefinitions:
      owned:
      - kind: WebhookTest
        name: webhooktests.webhook.operators.coreos.io 1
        version: v1
    install:
      spec:
        deployments:
        - name: webhook-operator-webhook
          ...
          ...
          ...
      strategy: deployment
    installModes:
    - supported: false
      type: OwnNamespace
    - supported: false
      type: SingleNamespace
    - supported: false
      type: MultiNamespace
    - supported: true
      type: AllNamespaces
    webhookdefinitions:
    - type: ValidatingAdmissionWebhook 2
      admissionReviewVersions:
      - v1beta1
      - v1
      containerPort: 443
      targetPort: 4343
      deploymentName: webhook-operator-webhook
      failurePolicy: Fail
      generateName: vwebhooktest.kb.io
      rules:
      - apiGroups:
        - webhook.operators.coreos.io
        apiVersions:
        - v1
        operations:
        - CREATE
        - UPDATE
        resources:
        - webhooktests
      sideEffects: None
      webhookPath: /validate-webhook-operators-coreos-io-v1-webhooktest
    - type: MutatingAdmissionWebhook 3
      admissionReviewVersions:
      - v1beta1
      - v1
      containerPort: 443
      targetPort: 4343
      deploymentName: webhook-operator-webhook
      failurePolicy: Fail
      generateName: mwebhooktest.kb.io
      rules:
      - apiGroups:
        - webhook.operators.coreos.io
        apiVersions:
        - v1
        operations:
        - CREATE
        - UPDATE
        resources:
        - webhooktests
      sideEffects: None
      webhookPath: /mutate-webhook-operators-coreos-io-v1-webhooktest
    - type: ConversionWebhook 4
      admissionReviewVersions:
      - v1beta1
      - v1
      containerPort: 443
      targetPort: 4343
      deploymentName: webhook-operator-webhook
      generateName: cwebhooktest.kb.io
      sideEffects: None
      webhookPath: /convert
      conversionCRDs:
      - webhooktests.webhook.operators.coreos.io 5
...

    1
    変換 Webhook がターゲットとする CRD がここに存在している必要があります。
    2
    検証用の受付 Webhook。
    3
    変更用の受付 Webhook。
    4
    変換 Webhook。
    5
    各 CRD の spec.PreserveUnknownFields プロパティーは false または nil に設定される必要があります。

関連情報

5.7.9.1. OLM に関する Webhook の考慮事項

Operator Lifecycle Manager (OLM) を使用して Webhook で Operator をデプロイする場合、以下を定義する必要があります。

  • type フィールドは ValidatingAdmissionWebhook、MutatingAdmissionWebhook、または ConversionWebhook のいずれかに設定する必要があります。そうでないと、CSV は失敗フェーズに置かれます。
  • CSV には、webhookdefinition の deploymentName フィールドに指定される値に等しい名前のデプロイメントが含まれる必要があります。

Webhook が作成されると、OLM は、Operator がデプロイされる Operator グループに一致する namespace でのみ Webhook が機能するようにします。

認証局に関する制約

OLM は、各デプロイメントに単一の認証局 (CA) を提供するように設定されます。CA を生成してデプロイメントにマウントするロジックは、元々 API サービスのライフサイクルロジックで使用されていました。結果は、以下のようになります。

  • TLS 証明書ファイルは、/apiserver.local.config/certificates/apiserver.crt にあるデプロイメントにマウントされます。
  • TLS キーファイルは、/apiserver.local.config/certificates/apiserver.key にあるデプロイメントにマウントされます。
受付 Webhook ルールに関する制約

Operator がクラスターをリカバリー不可能な状態に設定しないようにするため、OLM は受付 Webhook に定義されたルールが以下の要求のいずれかをインターセプトする場合に、失敗フェーズに CSV を配置します。

  • すべてのグループをターゲットとする要求
  • operators.coreos.com グループをターゲットとする要求
  • ValidatingWebhookConfigurations または MutatingWebhookConfigurations リソースをターゲットとする要求
変換 Webhook の制約

OLM は、変換 Webhook 定義が以下の制約に準拠しない場合に、失敗フェーズに CSV を配置します。

  • 変換 Webhook と特長とする CSV は、AllNamespaces インストールモードのみをサポートできます。
  • 変換 Webhook がターゲットとする CRD では、spec.preserveUnknownFields フィールドを false または nil に設定する必要があります。
  • CSV で定義される変換 Webhook は所有 CRD をターゲットにする必要があります。
  • 特定の CRD には、クラスター全体で 1 つの変換 Webhook のみを使用できます。

5.7.10. カスタムリソース定義 (CRD) について

Operator が使用できる以下の 2 つのタイプのカスタムリソース定義 (CRD) があります。1 つ目は Operator が所有する 所有 タイプと、もう 1 つは Operator が依存する 必須 タイプです。

5.7.10.1. 所有 CRD (Owned CRD)

Operator が所有するカスタムリソース定義 (CRD) は CSV の最も重要な部分です。これは Operator と必要な RBAC ルール間のリンク、依存関係の管理、および他の Kubernetes の概念を設定します。

Operator は通常、複数の CRD を使用して複数の概念を結び付けます (あるオブジェクトの最上位のデータベース設定と別のオブジェクトのレプリカセットの表現など)。それぞれは CSV ファイルにリスト表示される必要があります。

表5.14 所有 CRD フィールド
フィールド説明必須/オプション

Name

CRD のフルネーム。

必須

Version

オブジェクト API のバージョン。

必須

Kind

CRD の機械可読名。

必須

DisplayName

CRD 名の人間が判読できるバージョン (例: MongoDB Standalone)。

必須

説明

Operator がこの CRD を使用する方法に関する短い説明、または CRD が提供する機能の説明。

必須

Group

この CRD が所属する API グループ (例: database.example.com)。

オプション

Resources

CRD が 1 つ以上の Kubernetes オブジェクトのタイプを所有する。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法をユーザーに知らせるために resources セクションにリスト表示されます。

この場合、オーケストレーションするすべてのリストではなく、重要なオブジェクトのみをリスト表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する設定マップをリスト表示しないでください。

オプション

SpecDescriptors、StatusDescriptors、および ActionDescriptors

これらの記述子は、エンドユーザーにとって最も重要な Operator の入力および出力で UI にヒントを提供する手段になります。CRD にユーザーが指定する必要のあるシークレットまたは設定マップの名前が含まれる場合は、それをここに指定できます。これらのアイテムはリンクされ、互換性のある UI で強調表示されます。

記述子には、3 つの種類があります。

  • SpecDescriptors: オブジェクトの spec ブロックのフィールドへの参照。
  • StatusDescriptors: オブジェクトの status ブロックのフィールドへの参照。
  • ActionDescriptors: オブジェクトで実行できるアクションへの参照。

すべての記述子は以下のフィールドを受け入れます。

  • DisplayName: Spec、Status、または Action の人間が判読できる名前。
  • Description: Spec、Status、または Action、およびそれが Operator によって使用される方法に関する短い説明。
  • Path: この記述子が記述するオブジェクトのフィールドのドットで区切られたパス。
  • X-Descriptors: この記述子が持つ "機能" および使用する UI コンポーネントを判別するために使用されます。OpenShift Container Platform の正規の React UI X-Descriptor のリスト は、openshift/console プロジェクトを参照してください。

記述子 一般の詳細は、openshift/console プロジェクトも参照してください。

オプション

以下の例は、シークレットおよび設定マップでユーザー入力を必要とし、サービス、ステートフルセット、Pod および設定マップのオーケストレーションを行う MongoDB Standalone CRD を示しています。

所有 CRD の例

      - displayName: MongoDB Standalone
        group: mongodb.com
        kind: MongoDbStandalone
        name: mongodbstandalones.mongodb.com
        resources:
          - kind: Service
            name: ''
            version: v1
          - kind: StatefulSet
            name: ''
            version: v1beta2
          - kind: Pod
            name: ''
            version: v1
          - kind: ConfigMap
            name: ''
            version: v1
        specDescriptors:
          - description: Credentials for Ops Manager or Cloud Manager.
            displayName: Credentials
            path: credentials
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:selector:core:v1:Secret'
          - description: Project this deployment belongs to.
            displayName: Project
            path: project
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:selector:core:v1:ConfigMap'
          - description: MongoDB version to be installed.
            displayName: Version
            path: version
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:label'
        statusDescriptors:
          - description: The status of each of the pods for the MongoDB cluster.
            displayName: Pod Status
            path: pods
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:podStatuses'
        version: v1
        description: >-
          MongoDB Deployment consisting of only one host. No replication of
          data.

5.7.10.2. 必須 CRD (Required CRD)

他の必須 CRD の使用は完全にオプションであり、これらは個別 Operator のスコープを縮小し、エンドツーエンドのユースケースに対応するために複数の Operator を一度に作成するために使用できます。

一例として、Operator がアプリケーションをセットアップし、分散ロックに使用する (etcd Operator からの) etcd クラスター、およびデータストレージ用に (Postgres Operator からの) Postgres データベースをインストールする場合があります。

Operator Lifecycle Manager (OLM) は、これらの要件を満たすためにクラスター内の利用可能な CRD および Operator に対してチェックを行います。適切なバージョンが見つかると、Operator は必要な namespace 内で起動し、サービスアカウントが各 Operator が必要な Kubernetes リソースを作成し、監視し、変更できるようにするために作成されます。

表5.15 必須 CRD フィールド
フィールド説明必須/オプション

Name

必要な CRD のフルネーム。

必須

Version

オブジェクト API のバージョン。

必須

Kind

Kubernetes オブジェクトの種類。

必須

DisplayName

CRD の人間による可読可能なバージョン。

必須

説明

大規模なアーキテクチャーにおけるコンポーネントの位置付けに関するサマリー。

必須

必須 CRD の例

    required:
    - name: etcdclusters.etcd.database.coreos.com
      version: v1beta2
      kind: EtcdCluster
      displayName: etcd Cluster
      description: Represents a cluster of etcd nodes.

5.7.10.3. CRD のアップグレード

OLM は、単一のクラスターサービスバージョン (CSV) によって所有されている場合にはカスタムリソース定義 (CRD) をすぐにアップグレードします。CRD が複数の CSV によって所有されている場合、CRD は、以下の後方互換性の条件のすべてを満たす場合にアップグレードされます。

  • 現行 CRD の既存の有効にされたバージョンすべてが新規 CRD に存在する。
  • 検証が新規 CRD の検証スキーマに対して行われる場合、CRD の提供バージョンに関連付けられる既存インスタンスまたはカスタムリソースすべてが有効である。
5.7.10.3.1. 新規 CRD バージョンの追加

手順

CRD の新規バージョンを Operator に追加するには、以下を実行します。

  1. CSV の versions セクションに CRD リソースの新規エントリーを追加します。

    たとえば、現在の CRD にバージョン v1alpha1 があり、新規バージョン v1beta1 を追加し、これを新規のストレージバージョンとしてマークをする場合に、v1beta1 の新規エントリーを追加します。 

    versions:
  - name: v1alpha1
    served: true
    storage: false
  - name: v1beta1 1
    served: true
    storage: true
    1
    新規エントリー。

  2. CSV が新規バージョンを使用する場合、CSV の owned セクションの CRD の参照バージョンが更新されていることを確認します。 

    customresourcedefinitions:
  owned:
  - name: cluster.example.com
    version: v1beta1 1
    kind: cluster
    displayName: Cluster
    1
    version を更新します。
  3. 更新された CRD および CSV をバンドルにプッシュします。
5.7.10.3.2. CRD バージョンの非推奨または削除

Operator Lifecycle Manager (OLM) では、カスタムリソース定義 (CRD) の提供バージョンをすぐに削除できません。その代わりに、CRD の非推奨バージョンを CRD の served フィールドを false に設定して無効にする必要があります。その後に、無効にされたバージョンではないバージョンを後続の CRD アップグレードで削除できます。

手順

特定バージョンの CRD を非推奨にし、削除するには、以下を実行します。

  1. 非推奨バージョンを non-serving (無効にされたバージョン) とマークして、このバージョンが使用されなくなり、後続のアップグレードで削除される可能性があることを示します。以下に例を示します。 

    versions:
  - name: v1alpha1
    served: false 1
    storage: true
    1
    false に設定します。

  2. 非推奨となるバージョンが現在 storage バージョンの場合、storage バージョンを有効にされたバージョンに切り替えます。以下に例を示します。 

    versions:
  - name: v1alpha1
    served: false
    storage: false 1
  - name: v1beta1
    served: true
    storage: true 2
    1 2
    storage フィールドを適宜更新します。
    注記

    CRD から storage バージョンであるか、このバージョンであった特定のバージョンを削除するために、そのバージョンが CRD のステータスの storedVersion から削除される必要があります。OLM は、保存されたバージョンが新しい CRD に存在しないことを検知した場合に、この実行を試行します。

  3. 上記の変更内容で CRD をアップグレードします。

  4. 後続のアップグレードサイクルでは、無効にされたバージョンを CRD から完全に削除できます。以下に例を示します。 

    versions:
  - name: v1beta1
    served: true
    storage: true
  5. 該当バージョンが CRD から削除される場合、CSV の owned セクションにある CRD の参照バージョンも更新されていることを確認します。

5.7.10.4. CRD テンプレート

Operator のユーザーは、どのオプションが必須またはオプションであるかを認識している必要があります。alm-examples という名前のアノテーションとして、設定の最小セットを使用して、各カスタムリソース定義 (CRD) のテンプレートを提供できます。互換性のある UI は、ユーザーがさらにカスタマイズできるようにこのテンプレートの事前入力を行います。

アノテーションは、Kind のリストで構成されます (例: CRD 名および Kubernetes オブジェクトの対応する metadata および spec)。

以下の詳細の例では、EtcdCluster、EtcdBackup および EtcdRestore のテンプレートを示しています。 

metadata:
  annotations:
    alm-examples: >-
      [{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdCluster","metadata":{"name":"example","namespace":"<operator_namespace>"},"spec":{"size":3,"version":"3.2.13"}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdRestore","metadata":{"name":"example-etcd-cluster"},"spec":{"etcdCluster":{"name":"example-etcd-cluster"},"backupStorageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdBackup","metadata":{"name":"example-etcd-cluster-backup"},"spec":{"etcdEndpoints":["<etcd-cluster-endpoints>"],"storageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}}]

5.7.10.5. 内部オブジェクトの非表示

Operator がタスクを実行するためにカスタムリソース定義 (CRD) を内部で使用する方法は一般的な方法です。これらのオブジェクトはユーザーが操作することが意図されていません。オブジェクトの操作により Operator のユーザーにとって混乱を生じさせる可能性があります。たとえば、データベース Operator には、ユーザーが replication: true で Database オブジェクトを作成する際に常に作成される Replication CRD が含まれる場合があります。

Operator の作成者は、operators.operatorframework.io/internal-objects アノテーションを Operator のクラスターサービスバージョン (CSV) に追加して、ユーザー操作を目的としていないユーザーインターフェイスの CRD を非表示にすることができます。

手順

  1. CRD のいずれかに internal のマークを付ける前に、アプリケーションの管理に必要となる可能性のあるデバッグ情報または設定が CR のステータスまたは spec ブロックに反映されていることを確認してください (使用する Operator に該当する場合)。

  2. operators.operatorframework.io/internal-objects アノテーションを Operator の CSV に追加し、ユーザーインターフェイスで非表示にする内部オブジェクトを指定します。

    内部オブジェクのトアノテーション

    apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  name: my-operator-v1.2.3
  annotations:
    operators.operatorframework.io/internal-objects: '["my.internal.crd1.io","my.internal.crd2.io"]' 1
...

    1
    内部 CRD を文字列の配列として設定します。

5.7.10.6. 必要なカスタムリソースの初期化

Operator では、ユーザーが Operator が完全に機能する前にカスタムリソースをインスタンス化する必要がある場合があります。ただし、ユーザーが必要な内容やリソースの定義方法を判断することが困難な場合があります。

Operator 開発者は、Operator のインストール中に operatorframework.io/initialization-resource をクラスターサービスバージョン (CSV) に追加することで、必要なカスタムリソースを 1 つ指定できます。次に、CSV で提供されるテンプレートを使用してカスタムリソースを作成するように求められます。アノテーションには、インストール時にリソースを初期化するために必要な完全な YAML 定義が含まれるテンプレートが含まれている必要があります。

このアノテーションが定義されている場合、OpenShift Container Platform Web コンソールから Operator をインストールすると、ユーザーには CSV で提供されるテンプレートを使用してリソースを作成することを求めるプロンプトが出されます。

手順

  • operatorframework.io/initialization-resource アノテーションを Operator の CSV に追加し、必要なカスタムリソースを指定します。たとえば、以下のアノテーションでは StorageCluster リソースの作成が必要であり、これは完全な YAML 定義を提供します。

    初期化リソースアノテーション

    apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  name: my-operator-v1.2.3
  annotations:
    operatorframework.io/initialization-resource: |-
        {
            "apiVersion": "ocs.openshift.io/v1",
            "kind": "StorageCluster",
            "metadata": {
                "name": "example-storagecluster"
            },
            "spec": {
                "manageNodes": false,
                "monPVCTemplate": {
                    "spec": {
                        "accessModes": [
                            "ReadWriteOnce"
                        ],
                        "resources": {
                            "requests": {
                                "storage": "10Gi"
                            }
                        },
                        "storageClassName": "gp2"
                    }
                },
                "storageDeviceSets": [
                    {
                        "count": 3,
                        "dataPVCTemplate": {
                            "spec": {
                                "accessModes": [
                                    "ReadWriteOnce"
                                ],
                                "resources": {
                                    "requests": {
                                        "storage": "1Ti"
                                    }
                                },
                                "storageClassName": "gp2",
                                "volumeMode": "Block"
                            }
                        },
                        "name": "example-deviceset",
                        "placement": {},
                        "portable": true,
                        "resources": {}
                    }
                ]
            }
        }
...

5.7.11. API サービスについて

CRD の場合のように、Operator が使用できる API サービスの 2 つのタイプ (所有 (owned) および 必須 (required)) があります。

5.7.11.1. 所有 API サービス

CSV が API サービスを所有する場合、CSV は API サービスおよびこれが提供する group/version/kind (GVK) をサポートする拡張 api-server のデプロイメントを記述します。

API サービスはこれが提供する group/version によって一意に識別され、提供することが予想される複数の種類を示すために複数回リスト表示できます。

表5.16 所有 API サービスフィールド
フィールド説明必須/オプション

Group

API サービスが提供するグループ (database.example.com など)。

必須

Version

API サービスのバージョン (v1alpha1 など)。

必須

Kind

API サービスが提供することが予想される種類。

必須

Name

指定された API サービスの複数形の名前

必須

DeploymentName

API サービスに対応する CSV で定義されるデプロイメントの名前 (所有 API サービスに必要)。CSV の保留フェーズに、OLM Operator は CSV の InstallStrategy で一致する名前を持つ Deployment 仕様を検索し、これが見つからない場合には、CSV を "Install Ready" フェーズに移行しません。

必須

DisplayName

API サービス名の人間が判読できるバージョン (例: MongoDB Standalone)。

必須

説明

Operator がこの API サービスを使用する方法に関する短い説明、または API サービスが提供する機能の説明。

必須

Resources

API サービスは 1 つ以上の Kubernetes オブジェクトのタイプを所有します。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法をユーザーに知らせるためにリソースセクションにリスト表示されます。

この場合、オーケストレーションするすべてのリストではなく、重要なオブジェクトのみをリスト表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する設定マップをリスト表示しないでください。

オプション

SpecDescriptors、StatusDescriptors、および ActionDescriptors

所有 CRD と基本的に同じです。

オプション

5.7.11.1.1. API サービスリソースの作成

Operator Lifecycle Manager (OLM) はそれぞれ固有の所有 API サービスにサービスおよび API サービスリソースを作成するか、これらを置き換えます。

  • サービス Pod セレクターは API サービスの記述の DeploymentName フィールドに一致する CSV デプロイメントからコピーされます。
  • 新規の CA キー/証明書ペアが各インストールに生成され、base64 でエンコードされた CA バンドルがそれぞれの API サービスリソースに組み込まれます。
5.7.11.1.2. API サービス提供証明書

OLM は、所有 API サービスがインストールされるたびに、提供するキー/証明書のペアの生成を処理します。提供証明書には、生成される Service リソースのホスト名が含まれる一般名 (CN) が含まれ、これは対応する API サービスリソースに組み込まれた CA バンドルのプライベートキーによって署名されます。

証明書は、デプロイメント namespace の kubernetes.io/tls タイプのシークレットとして保存され、apiservice-cert という名前のボリュームは、API サービスの記述の DeploymentName フィールドに一致する CSV のデプロイメントのボリュームセクションに自動的に追加されます。

存在していない場合、一致する名前を持つボリュームマウントもそのデプロイメントのすべてのコンテナーに追加されます。これにより、ユーザーは、カスタムパスの要件に対応するために、予想される名前のボリュームマウントを定義できます。生成されるボリュームマウントのパスは /apiserver.local.config/certificates にデフォルト設定され、同じパスの既存のボリュームマウントが置き換えられます。

5.7.11.2. 必要な API サービス

OLM は、必要なすべての CSV に利用可能な API サービスがあり、すべての予想される GVK がインストールの試行前に検出可能であることを確認します。これにより、CSV は所有しない API サービスによって提供される特定の種類に依存できます。

表5.17 必須 API サービスフィールド
フィールド説明必須/オプション

Group

API サービスが提供するグループ (database.example.com など)。

必須

Version

API サービスのバージョン (v1alpha1 など)。

必須

Kind

API サービスが提供することが予想される種類。

必須

DisplayName

API サービス名の人間が判読できるバージョン (例: MongoDB Standalone)。

必須

説明

Operator がこの API サービスを使用する方法に関する短い説明、または API サービスが提供する機能の説明。

必須

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

© 2024 Red Hat, Inc.