扩展 Kubernetes API

• 1: 定制资源
• 2: Kubernetes API 聚合层

1 - 定制资源

定制资源（Custom Resource） 是对 Kubernetes API 的扩展。 本页讨论何时向 Kubernetes 集群添加定制资源，何时使用独立的服务。 本页描述添加定制资源的两种方法以及怎样在二者之间做出抉择。

定制资源

资源（Resource） 是 Kubernetes API 中的一个端点， 其中存储的是某个类别的 API 对象的一个集合。 例如内置的 Pod 资源包含一组 Pod 对象。

定制资源（Custom Resource） 是对 Kubernetes API 的扩展，不一定在默认的 Kubernetes 安装中就可用。定制资源所代表的是对特定 Kubernetes 安装的一种定制。 不过，很多 Kubernetes 核心功能现在都用定制资源来实现，这使得 Kubernetes 更加模块化。

定制资源可以通过动态注册的方式在运行中的集群内或出现或消失，集群管理员可以独立于集群更新定制资源。 一旦某定制资源被安装，用户可以使用 kubectl 来创建和访问其中的对象，就像他们为 Pod 这种内置资源所做的一样。

定制控制器

就定制资源本身而言，它只能用来存取结构化的数据。 当你将定制资源与定制控制器（Custom Controller） 结合时， 定制资源就能够提供真正的声明式 API（Declarative API）。

Kubernetes 声明式 API 强制对职权做了一次分离操作。 你声明所用资源的期望状态，而 Kubernetes 控制器使 Kubernetes 对象的当前状态与你所声明的期望状态保持同步。 声明式 API 的这种机制与命令式 API（你指示服务器要做什么，服务器就去做什么）形成鲜明对比。

你可以在一个运行中的集群上部署和更新定制控制器，这类操作与集群的生命周期无关。 定制控制器可以用于任何类别的资源，不过它们与定制资源结合起来时最为有效。 Operator 模式就是将定制资源与定制控制器相结合的。 你可以使用定制控制器来将特定于某应用的领域知识组织起来，以编码的形式构造对 Kubernetes API 的扩展。

我是否应该向我的 Kubernetes 集群添加定制资源？

在创建新的 API 时， 请考虑是将你的 API 与 Kubernetes 集群 API 聚合起来， 还是让你的 API 独立运行。

声明式 API

典型地，在声明式 API 中：

• 你的 API 包含相对而言为数不多的、尺寸较小的对象（资源）。
• 对象定义了应用或者基础设施的配置信息。
• 对象更新操作频率较低。
• 通常需要人来读取或写入对象。
• 对象的主要操作是 CRUD 风格的（创建、读取、更新和删除）。
• 不需要跨对象的事务支持：API 对象代表的是期望状态而非确切实际状态。

命令式 API（Imperative API）与声明式有所不同。 以下迹象表明你的 API 可能不是声明式的：

• 客户端发出“做这个操作”的指令，之后在该操作结束时获得同步响应。
• 客户端发出“做这个操作”的指令，并获得一个操作 ID，之后需要检查一个 Operation（操作） 对象来判断请求是否成功完成。
• 你会将你的 API 类比为远程过程调用（Remote Procedure Call，RPC）。
• 直接存储大量数据；例如每个对象几 kB，或者存储上千个对象。
• 需要较高的访问带宽（长期保持每秒数十个请求）。
• 存储有应用来处理的最终用户数据（如图片、个人标识信息（PII）等）或者其他大规模数据。
• 在对象上执行的常规操作并非 CRUD 风格。
• API 不太容易用对象来建模。
• 你决定使用操作 ID 或者操作对象来表现悬决的操作。

我应该使用一个 ConfigMap 还是一个定制资源？

如果满足以下条件之一，应该使用 ConfigMap：

• 存在一个已有的、文档完备的配置文件格式约定，例如 mysql.cnf 或 pom.xml。
• 你希望将整个配置文件放到某 configMap 中的一个主键下面。
• 配置文件的主要用途是针对运行在集群中 Pod 内的程序，供后者依据文件数据配置自身行为。
• 文件的使用者期望以 Pod 内文件或者 Pod 内环境变量的形式来使用文件数据， 而不是通过 Kubernetes API。
• 你希望当文件被更新时通过类似 Deployment 之类的资源完成滚动更新操作。

如果以下条件中大多数都被满足，你应该使用定制资源（CRD 或者 聚合 API）：

