自定义资源

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

自定义资源

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

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

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

自定义控制器

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

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

您可以在运行的集群上独立于集群的生命周期部署和更新自定义控制器。自定义控制器可以与任何类型的资源一起工作，但与自定义资源结合使用时特别有效。 运算符模式 结合了自定义资源和自定义控制器。您可以使用自定义控制器将特定应用程序的领域知识编码到 Kubernetes API 的扩展中。

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

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

声明式 API

在声明式 API 中，通常

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

命令式 API 不是声明式的。以下迹象表明您的 API 可能不是声明式的

• 客户端说“执行此操作”，然后在完成后收到同步响应。
• 客户端说“执行此操作”，然后收到一个操作 ID，并且必须检查一个单独的操作对象以确定请求的完成。
• 您谈论远程过程调用（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 定义其 kind/resource 的对象的名称也必须是有效的 DNS 子域名。

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

请参考自定义控制器示例，了解如何注册新的自定义资源、使用新资源类型实例以及使用控制器来处理事件的示例。

API 服务器聚合

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

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

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

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

通常，CRD 非常适合以下情况

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

比较易用性

CRD 比聚合 API 更易于创建。

高级功能和灵活性

聚合 API 提供更高级的 API 功能和对其他功能（例如存储层）的定制。

常见功能

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

准备安装自定义资源

在将自定义资源添加到您的集群之前，需要注意几个方面。

第三方代码和新的故障点

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

安装聚合 API 服务器总是涉及运行新的部署。

存储

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

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

身份验证、授权和审计

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

如果您使用 RBAC 进行授权，大多数 RBAC 角色不会授予访问新资源的权限（除了 cluster-admin 角色或使用通配符规则创建的任何角色）。您需要显式授予访问新资源的权限。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 字段可用于声明自定义资源中的哪些其他字段可用于具有 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

然后可以使用字段选择器仅获取颜色为 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。