使用 CRD 扩展 Kubernetes API - 理解 Operators | Operators | OpenShift Container Platform 4.17

自定义资源定义
创建自定义资源定义
为自定义资源定义创建集群角色
从文件创建自定义资源
检查自定义资源

运算符特别使用了 Kubernetes 扩展机制，即自定义资源定义 (CRD)，以便运算符管理的自定义对象看起来和行为都像内置的原生 Kubernetes 对象一样。本指南介绍集群管理员如何通过创建和管理 CRD 来扩展其 OpenShift Container Platform 集群。

自定义资源定义

在 Kubernetes API 中，资源是一个端点，它存储特定种类 API 对象的集合。例如，内置的 Pods 资源包含 Pod 对象的集合。

自定义资源定义 (CRD) 对象在集群中定义了一种新的、唯一的对象类型（称为种类），并允许 Kubernetes API 服务器处理其整个生命周期。

自定义资源 (CR) 对象是从已由集群管理员添加到集群的 CRD 创建的，允许所有集群用户将新的资源类型添加到项目中。

当集群管理员向集群添加新的 CRD 时，Kubernetes API 服务器会通过创建一个新的 RESTful 资源路径来响应，整个集群或单个项目（命名空间）都可以访问该路径，并开始服务指定的 CR。

想要向其他用户授予对 CRD 的访问权限的集群管理员可以使用集群角色聚合向具有 admin、edit 或 view 默认集群角色的用户授予访问权限。集群角色聚合允许将自定义策略规则插入到这些集群角色中。此行为将新资源集成到集群的 RBAC 策略中，就好像它是内置资源一样。

运算符特别是通过将其与任何所需的 RBAC 策略和其他特定于软件的逻辑打包来使用 CRD。集群管理员也可以手动将 CRD 添加到集群中，而无需依赖运算符的生命周期，从而使所有用户都可以使用它们。

虽然只有集群管理员可以创建 CRD，但如果开发人员对 CRD 具有读写权限，他们可以从现有 CRD 创建 CR。

创建自定义资源定义

要创建自定义资源 (CR) 对象，集群管理员必须首先创建一个自定义资源定义 (CRD)。

先决条件

访问具有 cluster-admin 用户权限的 OpenShift Container Platform 集群。

步骤

要创建 CRD

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

CRD 的示例 YAML 文件

apiVersion: apiextensions.k8s.io/v1 (1)
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com (2)
spec:
  group: stable.example.com (3)
  versions:
    - name: v1 (4)
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                cronSpec:
                  type: string
                image:
                  type: string
                replicas:
                  type: integer
  scope: Namespaced (5)
  names:
    plural: crontabs (6)
    singular: crontab (7)
    kind: CronTab (8)
    shortNames:
    - ct (9)

1	使用 `apiextensions.k8s.io/v1` API。
2	指定定义的名称。这必须采用 `<plural-name>.<group>` 格式，使用 `group` 和 `plural` 字段中的值。
3	指定API的组名。API组是逻辑相关的对象集合。例如，所有批处理对象，如`Job`或`ScheduledJob`，都可以放在批处理API组中（例如`batch.api.example.com`）。最佳实践是使用组织的完全限定域名 (FQDN)。
4	指定要在URL中使用的版本名。每个API组可以存在多个版本，例如`v1alpha`、`v1beta`、`v1`。
5	指定自定义对象是可用于单个项目 (`Namespaced`) 还是集群中的所有项目 (`Cluster`)。
6	指定在URL中使用的复数名称。`plural`字段与API URL中的资源相同。
7	指定用作CLI别名和显示的单数名称。
8	指定可以创建的对象类型。类型可以用驼峰式命名法。
9	指定在CLI上匹配您的资源的较短字符串。

默认情况下，CRD是集群范围的，所有项目都可以使用。

创建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。对象类型基于您创建的CRD对象的spec.kind字段。

为自定义资源定义创建集群角色

集群管理员可以为现有的集群范围自定义资源定义 (CRD) 授予权限。如果您使用admin、edit和view默认集群角色，则可以利用集群角色聚合来实现其规则。

您必须明确地为每个角色分配权限。权限较多的角色不会继承权限较少的角色的规则。如果您为某个角色分配规则，则还必须将该动词分配给权限较多的角色。例如，如果您向view角色授予get crontabs权限，则还必须将其授予edit和admin角色。admin或edit角色通常分配给通过项目模板创建项目的用户。

先决条件

创建CRD。

步骤

为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 (2)
  labels:
    # Add these permissions to the "view" default role.
    rbac.authorization.k8s.io/aggregate-to-view: "true" (8)
    rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true" (9)
rules:
- apiGroups: ["stable.example.com"] (5)
  resources: ["crontabs"] (6)
  verbs: ["get", "list", "watch"] (7)

1	使用`rbac.authorization.k8s.io/v1` API。
2	指定定义的名称。
3	指定此标签以向admin默认角色授予权限。
4	指定此标签以向edit默认角色授予权限。
5	指定CRD的组名。
6	指定这些规则适用的CRD的复数名称。
7	指定表示授予角色的权限的动词。例如，将读写权限应用于`admin`和`edit`角色，只将读取权限应用于`view`角色。
8	指定此标签以向`view`默认角色授予权限。
9	指定此标签以向`cluster-reader`默认角色授予权限。

创建集群角色
```
$ oc create -f <file_name>.yaml
```

从文件创建自定义资源

将自定义资源定义 (CRD) 添加到集群后，可以使用CLI从文件使用CR规范创建自定义资源 (CR)。

先决条件

由集群管理员添加到集群的CRD。

步骤

为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	从CRD中指定组名和API版本（名称/版本）。
2	在CRD中指定类型。
3	为对象指定名称。
4	指定对象的终结器（如有）。终结器允许控制器实现必须在删除对象之前完成的条件。
5	指定特定于对象类型的条件。

创建文件后，创建对象
```
$ oc create -f <file_name>.yaml
```

检查自定义资源

可以使用CLI检查集群中存在的自定义资源 (CR) 对象。

先决条件

CR对象存在于您有权访问的命名空间中。

步骤

要获取有关特定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
```

您还可以查看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 (1)

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

使用自定义资源定义扩展 Kubernetes API

自定义资源定义

创建自定义资源定义

为自定义资源定义创建集群角色

从文件创建自定义资源

检查自定义资源