• 你希望使用 Kubernetes 客户端库和 CLI 来创建和更改新的资源。
• 你希望 kubectl 能够直接支持你的资源；例如，kubectl get my-object object-name。
• 你希望构造新的自动化机制，监测新对象上的更新事件，并对其他对象执行 CRUD 操作，或者监测后者更新前者。
• 你希望编写自动化组件来处理对对象的更新。
• 你希望使用 Kubernetes API 对诸如 .spec、.status 和 .metadata 等字段的约定。
• 你希望对象是对一组受控资源的抽象，或者对其他资源的归纳提炼。

添加定制资源

Kubernetes 提供了两种方式供你向集群中添加定制资源：

• CRD 相对简单，创建 CRD 可以不必编程。
• API 聚合需要编程， 但支持对 API 行为进行更多的控制，例如数据如何存储以及在不同 API 版本间如何转换等。

Kubernetes 提供这两种选项以满足不同用户的需求，这样就既不会牺牲易用性也不会牺牲灵活性。

聚合 API 指的是一些下位的 API 服务器，运行在主 API 服务器后面；主 API 服务器以代理的方式工作。这种组织形式称作 API 聚合（API Aggregation，AA） 。 对用户而言，看起来仅仅是 Kubernetes API 被扩展了。

CRD 允许用户创建新的资源类别同时又不必添加新的 API 服务器。 使用 CRD 时，你并不需要理解 API 聚合。

无论以哪种方式安装定制资源，新的资源都会被当做定制资源，以便与内置的 Kubernetes 资源（如 Pods）相区分。

CustomResourceDefinitions

CustomResourceDefinition API 资源允许你定义定制资源。 定义 CRD 对象的操作会使用你所设定的名字和模式定义（Schema）创建一个新的定制资源， Kubernetes API 负责为你的定制资源提供存储和访问服务。 CRD 对象的名称必须是有效的 DNS 子域名， 该名称由定义的资源名称及其 API 组派生而来。有关详细信息， 请参见如何创建 CRD。 此外，由 CRD 定义的某种对象/资源的名称也必须是有效的 DNS 子域名。

CRD 使得你不必编写自己的 API 服务器来处理定制资源，不过其背后实现的通用性也意味着你所获得的灵活性要比 API 服务器聚合少很多。

关于如何注册新的定制资源、使用新资源类别的实例以及如何使用控制器来处理事件， 相关的例子可参见定制控制器示例。

API 服务器聚合

通常，Kubernetes API 中的每个资源都需要处理 REST 请求和管理对象持久性存储的代码。 Kubernetes API 主服务器能够处理诸如 Pod 和 Service 这些内置资源， 也可以按通用的方式通过 CRD 来处理定制资源。

聚合层（Aggregation Layer） 使得你可以通过编写和部署你自己的 API 服务器来为定制资源提供特殊的实现。 主 API 服务器将针对你要处理的定制资源的请求全部委托给你自己的 API 服务器来处理， 同时将这些资源提供给其所有客户端。

选择添加定制资源的方法

CRD 更为易用；聚合 API 则更为灵活。请选择最符合你的需要的方法。

通常，如果存在以下情况，CRD 可能更合适：

• 定制资源的字段不多；
• 你在组织内部使用该资源或者在一个小规模的开源项目中使用该资源，而不是在商业产品中使用。

比较易用性

CRD 比聚合 API 更容易创建。

高级特性与灵活性

聚合 API 可提供更多的高级 API 特性，也可对其他特性实行定制；例如，对存储层进行定制。

公共特性

与在 Kubernetes 平台之外实现定制资源相比， 无论是通过 CRD 还是通过聚合 API 来创建定制资源，你都会获得很多 API 特性：

准备安装定制资源

在向你的集群添加定制资源之前，有些事情需要搞清楚。

第三方代码和新的失效点的问题

尽管添加新的 CRD 不会自动带来新的失效点（Point of Failure），例如导致第三方代码被在 API 服务器上运行， 类似 Helm Charts 这种软件包或者其他安装包通常在提供 CRD 的同时还包含带有第三方代码的 Deployment，负责实现新的定制资源的业务逻辑。

安装聚合 API 服务器时，也总会牵涉到运行一个新的 Deployment。

存储

定制资源和 ConfigMap 一样也会消耗存储空间。创建过多的定制资源可能会导致 API 服务器上的存储空间超载。

聚合 API 服务器可以使用主 API 服务器相同的存储。如果是这样，你也要注意此警告。

身份认证、鉴权授权以及审计

CRD 通常与 API 服务器上的内置资源一样使用相同的身份认证、鉴权授权和审计日志机制。

