Operator

流程

1. 在 Web 控制台中导航至 Operators → OperatorHub 页面。

2. 在 Filter by keyword 方框中滚动或键入关键词（本例中为 Couchbase），以查找所需 Operator。

   图 4.1. 通过关键词筛选 Operator

   
3. 选定 Operator。对于社区 Operator 来说，系统会提醒您红帽对这类 Operator 不予认证。您必须确认收到该提醒才可继续。这时会显示 Operator 信息。
4. 阅读 Operator 信息并单击 Install。

5. 在 Create Operator Subscription 页面：

   1. 任选以下一项：

      • All namespaces on the cluster (default)，选择该项会将 Operator 安装至默认 openshift-operators 命名空间，以便供集群中的所有命名空间监视和使用。该选项并非始终可用。
      • A specific namespace on the cluster，该项支持您选择单一特定命名空间来安装 Operator。该 Operator 仅限在该单一命名空间中监视和使用。
   2. 选择一个更新频道（如有多个可用）。
   3. 如前面所述，选择自动或手动批准策略。

6. 单击 Subscribe，以便该 Operator 可供 OpenShift Container Platform 集群上的所选命名空间使用。

   1. 如果选择手动批准策略，则订阅的升级状态将保持正在升级，直至您审核并批准该 Install Plan。

      图 4.2. 在 Install Plan 页面手动批准

      

      在 Install Plan 页面批准后，订阅的升级状态将变为最新。

   2. 如果选择自动批准策略，则升级状态应自动变为最新，而无需人为干预。

      图 4.3. 订阅升级状态：最新

      

7. 当订阅的升级状态变为最新后，选择 Operators → Installed Operators 来验证最终是否出现了 Couchbase ClusterServiceVersion (CSV) 且其 Status 在相关命名空间中最终能否解析为 InstallSucceeded。

   注意

   对于 All namespaces…​ Installation 模式，状态在 openshift-operators 命名空间中解析为 InstallSucceeded，但如果检查其他命名空间，则状态为 Copied。

   如果没有：

   1. 检查 openshift-operators 项目（如果选择了 A specific namespace…​ Installation Mode）中的 openshift-operators 项目中的 Pod 的日志，这会在 Workloads → Pods 页面中报告问题以便进一步排除故障。

流程

1. 查看 OperatorHub 中集群可用的 Operator 列表。

   $ oc get packagemanifests -n openshift-marketplace
   NAME                               CATALOG               AGE
   3scale-operator                    Red Hat Operators     91m
   amq-online                         Red Hat Operators     91m
   amq-streams                        Red Hat Operators     91m
   ...
   couchbase-enterprise-certified     Certified Operators   91m
   mariadb                            Certified Operators   91m
   mongodb-enterprise                 Certified Operators   91m
   ...
   etcd                               Community Operators   91m
   jaeger                             Community Operators   91m
   kubefed                            Community Operators   91m
   ...

   注意适用于您所需 Operator 的 CatalogSource。

2. 检查所需 Operator，以验证其支持的 InstallMode 和可用频道：

   $ oc describe packagemanifests <operator_name> -n openshift-marketplace

3. OperatorGroup 是一个 OLM 资源用来选择目标命名空间。在这些目标命名空间中生成与 OperatorGroup 相同的命名空间中的所有 Operator 所需的 RBAC 访问。

   订阅 Operator 的命名空间必须具有与 Operator 的 InstallMode 相匹配的 OperatorGroup，可采用 AllNamespaces 模式，也可采用 SingleNamespace 模式。如果要安装的 Operator 采用 AllNamespaces 模式，则表明 openshift-operators 命名空间中已有适当的 OperatorGroup。

   如果要安装的 Operator 采用 SingleNamespace 模式，而您没有适当的 OperatorGroup，则必须创建一个。

   注意

   如果选择 SingleNamespace 模式，该流程的 Web 控制台版本会在后台自动为您处理 OperatorGroup 和订阅对象的创建。

   1. 创建 OperatorGroup 对象 YAML 文件，如 operatorgroup.yaml：

      OperatorGroup 示例

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: <operatorgroup_name>
        namespace: <namespace>
      spec:
        targetNamespaces:
        - <namespace>

   2. 创建 OperatorGroup 对象：

      $ oc apply -f operatorgroup.yaml

