2.7. CRD

2.7.1. 使用自定义资源定义来扩展 Kubernetes API

Operator 使用 Kubernetes 扩展机制(自定义资源定义(CRD)),以便使由 Operator 管理的自定义类似于内置的原生 Kubernetes 对象。本指南介绍了集群管理员如何通过创建和管理 CRD 来扩展其 OpenShift Container Platform 集群。

2.7.1.1. 自定义资源定义

在 Kubernetes API 中,resource(资源)是存储某一类 API 对象集的端点。例如,内置 Pod 资源包含一组 Pod 对象。

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

自定义资源 (CR) 对象由集群管理员通过集群中已添加的 CRD 创建,并支持所有集群用户在项目中增加新的资源类型。

当集群管理员增加新 CRD 至集群中时,Kubernetes API 服务器的回应方式是新建一个可由整个集群或单个项目(命名空间)访问的 RESTful 资源路径,并开始服务于指定的 CR。

集群管理员如果要向其他用户授予 CRD 访问权限,可使用集群角色聚合来向用户授予 admineditview 默认集群角色访问权限。集群角色聚合支持将自定义策略规则插入到这些集群角色中。此行为将新资源整合到集群的 RBAC 策略中,就像内置资源一样。

Operator 会通过将 CRD 与任何所需 RBAC 策略和其他软件特定逻辑打包到一起来利用 CRD。集群管理员也可以手动将 CRD 添加到 Operator 生命周期之外的集群中,供所有用户使用。

注意

虽然只有集群管理员可创建 CRD,但具有 CRD 读写权限的开发人员也可通过现有 CRD 来创建 CR。

2.7.1.2. 创建自定义资源定义

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

先决条件

  • cluster-admin 用户身份访问 OpenShift Container Platform 集群。

流程

要创建 CRD:

  1. 先创建一个包含以下字段类型的 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
      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> 格式,并使用来自 groupplural 字段的值。
    3
    为 API 指定组名。API 组是一个逻辑上相关的对象集。例如,JobScheduledJob 等所有批处理对象,均可添加至批处理 API 组(如 batch.api.example.com)中。最好使用您机构的完全限定域名(FQDN)。
    4
    指定 URL 中要用的版本名称。每个 API 组都可能存在于多个版本中,例如 v1alphav1betav1
    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。对象类型基于您创建的 CRD 对象的 spec.kind 字段。

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

集群管理员可向现有集群范围的自定义资源定义 (CRD) 授予权限。如果使用 admineditview 默认集群角色,请利用集群角色聚合来制定规则。

重要

您必须为每个角色明确分配权限。权限更多的角色不会继承权限较少角色的规则。如果要为某个角色分配规则,还必须将该操作动词分配给具有更多权限的角色。例如,如果要向 view 角色授予 get crontabs 的权限,也必须向 editadmin 角色授予该权限。adminedit 角色通常会分配给通过项目模板创建项目的用户。

先决条件

  • 创建 CRD。

流程

  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
    指定代表角色所获得的权限的操作动词。例如,对 adminedit 角色应用读写权限,对 view 角色应用只读权限。
    9
    指定该标签向 view 默认角色授予权限。
    10
    指定该标签向 cluster-reader 默认角色授予权限。
  2. 创建集群角色:

    $ oc create -f <file_name>.yaml

2.7.1.4. 通过文件创建自定义资源

将自定义资源定义 (CRD) 添加至集群后,可使用 CLI 按照自定义资源 (CR) 规范通过文件创建 CR。

先决条件

  • 集群管理员已将 CRD 添加至集群中。

流程

  1. 为 CR 创建 YAML 文件。在下面的定义示例中,cronSpecimage 自定义字段在 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
    指定特定于对象类型的条件。
  2. 创建完文件后,再创建对象:

    $ oc create -f <file_name>.yaml

2.7.1.5. 检查自定义资源

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

先决条件

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

流程

  1. 要获取特定类型的 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 的自定义数据。