第11章 Operator SDK

手順

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

   CLI を使用して新規 memcached-operator プロジェクトを作成します。

   $ mkdir -p $GOPATH/src/github.com/example-inc/
   $ cd $GOPATH/src/github.com/example-inc/
   $ operator-sdk new memcached-operator --dep-manager dep
   $ cd memcached-operator

2. 新規カスタムリソース定義 (CRD) を追加します。

   1. APIVersion を cache.example.com/v1apha1 に設定し、Kind を Memcached に設定した状態で、CLI を使用して Memcached という新規 CRD API を追加します。

      $ operator-sdk add api \
          --api-version=cache.example.com/v1alpha1 \
          --kind=Memcached

      これにより、pkg/apis/cache/v1alpha1/ の下で Memcached resource API のスキャフォールディングが実行されます。

   2. pkg/apis/cache/v1alpha1/memcached_types.go ファイルで、 Memcached カスタムリソース (CR) の仕様およびステータスを変更します。

      type MemcachedSpec struct {
      	// Size is the size of the memcached deployment
      	Size int32 `json:"size"`
      }
      type MemcachedStatus struct {
      	// Nodes are the names of the memcached pods
      	Nodes []string `json:"nodes"`
      }

   3. *_types.go ファイルを変更後は、以下のコマンドを常に実行し、該当するリソースタイプ用に生成されたコードを更新します。

      $ operator-sdk generate k8s

3. 新規コントローラーを追加します。

   1. 新規コントローラーをプロジェクトに追加し、 Memcached リソースを確認し、調整します。

      $ operator-sdk add controller \
          --api-version=cache.example.com/v1alpha1 \
          --kind=Memcached

      これにより、pkg/controller/memcached/ の下で新規コントローラー実装のスキャフォールディングが実行されます。

   2. この例では、生成されたコントローラーファイル pkg/controller/memcached/memcached_controller.go を実装例に置き換えます。

      コントローラーのサンプルは、それぞれの Memcached CR について以下の調整 (reconciliation) ロジックを実行します。

      • Memcached Deployment を作成します (ない場合)。
      • Deployment のサイズが、 Memcached CR 仕様で指定されるのと同じであることを確認します。
      • Memcached CR ステータスを Memcached Pod の名前で置き換えます。

      次の 2 つのサブステップでは、コントローラーがリソースを監視する方法および調整ループがトリガーされる方法を検査します。これらの手順を省略し、直接 Operator のビルドおよび実行に進むことができます。

   3. pkg/controller/memcached/memcached_controller.go ファイルでコントローラーの実装を検査し、コントローラーのリソースの監視方法を確認します。

      最初の監視は、プライマリーソースとしての Memcached タイプに対して実行します。それぞれの Add、Update、または Delete イベントについて、reconcile ループに Memcached オブジェクトの reconcile Request ( <namespace>:<name> キー) が送られます。

      err := c.Watch(
        &source.Kind{Type: &cachev1alpha1.Memcached{}}, &handler.EnqueueRequestForObject{})

      次の監視は、Deployment に対して実行されますが、イベントハンドラーは各イベントを、Deployment のオーナーの reconcile Request にマップします。この場合、これは Deployment が作成された Memcached オブジェクトです。これにより、コントローラーは Deployment をセカンダリーリソースとして監視できます。

      err := c.Watch(&source.Kind{Type: &appsv1.Deployment{}}, &handler.EnqueueRequestForOwner{
      		IsController: true,
      		OwnerType:    &cachev1alpha1.Memcached{},
      	})

   4. すべてのコントローラーには、reconcile ループを実装する Reconcile() メソッドのある Reconciler オブジェクトがあります。この reconcile ループには、キャッシュからプライマリーリソースオブジェクトの Memcached を検索するために使用される <namespace>:<name> キーである Request 引数が渡されます。

      func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error) {
        // Lookup the Memcached instance for this reconcile request
        memcached := &cachev1alpha1.Memcached{}
        err := r.client.Get(context.TODO(), request.NamespacedName, memcached)
        ...
      }

      Reconcile() の戻り値に応じて、reconcile Request は再度キューに入れられ、ループが再びトリガーされる可能性があります。

      // Reconcile successful - don't requeue
      return reconcile.Result{}, nil
      // Reconcile failed due to error - requeue
      return reconcile.Result{}, err
      // Requeue for any reason other than error
      return reconcile.Result{Requeue: true}, nil