4. 创建一个订阅对象 YAML 文件，以便为 Operator 订阅一个命名空间，如 sub.yaml：

   订阅示例

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: <operator_name>
     namespace: openshift-operators 1
   spec:
     channel: alpha
     name: <operator_name> 2
     source: redhat-operators 3
     sourceNamespace: openshift-marketplace 4

   1

   如果使用 AllNamespaces InstallMode，请指定 openshift-operators 命名空间。如果使用 SingleNamespace InstallMode，则指定相关单一命名空间。

   2

   要订阅的 Operator 的名称。

   3

   提供 Operator 的 CatalogSource 的名称。

   4

   CatalogSource 的命名空间。将 openshift-marketplace 用于默认的 OperatorHub CatalogSource。

5. 创建订阅对象：

   $ oc apply -f sub.yaml

   此时，OLM 已了解所选的 Operator。Operator 的 ClusterServiceVersion (CSV) 应出现在目标命名空间中，由 Operator 提供的 API 应可用于创建。

1. OLM 提取给定订阅对象。
2. OLM 获取与该订阅相关联的 OperatorGroup。
3. OLM 确定 OperatorGroup 是否已指定服务账户。
4. OLM 在服务账户范围内创建一个客户端，并使用该范围内客户端来安装 Operator。这样可确保 OperatorGroup 所请求的任何权限始终处于 OperatorGroup 中服务账户的权限范围内。
5. OLM 新建一个服务账户，在 CSV 中指定其权限集，并将其分配至 Operator。Operator 将根据所分配的服务账户运行。

1. 先创建一个包含以下字段类型的 YAML 文件：

   CRD 的 YAML 文件示例

   apiVersion: apiextensions.k8s.io/v1beta1 1
   kind: CustomResourceDefinition
   metadata:
     name: crontabs.stable.example.com 2
   spec:
     group: stable.example.com 3
     version: v1 4
     scope: Namespaced 5
     names:
       plural: crontabs 6
       singular: crontab 7
       kind: CronTab 8
       shortNames:
       - ct 9

   1

   使用 apiextensions.k8s.io/v1beta1 API。

   2

   为定义指定名称。名称必须采用 <plural-name>.<group> 格式，并使用来自 group 和 plural 字段的值。

   3

   为 API 指定组名。API 组是一个逻辑上相关的对象集。例如，Job 或 ScheduledJob 等所有批处理对象，均可添加至批处理 API 组 (如 batch.api.example.com) 中。最好使用组织的完全限定域名。

   4

   指定 URL 中要用的版本名称。每个 API 组均可能存在于多个版本中。例如：v1alpha、v1beta、v1。

   5

   指定自定义对象可用于某一个项目 (Namespaced) 还是集群中的所有项目 (Cluster)。

   6

   指定 URL 中要用的复数名称。plural 字段与 API URL 网址中的资源相同。

   7

   指定将在 CLI 上用作别名并用于显示的单数名称。

   8

   指定可创建的对象类型。类型可以采用 CamelCase。

   9

   指定与 CLI 中的资源相匹配的较短字符串。

   注意

   默认情况下，CRD 的覆盖范围为整个集群，适用于所有项目。

2. 创建 CRD 对象：

   $ oc create -f <file_name>.yaml

   在以下位置新建一个 RESTful API 端点：

   /apis/<spec:group>/<spec:version>/<scope>/*/<names-plural>/...

   例如，以下端点便是通过示例文件创建的：

   /apis/stable.example.com/v1/namespaces/*/crontabs/...

   现在，您即可使用该端点 URL 来创建和管理 CR。对象 Kind 基于您所创建的 CRD 对象的 spec.kind 字段。

流程

