5.5. Helm ベースの Operator

手順

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

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

      $ mkdir nginx-operator

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

      $ cd nginx-operator

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

      $ operator-sdk init \
          --plugins=helm

2. API を作成します。

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

   $ operator-sdk create api \
       --group demo \
       --version v1 \
       --kind Nginx

   この API は、helm create コマンドでビルトインの Helm チャートボイラープレートを使用します。

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. SCC(Security Context Constraints) を追加します。

   Nginx サービスアカウントには、OpenShift Container Platform で実行する特権アクセスが必要です。以下の SCC を nginx-sample Pod のサービスアカウントに追加します。

   $ oc adm policy add-scc-to-user \
       anyuid system:serviceaccount:nginx-operator-system:nginx-sample

6. サンプルカスタムリソース (CR) を作成します。

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

      $ oc apply -f config/samples/demo_v1_nginx.yaml \
          -n nginx-operator-system

   2. Operator を調整する CR を確認します。

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

7. CR を削除する

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

   $ oc delete -f config/samples/demo_v1_nginx.yaml -n nginx-operator-system

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

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

   $ make undeploy

手順

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

   $ mkdir -p $HOME/projects/nginx-operator

2. ディレクトリーに切り替えます。

   $ cd $HOME/projects/nginx-operator

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

   $ operator-sdk init \
       --plugins=helm \
       --domain=example.com \
       --group=demo \
       --version=v1 \
       --kind=Nginx

   注記

   デフォルトで、helm プラグインは、ボイラープレート Helm チャートを使用してプロジェクトを初期化します。--helm-chart フラグなどの追加のフラグを使用すると、既存の Helm チャートを使用してプロジェクトを初期化できます。

   init コマンドは、API バージョン example.com/v1 および Kind Nginx でのリソースの監視に特化した nginx-operator プロジェクトを作成します。

4. Helm ベースのプロジェクトの場合、init コマンドは、チャートのデフォルトマニフェストによってデプロイされるリソースに基づいて config/rbac/role.yaml ファイルに RBAC ルールを生成します。このファイルで生成されるルールが Operator のパーミッション要件を満たしていることを確認します。

手順

1. watches.yaml ファイルを編集し、overrideValues フィールドを追加して、環境変数に基づいてオーバーライドを含めます。

   ...
   - group: demo.example.com
     version: v1alpha1
     kind: Nginx
     chart: helm-charts/nginx
     overrideValues:
       proxy.http: $HTTP_PROXY
   ...

2. helm-charts/nginx/values.yaml ファイルに proxy.http 値を追加します。

   ...
   proxy:
     http: ""
     https: ""
     no_proxy: ""

3. チャートテンプレートで変数の使用がサポートされているようにするには、helm-charts/nginx/templates/deployment.yaml ファイルのチャートテンプレートを編集して以下を追加します。

   containers:
     - name: {{ .Chart.Name }}
       securityContext:
         - toYaml {{ .Values.securityContext | nindent 12 }}
       image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
       imagePullPolicy: {{ .Values.image.pullPolicy }}
       env:
         - name: http_proxy
           value: "{{ .Values.proxy.http }}"

4. 以下を 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 nginx-operator-system

2. config/samples/demo_v1_nginx.yaml で Nginx CR マニフェストのサンプルを編集し、以下の仕様が含まれるようにします。

   apiVersion: demo.example.com/v1
   kind: Nginx
   metadata:
     name: nginx-sample
   ...
   spec:
   ...
     replicaCount: 3

3. Nginx サービスアカウントには、OpenShift Container Platform で実行する特権アクセスが必要です。以下の SCC(Security Context Constraints) を nginx-sample Pod のサービスアカウントに追加します。

   $ oc adm policy add-scc-to-user \
       anyuid system:serviceaccount:nginx-operator-system:nginx-sample

4. CR を作成します。

   $ oc apply -f config/samples/demo_v1_nginx.yaml

5. Nginx Operator が、正しいサイズで CR サンプルのデプロイメントを作成することを確認します。

   $ oc get deployments

   出力例

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

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

   1. Pod を確認します。

      $ oc get pods

      出力例

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

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

      $ oc get nginx/nginx-sample -o yaml

      出力例

      apiVersion: demo.example.com/v1
      kind: Nginx
      metadata:
      ...
        name: nginx-sample
      ...
      spec:
        replicaCount: 3
      status:
        nodes:
        - nginx-sample-6fd7c98d8-7dqdr
        - nginx-sample-6fd7c98d8-g5k7v
        - nginx-sample-6fd7c98d8-m7vn7

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

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

      $ oc patch nginx nginx-sample \
          -p '{"spec":{"replicaCount": 5}}' \
          --type=merge

   2. Operator がデプロイメントサイズを変更することを確認します。

      $ oc get deployments

      出力例

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

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

   $ oc delete -f config/samples/demo_v1_nginx.yaml

9. このチュートリアルの一環として作成したリソースをクリーンアップします。

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

     $ make undeploy

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

     $ operator-sdk cleanup <project_name>

手順

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.7 を v4.5.5 に更新します。

      重要

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

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

      $ make

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

   Dockerfile の例

   FROM registry.redhat.io/openshift4/ose-helm-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 フィールドに置き換えます。

手順

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

   $ mkdir -p $HOME/github.com/example/memcached-operator