如果你使用 RBAC 来执行鉴权授权，大多数 RBAC 角色都不会授权对新资源的访问 （除了 cluster-admin 角色以及使用通配符规则创建的其他角色）。 你要显式地为新资源的访问授权。CRD 和聚合 API 通常在交付时会包含针对所添加的类别的新的角色定义。

聚合 API 服务器可能会使用主 API 服务器相同的身份认证、鉴权授权和审计机制，也可能不会。

访问定制资源

Kubernetes 客户端库可用来访问定制资源。 并非所有客户端库都支持定制资源。Go 和 Python 客户端库是支持的。

当你添加了新的定制资源后，可以用如下方式之一访问它们：

• kubectl
• Kubernetes 动态客户端
• 你所编写的 REST 客户端
• 使用 Kubernetes 客户端生成工具所生成的客户端。 生成客户端的工作有些难度，不过某些项目可能会随着 CRD 或聚合 API 一起提供一个客户端。

定制资源字段选择算符

字段选择算符允许客户端根据一个或多个资源字段的值选择定制资源。

所有定制资源都支持 metadata.name 和 metadata.namespace 字段选择算符。

当 CustomResourceDefinition 中声明的字段包含在 CustomResourceDefinition 的 spec.versions[*].selectableFields 字段中时，也可以与字段选择算符一起使用。

定制资源的可选择字段

你需要启用 CustomResourceFieldSelectors 特性门控 来使用此行为，然后将其应用到集群中的所有 CustomResourceDefinitions。

CustomResourceDefinition 字段可以用来在启用了 CustomResourceFieldSelectors 特性门控 （自 Kubernetes v1.31 起，此特性默认启用）的集群中控制哪些字段可以用在字段选择算符中。

以下示例将 .spec.color 和 .spec.size 字段添加为可选择字段。

customresourcedefinition/shirt-resource-definition.yaml

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: shirts.stable.example.com
spec:
  group: stable.example.com
  scope: Namespaced
  names:
    plural: shirts
    singular: shirt
    kind: Shirt
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              color:
                type: string
              size:
                type: string
    selectableFields:
    - jsonPath: .spec.color
    - jsonPath: .spec.size
    additionalPrinterColumns:
    - jsonPath: .spec.color
      name: Color
      type: string
    - jsonPath: .spec.size
      name: Size
      type: string

字段选择算符随后可用于仅获取 color 为 blue 的资源：

kubectl get shirts.stable.example.com --field-selector spec.color=blue

输出应该是：

NAME       COLOR  SIZE
example1   blue   S
example2   blue   M

接下来

• 了解如何使用聚合层扩展 Kubernetes API
• 了解如何使用 CustomResourceDefinition 来扩展 Kubernetes API

2 - Kubernetes API 聚合层

使用聚合层（Aggregation Layer），用户可以通过附加的 API 扩展 Kubernetes， 而不局限于 Kubernetes 核心 API 提供的功能。 这里的附加 API 可以是现成的解决方案，比如 metrics server， 或者你自己开发的 API。

聚合层不同于 定制资源定义（Custom Resource Definitions）。 后者的目的是让 kube-apiserver 能够识别新的对象类别（Kind）。

聚合层

聚合层在 kube-apiserver 进程内运行。在扩展资源注册之前，聚合层不做任何事情。 要注册 API，你可以添加一个 APIService 对象，用它来 “申领” Kubernetes API 中的 URL 路径。 自此以后，聚合层将把发给该 API 路径的所有内容（例如 /apis/myextension.mycompany.io/v1/…） 转发到已注册的 APIService。

APIService 的最常见实现方式是在集群中某 Pod 内运行扩展 API 服务器（Extension API Server）。 如果你在使用扩展 API 服务器来管理集群中的资源，该扩展 API 服务器（也被写成 "extension-apiserver"） 一般需要和一个或多个控制器一起使用。 apiserver-builder 库同时提供构造扩展 API 服务器和控制器框架代码。

响应延迟

扩展 API 服务器（Extension API Server）与 kube-apiserver 之间需要存在低延迟的网络连接。 发现请求需要在五秒钟或更短的时间内完成到 kube-apiserver 的往返。

如果你的扩展 API 服务器无法满足这一延迟要求，应考虑如何更改配置以满足需要。

接下来

• 阅读配置聚合层文档， 了解如何在自己的环境中启用聚合器。
• 接下来，了解安装扩展 API 服务器， 开始使用聚合层。
• 从 API 参考资料中研究关于 APIService 的内容。

或者，学习如何使用 CustomResourceDefinition 扩展 Kubernetes API。