1. 为 CRD 创建集群角色定义文件。集群角色定义是一个 YAML 文件，其中包含适用于各个集群角色的规则。OpenShift Container Platform 控制器会将您指定的规则添加至默认集群角色中。

   集群角色定义的 YAML 文件示例

   kind: ClusterRole
   apiVersion: rbac.authorization.k8s.io/v1 1
   metadata:
     name: aggregate-cron-tabs-admin-edit 2
     labels:
       rbac.authorization.k8s.io/aggregate-to-admin: "true" 3
       rbac.authorization.k8s.io/aggregate-to-edit: "true" 4
   rules:
   - apiGroups: ["stable.example.com"] 5
     resources: ["crontabs"] 6
     verbs: ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"] 7
   ---
   kind: ClusterRole
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
     name: aggregate-cron-tabs-view 8
     labels:
       # Add these permissions to the "view" default role.
       rbac.authorization.k8s.io/aggregate-to-view: "true" 9
       rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true" 10
   rules:
   - apiGroups: ["stable.example.com"] 11
     resources: ["crontabs"] 12
     verbs: ["get", "list", "watch"] 13

   1

   使用 rbac.authorization.k8s.io/v1 API。

   2 8

   为定义指定名称。

   3

   指定该标签向 admin 默认角色授予权限。

   4

   指定该标签向 edit 默认角色授予权限。

   5 11

   指定 CRD 的组名。

   6 12

   指定适用于这些规则的 CRD 的复数名称。

   7 13

   指定代表角色所获得的权限的操作动词。例如，对 admin 和 edit 角色应用读写权限，对 view 角色应用只读权限。

   9

   指定该标签向 view 默认角色授予权限。

   10

   指定该标签向 cluster-reader 默认角色授予权限。

2. 创建集群角色：

   $ oc create -f <file_name>.yaml

流程

1. 为 CR 创建 YAML 文件。在下面的定义示例中，cronSpec 和 image 自定义字段在 Kind: CronTab 的 CR 中设定。Kind 来自 CRD 对象的 spec.kind 字段。

   CR 的 YAML 文件示例

   apiVersion: "stable.example.com/v1" 1
   kind: CronTab 2
   metadata:
     name: my-new-cron-object 3
     finalizers: 4
     - finalizer.stable.example.com
   spec: 5
     cronSpec: "* * * * /5"
     image: my-awesome-cron-image

   1

   指定自定义资源定义中的组名和 API 版本（名称/版本）。

   2

   指定 CRD 中的类型。

   3

   指定对象的名称。

   4

   指定对象的结束程序（如有）。结束程序可让控制器实现在删除对象之前必须完成的条件。

   5

   指定特定于对象类型的条件。

2. 创建完文件后，再创建对象：

   $ oc create -f <file_name>.yaml

流程

1. 要获得特定 Kind 的 CR 的信息，请运行：

   $ oc get <kind>

   例如：

   $ oc get crontab
   
   NAME                 KIND
   my-new-cron-object   CronTab.v1.stable.example.com

   资源名称不区分大小写，您既可使用 CRD 中定义的单数或复数形式，也可使用简称。例如：

   $ oc get crontabs
   $ oc get crontab
   $ oc get ct

2. 还可查看 CR 的原始 YAML 数据：

   $ oc get <kind> -o yaml

   $ oc get ct -o yaml
   
   apiVersion: v1
   items:
   - apiVersion: stable.example.com/v1
     kind: CronTab
     metadata:
       clusterName: ""
       creationTimestamp: 2017-05-31T12:56:35Z
       deletionGracePeriodSeconds: null
       deletionTimestamp: null
       name: my-new-cron-object
       namespace: default
       resourceVersion: "285"
       selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object
       uid: 9423255b-4600-11e7-af6a-28d2447dc82b
     spec:
       cronSpec: '* * * * /5' 1
       image: my-awesome-cron-image 2

   1 2

   显示用于创建对象的 YAML 的自定义数据。

流程

