5.4. Ansible ベース Operator

5.4.1. Ansible ベースの Operator の Operator SDK の使用を開始する

Operator プロジェクトを生成するための Operator SDK には、Go コードを作成せずに Kubernetes リソースを統一されたアプリケーションとしてデプロイするために、既存の Ansible Playbook およびモジュールを使用するオプションがあります。

Operator SDK によって提供されるツールおよびライブラリーを使用して Ansible ベースの Operator をセットアップし、実行するための基本を示すには、Operator 開発者は Ansible ベースの Memcached Operator のサンプルをビルドして、分散キー/値のストアを作成し、クラスターへデプロイすることができます。

5.4.1.1. 前提条件

  • Operator SDK CLI がインストールされていること。
  • OpenShift CLI (oc) v4.12 以降がインストールされている
  • Ansible v2.9.0
  • Ansible Runner v2.0.2+
  • Ansible Runner HTTP Event Emitter プラグイン v1.0.0+
  • Python 3.8.6 以降
  • OpenShift Python クライアント v0.12.0 以降
  • cluster-admin パーミッションを持つアカウントを使用して、oc で OpenShift Container Platform 4.12 クラスターにログインしている
  • クラスターがイメージをプルできるようにするには、イメージをプッシュするリポジトリーを public として設定するか、イメージプルシークレットを設定する必要があります。

5.4.1.2. Ansible ベース Operator の作成およびデプロイ

Operator SDK を使用して、Memcached の単純な Ansible ベースの Operator をビルドし、デプロイできます。

