5.4. Ansible ベースの 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

手順

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 に渡されます。

手順

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"

手順

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

   $ oc project memcached-operator-system

2. config/samples/cache_v1_memcached.yaml で Memcached 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>

手順

1. 次の例に示すように、Operator プロジェクトの Makefile を編集して、Operator SDK バージョンを v1.36.1-ocp に更新します。

   Makefile の例

   # Set the Operator SDK version to use. By default, what is installed on the system is used.
   # This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.
   OPERATOR_SDK_VERSION ?= v1.36.1-ocp

2. Red Hat Enterprise Linux (RHEL) 9 ベースのイメージを使用するように kube-rbac-proxy コンテナーを更新します。

   1. 次のファイルで kube-rbac-proxy コンテナーのエントリーを見つけます。

      • config/default/manager_auth_proxy_patch.yaml
      • Operator プロジェクトの bundle/manifests/<operator_name>.clusterserviceversion.yaml (チュートリアルの memcached-operator.clusterserviceversion.yaml など)

   2. プル仕様のイメージ名を ose-kube-rbac-proxy から ose-kube-rbac-proxy-rhel9 に更新し、タグを v4 に更新します。

      v4 イメージタグを使用した ose-kube-rbac-proxy-rhel9 プル仕様の例

      # ...
            containers:
            - name: kube-rbac-proxy
              image: registry.redhat.io/openshift4/ose-kube-rbac-proxy-rhel9:v4
      # ...

3. 次の例に示すように、Operator の Dockerfile を編集して、ose-ansible-rhel9-operator イメージタグを 4 に更新します。

   Dockerfile の例

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

4. kustomize/v2 プラグインは、現在 stable であり、go/v4、ansible/v1、helm/v1、hybrid/v1-alpha プラグインを使用するときにプラグインチェーンで使用されるデフォルトのバージョンです。このデフォルトのスキャフォールドの詳細は、Kubebuilder ドキュメントの Kustomize v2 を参照してください。

5. Operator プロジェクトでマルチプラットフォームビルドまたはマルチアーキテクチャービルドを使用する場合は、プロジェクト Makefile 内の既存の docker-buildx ターゲットを次の定義に置き換えます。

   Makefile の例

   docker-buildx:
   ## Build and push the Docker image for the manager for multi-platform support
   	- docker buildx create --name project-v3-builder
   	docker buildx use project-v3-builder
   	- docker buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile .
   	- docker buildx rm project-v3-builder

6. Operator プロジェクトの Kubernetes バージョンを、1.29 を使用するようにアップグレードする必要があります。プロジェクト構造、Makefile、go.mod ファイルに次の変更を加える必要があります。

   重要

   go/v3 プラグインは Kubebuilder によって非推奨化が進められています。そのため、Operator SDK も今後のリリースで go/v4 に移行します。

   1. go.mod ファイルを更新して、依存関係をアップグレードします。

      k8s.io/api v0.29.2
      k8s.io/apimachinery v0.29.2
      k8s.io/client-go v0.29.2
      sigs.k8s.io/controller-runtime v0.17.3

   2. 次のコマンドを実行して、アップグレードした依存関係をダウンロードします。

      $ go mod tidy

手順

1. Ansible 2.15 以降をインストールします。

   $ sudo dnf install ansible

2. Python Kubernetes クライアント パッケージをインストールします。

   $ pip install kubernetes

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

手順

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. デフォルトで state を present に設定するように、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. state を absent に設定して 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

手順

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. デフォルト変数 state を present に設定し、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

手順

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

手順

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