1. 为 CR 创建 YAML 文件。在下面的定义示例中，cronSpec 和 image 自定义字段在 Kind: CronTab 的 CR 中设定。Kind 来自 CRD 对象的 spec.kind 字段。

   CR 的 YAML 文件示例

   apiVersion: "stable.example.com/v1" 1
   kind: CronTab 2
   metadata:
     name: my-new-cron-object 3
     finalizers: 4
     - finalizer.stable.example.com
   spec: 5
     cronSpec: "* * * * /5"
     image: my-awesome-cron-image

   1

   指定自定义资源定义中的组名和 API 版本（名称/版本）。

   2

   指定 CRD 中的类型。

   3

   指定对象的名称。

   4

   指定对象的结束程序（如有）。结束程序可让控制器实现在删除对象之前必须完成的条件。

   5

   指定特定于对象类型的条件。

2. 创建完文件后，再创建对象：

   $ oc create -f <file_name>.yaml

流程

1. 要获得特定 Kind 的 CR 的信息，请运行：

   $ oc get <kind>

   例如：

   $ oc get crontab
   
   NAME                 KIND
   my-new-cron-object   CronTab.v1.stable.example.com

   资源名称不区分大小写，您既可使用 CRD 中定义的单数或复数形式，也可使用简称。例如：

   $ oc get crontabs
   $ oc get crontab
   $ oc get ct

2. 还可查看 CR 的原始 YAML 数据：

   $ oc get <kind> -o yaml

   $ oc get ct -o yaml
   
   apiVersion: v1
   items:
   - apiVersion: stable.example.com/v1
     kind: CronTab
     metadata:
       clusterName: ""
       creationTimestamp: 2017-05-31T12:56:35Z
       deletionGracePeriodSeconds: null
       deletionTimestamp: null
       name: my-new-cron-object
       namespace: default
       resourceVersion: "285"
       selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object
       uid: 9423255b-4600-11e7-af6a-28d2447dc82b
     spec:
       cronSpec: '* * * * /5' 1
       image: my-awesome-cron-image 2

   1 2

   显示用于创建对象的 YAML 的自定义数据。

流程

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

流程

1. 创建新 Operator 项目。命名空间范围的 Operator 会监视和管理单一命名空间中的资源。命名空间范围的 Operator 因具有高灵活性而常被视为首选。这类 Operator 支持解耦升级、针对故障和监控隔离命名空间以及区别化 API 定义。

   要创建基于 Ansible 的、全命名空间范围的新 memcached-operator 项目并改为其目录，请使用以下命令：

   $ operator-sdk new memcached-operator \
       --api-version=cache.example.com/v1alpha1 \
       --kind=Memcached \
       --type=ansible
   $ cd memcached-operator

   这样会创建一个 memcached-operator 项目，专门用于监视 APIVersion 为 example.com/v1apha1、Kind 为 Memcached 的 Memcached 资源。

2. 自定义 Operator 逻辑。

   在本例中，memcached-operator 会针对每个 Memcached 自定义资源 (CR) 执行以下协调逻辑：

   • 如果尚无 memcached Deployment，请创建一个。
   • 确保 Deployment 大小与 Memcached CR 指定的大小相同。

   默认情况下，memcached-operator 会监视 Memcached 资源事件，如 watches.yaml 文件中所示，并执行 Ansible 角色 Memcached：

   - version: v1alpha1
     group: cache.example.com
     kind: Memcached

   您可选择在 watches.yaml 文件中自定义以下逻辑：

   1. 指定 role 选项会将 Operator 配置为在通过 Ansible 角色启动 ansible-runner 时使用该指定路径。默认情况下，新命令会填写一个绝对路径，指向您的角色应前往的位置：

      - version: v1alpha1
        group: cache.example.com
        kind: Memcached
        role: /opt/ansible/roles/memcached

   2. 指定 watches.yaml 文件中的 playbook 选项会将 Operator 配置为在通过 Ansible playbook 启动 ansible-runner 时使用该指定路径。

      - version: v1alpha1
        group: cache.example.com
        kind: Memcached
        playbook: /opt/ansible/playbook.yaml

