5.4. 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. Delete a CR.

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

   $ oc delete -f config/samples/cache_v1_memcached.yaml -n memcached-operator-system

7. クリーンアップします。

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

   $ make undeploy

手順

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 の Dockerfile に次の変更を加えます。

   1. 次の例に示すように、ansible-operator-2.11-preview ベースイメージを ansible-operator ベースイメージに置き換え、バージョンを 1.31.0 に更新します。

      Dockerfile の例

      FROM quay.io/operator-framework/ansible-operator:v1.31.0

   2. Ansible Operator バージョン 1.30.0 の Ansible 2.15.0 への更新により、次のプリインストールされた Python モジュールが削除されました。

      • ipaddress
      • openshift
      • jmespath
      • cryptography
      • oauthlib

      Operator がこれらの削除された Python モジュールのいずれかに依存している場合は、Dockerfile を更新して、pip install コマンドを使用して必要なモジュールをインストールします。

2. 次の例に示すように、Operator プロジェクトの Makefile を編集して OPERATOR_SDK_VERSION フィールドを追加し、v1.31.0-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.31.0-ocp

3. 次の例に示すように、requirements.yaml ファイルと requirements.go ファイルを更新して、community.kubernetes コレクションを削除し、operator_sdk.util コレクションをバージョン 0.5.0 に更新します。

   requirements.yaml ファイルの例

     collections:
   -  - name: community.kubernetes 1
   -    version: "2.0.1"
      - name: operator_sdk.util
   -    version: "0.4.0"
   +    version: "0.5.0" 2
      - name: kubernetes.core
        version: "2.4.0"
      - name: cloud.common

   1

   community.kubernetes コレクションを削除します

   2

   operator_sdk.util コレクションをバージョン 0.5.0 に更新します。

4. 次の例に示すように、molecule/kind/molecule.yml および molecule/default/molecule.yml ファイルから lint フィールドのすべてのインスタンスを削除します。

     ---
     dependency:
       name: galaxy
     driver:
       name: delegated
   -   lint: |
   -     set -e
   -     yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}" .
     platforms:
       - name: cluster
         groups:
   	- k8s
     provisioner:
       name: ansible
   -     lint: |
   -       set -e
         ansible-lint
       inventory:
         group_vars:
   	all:
   	  namespace: ${TEST_OPERATOR_NAMESPACE:-osdk-test}
         host_vars:
   	localhost:
   	  ansible_python_interpreter: '{{ ansible_playbook_python }}'
   	  config_dir: ${MOLECULE_PROJECT_DIRECTORY}/config
   	  samples_dir: ${MOLECULE_PROJECT_DIRECTORY}/config/samples
   	  operator_image: ${OPERATOR_IMAGE:-""}
   	  operator_pull_policy: ${OPERATOR_PULL_POLICY:-"Always"}
   	  kustomize: ${KUSTOMIZE_PATH:-kustomize}
       env:
         K8S_AUTH_KUBECONFIG: ${KUBECONFIG:-"~/.kube/config"}
     verifier:
       name: ansible
   -     lint: |
   -       set -e
   -      ansible-lint

手順

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