5.8. バンドルイメージの使用
Operator Lifecycle Manager (OLM) で使用するためのバンドル形式で Operator をパッケージ化してデプロイし、アップグレードするには、Operator SDK を使用できます。
5.8.1. Operator のバンドル
Operator Bundle Format は、Operator SDK および Operator Lifecycle Manager (OLM) のデフォルトパッケージ方法です。Operator SDK を使用して OLM に対して Operator を準備し、バンドルイメージをとして Operator プロジェクトをビルドしてプッシュできます。
前提条件
- 開発ワークステーションに Operator SDK CLI がインストールされていること。
-
OpenShift CLI (
oc
) v4.9+ がインストールされていること。 - Operator プロジェクトが Operator SDK を使用して初期化されていること。
- Operator が Go ベースの場合、プロジェクトを更新して OpenShift Container Platform での実行をサポートするイメージを使用する必要がある。
手順
以下の
make
コマンドを Operator プロジェクトディレクトリーで実行し、Operator イメージをビルドし、プッシュします。以下の手順のIMG
引数を変更して、アクセス可能なリポジトリーを参照します。Quay.io などのリポジトリーサイトにコンテナーを保存するためのアカウントを取得できます。イメージをビルドします。
$ make docker-build IMG=<registry>/<user>/<operator_image_name>:<tag>
注記Operator の SDK によって生成される Dockerfile は、
go build
についてGOARCH=amd64
を明示的に参照します。これは、AMD64 アーキテクチャー以外の場合はGOARCH=$TARGETARCH
に修正できます。Docker は、-platform
で指定された値に環境変数を自動的に設定します。Buildah では、そのために-build-arg
を使用する必要があります。詳細は、Multiple Architectures を参照してください。イメージをリポジトリーにプッシュします。
$ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag>
Operator SDK
generate bundle
およびbundle validate
のサブコマンドを含む複数のコマンドを呼び出すmake bundle
コマンドを実行し、Operator バンドルマニフェストを作成します。$ make bundle IMG=<registry>/<user>/<operator_image_name>:<tag>
Operator のバンドルマニフェストは、アプリケーションを表示し、作成し、管理する方法を説明します。
make bundle
コマンドは、以下のファイルおよびディレクトリーを Operator プロジェクトに作成します。-
ClusterServiceVersion
オブジェクトを含むbundle/manifests
という名前のバンドルマニフェストディレクトリー -
bundle/metadata
という名前のバンドルメタデータディレクトリー -
config/crd
ディレクトリー内のすべてのカスタムリソース定義 (CRD) -
Dockerfile
bundle.Dockerfile
続いて、これらのファイルは
operator-sdk bundle validate
を使用して自動的に検証され、ディスク上のバンドル表現が正しいことを確認します。-
以下のコマンドを実行し、バンドルイメージをビルドしてプッシュします。OLM は、1 つ以上のバンドルイメージを参照するインデックスイメージを使用して Operator バンドルを使用します。
バンドルイメージをビルドします。イメージをプッシュしようとするレジストリー、ユーザー namespace、およびイメージタグの詳細で
BUNDLE_IMG
を設定します。$ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>
バンドルイメージをプッシュします。
$ docker push <registry>/<user>/<bundle_image_name>:<tag>
5.8.2. Operator Lifecycle Manager を使用した Operator のデプロイ
Operator Lifecycle Manager (OLM) は、Kubernetes クラスターで Operator (およびそれらの関連サービス) をインストールし、更新し、ライフサイクルを管理するのに役立ちます。OLM はデフォルトで OpenShift Container Platform にインストールされ、Kubernetes 拡張として実行されるため、追加のツールなしにすべての Operator のライフサイクル管理機能に Web コンソールおよび OpenShift CLI (oc
) を使用できます。
Operator Bundle Format は、Operator SDK および OLM のデフォルトパッケージ方法です。Operator SDK を使用して OLM でバンドルイメージを迅速に実行し、適切に実行されるようにできます。
前提条件
- 開発ワークステーションに Operator SDK CLI がインストールされていること。
- ビルドされ、レジストリーにプッシュされる Operator バンドルイメージ。
-
(OpenShift Container Platform 4.9 など、
apiextensions.k8s.io/v1
CRD を使用する場合は v1.16.0 以降の) Kubernetes ベースのクラスターに OLM がインストールされていること。 -
cluster-admin
パーミッションのあるアカウントを使用してoc
でクラスターへログインしていること。 - Operator が Go ベースの場合、プロジェクトを更新して OpenShift Container Platform での実行をサポートするイメージを使用する必要がある。
手順
以下のコマンドを入力してクラスターで Operator を実行します。
$ operator-sdk run bundle \ [-n <namespace>] \1 <registry>/<user>/<bundle_image_name>:<tag>
- 1
- デフォルトで、このコマンドは
~/.kube/config
ファイルの現在アクティブなプロジェクトに Operator をインストールします。-n
フラグを追加して、インストールに異なる namespace スコープを設定できます。
このコマンドにより、以下のアクションが行われます。
- バンドルイメージをインジェクトしてインデックスイメージを作成します。インデックスイメージは不透明で一時的なものですが、バンドルを実稼働環境でカタログに追加する方法を正確に反映します。
- 新規インデックスイメージを参照するカタログソースを作成します。これにより、OperatorHub が Operator を検出できるようになります。
-
OperatorGroup
、Subscription
、InstallPlan
、および RBAC を含むその他の必要なオブジェクトすべてを作成して、Operator をクラスターにデプロイします。
5.8.3. バンドルされた Operator を含むカタログの公開
Operator をインストールおよび管理するには、Operator Lifecycle Manager (OLM) では、Operator バンドルがクラスターのカタログで参照されるインデックスイメージに一覧表示される必要があります。Operator の作成者は、Operator SDK を使用して Operator のバンドルおよびそれらのすべての依存関係を含むインデックスを作成できます。これは、リモートクラスターでのテストおよびコンテナーレジストリーへの公開に役立ちます。
Operator SDK は opm
CLI を使用してインデックスイメージの作成を容易にします。opm
コマンドの経験は必要ありません。高度なユースケースでは、Operator SDK を使用せずに、opm
コマンドを直接使用できます。
前提条件
- 開発ワークステーションに Operator SDK CLI がインストールされていること。
- ビルドされ、レジストリーにプッシュされる Operator バンドルイメージ。
-
(OpenShift Container Platform 4.9 など、
apiextensions.k8s.io/v1
CRD を使用する場合は v1.16.0 以降の) Kubernetes ベースのクラスターに OLM がインストールされていること。 -
cluster-admin
パーミッションのあるアカウントを使用してoc
でクラスターへログインしていること。
手順
以下の
make
コマンドを Operator プロジェクトディレクトリーで実行し、Operator バンドルを含むインデックスイメージをビルドします。$ make catalog-build CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>
ここでは、
CATALOG_IMG
引数は、アクセス権限のあるリポジトリーを参照します。Quay.io などのリポジトリーサイトにコンテナーを保存するためのアカウントを取得できます。ビルドしたインデックスイメージをリポジトリーにプッシュします。
$ make catalog-push CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>
ヒント複数のアクションを順番にまとめて実行する場合には、Operator SDK の
make
コマンドを併用できます。たとえば、Operator プロジェクトのバンドルイメージをビルドしていない場合は、以下の構文でバンドルイメージとインデックスイメージの両方をビルドしてプッシュできます。$ make bundle-build bundle-push catalog-build catalog-push \ BUNDLE_IMG=<bundle_image_pull_spec> \ CATALOG_IMG=<index_image_pull_spec>
または、
Makefile
のIMAGE_TAG_BASE
フィールドを既存のリポジトリーに設定できます。IMAGE_TAG_BASE=quay.io/example/my-operator
次に、以下の構文を使用して、バンドルイメージ用の
quay.io/example/my-operator-bundle:v0.0.1
およびquay.io/example/my-operator-catalog:v0.0.1
など、自動生成される名前でイメージをビルドおよびプッシュできます。$ make bundle-build bundle-push catalog-build catalog-push
生成したインデックスイメージを参照する
CatalogSource
オブジェクトを定義して、oc apply
コマンドまたは Web コンソールを使用してオブジェクトを作成します。CatalogSource
YAML の例apiVersion: operators.coreos.com/v1alpha1 kind: CatalogSource metadata: name: cs-memcached namespace: default spec: displayName: My Test publisher: Company sourceType: grpc image: quay.io/example/memcached-catalog:v0.0.1 1 updateStrategy: registryPoll: interval: 10m
- 1
CATALOG_IMG
引数を使用して、image
を以前に使用したイメージプル仕様に設定します。
カタログソースを確認します。
$ oc get catalogsource
出力例
NAME DISPLAY TYPE PUBLISHER AGE cs-memcached My Test grpc Company 4h31m
検証
カタログを使用して Operator をインストールします。
oc apply
コマンドまたは Web コンソールを使用して、OperatorGroup
オブジェクトを定義して作成します。OperatorGroup
YAML の例apiVersion: operators.coreos.com/v1 kind: OperatorGroup metadata: name: my-test namespace: default spec: targetNamespaces: - default
oc apply
コマンドまたは Web コンソールを使用して、Subscription
オブジェクトを定義して作成します。サブスクリプション
YAML の例apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: catalogtest namespace: default spec: channel: "alpha" installPlanApproval: Manual name: catalog source: cs-memcached sourceNamespace: default startingCSV: memcached-operator.v0.0.1
インストールされた Operator が実行されていることを確認します。
Operator グループを確認します。
$ oc get og
出力例
NAME AGE my-test 4h40m
クラスターサービスバージョン (CSV) を確認します。
$ oc get csv
出力例
NAME DISPLAY VERSION REPLACES PHASE memcached-operator.v0.0.1 Test 0.0.1 Succeeded
Operator の Pod を確認します。
$ oc get pods
出力例
NAME READY STATUS RESTARTS AGE 9098d908802769fbde8bd45255e69710a9f8420a8f3d814abe88b68f8ervdj6 0/1 Completed 0 4h33m catalog-controller-manager-7fd5b7b987-69s4n 2/2 Running 0 4h32m cs-memcached-7622r 1/1 Running 0 4h33m
関連情報
-
高度なユースケースの
opm
CLI の直接使用に関する詳細は、カスタムカタログの管理 を参照してください。
5.8.4. Operator Lifecycle Manager での Operator アップグレードのテスト
インデックスイメージおよびカタログソースを手動で管理しなくても、Operator SDK で Operator Lifecycle Manager (OLM) 統合を使用して Operator のアップグレードを迅速にテストできます。
run bundle-upgrade
サブコマンドは、より新しいバージョンのバンドルイメージを指定することにより、インストールされた Operator をトリガーしてそのバージョンにアップグレードするプロセスを自動化します。
前提条件
-
run bundle
サブコマンドを使用するか、または従来の OLM インストールを使用して、Operator を OLM でと合わせてインストールしておく - インストールされた Operator のより新しいバージョンを表すバンドルイメージ
手順
Operator が OLM でまだインストールしていない場合は、
run bundle
サブコマンドまたは従来の OLM インストールを使用して、以前のバージョンの Operator をインストールします。注記以前のバージョンのバンドルが従来 OLM を使用してインストールされている場合には、アップグレード予定の新しいバンドルは、カタログソースで参照されるインデックスイメージ内に含めることはできません。含めてしまっている場合には、
run bundle-upgrade
サブコマンドを実行すると、新しいバンドルがパッケージおよびクラスターサービスバージョン (CSV) を提供するインデックスですでに参照されているので、レジストリー Pod が失敗します。たとえば、前述のバンドルイメージを指定して、Memcached Operator 用に以下の
run bundle
サブコマンドを使用できます。$ operator-sdk run bundle <registry>/<user>/memcached-operator:v0.0.1
出力例
INFO[0009] Successfully created registry pod: quay-io-demo-memcached-operator-v0-0-1 INFO[0009] Created CatalogSource: memcached-operator-catalog INFO[0010] OperatorGroup "operator-sdk-og" created INFO[0010] Created Subscription: memcached-operator-v0-0-1-sub INFO[0013] Approved InstallPlan install-bqggr for the Subscription: memcached-operator-v0-0-1-sub INFO[0013] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to reach 'Succeeded' phase INFO[0013] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to appear INFO[0019] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Succeeded
Operator のより新しいバージョンのバンドルイメージを指定して、インストールされた Operator をアップグレードします。
$ operator-sdk run bundle-upgrade <registry>/<user>/memcached-operator:v0.0.2
出力例
INFO[0002] Found existing subscription with name memcached-operator-v0-0-1-sub and namespace my-project INFO[0002] Found existing catalog source with name memcached-operator-catalog and namespace my-project INFO[0009] Successfully created registry pod: quay-io-demo-memcached-operator-v0-0-2 INFO[0009] Updated catalog source memcached-operator-catalog with address and annotations INFO[0010] Deleted previous registry pod with name "quay-io-demo-memcached-operator-v0-0-1" INFO[0041] Approved InstallPlan install-gvcjh for the Subscription: memcached-operator-v0-0-1-sub INFO[0042] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.2" to reach 'Succeeded' phase INFO[0042] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: InstallReady INFO[0043] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Installing INFO[0044] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Succeeded INFO[0044] Successfully upgraded to "memcached-operator.v0.0.2"
インストールされた Operator のクリーンアップ
$ operator-sdk cleanup memcached-operator
5.8.5. OpenShift Container Platform バージョンとの Operator 互換性の制御
Kubernetes は、今後のリリースで削除される特定の API を定期的に非推奨にします。Operator が非推奨の API を使用している場合、OpenShift Container Platform クラスターを API が削除された Kubernetes バージョンにアップグレードした後に機能しない可能性があります。
Operator の作成者は、Kubernetes ドキュメントの 旧版の API 移行ガイド を確認し、非推奨および削除済みの API が使用されないように Operator プロジェクトを最新の状態に維持することが強く推奨されます。理想的には、OpenShift Container Platform の今後のバージョンでは Operator の互換性が失われるので今後のバージョンがリリースされる前に Operator を更新することをお勧めします。
API が OpenShift Container Platform バージョンから削除されると、削除された API を依然として使用しているクラスターバージョンで実行されている Operator が適切に機能しなくなります。Operator の作成者は、Operator ユーザーの中断を回避するために、API の非推奨および削除に対応するように Operator プロジェクトを更新する計画を立てる必要があります。
Operator のイベントアラートを確認して、現在使用中の API に関する警告があるかどうかをチェックできます。次のリリースで削除される API が検出されると、以下のアラートが表示されます。
APIRemovedInNextReleaseInUse
- 今後の OpenShift Container Platform リリースで削除される API。
APIRemovedInNextEUSReleaseInUse
- 次の OpenShift Container Platform Extended Update Support (EUS) リリースで削除される API。
クラスター管理者が Operator をインストールしている場合に、OpenShift Container Platform の次のバージョンにアップグレードする前に、そのクラスターのバージョンと互換性がある Operator のバージョンがインストールされていることを確認する必要があります。Operator プロジェクトを更新して非推奨または削除済みの API を使用しないようにすることが推奨されますが、OpenShift Container Platform の以前のバージョンを引き続き使用して 削除済みの API で Operator バンドルを公開する必要がある場合には、バンドルが正しく設定されていることを確認します。
以下の手順では、管理者が互換性のないバージョンの OpenShift Container Platform に Operator をインストールできないようにするのに役立ちます。これらの手順では、管理者が、クラスターに現在インストールされている Operator のバージョンと互換性のない OpenShift Container Platform のバージョンにアップグレードできないようにします。
この手順は、Operator の現行バージョンが、何らかの理由で特定の OpenShift Container Platform バージョンで適切に機能しないことがわかっている場合にも役立ちます。Operator の配信先のクラスターバージョンを定義することで、許可された範囲外のクラスターバージョンのカタログに Operator が表示されないようにします。
非推奨の API を使用する Operator は、クラスター管理者が API がサポートされなくなった OpenShift Container Platform の将来のバージョンにアップグレードする際に、重大なワークロードに悪影響を及ぼす可能性があります。Operator が非推奨の API を使用している場合は、できるだけ早く Operator プロジェクトで以下の設定を指定する必要があります。
前提条件
- 既存の Operator プロジェクト
手順
Operator の特定のバンドルはサポートされておらず、特定のクラスターバージョンよりも後の OpenShift Container Platform で正常に機能しない場合は、Operator と互換性のある OpenShift Container Platform の最大バージョンを設定します。Operator プロジェクトのクラスターサービスバージョン (CSV) で
olm.maxOpenShiftVersion
アノテーションを設定して、インストールされている Operator を互換性のあるバージョンにアップグレードする前に、管理者がクラスターをアップグレードできないようにします。重要Operator バンドルバージョンが新しいバージョンで機能しない場合にのみ、
olm.maxOpenShiftVersion
アノテーションを使用する必要があります。クラスター管理者は、ソリューションがインストールされている状態でクラスターをアップグレードできないことに注意してください。新しいバージョンおよび有効なアップグレードパスを指定しない場合、クラスター管理者は Operator をアンインストールし、クラスターのバージョンをアップグレードできます。olm.maxOpenShiftVersion
アノテーションを含む CSV の例apiVersion: operators.coreos.com/v1alpha1 kind: ClusterServiceVersion metadata: annotations: "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "<cluster_version>"}]' 1
- 1
- Operator と互換性がある OpenShift Container Platform の最大クラスターバージョンを指定します。たとえば、
value
を4.9
に設定すると、このバンドルがクラスターにインストールされている場合、クラスターが OpenShift Container Platform 4.9 より後のバージョンにアップグレードされなくなります。
バンドルが Red Hat 提供の Operator カタログでのディストリビューション向けの場合には、以下のプロパティーを設定して、Operator の OpenShift Container Platform を互換性のあるバージョンに設定します。この設定では、Operator は互換性のある OpenShift Container Platform のバージョンを対象とするカタログにだけ含まれます。
注記この手順は、Red Hat が提供するカタログに Operator を公開する場合にのみ有効です。バンドルがカスタムカタログのディストリビューションのみを目的としている場合には、この手順を省略できます。詳細は、Red Hat が提供する Operator カタログについてを参照してください。
プロジェクトの
bundle/metadata/annotations.yaml
ファイルにcom.redhat.openshift.versions
アノテーションを設定します。互換性のあるバージョンを含む
bundle/metadata/annotations.yaml
ファイルの例com.redhat.openshift.versions: "v4.7-v4.9" 1
- 1
- 範囲または単一バージョンに設定します。
バンドルが互換性のないバージョンの OpenShift Container Platform に引き継がれないようにするには、Operator バンドルイメージで適切な
com.redhat.openshift.versions
ラベルを使用してインデックスイメージが生成されていることを確認します。たとえば、プロジェクトが Operator SDK を使用して生成された場合は、bundle.Dockerfile
ファイルを更新してください。互換性のあるバージョンを含む
bundle.Dockerfile
の例LABEL com.redhat.openshift.versions="<versions>" 1
- 1
- 範囲または単一バージョンに設定します (例:
v4.7-v4.9
)。この設定は、Operator を配信する必要があるクラスターのバージョンを定義し、Operator は、範囲外にあるクラスターバージョンのカタログに表示されません。
Operator の新規バージョンをバンドルして、更新バージョンをカタログに公開して配布できるようになりました。
関連情報
- Certified Operator Build Guide の Managing OpenShift Versions
- インストール済み Operator の更新
- Red Hat が提供する Operator カタログ
5.8.6. 関連情報
- Bundle Format の詳細は、Operator Framework パッケージ形式 を参照してください。
-
opm
コマンドを使用してバンドルイメージをインデックスイメージに追加する方法の詳細は、カスタムカタログの管理 を参照してください。 - インストールされた Operator のアップグレードの仕組みについての詳細は、Operator Lifecycle Manager ワークフロー を参照してください。