3. 构建 Memcached Ansible 角色。

   修改 roles/memcached/ 目录下生成的 Ansible 角色。该 Ansible 角色会控制修改资源时所执行的逻辑。

   1. 定义 Memcached spec。

      可完全在 Ansible 中定义基于 Ansible 的 Operator spec。Ansible Operator 会将 CR spec 字段中列出的所有键值对作为变量传递给 Ansible。在运行 Ansible 之前，Operator 会将 spec 字段中所有变量的名称转换为 snake 格式（小写并附带下划线）。例如，spec 中的 serviceAccount 在 Ansible 中会变成 service_account。

      提示

      您应在 Ansible 中对变量执行一些类型验证，以确保应用程序收到所需输入。

      如果用户未设置 spec 字段，则请修改 roles/memcached/defaults/main.yml 文件设置默认值：

      size: 1

   2. 定义 Memcached Deployment。

      定义了 Memcached spec 后，即可定义资源发生更改时实际应执行的 Ansible。因为这是一个 Ansible 角色，所以默认行为是执行 roles/memcached/tasks/main.yml 文件中的任务。

      目的是在不存在 Deployment 的情况下让 Ansible 创建 Deployment，该 Deployment 将运行 memcached:1.4.36-alpine 镜像。Ansible 2.7+ 支持 k8s Ansible 模块，本示例利用该模块来控制 Deployment 定义。

      修改 roles/memcached/tasks/main.yml 以匹配以下内容：

      - name: start memcached
        k8s:
          definition:
            kind: Deployment
            apiVersion: apps/v1
            metadata:
              name: '{{ meta.name }}-memcached'
              namespace: '{{ 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

      注意

      本示例使用 size 变量来控制 Memcached Deployment 的副本数。本示例将默认值设定为 1，但任何用户都可以创建一个 CR 覆盖该默认值。

4. 部署 CRD。

   在运行 Operator 之前，Kubernetes 需要了解 Operator 将会监视的新自定义资源定义 (CRD)。部署 Memcached CRD：

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

5. 构建并运行 Operator。

   有两种方式来构建和运行 Operator：

   • 作为 Kubernetes 集群内的一个 Pod。
   • 作为集群外的 Go 程序，使用 operator-sdk up 命令。

   选择以下任一方法：

   1. 作为 Kubernetes 集群内的一个 Pod 来运行。这是生产环境的首先方法。

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

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

      2. deploy/operator.yaml 文件中会生成 Deployment 清单。本文件中的部署镜像需要从占位符 REPLACE_IMAGE 修改为之前构建的镜像。为此，请运行：

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

      3. 部署 memcached-operator：

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

      4. 验证 memcached-operator 是否正在运行：

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

   2. 在集群外运行。这是开发阶段的首选方法，可加快部署和测试的速度。

      请确保已安装 Ansible Runner 和 Ansible Runner HTTP Plug-in，否则在创建 CR 时，系统会显示 Ansible Runner 出现意外错误。

      此外，还务必要确保您的计算机上存在 watches.yaml 文件中引用的角色路径。因为通常会在磁盘上角色所处的位置使用容器，所以必须手动将角色复制到已配置的 Ansible 角色路径中（如 /etc/ansible/roles）。

      1. 要使用 $HOME/.kube/config 中的默认 Kubernetes 配置文件在本地运行 Operator：

         $ operator-sdk up local

         要使用所提供的 Kubernetes 配置文件在本地运行 Operator：

         $ operator-sdk up local --kubeconfig=config

6. 创建一个 Memcached CR。

   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，确认已创建三个副本：

      $ 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

7. 更新大小。

   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
      
      $ oc apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml

   2. 确认 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/operator.yaml
   $ oc delete -f deploy/role_binding.yaml
   $ oc delete -f deploy/role.yaml
   $ oc delete -f deploy/service_account.yaml
   $ oc delete -f deploy/crds/cache_v1alpha1_memcached_crd.yaml

流程

1. 要通过应用程序手动跟踪 CR 状态，请将 manageStatus 字段设置为 false 来更新 Watches 文件：

   - version: v1
     group: api.example.com
     kind: Foo
     role: /opt/ansible/roles/Foo
     manageStatus: false

