第4章 カタログ
4.1. ファイルベースのカタログ リンクのコピーリンクがクリップボードにコピーされました!
OpenShift Container Platform の Operator Lifecycle Manager (OLM) v1 は、クラスター上のクラスター拡張機能 (Operator を含む) を検出および取得するために使用する ファイルベースのカタログ をサポートします。
4.1.1. 主な特徴 リンクのコピーリンクがクリップボードにコピーされました!
ファイルベースのカタログ は、Operator Lifecycle Manager (OLM) の最新バージョンのカタログ形式です。この形式は、プレーンテキストベース (JSON または YAML) であり、以前の SQLite データベース形式の宣言的な設定の進化であり、完全な下位互換性があります。この形式の目標は、Operator のカタログ編集、設定可能性、および拡張性を有効にすることです。
- 編集
ファイルベースのカタログを使用すると、カタログの内容を操作するユーザーは、形式を直接変更し、変更が有効であることを確認できます。この形式はプレーンテキストの JSON または YAML であるため、カタログメンテナーは、一般的に知られている、サポート対象の JSON または YAML ツール (例:
jq
CLI) を使用して、手動でカタログメタデータを簡単に操作できます。この編集機能により、以下の機能とユーザー定義の拡張が有効になります。
- 既存のバンドルの新規チャネルへのプロモート
- パッケージのデフォルトチャネルの変更
- アップグレードパスを追加、更新、および削除するためのカスタムアルゴリズム
- コンポーザービリティー
ファイルベースのカタログは、任意のディレクトリー階層に保管され、カタログの作成が可能になります。たとえば、2 つのファイルベースのカタログディレクトリー (
catalogA
およびcatalogB
) を見てみましょう。カタログメンテナーは、新規のディレクトリーcatalogC
を作成してcatalogA
とcatalogB
をそのディレクトリーにコピーし、新しく結合カタログを作成できます。このコンポーザービリティーにより、カタログの分散化が可能になります。この形式により、Operator の作成者は Operator 固有のカタログを維持でき、メンテナーは個別の Operator カタログで構成されるカタログを簡単にビルドできます。ファイルベースのカタログは、他の複数のカタログを組み合わせたり、1 つのカタログのサブセットを抽出したり、またはこれらの両方を組み合わせたりすることで作成できます。
注記パッケージ内でパッケージおよびバンドルを重複できません。
opm validate
コマンドは、重複が見つかった場合はエラーを返します。Operator の作成者は Operator、その依存関係およびそのアップグレードの互換性を最も理解しているので、Operator 固有のカタログを独自のカタログに維持し、そのコンテンツを直接制御できます。ファイルベースのカタログの場合に、Operator の作成者はカタログでパッケージをビルドして維持するタスクを所有します。ただし、複合カタログメンテナーは、カタログ内のパッケージのキュレートおよびユーザーにカタログを公開するタスクのみを所有します。
- 拡張性
ファイルベースのカタログ仕様は、カタログの低レベル表現です。これは低レベルの形式で直接保守できますが、カタログメンテナーは、このレベルの上に任意の拡張をビルドして、独自のカスタムツールを使用して任意数の変更を加えることができます。
たとえば、
(mode=semver)
などの高レベルの API を、アップグレードパス用に低レベルのファイルベースのカタログ形式にツールで変換できます。または、カタログメンテナーは、特定の条件を満たすバンドルに新規プロパティーを追加して、すべてのバンドルメタデータをカスタマイズする必要がある場合があります。このような拡張性を使用すると、今後の OpenShift Container Platform リリース向けに、追加の正式なツールを下層の API 上で開発できますが、主な利点として、カタログメンテナーにもこの機能がある点が挙げられます。
4.1.2. ディレクトリー構造 リンクのコピーリンクがクリップボードにコピーされました!
ファイルベースのカタログは、ディレクトリーベースのファイルシステムから保存してロードできます。opm
CLI は、root ディレクトリーを元に、サブディレクトリーに再帰してカタログを読み込みます。CLI は、検出されるすべてのファイルの読み込みを試行し、エラーが発生した場合には失敗します。
.gitignore
ファイルとパターンと優先順位が同じ .indexignore
ファイルを使用して、カタログ以外のファイルを無視できます。
例: .indexignore
ファイル
カタログメンテナーは、必要なレイアウトを柔軟に選択できますが、各パッケージのファイルベースのカタログ Blob は別々のサブディレクトリーに保管することを推奨します。個々のファイルは JSON または YAML のいずれかをしようしてください。カタログ内のすべてのファイルが同じ形式を使用する必要はありません。
推奨される基本構造
この推奨の構造には、ディレクトリー階層内の各サブディレクトリーは自己完結型のカタログであるという特性があるため、カタログの作成、検出、およびナビゲーションなどのファイルシステムの操作が簡素化されます。このカタログは、親カタログのルートディレクトリーにコピーして親カタログに追加することもできます。
4.1.3. スキーマ リンクのコピーリンクがクリップボードにコピーされました!
ファイルベースのカタログは、任意のスキーマで拡張できる CUE 言語仕様 に基づく形式を使用します。以下の _Meta
CUE スキーマは、すべてのファイルベースのカタログ Blob が順守する必要のある形式を定義します。
_Meta
スキーマ
この仕様にリストされている CUE スキーマは網羅されていると見なされます。opm validate
コマンドには、CUE で簡潔に記述するのが困難または不可能な追加の検証が含まれます。
Operator Lifecycle Manager(OLM) カタログは、現時点で OLM の既存のパッケージおよびバンドルの概念に対応する 3 つのスキーマ (olm.package
、olm.channel
および olm.bundle
) を使用します。
カタログの各 Operator パッケージには、olm.package
Blob が 1 つ (少なくとも olm.channel
Blob 1 つ、および 1 つ以上の olm.bundle
Blob) が必要です。
olm.*
スキーマは OLM 定義スキーマ用に予約されています。カスタムスキーマには、所有しているドメインなど、一意の接頭辞を使用する必要があります。
4.1.3.1. olm.package スキーマ リンクのコピーリンクがクリップボードにコピーされました!
olm.package
スキーマは Operator のパッケージレベルのメタデータを定義します。これには、名前、説明、デフォルトのチャネル、およびアイコンが含まれます。
例4.1 olm.package
スキーマ
4.1.3.2. olm.channel スキーマ リンクのコピーリンクがクリップボードにコピーされました!
olm.channel
スキーマは、パッケージ内のチャネル、チャネルのメンバーであるバンドルエントリー、およびそのバンドルのアップグレードパスを定義します。
バンドルエントリーが複数の olm.channel
Blob 内のエッジを表す場合、バンドルエントリーはチャネルごとに 1 つだけ指定できます。
エントリーの replaces
値が、このカタログにも別のカタログにも存在しない別のバンドル名を参照していても、有効とされます。ただし、他のすべてのチャネルの普遍条件に該当する必要があります (チャネルに複数のヘッドがない場合など)。
例4.2 olm.channel
スキーマ
skipRange
フィールドを使用すると、スキップされた Operator バージョンが更新グラフからプルーニングされ、ユーザーが Subscription
オブジェクトの spec.startingCSV
プロパティーを使用してそのバージョンをインストールできなくなります。
skipRange
フィールドと replaces
フィールドの両方を使用すると、以前にインストールしたバージョンをユーザーが将来インストールできるように維持しながら、Operator を段階的に更新できます。replaces
フィールドが当該 Operator バージョンの直前のバージョンを参照していることを確認してください。
4.1.3.3. olm.bundle スキーマ リンクのコピーリンクがクリップボードにコピーされました!
例4.3 olm.bundle
スキーマ
4.1.3.4. olm.deprecations スキーマ リンクのコピーリンクがクリップボードにコピーされました!
オプションの olm.deprecations
スキーマは、カタログ内のパッケージ、バンドル、チャネルの非推奨情報を定義します。Operator の作成者は、このスキーマを使用して、サポートステータスや推奨アップグレードパスなど、Operator に関する関連メッセージを、カタログから Operator を実行しているユーザーに提供できます。
このスキーマが定義されている場合、OpenShift Container Platform の Web コンソールで、OperatorHub のインストール前ページとインストール後ページの両方に、カスタムの非推奨メッセージを含め、Operator の影響を受ける要素に対する警告バッジが表示されます。
olm.deprecations
スキーマエントリーには、非推奨の範囲を示す次の reference
タイプが 1 つ以上含まれています。Operator がインストールされると、指定されたメッセージが、関連する Subscription
オブジェクトのステータス状況として表示されます。
型 | スコープ | ステータス状況 |
---|---|---|
| パッケージ全体を表します。 |
|
| 1 つのチャンネルを表します。 |
|
| 1 つのバンドルバージョンを表します。 |
|
次の例で詳しく説明するように、各 reference
タイプには独自の要件があります。
例4.4 各 reference
タイプを使用した olm.deprecations
スキーマの例
- 1
- 各非推奨スキーマには
package
値が必要であり、そのパッケージ参照はカタログ全体で一意である必要があります。関連するname
フィールドを含めることはできません。 - 2
olm.package
スキーマにname
フィールドを含めることはできません。このフィールドは、スキーマ内で前に定義したpackage
フィールドによって決定されるためです。- 3
- すべての
message
フィールドは、reference
タイプを問わず、長さが 0 以外である必要があり、不透明なテキスト Blob として表す必要があります。 - 4
olm.channel
スキーマのname
フィールドは必須です。- 5
olm.bundle
スキーマのname
フィールドは必須です。
非推奨機能では、パッケージ、チャネル、バンドルなど、重複する非推奨は考慮されません。
Operator の作成者は、olm.deprecations
スキーマエントリーを deprecations.yaml
ファイルとしてパッケージの index.yaml
ファイルと同じディレクトリーに保存できます。
非推奨を含むカタログのディレクトリー構造の例
my-catalog └── my-operator ├── index.yaml └── deprecations.yaml
my-catalog
└── my-operator
├── index.yaml
└── deprecations.yaml
4.1.4. プロパティー リンクのコピーリンクがクリップボードにコピーされました!
プロパティーは、ファイルベースのカタログスキーマに追加できる任意のメタデータです。type
フィールドは、value
フィールドのセマンティックおよび構文上の意味を効果的に指定する文字列です。値には任意の JSON または YAML を使用できます。
OLM は、予約済みの olm.*
接頭辞をもう一度使用して、いくつかのプロパティータイプを定義します。
4.1.4.1. olm.package プロパティー リンクのコピーリンクがクリップボードにコピーされました!
olm.package
プロパティーは、パッケージ名とバージョンを定義します。これはバンドルの必須プロパティーであり、これらのプロパティーが 1 つ必要です。packageName
フィールドはバンドルのファーストクラス package
フィールドと同じでなければならず、version
フィールドは有効なセマンティクスバージョンである必要があります。
例4.5 olm.package
プロパティー
4.1.4.2. olm.gvk プロパティー リンクのコピーリンクがクリップボードにコピーされました!
olm.gvk
プロパティーは、このバンドルで提供される Kubernetes API の group/version/kind(GVK) を定義します。このプロパティーは、OLM が使用して、必須の API と同じ GVK をリストする他のバンドルの依存関係として、このプロパティーでバンドルを解決します。GVK は Kubernetes GVK の検証に準拠する必要があります。
例4.6 olm.gvk
プロパティー
4.1.4.3. olm.package.required リンクのコピーリンクがクリップボードにコピーされました!
olm.package.required
プロパティーは、このバンドルが必要な別のパッケージのパッケージ名とバージョン範囲を定義します。バンドルにリストされている必要なパッケージプロパティーごとに、OLM は、リストされているパッケージのクラスターに必要なバージョン範囲で Operator がインストールされていることを確認します。versionRange
フィールドは有効なセマンティクスバージョン (semver) の範囲である必要があります。
例4.7 olm.package.required
プロパティー
4.1.4.4. olm.gvk.required リンクのコピーリンクがクリップボードにコピーされました!
olm.gvk.required
プロパティーは、このバンドルが必要とする Kubernetes API の group/version/kind(GVK) を定義します。バンドルにリストされている必要な GVK プロパティーごとに、OLM は、提供する Operator がクラスターにインストールされていることを確認します。GVK は Kubernetes GVK の検証に準拠する必要があります。
例4.8 olm.gvk.required
プロパティー
4.1.5. カタログの例 リンクのコピーリンクがクリップボードにコピーされました!
ファイルベースのカタログを使用すると、カタログメンテナーは Operator のキュレーションおよび互換性に集中できます。Operator の作成者は Operator 用に Operator 固有のカタログをすでに生成しているので、カタログメンテナーは、各 Operator カタログをカタログのルートディレクトリーのサブディレクトリーにレンダリングしてビルドできます。
ファイルベースのカタログをビルドする方法は多数あります。以下の手順は、単純なアプローチの概要を示しています。
カタログの設定ファイルを 1 つ維持し、カタログ内に Operator ごとにイメージの参照を含めます。
カタログ設定ファイルのサンプル
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 設定ファイルを解析し、その参照から新規カタログを作成するスクリプトを実行します。
スクリプトの例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.1.6. ガイドライン リンクのコピーリンクがクリップボードにコピーされました!
ファイルベースのカタログを維持する場合には、以下のガイドラインを考慮してください。
4.1.6.1. イミュータブルなバンドル リンクのコピーリンクがクリップボードにコピーされました!
Operator Lifecycle Manager(OLM) に関する一般的なアドバイスとして、バンドルイメージとそのメタデータをイミュータブルとして処理する必要がある点があります。
破損したバンドルがカタログにプッシュされている場合には、少なくとも 1 人のユーザーがそのバンドルにアップグレードしたと想定する必要があります。このような想定に基づいて、破損したバンドルをインストールしたユーザーがアップグレードを確実に受け取れるように、破損したバンドルのアップグレードパスを使用して別のバンドルをリリースする必要があります。OLM は、カタログでバンドルの内容が更新された場合に、インストールされたバンドルは再インストールされません。
ただし、カタログメタデータの変更が推奨される場合があります。
-
チャネルプロモーション: バンドルをすでにリリースし、後で別のチャネルに追加することにした場合は、バンドルのエントリーを別の
olm.channel
Blob に追加できます。 -
新規アップグレードパス:
1.2.z
バンドルバージョンを新たにリリースしたが (例:1.2.4
)、1.3.0
がすでにリリースされている場合は、1.2.4
をスキップするように1.3.0
のカタログメタデータを更新できます。
4.1.6.2. ソース制御 リンクのコピーリンクがクリップボードにコピーされました!
カタログメタデータはソースコントロールに保存され、信頼できる情報源として処理される必要があります。以下の手順で、カタログイメージを更新する必要があります。
- ソース制御されたカタログディレクトリーを新規コミットを使用して更新します。
-
カタログイメージをビルドし、プッシュします。ユーザーがカタログが利用可能になり次第更新を受信できるように、一貫性のあるタグ付け (
:latest
or:<target_cluster_version>
) を使用します。
4.1.7. CLI の使用 リンクのコピーリンクがクリップボードにコピーされました!
opm
CLI を使用してファイルベースのカタログを作成する手順の詳細は、カスタムカタログの管理 を参照してください。
ファイルベースのカタログの管理に関連する opm
CLI コマンドの参考情報は、CLI ツール を参照してください。
4.1.8. 自動化 リンクのコピーリンクがクリップボードにコピーされました!
Operator の作成者およびカタログメンテナーは、CI/CD ワークフローを使用してカタログのメンテナンスを自動化することが推奨されます。カタログメンテナーは、GitOps 自動化をビルドして以下のタスクを実行し、これをさらに向上させることができます。
- パッケージのイメージ参照の更新など、プル要求 (PR) の作成者が要求された変更を実行できることを確認します。
-
カタログの更新で
opm validate
コマンドが指定されていることを確認します。 - 更新されたバンドルまたはカタログイメージの参照が存在し、カタログイメージがクラスターで正常に実行され、そのパッケージの Operator が正常にインストールされることを確認します。
- 以前のチェックに合格した PR を自動的にマージします。
- カタログイメージを自動的にもう一度ビルドして公開します。