自定义资源
自定义资源 是 Kubernetes API 的扩展。本页讨论何时向 Kubernetes 群集添加自定义资源以及何时使用独立服务。它描述了添加自定义资源的两种方法以及如何在它们之间进行选择。
- 自定义资源
- 自定义控制器
- 是否需要向 Kubernetes 集群添加自定义资源？
- 我应该使用 configMap 还是自定义资源？
- 添加自定义资源
- 自定义资源定义(CustomResourceDefinition)
- API服务器聚合
- 选择添加自定义资源的方法
- 准备安装自定义资源
- 访问自定义资源
- 接下来
自定义资源
资源 是Kubernetes API中的端点，用于存储 某种API 对象的集合。例如,内置 Pod 资源包含 Pod 对象的集合。
自定义资源 是 Kubernetes API 的扩展，在 Kubernetes 的默认安装中不一定可用。它使 Kubernetes 具备可定制化安装的能力。但是，很多核心 Kubernetes 功能现在都使用自定义资源构建，使 Kubernetes 模块更加合理。
自定义资源可以通过动态注册在运行的集群中显示或者消失，并且集群管理员可以独立于集群本身更新自定义资源。安装自定义资源后,用户可以使用 kubectl 创建和访问其对象，就像对 Pod 等内置资源一样。
自定义控制器
自定义资源可以存储和检索结构化数据。将自定义资源和自定义控制器结合时，自定义资源提供一个真正 声明式 API 。
声明式 API 允许使用者_声明_或者指定所需的资源状态，并使当前状态与预期状态保持一致。控制器将结构化数据解释为用户所需状态的记录,并持续维护此状态。
你可以在运行中的集群上部署或更新自定义控制器，而这一操作是与集群自身的生命期无关的。自定义控制器可以与任何资源一起工作，但是与自定义资源相结合时他们特别有效。 Operator 模式 结合了自定义资源和自定义控制器。您可以使用自定义控制器将特定应用程序的领域知识编码到 Kubernetes API 的扩展中。
是否需要向 Kubernetes 集群添加自定义资源？
创建新 API 的时候，请考虑是将 API 与 Kubernetes 集群 API 聚合 还是将API独立。
| 如果属于下面情况之一，可以考虑采用 API 聚合: | 如果属于下面情况之一，首选独立 API : |
|---|---|
| API 具有声明性. | API 不适合声明性模型. |
你希望可使用 kubectl 来读写新类型。 |
不需要 kubectl 支持 |
| 你希望在 Kubernetes 用户界面（如 dashboard）中和内置类型一起看到你的新类型。 | 不需要 Kubernetes 使用界面支持。 |
| 你正在开发新的 API。 | 你已经有一个运行良好的程序为你提供 API 服务。 |
| 你愿意接受 Kubernetes 对 REST 资源路径的格式限制，例如 API 组和命名空间。 (参照 API 概述.) | 你需要有一个特定的 REST 路径来兼容已经定义的 REST API 。 |
| 你的资源可以很自然地归入集群作用域或者集群中的某个命名空间的作用域。 | 集群或者命名空间作用域均不合适；你需要控制资源路径的细节。 |
| 你希望重用 Kubernetes API 的支持功能. | 你不需要这些功能。 |
声明式 API
在声明式 API 中，通常：
- API由相对较少的对象（资源）组成。
- 对象定义了应用或基础设施的配置项。
- 对象更新相对较少。
- 用户经常需要读取和写入对象。
- 对象上的主要操作是 CRUD（创建，读取，更新和删除）。
- 不需要跨对象的事务：API 表示一个所需的状态，而不是一个确切的状态。
命令式 API 不是声明式的。API 不是声明式的特点包括：
- 客户端说“执行此操作”，然后在完成时获取同步响应。
- 客户端说“执行此操作”，然后获取一个操作 ID，并且为了确认请求的完成，必须检查单独的操作对象。
- 说的是远程过程调用（RPCs）。
- 直接存储大量数据（例如，每个对象几 kB，或1000个对象）。
- 需要高带宽访问（每秒持续的10个请求）
- 存储业务用户数据（如图像、PII 等）或者其他由应用程序处理的大规模数据。
- 对于对象的自然操作不是 CRUD。
- API 不容易建模成对象。
- 你选择使用操作 ID 或者操作对象来表示待解决的操作。
我应该使用 configMap 还是自定义资源？
如果以下任何一项适用，请使用 ConfigMap ：
- 存在一种记录良好的配置文件格式，，例如
mysql.cnf或者pom.xml。 - 你想把所有的配置文件都放进 configMap 的一个键中。
- 配置文件的作用就是，让运行在集群中 Pod 的程序配置自身环境。
- 文件使用者更倾向于使用通过 Pod 中的文件或 Pod 中的环境变量，而不是使用 Kubernetes API。
- 你希望在更新文件时通过部署等执行滚动更新。
Note: 对敏感数据使用 secret , 类似于 configMap ，但更安全。
如果以下大多数情况出现，请使用自定义资源（ CustomResourceDefinition 或者 API集合 ）：
- 您希望使用 Kubernetes 客户端库和 CLIs 来创建和更新新资源。
- 你希望从 kubectl 得到顶级支持（比如：
kubectl get my-object object-name）。 - 你希望新建一个自动化以监视新对象的更新，然后监视 CRUD 其他对象，反之亦然。
- 你希望编写处理对象更新的自动化。
- 你想要使用 Kubernetes API约定，比如像
.spec，.status，和.metadata。 - 你希望对象是受控资源集合的抽象，或者是其他资源的汇总。
添加自定义资源
Kubernetes 提供了两种将自定义资源添加到集群的方法：
- CustomResourceDefinition 非常简单，无需任何编程即可创建。
- API 聚集需要编程，但允许对 API 行为进行更多控制，比如数据的存储方式和 API 版本之间的转换。
Kubernetes 提供了两个选项来满足不同使用者的需要，因此无论是易用性还是灵活性都不受影响。
API 聚集是位于主API服务器后面的从属 API 服务器，用来充当代理。这种安排被称作API 聚合 （AA）。对于用户来说，Kubernetes API 似乎只是扩展了。
CustomResourceDefinition 允许用户在不添加其他 API 服务器的情况下创建新类型的资源。您无需了解 API 集合就可以使用 CustomResourceDefinition 。
无论如何安装，新资源都被称为自定义资源，已将其与内置的 Kubernetes（如 Pod ）资源区分开。
自定义资源定义(CustomResourceDefinition)
CustomResourceDefinition API 资源允许你去定义自定义资源。定义 CustomResourceDefinition 对象创建了一个新的自定义资源，该资源具有您指定的名称和架构。Kubernetes API 提供并处理自定义资源的存储。
这样，你就不用为了处理自定义资源来编写你自己的API服务器了，但是实现的通用性意味着比 API 服务器集合的灵活性要低。
有关如何注册新自定义资源、使用新资源类型的实例以及使用控制器处理事件的示例,请参阅自定义控制器示例。
API服务器聚合
通常，Kubernetes API 中的每个资源都需要代码来处理 REST 请求和管理对象的持续存储。主 Kubernetes API服务器处理像 Pod 和 services 的内置资源，还可以通过 CustomResourceDefinition 以通用的方式处理自定义资源。
集合层允许您通过编写部署你自己独立的API服务器来为自定义资源提供专用实现。
主 API 服务器将委托您处理自定义资源，使其可供所有客户端使用。
选择添加自定义资源的方法
CustomResourceDefinition 更易于使用。API 集合更加灵活。选择更能满足您需求的方法。
通常，CustomResourceDefinition 更适合以下几个方面：
- 你有几个字段。
- 你正在使用公司内的资源，或者一个小的开源项目的一部分（区别于商业产品）
比较易用性
CustomResourceDefinition 比 API 集合更容易创建。
| CustomResourceDefinition（CRD） | API 集合 |
|---|---|
| 不需要编程。用户可以为 CRD 控制器选择任何语言。 | 需要在 Go 中编程并构建二进制和镜像。用户可以为CRD控制器选择任何语言。 |
| 无需运行其他服务; CR 由 API 服务器处理。 | 要创建其他服务，并可以会失败。 |
| 一旦 CRD 创建，无需后续支持。任何错误修复都是正常 Kubernetes Master 升级的一部分。 | 可能需要定期从上游拾取错误修复，并重建和更新 API 集合服务器。 |
| 无需处理 API 的多个版本。例如：当您控制此资源的客户端时，可以将其与 API 同步升级。 | 你需要处理 API 的多个版本，例如：当开发一个扩展，与世界分享时。 |
高级功能和灵活性
API 集合提供更高级的 API 特性以及其他功能的自定义，例如：存储层。
| 特性 | 描述 | CustomResourceDefinition | API集合 |
|---|---|---|---|
| 验证 | 帮助用户避免错误并且允许您独立于客户端发展API。 当有许多客户端无法同时更新时，这些功能非常有用。 | 是的。大多数验证可以在CustomResourceDefinition 中使用OpenAPI v3.0 validation来验证。 其他验证可以通过添加验证的 Webhook来支持. | 是的，任意验证检查。 |
| 违约 | 见上文 | 是的， 通过 突变的 Webhook; 规划, 通过 CustomResourceDefinition OpenAPI 架构. | 是的 |
| 多版本 | 允许通过两个 API 版本为同一对象提供服务。 可帮助简化 API 更改,如重命名字段。 如果您控制客户端版本,则不太重要。 | 是的 | 是的 |
| 自定义存储 | 如果需要不同性能模式的存储(例如，时间序列数据库而不是密钥值存储) 或为了安全进行隔离(例如，加密机密或不同的） | 不是 | 是的 |
| 定制业务逻辑 | 在创建，读取，更新或删除对象时执行任意检查或操作 | 是的, 使用 Webhooks。 | 是的 |
| Scale 子资源 | 允许 HorizontalPodAutoscaler 和 PodDisruptionBudget 与您的新资源进行互换 | 是的 | 是的 |
| Status 子资源 |
|
是的 | 是的 |
| 其他子资源 | 添加 CRUD 以外的操作,如”日志”或”执行”。 | 不是 | 是的 |
| 战略-合并-补丁 | 新的端点支持具有 Content-Type: application/strategic-merge-patch+json 的 PATCH . 可用于更新可在本地和服务器修改的对象。更多信息，请参阅“使用 kubectl 修补程序更新API对象” |
不是 | 是的 |
| 协议缓冲区 | 新资源支持希望使用协议缓冲区的客户端 | 不是 | 是的 |
| OpenAPI 架构 | 是否有可从服务器动态提取类型的 OpenAPI (swagger) 架构？用户通过确保只设置允许的字段来避免拼写错误的字段名称是否被设置？ 是否是强制执行类型 (换句话说，不要在 string 字段中放置 int ?) |
不，但有计划 | 是的 |
公共特性
与在 Kubernetes 平台之外实现它相比，当通过 CustomResourceDefinition 或 AA 创建自定义资源时，您可以获得 API 的许多功能：
| 功能 | 作用 |
|---|---|
| CRUD | 通过 HTTP 和 kubectl ，新的端点通过 HTTP 和 kubectl 支持 CRUD 基本操作 |
| Watch | 新的端点通过 HTTP 支持 Kubernetes 监视功能 |
| 发现 | 如 Kubectl 和 dashboard 客户端会自动提供资源上的列表、显示和字段编辑操作 |
| json-patch | 新的端点支持打上 Content-Type: application/json-patch+json 的 PATCH |
| merge-patch | 新的端点支持打上 Content-Type: application/merge-patch+json 的 PATCH |
| HTTPS | 新的端点使用 HTTPS |
| 内置身份验证 | 对扩展的访问使用核心API服务（聚合层）进行身份认证 |
| 内置授权 | 对扩展的访问可以重用被核心API服务使用的授权（例如，基于角色的访问控制 role-based access control） |
| 终结器 | 阻止删除扩展资源,直到进行外部清理。 |
| 准入 Webhooks | 在任何创建/更新/删除操作期间设置默认值并验证扩展资源。 |
| UI/CLI 显示 | Kubectl ,和 dashboard 可以显示扩展资源。 |
| 未设置与空 | 客户端可以把未设置字段从零值字段中区分出来。 |
| 客户端库生成 | Kubernetes 提供通用客户端库，以及用于生成特定客户端库的工具。 |
| 标签和注释 | 工具知道如何编辑核心和自定义资源的跨对象的通用元数据 |
准备安装自定义资源
在将自定义资源添加到群集之前,需要注意几个要点。
第三方代码和新的故障点
虽然创建CRD不会自动添加任何新的故障点（例如，通过第三方代码在 API 服务器上运行），但包（例如，图表）或其他安装捆绑包经常包括 CustomResourceDefinition 以及 Deployment 第三方代码来实现新的自定义资源的业务逻辑。
安装新的聚合 API 服务器总是涉及运行新的部署。
存储
自定义资源与 ConfigMap 以相同的方式消耗存储空间。创建过多的自定义资源会过载 API 服务器的存储空间。
API 集合服务器可以使用与主 API 服务器相同的存储，在这种情况下,将应用相同的警告。
身份验证、授权和审核
CustomResourceDefinition 始终使用与 API 服务器内置资源相同的身份验证、授权和审核日志记录。
如果使用 RBAC 进行授权，大多数 RBAC （基于角色的访问控制）的角色不会授予对新资源的访问权限（除了集群管理员角色或任何通配符规则创建的角色）。您需要明确授予对新资源的访问权限。CustomResourceDefinition 和 API集合 通常与他们添加类型的新角色定义捆绑。
API 集合服务器可能使用或不使用与主 API 服务器相同的身份验证，授权和审核。
访问自定义资源
Kubernetes 客户端库可用于访问自定义资源。并非所有客户端库都支持自定义资源。go 和 python 客户端库可以。
当你添加了一个自定义资源，可以使用一下命令来访问它：
- kubectl
- kubernetes 动态客户端。
- 你编写的 REST 客户端。
接下来
- 了解如何使用聚合层扩展 Kubernetes API。
反馈
此页是否对您有帮助？
Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.