第 12 章 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
   $ cd memcached-operator

2. 添加新的自定义资源定义 (CRD)。

   1. 使用 CLI 来添加名为 Memcached 的新 CRD API，将 APIVersion 设置为 cache.example.com/v1apha1，将 Kind 设置为 Memcached：

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

      这样会将 Memcached 资源 API 构建至 pkg/apis/cache/v1alpha1/ 下。

   2. 修改 pkg/apis/cache/v1alpha1/memcached_types.go 文件中 Memcached 自定义资源 (CR) 的 spec 和状态：

      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-type 规格：

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

   API 代码中的标记用法会在 Kubebuilder 生成 CRD 和用于配置/代码生成的标记文档中讨论。Kubebuilder CRD 验证文档还提供了 OpenAPIv3 验证标记的完整列表。

   如果您添加了任何自定义验证，请运行以下命令更新 CRD 的 deploy/crds/cache.example.com_memcacheds_crd.yaml 文件中的 OpenAPI 验证部分：

   $ operator-sdk generate openapi

   生成的 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 CR 执行以下协调逻辑：

      • 如果尚无 Memcached Deployment，请创建一个。
      • 确保 Deployment 大小与 Memcached CR spec 中指定的大小相同。
      • 使用 Memcached Pod 的名称来更新 Memcached CR 状态。

      接下来的两个子步骤用于检查控制器如何监视资源以及协调循环会如何被触发。您可跳过这些步骤，直接构建和运行 Operator。

   3. 检查 pkg/controller/memcached/memcached_controller.go 文件中的控制器实现，了解控制器如何监视资源。

      首先要监视的是作为主要资源的 Memcached 类型。对于每个添加、更新或删除事件，协调循环均会针对该 Memcached 对象发送一个协调 Request（<namespace>:<name> 键）：

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

      接下来监视 Deployment，但事件处理程序会将每个事件映射到 Deployment 所有者的协调 Request 中。即本例中为其创建 Deployment 的 Memcached 对象。这样可让控制器将 Deployment 视为辅助资源：

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

   4. 每个控制器均有一个协调器对象，且该对象带有实现协调循环的 Reconcile() 方法。系统会将 Request 参数传递到该协调循环，该参数是一个用于从缓存中查找主资源对象 Memcached 的 <namespace>:<name> 键：

      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() 的返回值，协调 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 之前，必须使用 Kubernetes API 服务器来注册 CRD：

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

   2. 注册 CRD 之后，运行 Operator 时有两个选项可供选择：

      • 作为 Kubernetes 集群内的一个 Deployment 来运行
      • 作为集群外的 Go 程序运行

      选择以下任一方法。

      1. 选项 A：作为集群内的一个 Deployment 来运行。

         1. 构建 memcached-operator 镜像并将其推送至 registry：

            $ 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 上有一个可供下一步使用的账户，或者替换您的首选容器 registry。在 registry 中，创建一个名为 memcached-operator 的新公共镜像存储库。

         4. 将镜像推送至 registry：

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

         您可借助标记 --kubeconfig=<path/to/kubeconfig> 来使用特定的 kubeconfig。

6. 通过创建 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. 检查 Pod 和 CR 状态，以确认其状态中是否更新了 memcached Pod 名称：

      $ 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 已更改 Deployment 大小：

      $ 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 olm-catalog gen-csv --csv-version 0.0.1

   注意

   更多有关手动定义清单文件的信息，请参阅构建用于 Operator Framework 的 CSV。

2. 创建一个 OperatorGroup，指定 Operator 的目标命名空间。在要创建 CSV 的命名空间中创建以下 OperatorGroup。本例中使用了 default 命名空间：

   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. 将 Operator 的 CSV 清单应用于集群中指定的命名空间：

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

      应用该清单时，集群不会立即更新，因为尚未满足清单中指定的要求。

   2. 创建角色、角色绑定和服务账户以便向 Operator 授予资源权限，创建自定义资源定义 (CRD) 以便创建受 Operator 管理的 Memcached 类型:

      $ 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，所以管理员可利用原生 Kubernetes RBAC 权限模型来限制哪些用户可以安装 Operator。

4. 创建应用程序实例。

   Memcached Operator 正在 default 命名空间中运行。用户通过 CustomResource 实例与 Operator 交互；这种情况下，资源拥有类型 Memcached。原生 Kubernetes RBAC 也适用于 CustomResource，让管理员能够控制与每个 Operator 的交互。

   在该命名空间中创建 Memcached 实例将触发 Memcached Operator，以针对运行由 Operator 管理的 Memcached 服务器的 Pod 进行实例化。您创建的 CustomResource 越多，在此命名空间中运行的 Memcached Operator 管理的 Memcached 实例就越独特。

   $ 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

5. 更新应用程序。

   通过引用旧 Operator 清单的 replaces 字段来创建新 Operator 清单，以手动更新 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