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 を作成します。
1. 更新メカニズムは、deploy/ で既存の CSV の有無をチェックします。これが見つからない場合、ここでは キャッシュ と呼ばれる ClusterServiceVersion オブジェクトを作成し、Kubernetes API ObjectMeta などの Operator メタデータから派生するフィールドを簡単に設定できます。
2. 更新メカニズムは、deploy/ で Deployment リソースなどの CSV が使用するデータが含まれるマニフェストを検索し、このデータを使ってキャッシュ内の該当する CSV フィールドを設定します。
3. 検索が完了したら、設定されたすべてのキャッシュフィールドが CSV YAML ファイルに書き込まれます。

または、以下を実行します。

YAML マニフェストおよびソースファイルで利用可能なデータを使用して、現時点で事前に定義されている場所で既存の CSV を更新します。
1. 更新メカニズムは、deploy/ で既存の CSV の有無をチェックします。これが見つかる場合、CSV YAML ファイルのコンテンツは ClusterServiceVersion キャッシュにマーシャルされます。
2. 更新メカニズムは、deploy/ で Deployment リソースなどの CSV が使用するデータが含まれるマニフェストを検索し、このデータを使ってキャッシュ内の該当する CSV フィールドを設定します。
3. 検索が完了したら、設定されたすべてのキャッシュフィールドが CSV YAML ファイルに書き込まれます。

注記

ファイル全体ではなく、個別の YAML フィールドが上書きされます。 CSV の説明および他の生成されない部分が保持される必要があるためです。

11.4.2. CSV 構成の設定

Operator の作者者は、deploy/olm-catalog/csv-config.yaml ファイルでいくつかのフィールドを設定し、CSV の構成を設定できます。

フィールド	説明
`operator-path` (文字列)	Operator リソースマニフェストファイルのパス。デフォルトで `deploy/operator.yaml` に設定されます。
`crd-cr-path-list` (string(, string)*)	CRD および CR マニフェストファイルのパス。デフォルトで `[deploy/crds/*_{crd,cr}.yaml]` に設定されます。
`rbac-path-list` (string(, string)*)	RBAC ロールマニフェストファイルのパス。デフォルトで `[deploy/role.yaml]` に設定されます。

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

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

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

表11.5 必須
フィールド	説明
`metadata.name`	CSV の固有名。Operator バージョンは、`app-operator.v0.1.1` などのように一意性を確保するために名前に含める必要があります。
`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`: CRD の説明。 `resources`: CRD によって利用される任意の Kubernetes リソース (例: Pod および StatefulSet)。 `specDescriptors`: Operator の入力および出力についての UI ヒント。

表11.6 オプション
フィールド	説明
`spec.replaces`	この CSV によって置き換えられる CSV の名前。
`spec.links`	それぞれが `name` および `url` を持つ、Operator および管理されているアプリケーションに関する URL (例: Web サイトおよびドキュメント)。
`spec.selector`	Operator がクラスターでのリソースのペアの作成に使用するセレクター。
`spec.icon`	`mediatype` で `base64data` フィールドに設定される、Operator に固有の base64 でエンコーディングされるアイコン。
`spec.maturity`	Operator の成熟度モデルに応じた Operator の機能レベル (例: `Seamless Upgrades`)。

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

注記

現時点でユーザーの介入を必要とするいくつかの YAML フィールドは、Operator コードから解析される可能性があります。このような Operator SDK 機能は、今後の設計ドキュメントで扱われます。

追加リソース

Operator 成熟度モデル

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 ファイルに一覧表示される必要があります。