手順

  1. プロジェクトを作成します。

    1. プロジェクトディレクトリーを作成します。

      $ mkdir memcached-operator
    2. プロジェクトディレクトリーに移動します。

      $ cd memcached-operator
    3. ansible プラグインを指定して operator-sdk init コマンドを実行し、プロジェクトを初期化します。

      $ operator-sdk init \
          --plugins=ansible \
          --domain=example.com
  2. API を作成します。

    単純な Memcached API を作成します。

    $ operator-sdk create api \
        --group cache \
        --version v1 \
        --kind Memcached \
        --generate-role 1
    1
    API の Ansible ロールを生成します。
  3. Operator イメージをビルドし、プッシュします。

    デフォルトの Makefile ターゲットを使用して Operator をビルドし、プッシュします。プッシュ先となるレジストリーを使用するイメージのプル仕様を使用して IMG を設定します。

    $ make docker-build docker-push IMG=<registry>/<user>/<image_name>:<tag>
  4. Operator を実行します。

    1. CRD をインストールします。

      $ make install
    2. プロジェクトをクラスターにデプロイします。IMG をプッシュしたイメージに設定します。

      $ make deploy IMG=<registry>/<user>/<image_name>:<tag>
  5. サンプルカスタムリソース (CR) を作成します。

    1. サンプル CR を作成します。

      $ oc apply -f config/samples/cache_v1_memcached.yaml \
          -n memcached-operator-system
    2. Operator を調整する CR を確認します。

      $ oc logs deployment.apps/memcached-operator-controller-manager \
          -c manager \
          -n memcached-operator-system

      出力例

      ...
      I0205 17:48:45.881666       7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator
      {"level":"info","ts":1612547325.8819902,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
      {"level":"info","ts":1612547325.98242,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
      {"level":"info","ts":1612547325.9824686,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4}
      {"level":"info","ts":1612547348.8311093,"logger":"runner","msg":"Ansible-runner exited successfully","job":"4037200794235010051","name":"memcached-sample","namespace":"memcached-operator-system"}

  6. CR を削除する

    次のコマンドを実行して CR を削除します。

    $ oc delete -f config/samples/cache_v1_memcached.yaml -n memcached-operator-system
  7. クリーンアップします。

    以下のコマンドを実行して、この手順の一部として作成されたリソースをクリーンアップします。

    $ make undeploy

5.4.1.3. 次のステップ

5.4.2. Ansible ベース Operator の Operator SDK チュートリアル

Operator 開発者は、Operator SDK での Ansible のサポートを利用して、Ansible ベースの Memcached Operator のサンプルをビルドして、分散キー/値のストアを作成し、そのライフサイクルを管理することができます。このチュートリアルでは、以下のプロセスについて説明します。

  • Memcached デプロイメントを作成します。
  • デプロイメントのサイズが、Memcached カスタムリソース (CR) 仕様で指定されたものと同じであることを確認します。
  • ステータスライターを使用して、Memcached CR ステータスを memcached Pod の名前で更新します。

このプロセスは、Operator Framework の 2 つの重要な設定要素を使用して実行されます。

Operator SDK
operator-sdk CLI ツールおよび controller-runtime ライブラリー API
Operator Lifecycle Manager (OLM)
クラスター上の Operator のインストール、アップグレード、ロールベースのアクセス制御 (RBAC)
注記

このチュートリアルでは、Ansible ベースの Operator の Operator SDK の使用を開始する よりも詳細に説明します。

5.4.2.1. 前提条件

  • Operator SDK CLI がインストールされていること。
  • OpenShift CLI (oc) v4.12 以降がインストールされている
  • Ansible v2.9.0
  • Ansible Runner v2.0.2+
  • Ansible Runner HTTP Event Emitter プラグイン v1.0.0+
  • Python 3.8.6 以降
  • OpenShift Python クライアント v0.12.0 以降
  • cluster-admin パーミッションを持つアカウントを使用して、oc で OpenShift Container Platform 4.12 クラスターにログインしている
  • クラスターがイメージをプルできるようにするには、イメージをプッシュするリポジトリーを public として設定するか、イメージプルシークレットを設定する必要があります。

5.4.2.2. プロジェクトの作成

Operator SDK CLI を使用して memcached-operator というプロジェクトを作成します。

手順

  1. プロジェクトのディレクトリーを作成します。

    $ mkdir -p $HOME/projects/memcached-operator
  2. ディレクトリーに切り替えます。

    $ cd $HOME/projects/memcached-operator
  3. ansible プラグインを指定して operator-sdk init コマンドを実行し、プロジェクトを初期化します。

    $ operator-sdk init \
        --plugins=ansible \
        --domain=example.com
5.4.2.2.1. PROJECT ファイル

operator-sdk init コマンドで生成されるファイルの 1 つに、Kubebuilder の PROJECT ファイルがあります。プロジェクトルートから実行される後続の operator-sdk コマンドおよび help 出力は、このファイルを読み取り、プロジェクトタイプが Ansible であることを認識しています。以下に例を示します。

domain: example.com
layout:
- ansible.sdk.operatorframework.io/v1
plugins:
  manifests.sdk.operatorframework.io/v2: {}
  scorecard.sdk.operatorframework.io/v2: {}
  sdk.x-openshift.io/v1: {}
projectName: memcached-operator
version: "3"

5.4.2.3. API の作成

Operator SDK CLI を使用して Memcached API を作成します。

手順

  • 以下のコマンドを実行して、グループ cache、バージョン、v1、および種類 Memcached を指定して API を作成します。

    $ operator-sdk create api \
        --group cache \
        --version v1 \
        --kind Memcached \
        --generate-role 1
    1
    API の Ansible ロールを生成します。

API の作成後に、Operator プロジェクトは以下の構造で更新します。

Memcached CRD
サンプル Memcached リソースが含まれます。
Manager

以下を使用して、クラスターの状態を必要な状態に調整するプログラム。

  • reconciler (Ansible ロールまたは Playbook のいずれか)
  • Memcached リソースを memcached Ansible ロールに接続する watches.yaml ファイル

5.4.2.4. マネージャーの変更

Operator プロジェクトを更新して、Ansible ロールの形式で reconcile ロジックを提供します。これは、Memcached リソースが作成、更新、または削除されるたびに実行されます。

手順

  1. roles/memcached/tasks/main.yml ファイルを以下の構造で更新します。

    ---
    - name: start memcached
      k8s:
        definition:
          kind: Deployment
          apiVersion: apps/v1
          metadata:
            name: '{{ ansible_operator_meta.name }}-memcached'
            namespace: '{{ ansible_operator_meta.namespace }}'
          spec:
            replicas: "{{size}}"
            selector:
              matchLabels:
                app: memcached
            template:
              metadata:
                labels:
                  app: memcached
              spec:
                containers:
                - name: memcached
                  command:
                  - memcached
                  - -m=64
                  - -o
                  - modern
                  - -v
                  image: "docker.io/memcached:1.4.36-alpine"
                  ports:
                    - containerPort: 11211

    この memcached ロールは、memcached デプロイメントが存在することを確実にし、デプロイメントサイズを設定します。

  2. roles/memcached/defaults/main.yml ファイルを編集して、Ansible ロールで使用される変数のデフォルト値を設定します。

    ---
    # defaults file for Memcached
    size: 1
  3. 以下の構造で、config/samples/cache_v1_memcached.yaml ファイルの Memcached サンプルリソースを更新します。

    apiVersion: cache.example.com/v1
    kind: Memcached
    metadata:
      labels:
        app.kubernetes.io/name: memcached
        app.kubernetes.io/instance: memcached-sample
        app.kubernetes.io/part-of: memcached-operator
        app.kubernetes.io/managed-by: kustomize
        app.kubernetes.io/created-by: memcached-operator
      name: memcached-sample
    spec:
      size: 3

    カスタムリソース (CR) 仕様のキー/値のペアは、追加の変数として Ansible に渡されます。

注記

spec フィールドのすべての変数の名前は、Ansible の実行前に Operator によってスネークケース (小文字 + アンダースコア) に変換されます。たとえば、仕様の serviceAccount は Ansible では service_account になります。

watches.yaml ファイルで snakeCaseParameters オプションを false に設定して、このケース変換を無効にすることができます。Ansible で変数についてのタイプの検証を実行し、アプリケーションが予想される入力を受信していることを確認することが推奨されます。

5.4.2.5. プロキシーサポートの有効化

Operator の作成者は、ネットワークプロキシーをサポートする Operator を開発できるようになりました。クラスター管理者は、Operator Lifecycle Manager (OLM) によって処理される環境変数のプロキシーサポートを設定します。Operator は以下の標準プロキシー変数の環境を検査し、値をオペランドに渡して、プロキシーされたクラスターをサポートする必要があります。

  • HTTP_PROXY
  • HTTPS_PROXY
  • NO_PROXY
注記

このチュートリアルでは、HTTP_PROXY を環境変数の例として使用します。

前提条件

  • クラスター全体の egress プロキシーが有効にされているクラスター。

手順

  1. 以下で roles/memcached/tasks/main.yml ファイルを更新して、環境変数をデプロイメントに追加します。

    ...
    env:
       - name: HTTP_PROXY
         value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
       - name: http_proxy
         value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
    ...
  2. 以下を config/manager/manager.yaml ファイルに追加して、Operator デプロイメントに環境変数を設定します。

    containers:
     - args:
       - --leader-elect
       - --leader-election-id=ansible-proxy-demo
       image: controller:latest
       name: manager
       env:
         - name: "HTTP_PROXY"
           value: "http_proxy_test"

5.4.2.6. Operator の実行

Operator SDK CLI を使用して Operator をビルドし、実行する方法は 3 つあります。

  • クラスター外で Go プログラムとしてローカルに実行します。
  • クラスター上のデプロイメントとして実行します。
  • Operator をバンドルし、Operator Lifecycle Manager (OLM) を使用してクラスター上にデプロイします。
5.4.2.6.1. クラスター外でローカルに実行する。

Operator プロジェクトをクラスター外の Go プログラムとして実行できます。これは、デプロイメントとテストを迅速化するという開発目的において便利です。

手順

  • 以下のコマンドを実行して、~/.kube/config ファイルに設定されたクラスターにカスタムリソース定義 (CRD) をインストールし、Operator をローカルで実行します。

    $ make install run

    出力例

    ...
    {"level":"info","ts":1612589622.7888272,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
    {"level":"info","ts":1612589622.7897573,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
    {"level":"info","ts":1612589622.789971,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
    {"level":"info","ts":1612589622.7899997,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
    {"level":"info","ts":1612589622.8904517,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
    {"level":"info","ts":1612589622.8905244,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}

5.4.2.6.2. クラスター上でのデプロイメントとしての実行

Operator プロジェクトは、クラスター上でデプロイメントとして実行できます。

手順

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

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

      $ make docker-build IMG=<registry>/<user>/<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>/<image_name>:<tag>
      注記

      両方のコマンドのイメージの名前とタグ (例: IMG=<registry>/<user>/<image_name>:<tag>) を Makefile に設定することもできます。IMG ?= controller:latest の値を変更して、デフォルトのイメージ名を設定します。

  2. 以下のコマンドを実行して Operator をデプロイします。

    $ make deploy IMG=<registry>/<user>/<image_name>:<tag>

    デフォルトで、このコマンドは <project_name>-system の形式で Operator プロジェクトの名前で namespace を作成し、デプロイメントに使用します。このコマンドは、config/rbac から RBAC マニフェストもインストールします。

  3. 以下のコマンドを実行して、Operator が実行されていることを確認します。

    $ oc get deployment -n <project_name>-system

    出力例

    NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
    <project_name>-controller-manager       1/1     1            1           8m

5.4.2.6.3. Operator のバンドルおよび Operator Lifecycle Manager を使用したデプロイ
5.4.2.6.3.1. Operator のバンドル

Operator Bundle Format は、Operator SDK および Operator Lifecycle Manager (OLM) のデフォルトパッケージ方法です。Operator SDK を使用して OLM に対して Operator を準備し、バンドルイメージをとして Operator プロジェクトをビルドしてプッシュできます。

前提条件

  • 開発ワークステーションに Operator SDK CLI がインストールされていること。
  • OpenShift CLI (oc) v4.12 以降がインストールされている
  • Operator プロジェクトが Operator SDK を使用して初期化されていること。

手順

  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>
5.4.2.6.3.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.12 など、apiextensions.k8s.io/v1 CRD を使用する場合は v1.16.0 以降の) Kubernetes ベースのクラスターに OLM がインストールされていること。
  • cluster-admin パーミッションのあるアカウントを使用して oc でクラスターへログインしていること。

手順

  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 を検出できるようになります。
    • OperatorGroupSubscriptionInstallPlan、および RBAC を含むその他の必要なリソースすべてを作成して、Operator をクラスターにデプロイします。

5.4.2.7. カスタムリソースの作成

Operator のインストール後に、Operator によってクラスターに提供されるカスタムリソース (CR) を作成して、これをテストできます。

前提条件

  • クラスターにインストールされている Memcached CR を提供する Memcached Operator の例

手順

  1. Operator がインストールされている namespace へ変更します。たとえば、make deploy コマンドを使用して Operator をデプロイした場合は、以下のようになります。

    $ oc project memcached-operator-system
  2. config/samples/cache_v1_memcached.yamlMemcached CR マニフェストのサンプルを編集し、以下の仕様が含まれるようにします。

    apiVersion: cache.example.com/v1
    kind: Memcached
    metadata:
      name: memcached-sample
    ...
    spec:
    ...
      size: 3
  3. CR を作成します。

    $ oc apply -f config/samples/cache_v1_memcached.yaml
  4. Memcached Operator が、正しいサイズで CR サンプルのデプロイメントを作成することを確認します。

    $ oc get deployments

    出力例

    NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
    memcached-operator-controller-manager   1/1     1            1           8m
    memcached-sample                        3/3     3            3           1m

  5. ステータスが Memcached Pod 名で更新されていることを確認するために、Pod および CR ステータスを確認します。

    1. Pod を確認します。

      $ oc get pods

      出力例

      NAME                                  READY     STATUS    RESTARTS   AGE
      memcached-sample-6fd7c98d8-7dqdr      1/1       Running   0          1m
      memcached-sample-6fd7c98d8-g5k7v      1/1       Running   0          1m
      memcached-sample-6fd7c98d8-m7vn7      1/1       Running   0          1m

    2. CR ステータスを確認します。

      $ oc get memcached/memcached-sample -o yaml

      出力例

      apiVersion: cache.example.com/v1
      kind: Memcached
      metadata:
      ...
        name: memcached-sample
      ...
      spec:
        size: 3
      status:
        nodes:
        - memcached-sample-6fd7c98d8-7dqdr
        - memcached-sample-6fd7c98d8-g5k7v
        - memcached-sample-6fd7c98d8-m7vn7

  6. デプロイメントサイズを更新します。

    1. config/samples/cache_v1_memcached.yaml ファイルを更新し、Memcached CR の spec.size フィールドを 3 から 5 に変更します。

      $ oc patch memcached memcached-sample \
          -p '{"spec":{"size": 5}}' \
          --type=merge
    2. Operator がデプロイメントサイズを変更することを確認します。

      $ oc get deployments

      出力例

      NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
      memcached-operator-controller-manager   1/1     1            1           10m
      memcached-sample                        5/5     5            5           3m

  7. 次のコマンドを実行して CR を削除します。

    $ oc delete -f config/samples/cache_v1_memcached.yaml
  8. このチュートリアルの一環として作成したリソースをクリーンアップします。

    • Operator のテストに make deploy コマンドを使用した場合は、以下のコマンドを実行します。

      $ make undeploy
    • Operator のテストに operator-sdk run bundle コマンドを使用した場合は、以下のコマンドを実行します。

      $ operator-sdk cleanup <project_name>

5.4.2.8. 関連情報

5.4.3. Ansible ベース Operator のプロジェクトレイアウト

operator-sdk CLI は、各 Operator プロジェクトに多数のパッケージおよびファイルを生成、または スキャフォールディング することができます。

5.4.3.1. Ansible ベースのプロジェクトレイアウト

operator-sdk init --plugins ansible コマンドを使用して生成される Ansible ベースの Operator プロジェクトには、以下のディレクトリーおよびファイルが含まれます。

ファイルまたはディレクトリー目的

Dockerfile

Operator のコンテナーイメージをビルドするための Dockerfile。

Makefile

Operator バイナリーをラップするコンテナーイメージのビルド、公開、デプロイに使用するターゲット、およびカスタムリソース定義 (CRD) のインストールおよびアンインストールに使用するターゲット。

PROJECT

Operator のメタデータ情報が含まれる YAML ファイル。

config/crd

ベース CRD ファイルおよび kustomization.yaml ファイルの設定。

config/default

デプロイメント用のすべての Operator マニフェストを収集します。make deploy コマンドを使用します。

config/manager

コントローラーマネージャーデプロイメント。

config/prometheus

Operator をモニタリングするための ServiceMonitor リソース。

config/rbac

リーダー選択および認証プロキシーのロールとロールバインディング。

config/samples

CRD 用に作成されたサンプルリソース。

config/testing

テスト用の設定例。

playbooks/

実行する Playbook のサブディレクトリー。

roles/

実行するロールツリーのサブディレクトリー。

watches.yaml

監視するリソースの group/version/kind (GVK) および Ansible 呼び出しメソッド。新しいエントリーは、create api コマンドを使用して追加します。

requirements.yml

ビルド時にインストールする Ansible コレクションおよびロールの依存関係が含まれる YAML ファイル。

molecule/

ロールおよび Operator のエンドツーエンドのテストを行う Molecule シナリオ。

5.4.4. 新しい Operator SDK バージョンのプロジェクトのアップグレード

OpenShift Container Platform 4.12 は Operator SDK 1.25.4 をサポートします。ワークステーションに 1.28.0 CLI がすでにインストールされている場合は、最新バージョンをインストール して CLI を 1.31.0 に更新できます。

ただし、既存の Operator プロジェクトが Operator SDK 1.25.4 との互換性を維持するには、1.22.2 以降に導入された関連する重大な変更に対し、更新手順を実行する必要があります。アップグレードの手順は、以前は 1.22.2 で作成または維持されている Operator プロジェクトのいずれかで手動で実行する必要があります。

5.4.4.1. Operator SDK 1.25.4 の Ansible ベースの Operator プロジェクトの更新

次の手順では、1.25.4 との互換性を確保するため、既存の Ansible ベースの Operator プロジェクトを更新します。

前提条件

  • Operator SDK 1.25.4 がインストールされている
  • Operator SDK 1.22.2 で作成または保守されている Operator プロジェクト

手順

  1. config/default/manager_auth_proxy_patch.yaml ファイルに以下の変更を加えます。

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: controller-manager
      namespace: system
    spec:
      template:
        spec:
          containers:
          - name: kube-rbac-proxy
            image: registry.redhat.io/openshift4/ose-kube-rbac-proxy:v4.12 1
            args:
            - "--secure-listen-address=0.0.0.0:8443"
            - "--upstream=http://127.0.0.1:8080/"
            - "--logtostderr=true"
            - "--v=0"
    ...
    1
    タグバージョンを v4.11 から v4.12 に更新します。
  2. Makefile に以下の変更を加えます。

    1. マルチアーキテクチャービルドサポートを有効にするには、docker-buildx ターゲットをプロジェクトの Makefile に追加します。

      Makefile の例

      # PLATFORMS defines the target platforms for  the manager image be build to provide support to multiple
      # architectures. (i.e. make docker-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
      # - able to use docker buildx . More info: https://docs.docker.com/build/buildx/
      # - have enable BuildKit, More info: https://docs.docker.com/develop/develop-images/build_enhancements/
      # - be able to push the image for your registry (i.e. if you do not inform a valid value via IMG=<myregistry/image:<tag>> than the export will fail)
      # To properly provided solutions that supports more than one platform you should use this option.
      PLATFORMS ?= linux/arm64,linux/amd64,linux/s390x,linux/ppc64le
      .PHONY: docker-buildx
      docker-buildx: test ## Build and push docker image for the manager for cross-platform support
      	# copy existing Dockerfile and insert --platform=${BUILDPLATFORM} into Dockerfile.cross, and preserve the original Dockerfile
      	sed -e '1 s/\(^FROM\)/FROM --platform=\$$\{BUILDPLATFORM\}/; t' -e ' 1,// s//FROM --platform=\$$\{BUILDPLATFORM\}/' Dockerfile > Dockerfile.cross
      	- docker buildx create --name project-v3-builder
      	docker buildx use project-v3-builder
      	- docker buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile.cross
      	- docker buildx rm project-v3-builder
      	rm Dockerfile.cross

    2. Operator プロジェクトで 64 ビットのアーキテクチャーのサポートを有効にするには、Makefile に以下の変更を加えます。

      古い Makefile

      OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      ARCH := $(shell uname -m | sed 's/x86_64/amd64/')

      新しい Makefile

      OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      ARCH := $(shell uname -m | sed 's/x86_64/amd64/' |  sed 's/aarch64/arm64/')

    3. 次の例に示すように、Kustomize のバージョンを v4.5.5 に更新します。

      古い Makefile

      .PHONY: kustomize
      KUSTOMIZE = $(shell pwd)/bin/kustomize
      kustomize: ## Download kustomize locally if necessary.
      ifeq (,$(wildcard $(KUSTOMIZE)))
      ifeq (,$(shell which kustomize 2>/dev/null))
      	@{ \
      	set -e ;\
      	mkdir -p $(dir $(KUSTOMIZE)) ;\
      	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.8.7/kustomize_v3.8.7_$(OS)_$(ARCH).tar.gz | \
      	tar xzf - -C bin/ ;\
      	}
      else

      新しい Makefile

      .PHONY: kustomize
      KUSTOMIZE = $(shell pwd)/bin/kustomize
      kustomize: ## Download kustomize locally if necessary.
      ifeq (,$(wildcard $(KUSTOMIZE)))
      ifeq (,$(shell which kustomize 2>/dev/null))
      	@{ \
      	set -e ;\
      	mkdir -p $(dir $(KUSTOMIZE)) ;\
      	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v4.5.5/kustomize_v4.5.5_$(OS)_$(ARCH).tar.gz | \ 1
      	tar xzf - -C bin/ ;\
      	}
      else

      1
      バージョン v3.8.7v4.5.5 に更新します。
      重要

      Kustomize バージョン 4.0.0 では、go-getter プラグインが削除され、以前のバージョンとの下位互換性がない重大な変更が導入されました。古いバージョンの Kustomize に依存する Operator プロジェクトは、新しいリリースでは機能しない可能性があります。

    4. Makefile に変更を適用し、Operator を再構築するには、次のコマンドを入力します。

      $ make
  3. 次の例のとおり、Operator の Dockerfile 内のイメージタグを更新します。

    Dockerfile の例

    FROM registry.redhat.io/openshift4/ose-ansible-operator:v4.12 1

    1
    バージョンタグを v4.12 に更新します。
  4. 次の例に示すように、config/default/kustomizations.yaml ファイルを更新します。

    kustomizations.yaml ファイルの例

    # Adds namespace to all resources.
    namespace: memcached-operator-system
    # Value of this field is prepended to the
    # names of all resources, e.g. a deployment named
    # "wordpress" becomes "alices-wordpress".
    # Note that it should also match with the prefix (text before '-') of the namespace
    # field above.
    namePrefix: memcached-operator-
    
    # Labels to add to all resources and selectors.
    #labels: 1
    #- includeSelectors: true 2
    #  pairs:
    #    someName: someValue
    
    resources: 3
    - ../crd
    - ../rbac
    - ../manager

    1
    commonLabels フィールドを labels フィールドに置き換えます。
    2
    includeSelectors: true を追加します。
    3
    bases フィールドを resources フィールドに置き換えます。
  5. 次の変更を加えて、molecule/default/kustomize.yml ファイルを更新します。

    molecule/default/kustomize.yml ファイル例

    ---
    - name: Build kustomize testing overlay
      # load_restrictor must be set to none so we can load patch files from the default overlay
      command: '{{ kustomize }} build --load-restrictor LoadRestrictionsNone' 1
      args:
        chdir: '{{ config_dir }}/testing'
      register: resources
      changed_when: false

    1
    --load_restrictor none .--load-restrictor LoadRestrictionNone で置き換えます。

5.4.4.2. 関連情報

5.4.5. Operator SDK における Ansible サポート

5.4.5.1. カスタムリソースファイル

Operator は Kubernetes の拡張メカニズムであるカスタムリソース定義 (CRD) を使用するため、カスタムリソース (CR) は、組み込み済みのネイティブ Kubernetes オブジェクトのように表示され、機能します。

CR ファイル形式は Kubernetes リソースファイルです。オブジェクトには、必須およびオプションフィールドが含まれます。

表5.1 カスタムリソースフィールド

フィールド説明

apiVersion

作成される CR のバージョン。

kind

作成される CR の種類。

metadata

作成される Kubernetes 固有のメタデータ。

spec (オプション)

Ansible に渡される変数のキーと値のリスト。このフィールドは、デフォルトでは空です。

status

オブジェクトの現在の状態の概要を示します。Ansible ベースの Operator の場合、status サブリソース はデフォルトで CRD について有効にされ、operator_sdk.util.k8s_status Ansible モジュールによって管理されます。 これには、CR の status に対する condition 情報が含まれます。

annotations

CR に付加する Kubernetes 固有のアノテーション。

CR アノテーションの以下のリストは Operator の動作を変更します。

表5.2 Ansible ベースの Operator アノテーション

アノテーション説明

ansible.operator-sdk/reconcile-period

CR の調整間隔を指定します。この値は標準的な Golang パッケージ time を使用して解析されます。とくに、ParseDuration は、s のデフォルト接尾辞を適用し、秒単位で値を指定します。

Ansible ベースの Operator アノテーションの例

apiVersion: "test1.example.com/v1alpha1"
kind: "Test1"
metadata:
  name: "example"
annotations:
  ansible.operator-sdk/reconcile-period: "30s"

5.4.5.2. watches.yaml ファイル

group/version/kind(GVK) は Kubernetes API の一意の識別子です。watches.yaml ファイルには、その GVK によって特定される、カスタムリソース (CR) から Ansible ロールまたは Playbook へのマッピングのリストが含まれます。Operator はこのマッピングファイルが事前に定義された場所の /opt/ansible/watches.yaml にあることを予想します。

表5.3 watches.yaml ファイルのマッピング

フィールド説明

group

監視する CR のグループ。

version

監視する CR のバージョン。

kind

監視する CR の種類。

role (デフォルト)

コンテナーに追加される Ansible ロールへのパスです。たとえば、 roles ディレクトリーが /opt/ansible/roles/ にあり、ロールの名前が busybox の場合、この値は /opt/ansible/roles/busybox になります。このフィールドは playbook フィールドと相互に排他的です。

playbook

コンテナーに追加される Ansible Playbook へのパスです。この Playbook の使用はロールを呼び出す方法になります。このフィールドは role フィールドと相互に排他的です。

reconcilePeriod (オプション)

ロールまたは Playbook が特定の CR について実行される調整期間および頻度。

manageStatus (オプション)

true (デフォルト) に設定されると、Operator は CR のステータスを汎用的に管理します。false に設定されると、指定されたロール、または別のコントローラーの Playbook により、CR のステータスは他の場所で管理されます。

watches.yaml ファイルの例

- version: v1alpha1 1
  group: test1.example.com
  kind: Test1
  role: /opt/ansible/roles/Test1

- version: v1alpha1 2
  group: test2.example.com
  kind: Test2
  playbook: /opt/ansible/playbook.yml

- version: v1alpha1 3
  group: test3.example.com
  kind: Test3
  playbook: /opt/ansible/test3.yml
  reconcilePeriod: 0
  manageStatus: false

1
Test1test1 ロールへの単純なマッピングの例。
2
Test2 の Playbook への単純なマッピングの例。
3
Test3 の種類についてのより複雑な例。Playbook での CR ステータスを再度キューに入れるタスクまたはその管理を無効にします。
5.4.5.2.1. 高度なオプション

高度な機能は、それらを GVK ごとに watches.yaml ファイルに追加して有効にできます。それらは groupversionkind および playbook または role フィールドの下に移行できます。

一部の機能は、CR のアノテーションを使用してリソースごとに上書きできます。オーバーライドできるオプションには、以下に指定されるアノテーションが含まれます。

表5.4 高度な watches.yaml ファイルのオプション

機能YAML キー説明上書きのアノテーションデフォルト値

調整期間

reconcilePeriod

特定の CR についての調整実行の間隔。

ansible.operator-sdk/reconcile-period

1m

ステータスの管理

manageStatus

Operator は各 CR の status セクションの conditions セクションを管理できます。

 

true

依存するリソースの監視

watchDependentResources

Operator は Ansible によって作成されるリソースを動的に監視できます。

 

true

クラスタースコープのリソースの監視

watchClusterScopedResources

Operator は Ansible によって作成されるクラスタースコープのリソースを監視できます。

 

false

最大 Runner アーティファクト

maxRunnerArtifacts

Ansible Runner が各リソースについて Operator コンテナーに保持する アーティファクトディレクトリー の数を管理します。

ansible.operator-sdk/max-runner-artifacts

20

高度なオプションを含む watches.yml ファイルの例

- version: v1alpha1
  group: app.example.com
  kind: AppService
  playbook: /opt/ansible/playbook.yml
  maxRunnerArtifacts: 30
  reconcilePeriod: 5s
  manageStatus: False
  watchDependentResources: False

5.4.5.3. Ansible に送信される追加変数

追加の変数を Ansible に送信し、Operator で管理できます。カスタマーリソース (CR) の spec セクションでは追加変数としてキーと値のペアを渡します。これは、ansible-playbook コマンドに渡される追加変数と同等です。

また Operator は、CR の名前および CR の namespace についての meta フィールドの下に追加の変数を渡します。

以下は CR の例になります。

apiVersion: "app.example.com/v1alpha1"
kind: "Database"
metadata:
  name: "example"
spec:
  message: "Hello world 2"
  newParameter: "newParam"

追加変数として Ansible に渡される構造は以下のとおりです。

{ "meta": {
        "name": "<cr_name>",
        "namespace": "<cr_namespace>",
  },
  "message": "Hello world 2",
  "new_parameter": "newParam",
  "_app_example_com_database": {
     <full_crd>
   },
}

message および newParameter フィールドは追加変数として上部に設定され、meta は Operator に定義されるように CR の関連メタデータを提供します。meta フィールドは、Ansible のドット表記などを使用してアクセスできます。

---
- debug:
    msg: "name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}"

5.4.5.4. Ansible Runner ディレクトリー

Ansible Runner はコンテナーに Ansible 実行についての情報を維持します。これは /tmp/ansible-operator/runner/<group>/<version>/<kind>/<namespace>/<name> に置かれます。

関連情報

5.4.6. Kubernetes Collection for Ansible

Ansible を使用して Kubernetes でアプリケーションのライフサイクルを管理するには、Kubernetes Collection for Ansible を使用できます。この Ansible モジュールのコレクションにより、開発者は既存の Kubernetes リソースファイル (YAML で作成されている) を利用するか、ネイティブの Ansible でライフサイクル管理を表現することができます。

Ansible を既存の Kubernetes リソースファイルと併用する最大の利点の 1 つに、Ansible のいくつかを変数のみを使う単純な方法でのリソースのカスタマイズを可能にする Jinja テンプレートを使用できる点があります。

このセクションでは、Kubernetes コレクションの使用法を詳細に説明します。使用を開始するには、Playbook を使用してローカルワークステーションにコレクションをインストールし、これをテストしてから、Operator 内での使用を開始します。

5.4.6.1. Kubernetes Collection for Ansible のインストール

Kubernetes Collection for Ansible をローカルワークステーションにインストールできます。

手順

  1. Ansible 2.9+ をインストールします。

    $ sudo dnf install ansible
  2. OpenShift python クライアント パッケージをインストールします。

    $ pip3 install openshift
  3. 以下の方法のいずれかを使用して、Kubernetes コレクションをインストールします。

    • コレクションは、Ansible Galaxy から直接インストールできます。

      $ ansible-galaxy collection install community.kubernetes
    • Operator がすでに初期化されている場合は、プロジェクトのトップレベルに requirements.yml ファイルがあるかもしれません。このファイルは、Operator が機能するためにインストールする必要のある Ansible 依存関係を指定します。デフォルトで、このファイルは community.kubernetes コレクションと operator_sdk.util コレクションをインストールします。これは、Operator 固有の機能のモジュールおよびプラグインを提供します。

      requirements.yml ファイルから依存モジュールをインストールするには、以下を実行します。

      $ ansible-galaxy collection install -r requirements.yml

5.4.6.2. Kubernetes コレクションのローカルでのテスト

Operator 開発者は、毎回 Operator を実行し、再ビルドするのではなく、Ansible コードをローカルマシンから実行することができます。

前提条件

  • Ansible ベースの Operator プロジェクトを初期化し、Operator SDK を使用して、生成された Ansible ロールを持つ API を作成します。
  • Kubernetes Collection for Ansible をインストールします。

手順

  1. Ansible ベースの Operator プロジェクトディレクトリーで、必要な Ansible ロジックを使用して roles/<kind>/tasks/main.yml ファイルを変更します。roles/<kind>/ ディレクトリーは、API の作成時に --generate-role フラグを使用する場合に作成されます。<kind> を置き換え可能なものは、API に指定した kind と一致します。

    以下の例では、state という名前の変数の値に基づいた設定マップを作成し、削除します。

    ---
    - name: set ConfigMap example-config to {{ state }}
      community.kubernetes.k8s:
        api_version: v1
        kind: ConfigMap
        name: example-config
        namespace: <operator_namespace> 1
        state: "{{ state }}"
      ignore_errors: true 2
    1
    config map を作成する namespace を指定します。
    2
    ignore_errors: true を設定することにより、存在しない設定マップを削除しても失敗しません。
  2. デフォルトで statepresent に設定するように、roles/<kind>/defaults/main.yml ファイルを変更します。

    ---
    state: present
  3. プロジェクトディレクトリーのトップレベルに playbook.yml ファイルを作成して Ansible playbook を作成し、<kind> ロールを追加します。

    ---
    - hosts: localhost
      roles:
        - <kind>
  4. Playbook を実行します。

    $ ansible-playbook playbook.yml

    出力例

    [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
    
    PLAY [localhost] ********************************************************************************
    
    TASK [Gathering Facts] ********************************************************************************
    ok: [localhost]
    
    TASK [memcached : set ConfigMap example-config to present] ********************************************************************************
    changed: [localhost]
    
    PLAY RECAP ********************************************************************************
    localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

  5. 設定マップが作成されたことを確認します。

    $ oc get configmaps

    出力例

    NAME               DATA   AGE
    example-config     0      2m1s

  6. stateabsent に設定して Playbook を再実行します。

    $ ansible-playbook playbook.yml --extra-vars state=absent

    出力例

    [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
    
    PLAY [localhost] ********************************************************************************
    
    TASK [Gathering Facts] ********************************************************************************
    ok: [localhost]
    
    TASK [memcached : set ConfigMap example-config to absent] ********************************************************************************
    changed: [localhost]
    
    PLAY RECAP ********************************************************************************
    localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

  7. 設定マップが削除されたことを確認します。

    $ oc get configmaps

5.4.6.3. 次のステップ

  • カスタムリソース (CR) の変更時に、Operator 内でカスタム Ansible ロジックをトリガーする方法については、Operator 内での Ansible の使用 参照してください。

5.4.7. Operator 内での Ansible の使用

Kubernetes Collection for Ansible をローカルで使用すること に慣れたら、カスタムリソース (CR) の変更時に Operator 内で同じ Ansible ロジックをトリガーできます。この例では、Ansible ロールを、Operator が監視する特定の Kubernetes リソースにマップします。このマッピングは watches.yaml ファイルで実行されます。

5.4.7.1. カスタムリソースファイル

Operator は Kubernetes の拡張メカニズムであるカスタムリソース定義 (CRD) を使用するため、カスタムリソース (CR) は、組み込み済みのネイティブ Kubernetes オブジェクトのように表示され、機能します。

CR ファイル形式は Kubernetes リソースファイルです。オブジェクトには、必須およびオプションフィールドが含まれます。

表5.5 カスタムリソースフィールド

フィールド説明

apiVersion

作成される CR のバージョン。

kind

作成される CR の種類。

metadata

作成される Kubernetes 固有のメタデータ。

spec (オプション)

Ansible に渡される変数のキーと値のリスト。このフィールドは、デフォルトでは空です。

status

オブジェクトの現在の状態の概要を示します。Ansible ベースの Operator の場合、status サブリソース はデフォルトで CRD について有効にされ、operator_sdk.util.k8s_status Ansible モジュールによって管理されます。 これには、CR の status に対する condition 情報が含まれます。

annotations

CR に付加する Kubernetes 固有のアノテーション。

CR アノテーションの以下のリストは Operator の動作を変更します。

表5.6 Ansible ベースの Operator アノテーション

アノテーション説明

ansible.operator-sdk/reconcile-period

CR の調整間隔を指定します。この値は標準的な Golang パッケージ time を使用して解析されます。とくに、ParseDuration は、s のデフォルト接尾辞を適用し、秒単位で値を指定します。

Ansible ベースの Operator アノテーションの例

apiVersion: "test1.example.com/v1alpha1"
kind: "Test1"
metadata:
  name: "example"
annotations:
  ansible.operator-sdk/reconcile-period: "30s"

5.4.7.2. Ansible ベース Operator のローカルでのテスト

Operator プロジェクトのトップレベルディレクトリーから make run コマンドを使用して、ローカルで実行中の Ansible ベースの Operator 内でロジックをテストできます。make run Makefile ターゲットは、ansible-operator バイナリーをローカルで実行します。これは watches.yaml ファイルを読み取り、~/.kube/config ファイルを使用して k8s モジュールが実行するように Kubernetes クラスターと通信します。

注記

環境変数 ANSIBLE_ROLES_PATH を設定するか、ansible-roles-path フラグを使用して、ロールパスをカスタマイズすることができます。ロールが ANSIBLE_ROLES_PATH の値にない場合、Operator は {{current directory}}/roles で検索します。

前提条件

手順

  1. カスタムリソース定義 (CRD) およびカスタムリソース (CR) の適切なロールベースアクセス制御 (RBAC) 定義をインストールします。

    $ make install

    出力例

    /usr/bin/kustomize build config/crd | kubectl apply -f -
    customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created

  2. make run コマンドを実行します。

    $ make run

    出力例

    /home/user/memcached-operator/bin/ansible-operator run
    {"level":"info","ts":1612739145.2871568,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"}
    ...
    {"level":"info","ts":1612739148.347306,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"}
    {"level":"info","ts":1612739148.3488882,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2}
    {"level":"info","ts":1612739148.3490262,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false}
    {"level":"info","ts":1612739148.3490646,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
    {"level":"info","ts":1612739148.350217,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
    {"level":"info","ts":1612739148.3506632,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
    {"level":"info","ts":1612739148.350784,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
    {"level":"info","ts":1612739148.5511978,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
    {"level":"info","ts":1612739148.5512562,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}

    Operator が CR のイベントを監視していることから、CR の作成により、Ansible ロールの実行がトリガーされます。

    注記

    config/samples/<gvk>.yaml CR マニフェストの例を見てみましょう。

    apiVersion: <group>.example.com/v1alpha1
    kind: <kind>
    metadata:
      name: "<kind>-sample"

    spec フィールドが設定されていないため、Ansible は追加の変数なしで起動します。CR から Ansible へ追加の変数を渡すことについては、別のセクションで説明します。Operator に妥当なデフォルトを設定することは重要です。

  3. デフォルト変数 statepresent に設定し、CR インスタンスを作成します。

    $ oc apply -f config/samples/<gvk>.yaml
  4. example-config 設定マップが作成されたことを確認します。

    $ oc get configmaps

    出力例

    NAME                    STATUS    AGE
    example-config          Active    3s

  5. state フィールドを absent に設定するように、config/samples/<gvk>.yaml ファイルを変更します。以下に例を示します。

    apiVersion: cache.example.com/v1
    kind: Memcached
    metadata:
      name: memcached-sample
    spec:
      state: absent
  6. 変更を適用します。

    $ oc apply -f config/samples/<gvk>.yaml
  7. 設定マップが削除されていることを確認します。

    $ oc get configmap

5.4.7.3. クラスター上での Ansible ベース Operator のテスト

カスタム Ansible ロジックを Operator 内でローカルにテストした後、OpenShift Container Platform クラスターの Pod 内で Operator をテストできます。実稼働環境での使用を目的としている場合、このテストが推奨されます。

Operator プロジェクトは、クラスター上でデプロイメントとして実行できます。

手順

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

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

      $ make docker-build IMG=<registry>/<user>/<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>/<image_name>:<tag>
      注記

      両方のコマンドのイメージの名前とタグ (例: IMG=<registry>/<user>/<image_name>:<tag>) を Makefile に設定することもできます。IMG ?= controller:latest の値を変更して、デフォルトのイメージ名を設定します。

  2. 以下のコマンドを実行して Operator をデプロイします。

    $ make deploy IMG=<registry>/<user>/<image_name>:<tag>

    デフォルトで、このコマンドは <project_name>-system の形式で Operator プロジェクトの名前で namespace を作成し、デプロイメントに使用します。このコマンドは、config/rbac から RBAC マニフェストもインストールします。

  3. 以下のコマンドを実行して、Operator が実行されていることを確認します。

    $ oc get deployment -n <project_name>-system

    出力例

    NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
    <project_name>-controller-manager       1/1     1            1           8m

5.4.7.4. Ansible ログ

Ansible ベースの Operator は、Ansible の実行に関するログを提供します。これは、Ansible タスクのデバッグに役立ちます。ログには、Operator の内部および Kubernetes との対話に関する詳細情報を含めることもできます。

5.4.7.4.1. Ansible ログの表示

前提条件

  • Ansible ベースの Operator が、デプロイメントとしてクラスター上で実行されている。

手順

  • Ansible ベースの Operator からログを表示するには、以下のコマンドを実行します。

    $ oc logs deployment/<project_name>-controller-manager \
        -c manager \1
        -n <namespace> 2
    1
    manager コンテナーのログを表示します。
    2
    make deploy コマンドを使用して Operator をデプロイメントとして実行している場合は、<project_name>-system namespace を使用します。

    出力例

    {"level":"info","ts":1612732105.0579333,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"}
    {"level":"info","ts":1612732105.0587437,"logger":"cmd","msg":"WATCH_NAMESPACE environment variable not set. Watching all namespaces.","Namespace":""}
    I0207 21:08:26.110949       7 request.go:645] Throttling request took 1.035521578s, request: GET:https://172.30.0.1:443/apis/flowcontrol.apiserver.k8s.io/v1alpha1?timeout=32s
    {"level":"info","ts":1612732107.768025,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":"127.0.0.1:8080"}
    {"level":"info","ts":1612732107.768796,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2}
    {"level":"info","ts":1612732107.7688773,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false}
    {"level":"info","ts":1612732107.7688901,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
    {"level":"info","ts":1612732107.770032,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
    I0207 21:08:27.770185       7 leaderelection.go:243] attempting to acquire leader lease  memcached-operator-system/memcached-operator...
    {"level":"info","ts":1612732107.770202,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
    I0207 21:08:27.784854       7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator
    {"level":"info","ts":1612732107.7850506,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
    {"level":"info","ts":1612732107.8853772,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
    {"level":"info","ts":1612732107.8854098,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4}

5.4.7.4.2. ログでの Ansible のすべての結果の有効化

環境変数 ANSIBLE_DEBUG_LOGSTrue に設定すると、Ansible のすべての結果をログで確認できるようになります。これはデバッグの際に役立ちます。

手順

  • config/manager/manager.yaml ファイルおよび config/default/manager_auth_proxy_patch.yaml ファイルを編集し、以下の設定を追加します。

          containers:
          - name: manager
            env:
            - name: ANSIBLE_DEBUG_LOGS
              value: "True"
5.4.7.4.3. ログでの詳細デバッグの有効化

Ansible ベースの Operator の開発中は、ログでの追加のデバッグの有効化が役立つ場合があります。

手順

  • ansible.sdk.operatorframework.io/verbosity アノテーションをカスタムリソースに追加して、必要な詳細レベルを有効にします。以下に例を示します。

    apiVersion: "cache.example.com/v1alpha1"
    kind: "Memcached"
    metadata:
      name: "example-memcached"
      annotations:
        "ansible.sdk.operatorframework.io/verbosity": "4"
    spec:
      size: 4

5.4.8. カスタムリソースのステータス管理

5.4.8.1. Ansible ベースの Operator でのカスタムリソースのステータスについて

Ansible ベースの Operator は、以前の Ansible 実行に関する一般的な情報を使用して、カスタムリソース (CR) ステータス サブリソース を自動的に更新します。これには、以下のように成功したタスクおよび失敗したタスクの数と関連するエラーメッセージが含まれます。

status:
  conditions:
  - ansibleResult:
      changed: 3
      completion: 2018-12-03T13:45:57.13329
      failures: 1
      ok: 6
      skipped: 0
    lastTransitionTime: 2018-12-03T13:45:57Z
    message: 'Status code was -1 and not [200]: Request failed: <urlopen error [Errno
      113] No route to host>'
    reason: Failed
    status: "True"
    type: Failure
  - lastTransitionTime: 2018-12-03T13:46:13Z
    message: Running reconciliation
    reason: Running
    status: "True"
    type: Running

さらに Ansible ベースの Operator は、Operator の作成者が operator_sdk.util コレクション に含まれる k8s_status Ansible モジュールでカスタムのステータス値を指定できるようにします。これにより、作成者は必要に応じ、任意のキー/値のペアを使用して Ansible から status を更新できます。

デフォルトでは、Ansible ベースの Operator には、上記のように常に汎用的な Ansible 実行出力が含まれます。アプリケーションのステータスが Ansible 出力で更新 されない ようにする必要がある場合は、アプリケーションからステータスを手動で追跡することができます。

5.4.8.2. カスタムリソースステータスの手動による追跡

operator_sdk.util コレクションを使用して Ansible ベースの Operator を変更し、アプリケーションからカスタムリソース (CR) ステータスを手動で追跡できます。

前提条件

  • Operator SDK を使用して Ansible ベースの Operator プロジェクトが作成済みである。

手順

  1. manageStatus フィールドを false に設定して watches.yaml ファイルを更新します。

    - version: v1
      group: api.example.com
      kind: <kind>
      role: <role>
      manageStatus: false
  2. operator_sdk.util.k8s_status Ansible モジュールを使用して、サブリソースを更新します。たとえば、キー test および値 data を使用して更新するには、operator_sdk.util を以下のように使用することができます。

    - operator_sdk.util.k8s_status:
        api_version: app.example.com/v1
        kind: <kind>
        name: "{{ ansible_operator_meta.name }}"
        namespace: "{{ ansible_operator_meta.namespace }}"
        status:
          test: data
  3. スキャフォールディングされた Ansible ベースの Operator に含まれるロールの meta/main.yml ファイルで、コレクションを宣言することができます。

    collections:
      - operator_sdk.util
  4. ロールのメタでコレクションを宣言すると、k8s_status モジュールを直接起動することができます。

    k8s_status:
      ...
      status:
        key1: value1