4. Operator をビルドし、実行します 。

   1. Operator の実行前に、CRD を Kubernetes API サーバーに再度登録する必要があります。

      $ oc create \
          -f deploy/crds/cache_v1alpha1_memcached_crd.yaml

   2. CRD の登録後に、Operator を実行するための 2 つのオプションを選択できます。

      • Kubernetes クラスター内の Deployment を使用
      • クラスター内の Go プログラムを使用

      以下の方法のいずれかを選択します。

      1. オプション A: クラスター内の Deployment として実行する。

         1. memcached-operator イメージをビルドし、これをレジストリーにプッシュします。

            $ operator-sdk build quay.io/example/memcached-operator:v0.0.1

         2. Deployment マニフェストは deploy/operator.yaml に生成されます。デフォルトはプレースホルダーでしかないため、以下のように Deployment イメージを更新します。

            $ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml

         3. 次のステップについての quay.io にアカウントがあることを確認するか、または優先しているコンテナーレジストリーで置き換えます。レジストリーには、memcached-operator という名前の 新規パブリックイメージリポジトリーを作成します。

         4. イメージをレジストリーにプッシュします。

            $ docker push quay.io/example/memcached-operator:v0.0.1

         5. RBAC をセットアップし、memcached-operator をデプロイします。

            $ oc create -f deploy/role.yaml
            $ oc create -f deploy/role_binding.yaml
            $ oc create -f deploy/service_account.yaml
            $ oc create -f deploy/operator.yaml

         6. memcached-operator が設定されており、稼働していることを確認します。

            $ oc get deployment
            NAME                     DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
            memcached-operator       1         1         1            1           1m

      2. オプション B: クラスター外でローカルに実行する。

         この方法は、迅速にデプロイメントおよびテストを実行するための開発サイクルで優先される方法です。

         $HOME/.kube/config にあるデフォルトの Kubernetes 設定ファイルを使用して Operator をローカルで実行します。

         $ operator-sdk up local --namespace=default

         フラグ --kubeconfig=<path/to/kubeconfig> を使用して特定の kubeconfig を使用できます。

5. Memcached CR を作成して、Operator が Memcached アプリケーションをデプロイできることを確認します。

   1. deploy/crds/cache_v1alpha1_memcached_cr.yaml で生成された Memcached CR のサンプルを作成します。

      $ cat deploy/crds/cache_v1alpha1_memcached_cr.yaml
      apiVersion: "cache.example.com/v1alpha1"
      kind: "Memcached"
      metadata:
        name: "example-memcached"
      spec:
        size: 3
      
      $ oc apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml

   2. memcached-operator が CR の Deployment を作成できることを確認します。

      $ oc get deployment
      NAME                     DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
      memcached-operator       1         1         1            1           2m
      example-memcached        3         3         3            3           1m

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

      $ oc get pods
      NAME                                  READY     STATUS    RESTARTS   AGE
      example-memcached-6fd7c98d8-7dqdr     1/1       Running   0          1m
      example-memcached-6fd7c98d8-g5k7v     1/1       Running   0          1m
      example-memcached-6fd7c98d8-m7vn7     1/1       Running   0          1m
      memcached-operator-7cc7cfdf86-vvjqk   1/1       Running   0          2m
      
      $ oc get memcached/example-memcached -o yaml
      apiVersion: cache.example.com/v1alpha1
      kind: Memcached
      metadata:
        clusterName: ""
        creationTimestamp: 2018-03-31T22:51:08Z
        generation: 0
        name: example-memcached
        namespace: default
        resourceVersion: "245453"
        selfLink: /apis/cache.example.com/v1alpha1/namespaces/default/memcacheds/example-memcached
        uid: 0026cc97-3536-11e8-bd83-0800274106a1
      spec:
        size: 3
      status:
        nodes:
        - example-memcached-6fd7c98d8-7dqdr
        - example-memcached-6fd7c98d8-g5k7v
        - example-memcached-6fd7c98d8-m7vn7

6. デプロイメントのサイズを更新し、Operator がデプロイ済みの Memcached アプリケーションを管理できることを確認します 。

   1. memcached CR の spec.size フィールドを 3 から 4 に変更します。

      $ cat deploy/crds/cache_v1alpha1_memcached_cr.yaml
      apiVersion: "cache.example.com/v1alpha1"
      kind: "Memcached"
      metadata:
        name: "example-memcached"
      spec:
        size: 4

   2. 変更を適用します。

      $ oc apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml

   3. Operator が Deployment サイズを変更することを確認します。

      $ oc get deployment
      NAME                 DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
      example-memcached    4         4         4            4           5m

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

   $ oc delete -f deploy/crds/cache_v1alpha1_memcached_cr.yaml
   $ oc delete -f deploy/crds/cache_v1alpha1_memcached_crd.yaml
   $ oc delete -f deploy/operator.yaml
   $ oc delete -f deploy/role.yaml
   $ oc delete -f deploy/role_binding.yaml
   $ oc delete -f deploy/service_account.yaml

手順

1. Operator マニフェストを生成します 。

   Operator マニフェストは、アプリケーションを表示し、作成し、管理する方法について説明します (この場合は Memcached)。これは ClusterServiceVersion (CSV) オブジェクトで定義され、OLM が機能するために必要です。

   以下のコマンドを使用して CSV マニフェストを生成することができます。

   $ operator-sdk olm-catalog gen-csv --csv-version 0.0.1

   注記

   このコマンドは、Memcached Operator のビルド時に作成された memcached-operator/ ディレクトリーから実行されます。

   本書の目的を考慮し、次のいくつかのステップにおいても引き続きこの事前に定義されたマニフェストファイルを使用します。このマニフェスト内のイメージフィールドを変更して、直前のステップでビルドしたイメージを反映させることができますが、これは不要です。

   注記

   マニフェストファイルの手動による定義についての詳細は、「Building a CSV for the Operator Framework」を参照してください。

