5.8. バンドルイメージの使用

手順

1. 以下の make コマンドを Operator プロジェクトディレクトリーで実行し、Operator イメージをビルドし、プッシュします。以下の手順の IMG 引数を変更して、アクセス可能なリポジトリーを参照します。Quay.io などのリポジトリーサイトにコンテナーを保存するためのアカウントを取得できます。

   1. イメージをビルドします。

      $ 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 を参照してください。

   2. イメージをリポジトリーにプッシュします。

      $ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag>

2. 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 を使用して自動的に検証され、ディスク上のバンドル表現が正しいことを確認します。

3. 以下のコマンドを実行し、バンドルイメージをビルドしてプッシュします。OLM は、1 つ以上のバンドルイメージを参照するインデックスイメージを使用して Operator バンドルを使用します。

   1. バンドルイメージをビルドします。イメージをプッシュしようとするレジストリー、ユーザー namespace、およびイメージタグの詳細で BUNDLE_IMG を設定します。

      $ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>

   2. バンドルイメージをプッシュします。

      $ docker push <registry>/<user>/<bundle_image_name>:<tag>

手順

1. 以下のコマンドを入力してクラスターで Operator を実行します。

   $ operator-sdk run bundle \1
       -n <namespace> \2
       <registry>/<user>/<bundle_image_name>:<tag> 3

   1

   run bundle コマンドは、有効なファイルベースのカタログを作成し、OLM を使用して Operator バンドルをクラスターにインストールします。

   2

   オプション: デフォルトで、このコマンドは ~/.kube/config ファイルの現在アクティブなプロジェクトに Operator をインストールします。-n フラグを追加して、インストールに異なる namespace スコープを設定できます。

   3

   イメージを指定しない場合、コマンドは quay.io/operator-framework/opm:latest をデフォルトのインデックスイメージとして使用します。イメージを指定した場合は、コマンドはバンドルイメージ自体をインデックスイメージとして使用します。

   重要

   OpenShift Container Platform 4.11 の時点で、Operator カタログに関して、run bundle コマンドはデフォルトでファイルベースのカタログ形式をサポートします。Operator カタログに関して、非推奨の SQLite データベース形式は引き続きサポートされますが、今後のリリースで削除される予定です。Operator の作成者はワークフローをファイルベースのカタログ形式に移行することが推奨されます。

   このコマンドにより、以下のアクションが行われます。

   • バンドルイメージをインジェクトしてインデックスイメージを作成します。インデックスイメージは不透明で一時的なものですが、バンドルを実稼働環境でカタログに追加する方法を正確に反映します。
   • 新規インデックスイメージを参照するカタログソースを作成します。これにより、OperatorHub が Operator を検出できるようになります。
   • OperatorGroup、Subscription、InstallPlan、および RBAC を含むその他の必要なリソースすべてを作成して、Operator をクラスターにデプロイします。

手順

1. 以下の make コマンドを Operator プロジェクトディレクトリーで実行し、Operator バンドルを含むインデックスイメージをビルドします。

   $ make catalog-build CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>

   ここでは、CATALOG_IMG 引数は、アクセス権限のあるリポジトリーを参照します。Quay.io などのリポジトリーサイトにコンテナーを保存するためのアカウントを取得できます。

2. ビルドしたインデックスイメージをリポジトリーにプッシュします。

   $ 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

3. 生成したインデックスイメージを参照する CatalogSource オブジェクトを定義して、oc apply コマンドまたは Web コンソールを使用してオブジェクトを作成します。

   CatalogSource YAML の例

   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
     name: cs-memcached
     namespace: <operator_namespace>
   spec:
     displayName: My Test
     publisher: Company
     sourceType: grpc
     grpcPodConfig:
       securityContextConfig: <security_mode> 1
     image: quay.io/example/memcached-catalog:v0.0.1 2
     updateStrategy:
       registryPoll:
         interval: 10m

   1

   legacy または restricted の値を指定します。フィールドが設定されていない場合、デフォルト値は legacy です。今後の OpenShift Container Platform リリースでは、デフォルト値が restricted になる予定です。restricted 権限でカタログを実行できない場合は、このフィールドを手動で legacy に設定することを推奨します。

   2

   CATALOG_IMG 引数を使用して、image を以前に使用したイメージプル仕様に設定します。

