第4章 Operator の開発

手順

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

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

   $ mkdir -p $GOPATH/src/github.com/example-inc/

   $ cd $GOPATH/src/github.com/example-inc/

   $ operator-sdk new memcached-operator

   $ 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. オプション: カスタム検証を CRD に追加します。

   OpenAPI v3.0 スキーマは、マニフェストの生成時に spec.validation ブロックの CRD マニフェストに追加されます。この検証ブロックにより、Kubernetes が作成または更新時に Memcached CR のプロパティーを検証できます。

   さらに、pkg/apis/<group>/<version>/zz_generated.openapi.go ファイルが生成されます。このファイルには、デフォルトで存在する +k8s:openapi-gen=true annotation が Kind 型の宣言の上に存在する場合に、この検証ブロックの Go 表現が含まれます。この自動生成コードは Go の Kind タイプの OpenAPI モデルです。これを使用して完全な OpenAPI 仕様を作成し、クライアントを生成できます。

   Operator の作成者は Kubebuilder マーカー (アノテーション) を使用して API のカスタム検証を設定できます。これらのマーカーには、+kubebuilder:validation 接頭辞が常に必要です。たとえば、以下のマーカーを追加して enum 型の仕様を追加できます。

   // +kubebuilder:validation:Enum=Lion;Wolf;Dragon
   type Alias string

   API コードのマーカーの使用については、Kubebuilder ドキュメントの Generating CRDs および Markers for Config/Code Generation を参照してください。OpenAPIv3 検証マーカーの詳細の一覧については、Kubebuilder ドキュメントの CRD Validation を参照してください。

   カスタム検証を追加する場合は、以下のコマンドを実行し、CRD の deploy/crds/cache.example.com_memcacheds_crd.yaml ファイルの OpenAPI 検証セクションを更新します。

   $ operator-sdk generate crds

   生成される YAML の例

   spec:
     validation:
       openAPIV3Schema:
         properties:
           spec:
             properties:
               size:
                 format: int32
                 type: integer

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

   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 リソースについて以下の調整 (reconciliation) ロジックを実行します。

      • Memcached デプロイメントを作成します (ない場合)。
      • Deployment のサイズが、 Memcached CR 仕様で指定されるのと同じであることを確認します。
      • Memcached リソースのステータスを 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 オブジェクトに対して実行されますが、イベントハンドラーは各イベントを、デプロイメントのオーナーの reconcile (調整) Request にマップします。この場合、これはデプロイメントが作成された Memcached オブジェクトです。これにより、コントローラーはデプロイメントをセカンダリーリソースとして監視できます。

      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

5. 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: クラスター内のデプロイメントとして実行する。

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

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

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

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

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

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

            $ podman 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 run --local --namespace=default

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

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

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

   2. ファイルを表示します。

      $ cat deploy/crds/cache_v1alpha1_memcached_cr.yaml

      出力例

      apiVersion: "cache.example.com/v1alpha1"
      kind: "Memcached"
      metadata:
        name: "example-memcached"
      spec:
        size: 3

   3. オブジェクトを作成します。

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

   4. memcached-operator が CR のデプロイメントを作成できることを確認します。

      $ 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

   5. CR ステータスが 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

7. デプロイメントのサイズを更新し、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 がデプロイメントサイズを変更することを確認します。

      $ oc get deployment

      出力例

      NAME                 DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
      example-memcached    4         4         4            4           5m

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

   $ 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 が機能するために必要です。

   Memcached Operator のビルド時に作成された memcached-operator/ ディレクトリーから CSV を生成します。

   $ operator-sdk generate csv --csv-version 0.0.1

   注記

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

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

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

3. Operator をデプロイします。これらのファイルは、Memcached Operator のビルド時に Operator SDK よって deploy/ ディレクトリーに生成されたファイルを使用します。

   1. 各カスタムリソース定義 (CRD) kind の displayName フィールドを spec.customresourcedefinitions.owned セクションに追加して、生成される CSV マニフェストファイルを編集します。

      deploy/olm-catalog/memcached-operator/0.0.1/memcached-operator.v0.0.1.clusterserviceversion.yaml ファイル

      ...
      spec:
        customresourcedefinitions:
          owned:
          - kind: Memcached
            name: memcacheds.cache.example.com
            version: v1alpha1
            description: Memcached is the Schema for the memcacheds API
            displayName: Memcached 1
      ...

      1

      CRD の表示名を指定します。

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

      $ oc apply -f deploy/olm-catalog/memcached-operator/0.0.1/memcached-operator.v0.0.1.clusterserviceversion.yaml

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

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

      $ oc create -f deploy/crds/cache.example.com_memcacheds_crd.yaml

      $ oc create -f deploy/service_account.yaml

      $ oc create -f deploy/role.yaml

      $ oc create -f deploy/role_binding.yaml

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

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

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

   この namespace で Memcached オブジェクトのインスタンスを作成することにより、Operator で管理される memcached サーバーを実行する Pod をインスタンス化するために Memcached Operator がトリガーされます。カスタムリソースをより多く作成すると、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