サポートコンソール開発者トライアルの開始お問い合わせ

第4章 カタログ

4.1. ファイルベースのカタログ

重要

Operator Lifecycle Manager (OLM) v1 はテクノロジープレビュー機能です。テクノロジープレビュー機能は、Red Hat 製品サポートのサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではない場合があります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。

Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。

OpenShift Container Platform の Operator Lifecycle Manager (OLM) v1 は、クラスター上のクラスター拡張機能 (Operator を含む) を検出および取得するために使用する ファイルベースのカタログ をサポートします。

重要

現在、Operator Lifecycle Manager (OLM) v1 は、Red Hat が提供する Operator カタログなどのプライベートレジストリーを認証できません。これは既知の問題です。その結果、Red Hat Operators カタログがインストールされていることを前提とする OLM v1 の手順は機能しません。(OCPBUGS-36364)

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 ファイル

# Ignore everything except non-object .json and .yaml files
**/*
!*.json
!*.yaml
**/objects/*.json
**/objects/*.yaml

カタログメンテナーは、必要なレイアウトを柔軟に選択できますが、各パッケージのファイルベースのカタログ Blob は別々のサブディレクトリーに保管することを推奨します。個々のファイルは JSON または YAML のいずれかをしようしてください。カタログ内のすべてのファイルが同じ形式を使用する必要はありません。

推奨される基本構造

catalog
├── packageA
│   └── index.yaml
├── packageB
│   ├── .indexignore
│   ├── index.yaml
│   └── objects
│       └── packageB.v0.1.0.clusterserviceversion.yaml
└── packageC
    └── index.json
    └── deprecations.yaml

この推奨の構造には、ディレクトリー階層内の各サブディレクトリーは自己完結型のカタログであるという特性があるので、カタログの作成、検出、およびナビゲーションなどのファイルシステムの操作が簡素化されます。このカタログは、親カタログのルートディレクトリーにコピーして親カタログに追加することもできます。

4.1.3. スキーマ

ファイルベースのカタログは、任意のスキーマで拡張できる CUE 言語仕様 に基づく形式を使用します。以下の _Meta CUE スキーマは、すべてのファイルベースのカタログ Blob が順守する必要のある形式を定義します。

_Meta スキーマ

_Meta: {
  // schema is required and must be a non-empty string
  schema: string & !=""

  // package is optional, but if it's defined, it must be a non-empty string
  package?: string & !=""

  // properties is optional, but if it's defined, it must be a list of 0 or more properties
  properties?: [... #Property]
}

#Property: {
  // type is required
  type: string & !=""

  // value is required, and it must not be null
  value: !=null
}

注記

この仕様にリストされている 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 スキーマ

#Package: {
  schema: "olm.package"

  // Package name
  name: string & !=""

  // A description of the package
  description?: string

  // The package's default channel
  defaultChannel: string & !=""

  // An optional icon
  icon?: {
    base64data: string
    mediatype:  string
  }
}

4.1.3.2. olm.channel スキーマ

olm.channel スキーマは、パッケージ内のチャネル、チャネルのメンバーであるバンドルエントリー、およびそれらのバンドルのアップグレードエッジを定義します。

バンドルエントリーが複数の olm.channel Blob 内のエッジを表す場合、バンドルエントリーはチャネルごとに 1 つだけ指定できます。

エントリーの replaces 値が、このカタログにも別のカタログにも存在しない別のバンドル名を参照していても、有効とされます。ただし、他のすべてのチャネルの普遍条件に該当する必要があります (チャネルに複数のヘッドがない場合など)。

例4.2 olm.channel スキーマ

#Channel: {
  schema: "olm.channel"
  package: string & !=""
  name: string & !=""
  entries: [...#ChannelEntry]
}

#ChannelEntry: {
  // name is required. It is the name of an `olm.bundle` that
  // is present in the channel.
  name: string & !=""

  // replaces is optional. It is the name of bundle that is replaced
  // by this entry. It does not have to be present in the entry list.
  replaces?: string & !=""

  // skips is optional. It is a list of bundle names that are skipped by
  // this entry. The skipped bundles do not have to be present in the
  // entry list.
  skips?: [...string & !=""]

  // skipRange is optional. It is the semver range of bundle versions
  // that are skipped by this entry.
  skipRange?: string & !=""
}
警告

skipRange フィールドを使用すると、スキップされた Operator バージョンが更新グラフからプルーニングされ、ユーザーが Subscription オブジェクトの spec.startingCSV プロパティーを使用してそのバージョンをインストールできなくなります。

skipRange フィールドと replaces フィールドの両方を使用すると、以前にインストールしたバージョンをユーザーが将来インストールできるように維持しながら、Operator を段階的に更新できます。replaces フィールドが当該 Operator バージョンの直前のバージョンを参照していることを確認してください。

4.1.3.3. olm.bundle スキーマ

例4.3 olm.bundle スキーマ

#Bundle: {
  schema: "olm.bundle"
  package: string & !=""
  name: string & !=""
  image: string & !=""
  properties: [...#Property]
  relatedImages?: [...#RelatedImage]
}

#Property: {
  // type is required
  type: string & !=""

  // value is required, and it must not be null
  value: !=null
}

#RelatedImage: {
  // image is the image reference
  image: string & !=""

  // name is an optional descriptive name for an image that
  // helps identify its purpose in the context of the bundle
  name?: string & !=""
}

4.1.3.4. olm.deprecations スキーマ

オプションの olm.deprecations スキーマは、カタログ内のパッケージ、バンドル、チャネルの非推奨情報を定義します。Operator の作成者は、このスキーマを使用して、サポートステータスや推奨アップグレードパスなど、Operator に関する関連メッセージを、カタログから Operator を実行しているユーザーに提供できます。

このスキーマが定義されている場合、OpenShift Container Platform の Web コンソールで、OperatorHub のインストール前ページとインストール後ページの両方に、カスタムの非推奨メッセージを含め、Operator の影響を受ける要素に対する警告バッジが表示されます。

olm.deprecations スキーマエントリーには、非推奨の範囲を示す次の reference タイプが 1 つ以上含まれています。Operator がインストールされると、指定されたメッセージが、関連する Subscription オブジェクトのステータス状況として表示されます。

表4.1 非推奨の reference タイプ
タイプScopeステータス状況

olm.package

パッケージ全体を表します。

PackageDeprecated

olm.channel

1 つのチャンネルを表します。

ChannelDeprecated

olm.bundle

1 つのバンドルバージョンを表します。

BundleDeprecated

次の例で詳しく説明するように、各 reference タイプには独自の要件があります。

例4.4 各 reference タイプを使用した olm.deprecations スキーマの例

schema: olm.deprecations
package: my-operator 1
entries:
  - reference:
      schema: olm.package 2
    message: | 3
    The 'my-operator' package is end of life. Please use the
    'my-operator-new' package for support.
  - reference:
      schema: olm.channel
      name: alpha 4
    message: |
    The 'alpha' channel is no longer supported. Please switch to the
    'stable' channel.
  - reference:
      schema: olm.bundle
      name: my-operator.v1.68.0 5
    message: |
    my-operator.v1.68.0 is deprecated. Uninstall my-operator.v1.68.0 and
    install my-operator.v1.72.0 for support.
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

関連情報

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 プロパティー

#PropertyPackage: {
  type: "olm.package"
  value: {
    packageName: string & !=""
    version: string & !=""
  }
}

4.1.4.2. olm.gvk プロパティー

olm.gvk プロパティーは、このバンドルで提供される Kubernetes API の group/version/kind(GVK) を定義します。このプロパティーは、OLM が使用して、必須の API と同じ GVK をリストする他のバンドルの依存関係として、このプロパティーでバンドルを解決します。GVK は Kubernetes GVK の検証に準拠する必要があります。

例4.6 olm.gvk プロパティー

#PropertyGVK: {
  type: "olm.gvk"
  value: {
    group: string & !=""
    version: string & !=""
    kind: string & !=""
  }
}

4.1.4.3. olm.package.required

olm.package.required プロパティーは、このバンドルが必要な別のパッケージのパッケージ名とバージョン範囲を定義します。バンドルにリストされている必要なパッケージプロパティーごとに、OLM は、リストされているパッケージのクラスターに必要なバージョン範囲で Operator がインストールされていることを確認します。versionRange フィールドは有効なセマンティクスバージョン (semver) の範囲である必要があります。

例4.7 olm.package.required プロパティー

#PropertyPackageRequired: {
  type: "olm.package.required"
  value: {
    packageName: string & !=""
    versionRange: string & !=""
  }
}

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 プロパティー

#PropertyGVKRequired: {
  type: "olm.gvk.required"
  value: {
    group: string & !=""
    version: string & !=""
    kind: string & !=""
  }
}

4.1.5. カタログの例

ファイルベースのカタログを使用すると、カタログメンテナーは Operator のキュレーションおよび互換性に集中できます。Operator の作成者は Operator 用に Operator 固有のカタログをすでに生成しているので、カタログメンテナーは、各 Operator カタログをカタログのルートディレクトリーのサブディレクトリーにレンダリングしてビルドできます。

ファイルベースのカタログをビルドする方法は多数あります。以下の手順は、単純なアプローチの概要を示しています。

  1. カタログの設定ファイルを 1 つ維持し、カタログ内に Operator ごとにイメージの参照を含めます。

    カタログ設定ファイルのサンプル

    name: community-operators
repo: quay.io/community-operators/catalog
tag: latest
references:
- name: etcd-operator
  image: quay.io/etcd-operator/index@sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
- name: prometheus-operator
  image: quay.io/prometheus-operator/index@sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317

  2. 設定ファイルを解析し、その参照から新規カタログを作成するスクリプトを実行します。

    スクリプトの例

    name=$(yq eval '.name' catalog.yaml)
mkdir "$name"
yq eval '.name + "/" + .references[].name' catalog.yaml | xargs mkdir
for l in $(yq e '.name as $catalog | .references[] | .image + "|" + $catalog + "/" + .name + "/index.yaml"' catalog.yaml); do
  image=$(echo $l | cut -d'|' -f1)
  file=$(echo $l | cut -d'|' -f2)
  opm render "$image" > "$file"
done
opm generate dockerfile "$name"
indexImage=$(yq eval '.repo + ":" + .tag' catalog.yaml)
docker build -t "$indexImage" -f "$name.Dockerfile" .
docker push "$indexImage"

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. ソース制御

カタログメタデータはソースコントロールに保存され、信頼できる情報源として処理される必要があります。以下の手順で、カタログイメージを更新する必要があります。

  1. ソース制御されたカタログディレクトリーを新規コミットを使用して更新します。
  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 を自動的にマージします。
  • カタログイメージを自動的にもう一度ビルドして公開します。
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.