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 コマンドを提供します。これは、以下のサブコマンドを順番に実行するなどの複数のタスクを自動化します。
-
generate kustomize manifests -
generate bundle -
bundle validate
関連情報
- バンドルと CSV の生成を含む詳細な手順は、Operator のバンドル を参照してください。
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 フィールドのうち、必須フィールドとオプションフィールドについて詳細に示しています。
| フィールド | 説明 |
|---|---|
|
|
CSV の固有名。Operator バージョンは、 |
|
|
Operator の成熟度モデルに応じた機能レベル。オプションには、 |
|
| Operator を識別するためのパブリック名。 |
|
| Operator の機能に関する簡単な説明。 |
|
| Operator について記述するキーワード。 |
|
|
|
|
|
|
|
| Operator 内部で使用されるキー/値のペア。 |
|
|
Operator のセマンティクスバージョン。 例: |
|
|
Operator が使用する任意の CRD。このフィールドは、CRD YAML ファイルが
|
| フィールド | 説明 |
|---|---|
|
| この CSV によって置き換えられる CSV の名前。 |
|
|
それぞれが |
|
| Operator がクラスターでのリソースのペアの作成に使用するセレクター。 |
|
|
|
|
|
このバージョンでソフトウェアが達成した成熟度。オプションに、 |
上記の各フィールドが保持するデータの詳細は、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 アノテーションが非推奨となりました。詳細は、「非推奨のインフラストラクチャー機能のアノテーション」を参照してください。
| アノテーション | 説明 | 有効な値 [1] |
|---|---|---|
|
|
Operator はすべての依存関係を含む非接続カタログにミラーリングされるため、インターネットへのアクセスは必要ないかどうかを指定します。Operator は、 |
|
|
| Operator が基盤となるプラットフォームの FIPS-140 設定を受け入れ、FIPS モードで起動したノードで動作するかどうかを指定します。このモードでは、Operator とそれが管理するすべてのワークロード (オペランド) は、FIPS-140 検証用に提出された Red Hat Enterprise Linux (RHEL) 暗号化ライブラリーのみを呼び出します。 |
|
|
|
標準の |
|
|
| Operator が使用する TLS 暗号スイート、および該当する場合は管理対象のワークロード (オペランド) を変更するための既知の設定項目を Operator が実装するかどうかを指定します。 |
|
|
| Cloud Credential Operator (CCO) を使用して、AWS Secure Token Service (STS) を介した AWS API によるトークン化認証の設定を Operator がサポートするかどうかを指定します。 |
|
|
| Cloud Credential Operator (CCO) を使用して、Azure マネージド ID を介した Azure API によるトークン化認証の設定を Operator がサポートするかどうかを指定します。 |
|
|
| Cloud Credential Operator (CCO) を使用して、GCP Workload Identity Foundation (WIF) を介した Google Cloud API によるトークン化認証の設定を Operator がサポートするかどうかを指定します。 |
|
|
| Cloud-Native Network Function (CNF) Kubernetes プラグインを Operator が提供するかどうかを指定します。 |
|
|
| Container Network Interface (CNI) Kubernetes プラグインを Operator が提供するかどうかを指定します。 |
|
|
| Container Storage Interface (CSI) Kubernetes プラグインを Operator が提供するかどうかを指定します。 |
|
- 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 を探すときに、これらの機能を使用して表示やフィルタリングを行うことができます。
| 有効なアノテーション値 | 説明 |
|---|---|
|
| Operator はすべての依存関係を含む非接続カタログにミラーリングされるため、インターネットへのアクセスは必要ありません。ミラーリングに必要なすべての関連イメージが Operator によって一覧表示されます。 |
|
| Operator は Cloud-native Network Functions (CNF) Kubernetes プラグインを提供します。 |
|
| Operator は Container Network Interface (CNI) Kubernetes プラグインを提供します。 |
|
| Operator は Container Storage Interface (CSI) Kubernetes プラグインを提供します。 |
|
| 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 暗号化ライブラリーを使用します。 |
|
|
Operator はプロキシーの背後のクラスターでの実行をサポートします。Operator は、クラスターがプロキシーを使用するように設定される際に Operator Lifecycle Manager (OLM) が Operator に自動的に提供する標準のプロキシー環境変数の |
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 のアノテーションは任意です。
| アノテーション | 説明 |
|---|---|
|
| カスタムリソース定義 (CRD) テンプレートに最低限の設定セットを指定します。互換性のある UI は、ユーザーがさらにカスタマイズできるようにこのテンプレートの事前入力を行います。 |
|
|
Operator のインストール中に、クラスターサービスバージョン (CSV) に |
|
| Operator をデプロイする必要のある推奨 namespace を設定します。 |
|
|
指定された |
|
|
Operator を使用するために必要とされる特定のサブスクリプションをリスト表示するための自由形式の配列です。例: |
|
| ユーザーの操作を目的としていない 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 を使用します。
手順
config/manager/manager.yamlファイルで、Operator が使用する追加のイメージ参照の環境変数を設定します。ハードコードされたイメージ参照は、Operator プロジェクトタイプに関連するファイルの環境変数に置き換えます。
Go ベースの Operator プロジェクトの場合には、次の例に示すように、環境変数を
controllers/memcached_controller.goファイルに追加します。例5.11
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{{ ...注記変数が設定されていない場合、
os.Getenv関数は空の文字列を返します。ファイルを変更する前に、<related_image_environment_variable>を設定してください。Ansible ベースの Operator プロジェクトの場合には、次の例に示すように、環境変数を
roles/memcached/tasks/main.ymlファイルに追加します。例5.12
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 ...Helm ベースの Operator プロジェクトの場合、以下の例のように
overrideValuesフィールドをwatches.yamlファイルに追加します。例5.13
watches.yamlファイルの例以下の例のように、
overrideValuesフィールドの値をhelm-charts/memchached/values.yamlファイルに追加します。helm-charts/memchached/values.yamlファイルの例... relatedImage: ""
以下の例のように、
helm-charts/memcached/templates/deployment.yamlファイルのチャートテンプレートを編集します。例5.14
helm-charts/memcached/templates/deployment.yamlファイルの例
次の変更を加えて、
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 ...タグではなくダイジェスト (SHA) を使用するように Operator イメージを更新するには、
make bundleコマンドを実行し、USE_IMAGE_DIGESTSをtrueに設定します。$ make bundle USE_IMAGE_DIGESTS=true
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
デフォルトチャネルのチャネルヘッドにあるラベルのみが、パッケージマニフェストをラベルでフィルターする場合に考慮されます。たとえば、デフォルト以外のチャネルで Operator の追加アーキテクチャーを提供することは可能ですが、そのアーキテクチャーは PackageManifest API でのフィルターには使用できません。
CSV に os ラベルが含まれていない場合、これはデフォルトで以下の Linux サポートラベルが設定されているかのように処理されます。
labels:
operatorframework.io/os.linux: supported
CSV に arch ラベルが含まれていない場合、これはデフォルトで以下の AMD64 サポートラベルが設定されているかのように処理されます。
labels:
operatorframework.io/arch.amd64: supportedOperator が複数のノードアーキテクチャーまたはオペレーティングシステムをサポートする場合、複数のラベルを追加することもできます。
前提条件
- 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
関連情報
- マニフェストのリストの詳細は、Image Manifest V 2, Schema 2 仕様を参照してください。
5.7.5.1. Operator のアーキテクチャーおよびオペレーティングシステムのサポート
以下の文字列は、複数のアーキテクチャーおよびオペレーティングシステムをサポートする Operator のラベル付けまたはフィルター時に OpenShift Container Platform の Operator Lifecycle Manager (OLM) でサポートされます。
| アーキテクチャー | 文字列 |
|---|---|
| AMD64 |
|
| ARM64 |
|
| IBM Power® |
|
| IBM Z® |
|
| オペレーティングシステム | 文字列 |
|---|---|
| Linux |
|
| z/OS |
|
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.31.0 は operator-lib v0.11.0 をサポートします。
前提条件
- Operator プロジェクトが Operator SDK を使用して生成されている。
手順
Operator プロジェクトで Operator 条件を有効にするには、以下を実行します。
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 )
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 ...
関連情報
- Webhook 受付プラグインのタイプ
Kubernetes ドキュメント:
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 ファイルにリスト表示される必要があります。
| フィールド | 説明 | 必須/オプション |
|---|---|---|
|
| CRD のフルネーム。 | 必須 |
|
| オブジェクト API のバージョン。 | 必須 |
|
| CRD の機械可読名。 | 必須 |
|
|
CRD 名の人間が判読できるバージョン (例: | 必須 |
|
| Operator がこの CRD を使用する方法に関する短い説明、または CRD が提供する機能の説明。 | 必須 |
|
|
この CRD が所属する API グループ (例: | オプション |
|
|
CRD が 1 つ以上の Kubernetes オブジェクトのタイプを所有する。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法についてユーザーに知らせるために この場合、オーケストレーションするすべてのリストではなく、重要なオブジェクトのみをリスト表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する設定マップをリスト表示しないでください。 | オプション |
|
| これらの記述子は、エンドユーザーにとって最も重要な Operator の入力および出力で UI にヒントを提供する手段になります。CRD にユーザーが指定する必要のあるシークレットまたは設定マップの名前が含まれる場合は、それをここに指定できます。これらのアイテムはリンクされ、互換性のある UI で強調表示されます。 記述子には、3 つの種類があります。
すべての記述子は以下のフィールドを受け入れます。
記述子 一般の詳細は、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 リソースを作成し、監視し、変更できるようにするために作成されます。
| フィールド | 説明 | 必須/オプション |
|---|---|---|
|
| 必要な CRD のフルネーム。 | 必須 |
|
| オブジェクト API のバージョン。 | 必須 |
|
| Kubernetes オブジェクトの種類。 | 必須 |
|
| 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 に追加するには、以下を実行します。
CSV の
versionsセクションに CRD リソースの新規エントリーを追加します。たとえば、現在の CRD にバージョン
v1alpha1があり、新規バージョンv1beta1を追加し、これを新規のストレージバージョンとしてマークをする場合に、v1beta1の新規エントリーを追加します。versions: - name: v1alpha1 served: true storage: false - name: v1beta1 1 served: true storage: true- 1
- 新規エントリー。
CSV が新規バージョンを使用する場合、CSV の
ownedセクションの CRD の参照バージョンが更新されていることを確認します。customresourcedefinitions: owned: - name: cluster.example.com version: v1beta1 1 kind: cluster displayName: Cluster- 1
versionを更新します。
- 更新された CRD および CSV をバンドルにプッシュします。
5.7.10.3.2. CRD バージョンの非推奨または削除
Operator Lifecycle Manager (OLM) では、カスタムリソース定義 (CRD) の提供バージョンをすぐに削除できません。その代わりに、CRD の非推奨バージョンを CRD の served フィールドを false に設定して無効にする必要があります。その後に、無効にされたバージョンではないバージョンを後続の CRD アップグレードで削除できます。
手順
特定バージョンの CRD を非推奨にし、削除するには、以下を実行します。
非推奨バージョンを non-serving (無効にされたバージョン) とマークして、このバージョンが使用されなくなり、後続のアップグレードで削除される可能性があることを示します。以下に例を示します。
versions: - name: v1alpha1 served: false 1 storage: true- 1
falseに設定します。
非推奨となるバージョンが現在
storageバージョンの場合、storageバージョンを有効にされたバージョンに切り替えます。以下に例を示します。versions: - name: v1alpha1 served: false storage: false 1 - name: v1beta1 served: true storage: true 2注記CRD から
storageバージョンであるか、このバージョンであった特定のバージョンを削除するために、そのバージョンが CRD のステータスのstoredVersionから削除される必要があります。OLM は、保存されたバージョンが新しい CRD に存在しないことを検知した場合に、この実行を試行します。- 上記の変更内容で CRD をアップグレードします。
後続のアップグレードサイクルでは、無効にされたバージョンを CRD から完全に削除できます。以下に例を示します。
versions: - name: v1beta1 served: true storage: true-
該当バージョンが 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 を非表示にすることができます。
手順
-
CRD のいずれかに internal のマークを付ける前に、アプリケーションの管理に必要となる可能性のあるデバッグ情報または設定が CR のステータスまたは
specブロックに反映されていることを確認してください (使用する Operator に該当する場合)。 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 によって一意に識別され、提供することが予想される複数の種類を示すために複数回リスト表示できます。
| フィールド | 説明 | 必須/オプション |
|---|---|---|
|
|
API サービスが提供するグループ ( | 必須 |
|
|
API サービスのバージョン ( | 必須 |
|
| API サービスが提供することが予想される種類。 | 必須 |
|
| 指定された API サービスの複数形の名前 | 必須 |
|
|
API サービスに対応する CSV で定義されるデプロイメントの名前 (所有 API サービスに必要)。CSV の保留フェーズに、OLM Operator は CSV の | 必須 |
|
|
API サービス名の人間が判読できるバージョン (例: | 必須 |
|
| Operator がこの API サービスを使用する方法に関する短い説明、または API サービスが提供する機能の説明。 | 必須 |
|
| API サービスは 1 つ以上の Kubernetes オブジェクトのタイプを所有します。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法についてユーザーに知らせるためにリソースセクションにリスト表示されます。 この場合、オーケストレーションするすべてのリストではなく、重要なオブジェクトのみをリスト表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する設定マップをリスト表示しないでください。 | オプション |
|
| 所有 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 サービスによって提供される特定の種類に依存できます。
| フィールド | 説明 | 必須/オプション |
|---|---|---|
|
|
API サービスが提供するグループ ( | 必須 |
|
|
API サービスのバージョン ( | 必須 |
|
| API サービスが提供することが予想される種類。 | 必須 |
|
|
API サービス名の人間が判読できるバージョン (例: | 必須 |
|
| Operator がこの API サービスを使用する方法に関する短い説明、または API サービスが提供する機能の説明。 | 必須 |
