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 ジェネレーターが含まれます。
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.2.1. Operator メタデータアノテーション
Operator 開発者は、クラスターサービスバージョン (CSV) のメタデータで特定のアノテーションを手動で定義し、OperatorHub などのユーザーインターフェイス (UI) の機能を有効にしたり、機能を強調したりできます。
以下の表は、metadata.annotations フィールドを使用して、手動で定義できる Operator メタデータアノテーションを一覧表示しています。
| フィールド | 説明 |
|---|---|
|
| カスタムリソース定義 (CRD) テンプレートに最低限の設定セットを指定します。互換性のある UI は、ユーザーがさらにカスタマイズできるようにこのテンプレートの事前入力を行います。 |
|
|
Operator のインストール中に、クラスターサービスバージョン (CSV) に |
|
| Operator をデプロイする必要のある推奨 namespace を設定します。 |
|
| Operator によってサポートされるインフラストラクチャー機能。ユーザーは、Web コンソールで OperatorHub を使用して Operator を検出する際に、これらの機能で表示してフィルターを実行できます。有効で、大文字と小文字が区別される値は以下のとおりです。
重要
FIPS 検証済み/進行中のモジュール (Modules in Process) 暗号ライブラリーの使用は、
|
|
|
Operator を使用するために必要とされる特定のサブスクリプションを一覧表示するための自由形式の配列です。例: |
|
| ユーザーの操作を目的としていない UI の CRD を非表示にします。 |
使用例
Operator は非接続およびプロキシー対応をサポートします
operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'
Operator には OpenShift Container Platform ライセンスが必要です。
operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'
Operator には 3scale ライセンスが必要です
operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]'
Operator は非接続およびプロキシー対応をサポートします。また、OpenShift Container Platform ライセンスが必要です。
operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]' operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'
5.7.3. ネットワークが制限された環境についての Operator の有効化
Operator の作成者は、Operator がネットワークが制限された環境、または非接続の環境で適切に実行されるよう追加要件を満たすことを確認する必要があります。
非接続モードをサポートするための Operator の要件
Operator のクラスターサービスバージョン (CSV) で以下を行います。
- Operator がそれらの機能を実行するために必要となる可能性のある 関連イメージ または他のコンテナーを一覧表示します。
- 指定されたすべてのイメージを、タグではなくダイジェスト (SHA) で参照します。
- Operator のすべての依存関係は、非接続モードでの実行もサポートする必要があります。
- Operator にはクラスター外のリソースは必要ありません。
CSV の要件については、Operator の作成者は以下の変更を加えることができます。
前提条件
- CSV を含む Operator プロジェクト
手順
Operator の CSV の 2 つの場所で関連するイメージへの SHA 参照を使用します。
spec.relatedImagesを更新します。... spec: relatedImages: 1 - name: etcd-operator 2 image: quay.io/etcd-operator/operator@sha256:d134a9865524c29fcf75bbc4469013bc38d8a15cb5f41acfddb6b9e492f556e4 3 - name: etcd-image image: quay.io/etcd-operator/etcd@sha256:13348c15263bd8838ec1d5fc4550ede9860fcbb0f843e48cbccec07810eebb68 ...
Operator が使用する必要のあるイメージを挿入する環境変数を宣言する際に、デプロイメントの
envセクションを更新します。spec: install: spec: deployments: - name: etcd-operator-v3.1.1 spec: replicas: 1 selector: matchLabels: name: etcd-operator strategy: type: Recreate template: metadata: labels: name: etcd-operator spec: containers: - args: - /opt/etcd/bin/etcd_operator_run.sh env: - name: WATCH_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.annotations['olm.targetNamespaces'] - name: ETCD_OPERATOR_DEFAULT_ETCD_IMAGE 1 value: quay.io/etcd-operator/etcd@sha256:13348c15263bd8838ec1d5fc4550ede9860fcbb0f843e48cbccec07810eebb68 2 - name: ETCD_LOG_LEVEL value: INFO image: quay.io/etcd-operator/operator@sha256:d134a9865524c29fcf75bbc4469013bc38d8a15cb5f41acfddb6b9e492f556e4 3 imagePullPolicy: IfNotPresent livenessProbe: httpGet: path: /healthy port: 8080 initialDelaySeconds: 10 periodSeconds: 30 name: etcd-operator readinessProbe: httpGet: path: /ready port: 8080 initialDelaySeconds: 10 periodSeconds: 30 resources: {} serviceAccountName: etcd-operator strategy: deployment注記プローブの設定時に、
timeoutSeconds値はperiodSecondsの値よりも低い値である必要があります。timeoutSecondsのデフォルト値は1です。periodSecondsのデフォルト値は10です。
disconnectedアノテーションを追加します。これは、Operator が非接続環境で機能することを示します。metadata: annotations: operators.openshift.io/infrastructure-features: '["disconnected"]'Operator は、このインフラストラクチャー機能によって OperatorHub でフィルターされます。
5.7.4. 複数のアーキテクチャーおよびオペレーティングシステム用の 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.4.1. Operator のアーキテクチャーおよびオペレーティングシステムのサポート
以下の文字列は、複数のアーキテクチャーおよびオペレーティングシステムをサポートする Operator のラベル付けまたはフィルター時に OpenShift Container Platform の Operator Lifecycle Manager (OLM) でサポートされます。
| アーキテクチャー | 文字列 |
|---|---|
| AMD64 |
|
| 64 ビット PowerPC little-endian |
|
| IBM Z |
|
| オペレーティングシステム | 文字列 |
|---|---|
| Linux |
|
| z/OS |
|
OpenShift Container Platform およびその他の Kubernetes ベースのディストリビューションの異なるバージョンは、アーキテクチャーおよびオペレーティングシステムの異なるセットをサポートする可能性があります。
5.7.5. 推奨される 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.6. 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 v1.8.0 は operator-lib v0.3.0 をサポートします。
前提条件
- Operator プロジェクトが Operator SDK を使用して生成されている。
手順
Operator プロジェクトで Operator 条件を有効にするには、以下を実行します。
Operator プロジェクトの
go.modファイルで、operator-framework/operator-libを必要なライブラリーとして追加します。module github.com/example-inc/memcached-operator go 1.15 require ( k8s.io/apimachinery v0.19.2 k8s.io/client-go v0.19.2 sigs.k8s.io/controller-runtime v0.7.0 operator-framework/operator-lib v0.3.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.7. 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.7.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.8. カスタムリソース定義 (CRD) について
Operator が使用できる以下の 2 つのタイプのカスタムリソース定義 (CRD) があります。1 つ目は Operator が所有する 所有 タイプと、もう 1 つは Operator が依存する 必須 タイプです。
5.7.8.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.8.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.8.3. CRD のアップグレード
OLM は、単一のクラスターサービスバージョン (CSV) によって所有されている場合にはカスタムリソース定義 (CRD) をすぐにアップグレードします。CRD が複数の CSV によって所有されている場合、CRD は、以下の後方互換性の条件のすべてを満たす場合にアップグレードされます。
- 現行 CRD の既存の有効にされたバージョンすべてが新規 CRD に存在する。
- 検証が新規 CRD の検証スキーマに対して行われる場合、CRD の提供バージョンに関連付けられる既存インスタンスまたはカスタムリソースすべてが有効である。
5.7.8.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.8.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.8.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":"default"},"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.8.5. 内部オブジェクトの非表示
Operator がタスクを実行するためにカスタムリソース定義 (CRD) を内部で使用する方法は一般的な方法です。これらのオブジェクトはユーザーが操作することが意図されていません。オブジェクトの操作により Operator のユーザーにとって混乱を生じさせる可能性があります。たとえば、データベース Operator には、ユーザーが replication: true で Database オブジェクトを作成する際に常に作成される Replication CRD が含まれる場合があります。
Operator の作成者は、operators.operatorframework.io/internal-objects アノテーションを Operator のクラスターサービスバージョン (CSV) に追加して、ユーザー操作を目的としていないユーザーインターフェイスの CRD を非表示にすることができます。
手順
-
CRD のいずれかに internal のマークを付ける前に、アプリケーションの管理に必要となる可能性のあるデバッグ情報または設定が CR のステータスまたは
specブロックに反映されていることを確認してください (使用する Opearator に該当する場合)。 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.8.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.9. API サービスについて
CRD の場合のように、Operator が使用できる API サービスの 2 つのタイプ (所有 (owned) および 必須 (required)) があります。
5.7.9.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.9.1.1. API サービスリソースの作成
Operator Lifecycle Manager (OLM) はそれぞれ固有の所有 API サービスについてサービスおよび API サービスリソースを作成するか、またはこれらを置き換えます。
-
サービス Pod セレクターは API サービスの記述の
DeploymentNameフィールドに一致する CSV デプロイメントからコピーされます。 - 新規の CA キー/証明書ペアが各インストールについて生成され、base64 でエンコードされた CA バンドルがそれぞれの API サービスリソースに組み込まれます。
5.7.9.1.2. API サービス提供証明書
OLM は、所有 API サービスがインストールされるたびに、提供するキー/証明書のペアの生成を処理します。提供証明書には、生成される Service リソースのホスト名が含まれる一般名 (CN) が含まれ、これは対応する API サービスリソースに組み込まれた CA バンドルのプライベートキーによって署名されます。
証明書は、デプロイメント namespace の kubernetes.io/tls タイプのシークレットとして保存され、apiservice-cert という名前のボリュームは、 API サービスの記述の DeploymentName フィールドに一致する CSV のデプロイメントのボリュームセクションに自動的に追加されます。
存在していない場合、一致する名前を持つボリュームマウントもそのデプロイメントのすべてのコンテナーに追加されます。これにより、ユーザーは、カスタムパスの要件に対応するために、予想される名前のボリュームマウントを定義できます。生成されるボリュームマウントのパスは /apiserver.local.config/certificates にデフォルト設定され、同じパスの既存のボリュームマウントが置き換えられます。
5.7.9.2. 必要な API サービス
OLM は、必要なすべての CSV に利用可能な API サービスがあり、すべての予想される GVK がインストールの試行前に検出可能であることを確認します。これにより、CSV は所有しない API サービスによって提供される特定の種類に依存できます。
| フィールド | 説明 | 必須/オプション |
|---|---|---|
|
|
API サービスが提供するグループ ( | 必須 |
|
|
API サービスのバージョン ( | 必須 |
|
| API サービスが提供することが予想される種類。 | 必須 |
|
|
API サービス名の人間が判読できるバージョン (例: | 必須 |
|
| Operator がこの API サービスを使用する方法についての短い説明、または API サービスが提供する機能の説明。 | 必須 |