2. 然后，使用 k8s_status Ansible 模块来更新子资源。例如：要使用键 foo 和值 bar 来更新，可使用 k8s_status，如下所示：

   - k8s_status:
     api_version: app.example.com/v1
     kind: Foo
     name: "{{ meta.name }}"
     namespace: "{{ meta.namespace }}"
     status:
       foo: bar

流程

1. 创建新 Operator 项目。命名空间范围的 Operator 会监视和管理单一命名空间中的资源。命名空间范围的 Operator 因具有高灵活性而常被视为首选。这类 Operator 支持解耦升级、针对故障和监控隔离命名空间以及区别化 API 定义。

   要创建基于 Helm 的、全命名空间范围的新 nginx-operator 项目，请使用以下命令：

   $ operator-sdk new nginx-operator \
     --api-version=example.com/v1alpha1 \
     --kind=Nginx \
     --type=helm
   $ cd nginx-operator

   这样会创建一个 nginx-operator 项目，专门用于监视 APIVersion 为 example.com/v1apha1、Kind 为 Nginx 的 Nginx 资源。

2. 自定义 Operator 逻辑。

   在本例中，nginx-operator 会针对每个 Nginx 自定义资源 (CR) 执行以下协调逻辑：

   • 如果尚无 Nginx Deployment，请创建一个。
   • 如果尚无 Nginx Service，请创建一个。
   • 如果支持 Nginx Ingress 但尚不存在，请创建一个。
   • 确保 Deployment、Service 和可选的 Ingress 符合 Nginx CR 指定的所需配置（如副本数、镜像、服务类型）。

   默认情况下，nginx-operator 会监视 Vginx 资源事件，如 watches.yaml 文件中所示，并使用指定 Chart 执行 Helm 发行版本：

   - version: v1alpha1
     group: example.com
     kind: Nginx
     chart: /opt/helm/helm-charts/nginx

   1. 查阅 Nginx Helm Chart。

      创建 Helm Operator 项目后，Operator SDK 会创建一个 Helm Chart 示例，其中包含一组模板，用于简单的 Nginx 发行版本。

      本例中，针对 Deployment、Service 和 Ingress 资源提供了模板，另外还有 NOTES.txt 模板，Helm Chart 开发人员可利用该模板传达有关发型版本的实用信息。

      如果您对 Helm Chart 还不够熟悉，请花一点时间查阅 Helm Chart开发人员文档。

   2. 了解 Nginx CR spec。

      Helm 会使用一个名为 values 的概念来自定义 Helm Chart 的默认值，具体值在 Helm Chart 的 values.yaml 文件中定义。

      通过在 CR spec 中设置所需值来覆盖这些默认值。以副本数量为例：

      1. 首先，检查 helm-charts/nginx/values.yaml 文件，会发现 Chart 有一个名为 replicaCount 的值，默认设置为 1。要在部署中使用 2 个 Nginx 实例，您的 CR spec 中必须包含 replicaCount: 2。

         更新 deploy/crds/example.com_v1alpha1_nginx_cr.yaml 文件，如下所示：

         apiVersion: example.com/v1alpha1
         kind: Nginx
         metadata:
           name: example-nginx
         spec:
           replicaCount: 2

      2. 同样，服务端口默认设置为 80。要改用 8080，请通过添加服务端口覆盖来再次更新 deploy/crds/example.com_v1alpha1_nginx_cr.yaml 文件：

         apiVersion: example.com/v1alpha1
         kind: Nginx
         metadata:
           name: example-nginx
         spec:
           replicaCount: 2
           service:
             port: 8080

         Helm Operator 应用整个 spec，将其视为 values 文件内容，与 helm install -f ./overrides.yaml 命令的工作方式类似。

3. 部署 CRD。

   在运行 Operator 之前，Kubernetes 需要了解 Operator 将会监视的新自定义资源定义 (CRD)。部署以下 CRD：

   $ oc create -f deploy/crds/example_v1alpha1_nginx_crd.yaml

