11.4. ClusterServiceVersion (CSV) の生成
ClusterServiceVersion (CSV) は、Operator Lifecycle Manager (OLM) のクラスターでの Operator の実行を支援する Operator メタデータから作成される YAML マニフェストです。これは、ユーザーインターフェースにロゴ、説明、およびバージョンなどの情報を設定するために使用される Operator コンテナーイメージを伴うメタデータです。CSV は、Operator が必要とする RBAC ルールやそれが管理したり、依存したりするカスタムリソース (CR) などの Operator の実行に必要な技術情報の情報源でもあります。
Operator SDK には、手動で定義された YAML マニフェストおよび Operator ソースファイルに含まれる情報を使用してカスタマイズされた現行 Operator プロジェクトの ClusterServiceVersion (CSV) を生成するための olm-catalog gen-csv
サブコマンドが含まれます。
CSV で生成されるコマンドにより、Operator の作成者が Operator Lifecycle Manager (OLM) について詳しく知らなくても、Operator が OLM と対話させたり、メタデータをカタログレジストリーに公開したりできます。また、Kubernetes および OLM の新機能が実装される過程で CSV 仕様は変更されるため、Operator SDK はその後の新規 CSV 機能を処理できるように更新システムを容易に拡張できるようになっています。
CSV バージョンは Operator のバージョンと同じであり、新規 CSV は Operator バージョンのアップグレード時に生成されます。Operator 作成者は --csv-version
フラグを使用して、それらの Operator の状態を指定されたセマンティクスバージョンと共に CSV にカプセル化できます。
$ operator-sdk olm-catalog gen-csv --csv-version <version>
このアクションはべき等であり、新規バージョンが指定されるか、または YAML マニフェストまたはソースファイルが変更される場合にのみ CSV ファイルを更新します。Operator の作成者は CSV マニフェストのほとんどのフィールドを直接変更する必要はありません。変更が必要なフィールドについて、本書で定義されています。たとえば、CSV バージョンについては metadata.name
に組み込む必要があります。
11.4.1. CSV 生成の仕組み
Operator プロジェクトの deploy/
ディレクトリーは、Operator をデプロイするために必要なすべてのマニフェストの標準的な場所です。Operator SDK は deploy/
のマニフェストのデータを使用し、CSV を作成できます。以下がコマンドになります。
$ operator-sdk olm-catalog gen-csv --csv-version <version>
デフォルトで、CSV YAML ファイルを deploy/olm-catalog/
ディレクトリーに書き込みます。
3 つのタイプのマニフェストが CSV の生成に必要になります。
-
operator.yaml
-
*_{crd,cr}.yaml
-
RBAC ロールファイル (例:
role.yaml
)
Operator の作者にはこれらのファイルについてそれぞれ異なるバージョン管理の要件がある場合があり、deploy/olm-catalog/csv-config.yaml
ファイルに組み込む特定のファイルを設定できます。
ワークフロー
検出される既存の CSV に応じて、またすべての設定のデフォルト値が使用されることを仮定すると、olm-catalog gen-csv
サブコマンドは以下のいずれかを実行します。
既存の場所および命名規則と同じ設定で、YAML マニフェストおよびソースファイルの利用可能なデータを使用して新規 CSV を作成します。
-
更新メカニズムは、
deploy/
で既存の CSV の有無をチェックします。これが見つからない場合、ここでは キャッシュ と呼ばれる ClusterServiceVersion オブジェクトを作成し、Kubernetes APIObjectMeta
などの Operator メタデータから派生するフィールドを簡単に設定できます。 -
更新メカニズムは、
deploy/
で Deployment リソースなどの CSV が使用するデータが含まれるマニフェストを検索し、このデータを使ってキャッシュ内の該当する CSV フィールドを設定します。 - 検索が完了したら、設定されたすべてのキャッシュフィールドが CSV YAML ファイルに書き込まれます。
-
更新メカニズムは、
または、以下を実行します。
YAML マニフェストおよびソースファイルで利用可能なデータを使用して、現時点で事前に定義されている場所で既存の CSV を更新します。
-
更新メカニズムは、
deploy/
で既存の CSV の有無をチェックします。これが見つかる場合、CSV YAML ファイルのコンテンツは ClusterServiceVersion キャッシュにマーシャルされます。 -
更新メカニズムは、
deploy/
で Deployment リソースなどの CSV が使用するデータが含まれるマニフェストを検索し、このデータを使ってキャッシュ内の該当する CSV フィールドを設定します。 - 検索が完了したら、設定されたすべてのキャッシュフィールドが CSV YAML ファイルに書き込まれます。
-
更新メカニズムは、
ファイル全体ではなく、個別の YAML フィールドが上書きされます。 CSV の説明および他の生成されない部分が保持される必要があるためです。
11.4.2. CSV 構成の設定
Operator の作者者は、deploy/olm-catalog/csv-config.yaml
ファイルでいくつかのフィールドを設定し、CSV の構成を設定できます。
フィールド | 説明 |
---|---|
|
Operator リソースマニフェストファイルのパス。デフォルトで |
|
CRD および CR マニフェストファイルのパス。デフォルトで |
|
RBAC ロールマニフェストファイルのパス。デフォルトで |
11.4.3. 手動で定義される CSV フィールド
数多くの CSV フィールドは、生成される SDK 固有のマニフェスト以外のファイルを使用して設定することができません。これらのフィールドは、ほとんどの場合、人間が作成する、Operator および各種のカスタムリソース定義 (CRD) についての英語のメタデータです。
Operator 作成者はそれらの CSV YAML ファイルを直接変更する必要があり、パーソナライズ設定されたデータを以下の必須フィールドに追加します。Operator SDK は、必須フィールドのいずれかにデータが欠落していることが検出されると、CSV 生成に関する警告を送信します。
フィールド | 説明 |
---|---|
|
CSV の固有名。Operator バージョンは、 |
| Operator を識別するためのパブリック名。 |
| Operator の機能についての簡単な説明。 |
| Operator について記述するキーワード。 |
|
|
|
|
| Operator 内部で使用されるキー/値のペア。 |
|
Operator のセマンティクスバージョン。 例: |
|
Operator が使用する任意の CRD。このフィールドは、CRD YAML ファイルが
|
フィールド | 説明 |
---|---|
| この CSV によって置き換えられる CSV の名前。 |
|
それぞれが |
| Operator がクラスターでのリソースのペアの作成に使用するセレクター。 |
|
|
|
Operator の成熟度モデルに応じた Operator の機能レベル (例: |
上記の各フィールドが保持するデータについての詳細は、「CSV spec」を参照してください。
現時点でユーザーの介入を必要とするいくつかの YAML フィールドは、Operator コードから解析される可能性があります。 このような Operator SDK 機能は、今後の設計ドキュメントで扱われます。
追加リソース
11.4.4. CSV の生成
前提条件
- Operator プロジェクトが Operator SDK を使用して生成されている
手順
-
Operator プロジェクトで、必要な場合に
deploy/olm-catalog/csv-config.yaml
ファイルを変更して CSV 構成を設定します。 CSV を生成します。
$ operator-sdk olm-catalog gen-csv --csv-version <version>
-
deploy/olm-catalog/
ディレクトリーに生成される新規 CSV で、すべての必須で、手動で定義されたフィールドが適切に設定されていることを確認します。
11.4.5. カスタムリソース定義 (CRD)
Operator が使用できる以下の 2 つのタイプのカスタムリソース定義 (CRD) があります。1 つ目は Operator が所有する 所有 タイプと、もう 1 つは Operator が依存する 必須 タイプです。
11.4.5.1. 所有 CRD (Owned CRD)
Operator が所有する CRD は CSV の最も重要な部分です。これは Operator と必要な RBAC ルール間のリンク、依存関係の管理、および他の Kubernetes の概念を設定します。
Operator は通常、複数の CRD を使用して複数の概念を結び付けます (あるオブジェクトの最上位のデータベース設定と別のオブジェクトの ReplicaSet の表現など)。それぞれは CSV ファイルに一覧表示される必要があります。
フィールド | 説明 | 必須/オプション |
---|---|---|
| CRD のフルネーム。 | 必須 |
| オブジェクト API のバージョン。 | 必須 |
| CRD の機械可読名。 | 必須 |
|
CRD 名の人間が判読できるバージョン (例: | 必須 |
| Operator がこの CRD を使用する方法についての短い説明、または CRD が提供する機能の説明。 | 必須 |
|
この CRD が所属する API グループ (例: | オプション |
| CRD が 1 つ以上の Kubernetes オブジェクトのタイプを所有する。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法についてユーザーに知らせるためにリソースセクションに一覧表示されます。 この場合、オーケストレーションするすべての一覧ではなく、重要なオブジェクトのみを一覧表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する ConfigMap はここには表示しません。 | オプション |
| これらの記述子は、エンドユーザーにとって最も重要な Operator の入力および出力で UI にヒントを提供する手段になります。CRD にユーザーが指定する必要のあるシークレットまたは ConfigMap の名前が含まれる場合は、それをここに指定できます。これらのアイテムはリンクされ、互換性のある UI で強調表示されます。 記述子には、3 つの種類があります。
すべての記述子は以下のフィールドを受け入れます。
記述子一般についての詳細は、openshift/console プロジェクトも参照してください。 | オプション |
以下の例は、シークレットおよび ConfigMap でユーザー入力を必要とし、サービス、StatefulSet、Pod および ConfigMap のオーケストレーションを行う 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.
11.4.5.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.
11.4.5.3. 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>"}}}]
11.4.6. API サービスについて
CRD の場合のように、Operator が使用できる APIService の 2 つのタイプ( 所有 (owned) および 必須 (required))があります。
11.4.6.1. 所有 APIService (Owned APIService)
CSV が APIService を所有する場合、CSV は APIService をサポートする拡張 api-server
およびこれが提供する group-version-kinds
のデプロイメントを記述します。
APIService はこれが提供する group-version
によって一意に識別され、提供することが予想される複数の種類を示すために複数回一覧表示できます。
フィールド | 説明 | 必須/オプション |
---|---|---|
|
APIService が提供するグループ ( | 必須 |
|
APIService のバージョン ( | 必須 |
| APIService が提供することが予想される種類。 | 必須 |
| 指定された APIService の複数形の名前 | 必須 |
| APIService に対応する CSV で定義されるデプロイメントの名前 (所有 APIService に必要)。CSV が保留中のフェーズにある場合、OLM Operator は CSV の InstallStrategy で一致する名前を持つデプロイメント仕様を検索し、これが見つからない場合には、CSV をインストールの準備完了フェーズに移行しません。 | 必須 |
|
APIService 名の人間が判読できるバージョン (例: | 必須 |
| Operator がこの APIService を使用する方法についての短い説明、または APIService が提供する機能の説明。 | 必須 |
| APIService は 1 つ以上の Kubernetes オブジェクトのタイプを所有します。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法についてユーザーに知らせるためにリソースセクションに一覧表示されます。 この場合、オーケストレーションするすべての一覧ではなく、重要なオブジェクトのみを一覧表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する ConfigMap はここには表示しません。 | オプション |
| 所有 CRDと基本的に同じです。 | オプション |
11.4.6.1.1. APIService リソースの作成
Operator Lifecycle Manager (OLM) はそれぞれ固有の所有 APIService のサービスおよび APIService リソースを作成するか、またはこれらを置き換えます。
-
サービス Pod セレクターは APIServiceDescription の
DeDeploymentName
に一致する CSV デプロイメントからコピーされます。 - 新規の CA キー/証明書ペアが各インストールについて生成され、base64 でエンコードされた CA バンドルがそれぞれの APIService リソースに組み込まれます。
11.4.6.1.2. APIService 提供証明書
OLM は、所有 APIService がインストールされるたびに、提供するキー/証明書のペアの生成を処理します。提供証明書には、生成されるサービスリソースのホスト名が含まれる CN が含まれ、これは対応する APIService リソースに組み込まれた CA バンドルのプライベートキーによって署名されます。
証明書は、デプロイメント namespace の kubernetes.io/tls
タイプのシークレットとして保存され、 apiservice-cert
という名前のボリュームは、 APIServiceDescription の DeploymentName
フィールドに一致する CSV のデプロイメントのボリュームセクションに自動的に追加されます。
存在していない場合、一致する名前を持つ VolumeMount もそのデプロイメントのすべてのコンテナーに追加されます。これにより、ユーザーは、カスタムパスの要件に対応するために、予想される名前のボリュームマウントを定義できます。生成される volumeMount のパスは /apiserver.local.config/certificates
にデフォルト設定され、既存の volumeMounts が同じパスと置き換えられます。
11.4.6.2. 必須 APIService
OLM は、必要なすべての CSV に利用可能な APIService があり、すべての予想される group-version-kinds
がインストールの試行前に検出可能であることを確認します。これにより、CSV は所有しない APIServices によって提供される特定の種類に依存できます。
フィールド | 説明 | 必須/オプション |
---|---|---|
|
APIService が提供するグループ ( | 必須 |
|
APIService のバージョン ( | 必須 |
| APIService が提供することが予想される種類。 | 必須 |
|
APIService 名の人間が判読できるバージョン (例: | 必須 |
| Operator がこの APIService を使用する方法についての短い説明、または APIService が提供する機能の説明。 | 必須 |