2. Operator をデプロイします。

   1. Operator がターゲットとする namespace を指定する OperatorGroup を作成します。以下の OperatorGroup を、CSV を作成する namespace に作成します。この例では、 default namespace が使用されます。

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: memcached-operator-group
        namespace: default
      spec:
        targetNamespaces:
        - default

   2. Operator の CSV マニフェストをクラスターの指定された namespace に適用します。

      $ curl -Lo memcachedoperator.0.0.1.csv.yaml https://raw.githubusercontent.com/operator-framework/getting-started/master/memcachedoperator.0.0.1.csv.yaml
      $ oc apply -f memcachedoperator.0.0.1.csv.yaml
      $ oc get csv memcachedoperator.v0.0.1 -n default -o json | jq '.status'

      このマニフェストを適用する際に、クラスターはマニフェストで指定された要件を満たしていないためにすぐに更新を実行しません。

   3. リソースパーミッションを Operator に付与するためにロール、ロールバインディング、およびサービスアカウントを作成し、Operator が管理する Memcached タイプを作成するためにカスタムリソース定義 (CRD、Custom Resource Definition) を作成します。

      $ oc create -f deploy/crds/cache_v1alpha1_memcached_crd.yaml
      $ oc create -f deploy/service_account.yaml
      $ oc create -f deploy/role.yaml
      $ oc create -f deploy/role_binding.yaml

      注記

      これらのファイルは、Memcached Operator のビルド時に Operator SDK よって deploy/ ディレクトリーに生成されています。

      マニフェストの適用時に OLM は Operator を特定の namespace に作成するため、管理者は、Operator をインストールできるユーザーを制限するためのネイティブの Kubernetes RBAC パーミッションモデルを利用できます。

3. アプリケーションインスタンスを作成します 。

   Memcached Operator が default namespace で実行されるようになります。ユーザーは CustomResources のインスタンス経由で Operator と対話します。この場合、リソースには Memcached の種類が設定されます。ネイティブの Kubernetes RBAC は CustomResources に適用され、管理者には各 Operater と対話できるユーザーへの制御が提供されます。

   この namespace で Memcached のインスタンスを作成することにより、Operator で管理される memcached サーバーを実行する Pod をインスタンス化するために Memcached Operator がトリガーされます。CustomResources をより多く作成すると、Memcached のより多くの固有なインスタンスがこの namespace で実行されている Memcached Operator によって管理されます。

   $ cat <<EOF | oc apply -f -
   apiVersion: "cache.example.com/v1alpha1"
   kind: "Memcached"
   metadata:
     name: "memcached-for-wordpress"
   spec:
     size: 1
   EOF
   
   $ cat <<EOF | oc apply -f -
   apiVersion: "cache.example.com/v1alpha1"
   kind: "Memcached"
   metadata:
     name: "memcached-for-drupal"
   spec:
     size: 1
   EOF
   
   $ oc get Memcached
   NAME                      AGE
   memcached-for-drupal      22s
   memcached-for-wordpress   27s
   
   $ oc get pods
   NAME                                       READY     STATUS    RESTARTS   AGE
   memcached-app-operator-66b5777b79-pnsfj    1/1       Running   0          14m
   memcached-for-drupal-5476487c46-qbd66      1/1       Running   0          3s
   memcached-for-wordpress-65b75fd8c9-7b9x7   1/1       Running   0          8s

4. アプリケーションを更新します。

   新規 Operator マニフェストを、古い Operator マニフェストを参照する replaces フィールドを使って作成し、更新を Operator に手動で適用します。OLM は、古い Operator で管理されているすべてのリソースの所有権が、いずれのプログラムも停止することなく新規 Operator に移行できるようにします。新規バージョンの Operator 下で実行するリソースのアップグレードに必要なデータ移行を実行するかどうかは Operator によって異なります。

   以下のコマンドは、新規バージョンの Operator を使用して新規 Operator マニフェストファイルを適用する方法を示し、Pod が実行状態であることを示します。

   $ curl -Lo memcachedoperator.0.0.2.csv.yaml https://raw.githubusercontent.com/operator-framework/getting-started/master/memcachedoperator.0.0.2.csv.yaml
   $ oc apply -f memcachedoperator.0.0.2.csv.yaml
   $ oc get pods
   NAME                                       READY     STATUS    RESTARTS   AGE
   memcached-app-operator-66b5777b79-pnsfj    1/1       Running   0          3s
   memcached-for-drupal-5476487c46-qbd66      1/1       Running   0          14m
   memcached-for-wordpress-65b75fd8c9-7b9x7   1/1       Running   0          14m