4. 构建并运行 Operator。

   有两种方式来构建和运行 Operator：

   • 作为 Kubernetes 集群内的一个 Pod。
   • 作为集群外的 Go 程序，使用 operator-sdk up 命令。

   选择以下任一方法：

   1. 作为 Kubernetes 集群内的一个 Pod 来运行。这是生产环境的首先方法。

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

         $ operator-sdk build quay.io/example/nginx-operator:v0.0.1
         $ podman push quay.io/example/nginx-operator:v0.0.1

      2. deploy/operator.yaml 文件中会生成 Deployment 清单。本文件中的部署镜像需要从占位符 REPLACE_IMAGE 修改为之前构建的镜像。为此，请运行：

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

      3. 部署 nginx-operator：

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

      4. 验证 nginx-operator 是否正在运行：

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

   2. 在集群外运行。这是开发阶段的首选方法，可加快部署和测试的速度。

      此外，还务必要确保您的计算机上存在 watches.yaml 文件中引用的 Chart 路径。watches.yaml 文件默认能够与通过 operator-sdk build 命令构建的 Operator 镜像一起使用。当使用 operator-sdk up local 命令开发和测试您的 Operator 时，SDK 会在您的本地文件系统中查找该路径。

      1. 在该位置创建符号链接，以指向您的 Helm Chart 路径：

         $ sudo mkdir -p /opt/helm/helm-charts
         $ sudo ln -s $PWD/helm-charts/nginx /opt/helm/helm-charts/nginx

      2. 要使用 $HOME/.kube/config 中的默认 Kubernetes 配置文件在本地运行 Operator：

         $ operator-sdk up local

         要使用所提供的 Kubernetes 配置文件在本地运行 Operator：

         $ operator-sdk up local --kubeconfig=<path_to_config>

5. 部署 Nginx CR。

   应用之前修改的 Nginx CR：

   $ oc apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml

   确保 nginx-operator 为 CR 创建部署：

   $ oc get deployment
   NAME                                           DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
   example-nginx-b9phnoz9spckcrua7ihrbkrt1        2         2         2            2           1m

   检查 Pod，确认已创建两个副本：

   $ oc get pods
   NAME                                                      READY     STATUS    RESTARTS   AGE
   example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-fjcr9   1/1       Running   0          1m
   example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-ljbzl   1/1       Running   0          1m

   检查 Service 端口是否已设置为 8080：

   $ oc get service
   NAME                                      TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)    AGE
   example-nginx-b9phnoz9spckcrua7ihrbkrt1   ClusterIP   10.96.26.3   <none>        8080/TCP   1m

6. 更新 replicaCount 并删除端口。

   将 spec.replicaCount 字段从 2 改为 3，删除 spec.service 字段并应用更改：

   $ cat deploy/crds/example.com_v1alpha1_nginx_cr.yaml
   apiVersion: "example.com/v1alpha1"
   kind: "Nginx"
   metadata:
     name: "example-nginx"
   spec:
     replicaCount: 3
   
   $ oc apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml

   确认 Operator 已更改 Deployment 大小：

   $ oc get deployment
   NAME                                           DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
   example-nginx-b9phnoz9spckcrua7ihrbkrt1        3         3         3            3           1m

   检查 Service 端口是否已设置为默认值 80。

   $ oc get service
   NAME                                      TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)  AGE
   example-nginx-b9phnoz9spckcrua7ihrbkrt1   ClusterIP   10.96.26.3   <none>        80/TCP   1m

7. 清理资源：

   $ oc delete -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml
   $ oc delete -f deploy/operator.yaml
   $ oc delete -f deploy/role_binding.yaml
   $ oc delete -f deploy/role.yaml
   $ oc delete -f deploy/service_account.yaml
   $ oc delete -f deploy/crds/example_v1alpha1_nginx_crd.yaml

流程

1. 在 Operator 项目中，通过修改 deploy/olm-catalog/csv-config.yaml 文件来配置您的 CSV 组成（如果需要）。

2. 生成 CSV：

   $ operator-sdk olm-catalog gen-csv --csv-version <version>

3. 在 deploy/olm-catalog/ 目录中生成的新 CSV 中，确保正确设置所有必填的手动定义字段。