4. カタログソースを確認します。

   $ oc get catalogsource

   出力例

   NAME           DISPLAY     TYPE   PUBLISHER   AGE
   cs-memcached   My Test     grpc   Company     4h31m

検証

1. カタログを使用して Operator をインストールします。

   1. oc apply コマンドまたは Web コンソールを使用して、OperatorGroup オブジェクトを定義して作成します。

      OperatorGroup YAML の例

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: my-test
        namespace: <operator_namespace>
      spec:
        targetNamespaces:
        - <operator_namespace>

   2. oc apply コマンドまたは Web コンソールを使用して、Subscription オブジェクトを定義して作成します。

      サブスクリプション YAML の例

      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: catalogtest
        namespace: <catalog_namespace>
      spec:
        channel: "alpha"
        installPlanApproval: Manual
        name: catalog
        source: cs-memcached
        sourceNamespace: <operator_namespace>
        startingCSV: memcached-operator.v0.0.1

2. インストールされた Operator が実行されていることを確認します。

   1. Operator グループを確認します。

      $ oc get og

      出力例

      NAME             AGE
      my-test           4h40m

   2. クラスターサービスバージョン (CSV) を確認します。

      $ oc get csv

      出力例

      NAME                        DISPLAY   VERSION   REPLACES   PHASE
      memcached-operator.v0.0.1   Test      0.0.1                Succeeded

   3. 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

手順

1. 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[0006] Creating a File-Based Catalog of the bundle "quay.io/demo/memcached-operator:v0.0.1"
   INFO[0008] Generated a valid File-Based Catalog
   INFO[0012] Created registry pod: quay-io-demo-memcached-operator-v1-0-1
   INFO[0012] Created CatalogSource: memcached-operator-catalog
   INFO[0012] OperatorGroup "operator-sdk-og" created
   INFO[0012] Created Subscription: memcached-operator-v0-0-1-sub
   INFO[0015] Approved InstallPlan install-h9666 for the Subscription: memcached-operator-v0-0-1-sub
   INFO[0015] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to reach 'Succeeded' phase
   INFO[0015] Waiting for ClusterServiceVersion ""my-project/memcached-operator.v0.0.1" to appear
   INFO[0026] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Pending
   INFO[0028] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Installing
   INFO[0059] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Succeeded
   INFO[0059] OLM has successfully installed "memcached-operator.v0.0.1"

2. 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[0008] Generated a valid Upgraded File-Based Catalog
   INFO[0009] 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[0019] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Pending
   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"

3. インストール済み Operator のクリーンアップ

   $ operator-sdk cleanup memcached-operator

手順

1. 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 より後のバージョンにアップグレードされなくなります。

2. バンドルが Red Hat 提供の Operator カタログでのディストリビューション向けの場合には、以下のプロパティーを設定して、Operator の OpenShift Container Platform を互換性のあるバージョンに設定します。この設定では、Operator は互換性のある OpenShift Container Platform のバージョンを対象とするカタログにだけ含まれます。

   注記

   この手順は、Red Hat が提供するカタログに Operator を公開する場合にのみ有効です。バンドルがカスタムカタログのディストリビューションのみを目的としている場合には、この手順を省略できます。詳細は、Red Hat が提供する Operator カタログについてを参照してください。

   1. プロジェクトの bundle/metadata/annotations.yaml ファイルに com.redhat.openshift.versions アノテーションを設定します。

      互換性のあるバージョンを含む bundle/metadata/annotations.yaml ファイルの例

      com.redhat.openshift.versions: "v4.7-v4.9" 1

      1

      範囲または単一バージョンに設定します。

   2. バンドルが互換性のないバージョンの 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 は、範囲外にあるクラスターバージョンのカタログに表示されません。