自定义资源

自定义资源是 Kubernetes API 的扩展。此页面讨论何时向 Kubernetes 集群添加自定义资源，以及何时使用独立服务。它描述了添加自定义资源的两种方法，以及如何选择它们。

自定义资源

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

自定义资源是 Kubernetes API 的扩展，它不一定在默认的 Kubernetes 安装中可用。它表示特定 Kubernetes 安装的自定义。然而，许多核心 Kubernetes 功能现在是使用自定义资源构建的，这使得 Kubernetes 更加模块化。

自定义资源可以通过动态注册在运行的集群中出现和消失，并且集群管理员可以独立于集群本身更新自定义资源。安装自定义资源后，用户可以使用 kubectl 创建和访问其对象，就像他们对 Pods 等内置资源所做的那样。

自定义控制器

自定义资源本身允许您存储和检索结构化数据。当您将自定义资源与自定义控制器结合使用时，自定义资源将提供真正的声明式 API。

Kubernetes 声明式 API 强制执行职责分离。您声明资源的期望状态。Kubernetes 控制器使 Kubernetes 对象的当前状态与您声明的期望状态保持同步。这与命令式 API 形成对比，在命令式 API 中，您指示服务器执行什么操作。

您可以在运行的集群上部署和更新自定义控制器，而无需考虑集群的生命周期。自定义控制器可以使用任何类型的资源，但当与自定义资源结合使用时，它们尤其有效。Operator 模式结合了自定义资源和自定义控制器。您可以使用自定义控制器将特定应用程序的领域知识编码到 Kubernetes API 的扩展中。

我应该向我的 Kubernetes 集群添加自定义资源吗？

在创建新的 API 时，请考虑是否将您的 API 与 Kubernetes 集群 API 聚合，或者让您的 API 独立存在。

声明式 API

在声明式 API 中，通常

• 您的 API 由相对较少的相对较小的对象（资源）组成。
• 对象定义应用程序或基础结构的配置。
• 对象更新的频率相对较低。
• 人类通常需要读取和写入对象。
• 对象的主要操作是 CRUD（创建、读取、更新和删除）。
• 不需要跨对象的事务：API 表示期望的状态，而不是精确的状态。

命令式 API 不是声明式的。您的 API 可能不是声明式的迹象包括

• 客户端说“执行此操作”，然后在操作完成时收到同步响应。
• 客户端说“执行此操作”，然后收到操作 ID，并且必须检查单独的 Operation 对象以确定请求是否完成。
• 您谈论远程过程调用 (RPC)。
• 直接存储大量数据；例如，每个对象 > 几 kB，或 > 数千个对象。
• 需要高带宽访问（持续每秒 10 个请求）。
• 存储最终用户数据（例如图像、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 很简单，无需任何编程即可创建。
• API 聚合需要编程，但允许对 API 行为（如数据存储方式以及 API 版本之间的转换）进行更多控制。

Kubernetes 提供了这两种选择以满足不同用户的需求，从而在易用性和灵活性之间取得平衡。

聚合 API 是位于主 API 服务器之后的从属 API 服务器，主 API 服务器充当代理。这种安排称为 API 聚合(AA)。对于用户而言，Kubernetes API 看起来被扩展了。

CRD 允许用户创建新的资源类型，而无需添加另一个 API 服务器。您无需了解 API 聚合即可使用 CRD。

无论如何安装，新资源都被称为自定义资源，以将其与内置的 Kubernetes 资源（如 Pod）区分开来。

CustomResourceDefinitions

CustomResourceDefinition API 资源允许您定义自定义资源。定义 CRD 对象会创建一个新的自定义资源，其中包含您指定的名称和模式。Kubernetes API 提供并处理自定义资源的存储。CRD 对象本身的名称必须是从定义的资源名称及其 API 组派生的有效 DNS 子域名；有关更多详细信息，请参见 如何创建 CRD。此外，由 CRD 定义的类型/资源的对象名称也必须是有效的 DNS 子域名。

这使您无需编写自己的 API 服务器来处理自定义资源，但实现的通用性意味着您的灵活性不如 API 服务器聚合。

有关如何注册新的自定义资源，使用新资源类型的实例以及使用控制器处理事件的示例，请参阅 自定义控制器示例。

API 服务器聚合

通常，Kubernetes API 中的每个资源都需要代码来处理 REST 请求并管理对象的持久存储。主 Kubernetes API 服务器处理内置资源，如 *pod* 和 *service*，并且还可以通过 CRD 通用地处理自定义资源。

聚合层允许您通过编写和部署自己的 API 服务器为自定义资源提供专门的实现。主 API 服务器将对您处理的自定义资源的请求委派给您的 API 服务器，使其可用于其所有客户端。

选择添加自定义资源的方法

CRD 更易于使用。聚合 API 更灵活。选择最适合您需求的方法。

通常，如果满足以下条件，则 CRD 是一个不错的选择

• 您只有少量字段
• 您在公司内部或作为小型开源项目的一部分使用该资源（而不是商业产品）

比较易用性

与聚合 API 相比，CRD 更容易创建。

高级功能和灵活性

聚合 API 提供更高级的 API 功能和其他功能的自定义；例如，存储层。

通用功能

当您通过 CRD 或 AA 创建自定义资源时，与在 Kubernetes 平台之外实现自定义资源相比，您将为 API 获得许多功能。

准备安装自定义资源

在向集群添加自定义资源之前，需要注意以下几点。

第三方代码和新的故障点

虽然创建 CRD 不会自动添加任何新的故障点（例如，通过导致第三方代码在您的 API 服务器上运行），但软件包（例如，Chart）或其他安装包通常包含 CRD 以及实现新自定义资源业务逻辑的第三方代码的 Deployment。

安装聚合 API 服务器始终涉及运行新的 Deployment。

存储

自定义资源以与 ConfigMap 相同的方式消耗存储空间。创建过多的自定义资源可能会使 API 服务器的存储空间过载。

聚合 API 服务器可能使用与主 API 服务器相同的存储，在这种情况下，适用相同的警告。

身份验证、授权和审计

CRD 始终使用与 API 服务器的内置资源相同的身份验证、授权和审计日志记录。

如果您使用 RBAC 进行授权，则大多数 RBAC 角色将不会授予对新资源的访问权限（集群管理员角色或使用通配符规则创建的任何角色除外）。您需要显式授予对新资源的访问权限。CRD 和聚合 API 通常捆绑有他们添加的类型的新角色定义。

聚合 API 服务器可能使用也可能不使用与主 API 服务器相同的身份验证、授权和审计。

访问自定义资源

Kubernetes 客户端库 可用于访问自定义资源。并非所有客户端库都支持自定义资源。Go 和 Python 客户端库支持。

当你添加自定义资源时，可以使用以下方式访问它：

• kubectl
• Kubernetes 动态客户端。
• 你编写的 REST 客户端。
• 使用 Kubernetes 客户端生成工具 生成的客户端（生成客户端是一项高级任务，但某些项目可能会随 CRD 或 AA 一起提供客户端）。

自定义资源字段选择器

字段选择器 允许客户端根据一个或多个资源字段的值选择自定义资源。

所有自定义资源都支持 metadata.name 和 metadata.namespace 字段选择器。

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

自定义资源的可选字段

CustomResourceDefinition 的 spec.versions[*].selectableFields 字段可用于声明自定义资源中哪些其他字段可以用于字段选择器。

以下示例添加了 .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。