表11.7 所有 CRD フィールド
フィールド	説明	必須/オプション
`名前`	CRD のフルネーム。	必須
`Version`	オブジェクト API のバージョン。	必須
`Kind`	CRD の機械可読名。	必須
`DisplayName`	CRD 名の人間が判読できるバージョン (例: `MongoDB Standalone`)。	必須
`説明`	Operator がこの CRD を使用する方法についての短い説明、または CRD が提供する機能の説明。	必須
`Group`	この CRD が所属する API グループ (例: `database.example.com`)。	オプション
`Resources`	CRD が 1 つ以上の Kubernetes オブジェクトのタイプを所有する。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法についてユーザーに知らせるためにリソースセクションに一覧表示されます。この場合、オーケストレーションするすべての一覧ではなく、重要なオブジェクトのみを一覧表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する ConfigMap はここには表示しません。	オプション
`SpecDescriptors`、`StatusDescriptors`、および `ActionDescriptors`	これらの記述子は、エンドユーザーにとって最も重要な Operator の入力および出力で UI にヒントを提供する手段になります。CRD にユーザーが指定する必要のあるシークレットまたは ConfigMap の名前が含まれる場合は、それをここに指定できます。これらのアイテムはリンクされ、互換性のある UI で強調表示されます。記述子には、3 つの種類があります。 `SpecDescriptors`: オブジェクトの `spec` ブロックのフィールドへの参照。 `StatusDescriptors`: オブジェクトの `status` ブロックのフィールドへの参照。 `ActionDescriptors`: オブジェクトで実行できるアクションへの参照。すべての記述子は以下のフィールドを受け入れます。 `DisplayName`: 仕様、ステータス、またはアクションの人間が判読できる名前。 `Description`: 仕様、ステータス、またはアクション、およびそれが Operator によって使用される方法についての短い説明。 `Path`: この記述子が記述するオブジェクトのフィールドのドットで区切られたパス。 `X-Descriptors`: この記述子が持つ「機能」および使用する UI コンポーネントを判別するために使用されます。OpenShift Container Platform の正規の React UI X-Descriptor の一覧については、 openshift/console プロジェクトを参照してください。記述子一般についての詳細は、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 リソースを作成し、監視し、変更できるようにするために作成されます。

表11.8 必須 CRD フィールド
フィールド	説明	必須/オプション
`名前`	必要な 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.

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 によって一意に識別され、提供することが予想される複数の種類を示すために複数回一覧表示できます。

表11.9 所有 APIService フィールド
フィールド	説明	必須/オプション
`Group`	APIService が提供するグループ (`database.example.com`など)。	必須
`Version`	APIService のバージョン (`v1alpha1` など)。	必須
`Kind`	APIService が提供することが予想される種類。	必須
`名前`	指定された APIService の複数形の名前	必須
`DeploymentName`	APIService に対応する CSV で定義されるデプロイメントの名前 (所有 APIService に必要)。CSV が保留中のフェーズにある場合、OLM Operator は CSV の InstallStrategy で一致する名前を持つデプロイメント仕様を検索し、これが見つからない場合には、CSV をインストールの準備完了フェーズに移行しません。	必須
`DisplayName`	APIService 名の人間が判読できるバージョン (例: `MongoDB Standalone`)。	必須
`説明`	Operator がこの APIService を使用する方法についての短い説明、または APIService が提供する機能の説明。	必須
`Resources`	APIService は 1 つ以上の Kubernetes オブジェクトのタイプを所有します。これらは、トラブルシューティングが必要になる可能性のあるオブジェクトや、データベースを公開するサービスまたは Ingress ルールなどのアプリケーションに接続する方法についてユーザーに知らせるためにリソースセクションに一覧表示されます。この場合、オーケストレーションするすべての一覧ではなく、重要なオブジェクトのみを一覧表示することが推奨されます。たとえば、ユーザーが変更できない内部状態を保存する ConfigMap はここには表示しません。	オプション
`SpecDescriptors`、`StatusDescriptors`、および `ActionDescriptors`	所有 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 によって提供される特定の種類に依存できます。

表11.10 必須 APIService フィールド
フィールド	説明	必須/オプション
`Group`	APIService が提供するグループ (`database.example.com`など)。	必須
`Version`	APIService のバージョン (`v1alpha1` など)。	必須
`Kind`	APIService が提供することが予想される種類。	必須
`DisplayName`	APIService 名の人間が判読できるバージョン (例: `MongoDB Standalone`)。	必須
`説明`	Operator がこの APIService を使用する方法についての短い説明、または APIService が提供する機能の説明。	必須