2. ディレクトリーに切り替えます。

   $ cd $HOME/github.com/example/memcached-operator

3. operator-sdk init コマンドを実行してプロジェクトを初期化します。example.comのドメインを使用して、すべての API グループが<group> .example.comになるようにします。

   $ operator-sdk init \
       --plugins=hybrid.helm.sdk.operatorframework.io \
       --project-version="3" \
       --domain example.com \
       --repo=github.com/example/memcached-operator

   initコマンドは、チャートのデフォルトのマニフェストでデプロイされるリソースをもとに、config/rbac/role.yaml ファイルに RBAC ルールを生成します。config/rbac/role.yaml ファイルで生成されたルールが、Operator のパーミッション要件を満たしていることを確認します。

手順

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

   $ operator-sdk create api \
       --group=cache \
       --version v1 \
       --kind MemcachedBackup \
       --resource \
       --controller \
       --plugins=go/v3

2. プロンプトが表示されたら y を入力し、リソースとコントローラーの両方を作成します。

   $ Create Resource [y/n]
   y
   Create Controller [y/n]
   y

手順

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. Operator がインストールされている namespace へ変更します。

   $ oc project <project_name>-system

2. config/samples/cache_v1_memcached.yamlファイルにあるサンプルMemcached CRマニフェストを、 replica Countフィールドを3に変更して更新します。

   例5.7 config/samples/cache_v1_memcached.yaml ファイルの例

   apiVersion: cache.my.domain/v1
   kind: Memcached
   metadata:
     name: memcached-sample
   spec:
     # Default values copied from <project_dir>/helm-charts/memcached/values.yaml
     affinity: {}
     autoscaling:
       enabled: false
       maxReplicas: 100
       minReplicas: 1
       targetCPUUtilizationPercentage: 80
     fullnameOverride: ""
     image:
       pullPolicy: IfNotPresent
       repository: nginx
       tag: ""
     imagePullSecrets: []
     ingress:
       annotations: {}
       className: ""
       enabled: false
       hosts:
       - host: chart-example.local
         paths:
         - path: /
           pathType: ImplementationSpecific
       tls: []
     nameOverride: ""
     nodeSelector: {}
     podAnnotations: {}
     podSecurityContext: {}
     replicaCount: 3
     resources: {}
     securityContext: {}
     service:
       port: 80
       type: ClusterIP
     serviceAccount:
       annotations: {}
       create: true
       name: ""
     tolerations: []

3. Memcached CR を作成します。

   $ oc apply -f config/samples/cache_v1_memcached.yaml

4. Memcached Operator が、正しいサイズで CR サンプルのデプロイメントを作成することを確認します。

   $ oc get pods

   出力例

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

5. size を 2 に更新して、config/samples/cache_v1_memcachedbackup.yamlファイルにあるサンプル MemcachedBackup CR マニフェストを更新します。

   例5.8 config/samples/cache_v1_memcachedbackup.yamlファイルの例

   apiVersion: cache.my.domain/v1
   kind: MemcachedBackup
   metadata:
     name: memcachedbackup-sample
   spec:
     size: 2

6. MemcachedBackup CR を作成します。

   $ oc apply -f config/samples/cache_v1_memcachedbackup.yaml

7. memcachedbackup Pod の数が CR で指定されているものと同じであることを確認してください。

   $ oc get pods

   出力例

   NAME                                        READY     STATUS    RESTARTS   AGE
   memcachedbackup-sample-8649699989-4bbzg     1/1       Running   0          22m
   memcachedbackup-sample-8649699989-mq6mx     1/1       Running   0          22m

8. 上記の各 CR のspecを更新してから、再度適用できます。コントローラーは再度調整し、Pod のサイズがそれぞれの CR の仕様で指定されているとおりであることを確認します。

9. このチュートリアルの一環として作成したリソースをクリーンアップします。

   1. Memcachedリソースを削除します。

      $ oc delete -f config/samples/cache_v1_memcached.yaml

   2. MemcachedBackupリソースを削除します。

      $ oc delete -f config/samples/cache_v1_memcachedbackup.yaml

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

      $ make undeploy

手順

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. Makefile に変更を適用し、Operator を再構築するには、次のコマンドを入力します。

      $ make

3. Go とその依存関係を更新するには、go.mod ファイルに次の変更を加えます。

   go 1.19 1
   
   require (
     github.com/onsi/ginkgo/v2 v2.1.4 2
     github.com/onsi/gomega v1.19.0 3
     k8s.io/api v0.25.0 4
     k8s.io/apimachinery v0.25.0 5
     k8s.io/client-go v0.25.0 6
     sigs.k8s.io/controller-runtime v0.13.0 7
   )

   1

   バージョン 1.18 を 1.19 に更新します。

   2

   バージョン v1.16.5 を v2.1.4 に更新します。

   3

   バージョン v1.18.1 を v1.19.0 に更新します。

   4

   バージョン v0.24.0 を v0.25.0 に更新します。

   5

   バージョン v0.24.0 を v0.25.0 に更新します。

   6

   バージョン v0.24.0 を v0.25.0 に更新します。

   7

   バージョン v0.12.1 を v0.13.0 に更新します。

4. 更新されたバージョンをダウンロードし、依存関係をクリーンアップして、go.mod ファイルの変更を適用するには、次のコマンドを実行します。

   $ go mod tidy