Kubernetes容器-定制资源

定制资源（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 是[声明式的] declarative-apis)。 | 你的 API 不符合[声明式](declarative-apis
| 你希望可以是使用 `kubectl` 来读写你的新资源类别。 | 不要求 `kubectl` 支持。 |
| 你希望在 Kubernetes UI （如仪表板）中和其他内置类别一起查看你的新资源类别。 | 不需要 Kubernetes UI 支持。 |
| 你在开发新的 API。 | 你已经有一个提供 API 服务的程序并且工作良好。 |
| 你有意愿取接受 Kubernetes 对 REST 资源路径所作的格式限制，例如 API 组和名字空间。（参阅 [API 概述]） | 你需要使用一些特殊的 REST 路径以便与已经定义的 REST API 保持兼容。 |
| 你的资源可以自然地界定为集群作用域或集群中某个名字空间作用域。 | 集群作用域或名字空间作用域这种二分法很不合适；你需要对资源路径的细节进行控制。 |
| 你希望复用 [Kubernetes API 支持特性] common-features
<!--

### Declarative APIs
In a Declarative API, typically:
 - Your API consists of a relatively small number of relatively small objects (resources).
 - The objects define configuration of applications or infrastructure.
 - The objects are updated relatively infrequently.
 - Humans often need to read and write the objects.
 - The main operations on the objects are CRUD-y (creating, reading, updating and deleting).
 - Transactions across objects are not required: the API represents a desired state, not an exact state.
-->

### 声明式 APIs 

典型地，在声明式 API 中：
 - 你的 API 包含相对而言为数不多的、尺寸较小的对象（资源）。
 - 对象定义了应用或者基础设施的配置信息。
 - 对象更新操作频率较低。
 - 通常需要人来读取或写入对象。
 - 对象的主要操作是 CRUD 风格的（创建、读取、更新和删除）。
 - 不需要跨对象的事务支持：API 对象代表的是期望状态而非确切实际状态。
<!--
Imperative APIs are not declarative.
Signs that your API might not be declarative include:
 - The client says "do this", and then gets a synchronous response back when it is done.
 - The client says "do this", and then gets an operation ID back, and has to check a separate Operation object to determine completion of the request.
 - You talk about Remote Procedure Calls (RPCs).
 - Directly storing large amounts of data; for example, > a few kB per object, or > 1000s of objects.
 - High bandwidth access (10s of requests per second sustained) needed.
 - Store end-user data (such as images, PII, etc.) or other large-scale data processed by applications.
 - The natural operations on the objects are not CRUD-y.
 - The API is not easily modeled as objects.
 - You chose to represent pending operations with an operation ID or an operation object.
-->

命令式 API（Imperative API）与声明式有所不同。

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

## Should I use a ConfigMap or a custom resource?
Use a ConfigMap if any of the following apply:
* There is an existing, well-documented configuration file format, such as a `mysql.cnf` or `pom.xml`.
* You want to put the entire configuration file into one key of a configMap.
* The main use of the configuration file is for a program running in a Pod on your cluster to consume the file to configure itself.
* Consumers of the file prefer to consume via file in a Pod or environment variable in a pod, rather than the Kubernetes API.
* You want to perform rolling updates via Deployment, etc., when the file is updated.
-->

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

如果满足以下条件之一，应该使用 ConfigMap：
* 存在一个已有的、文档完备的配置文件格式约定，例如 `mysql.cnf` 或 `pom.xml`。
* 你希望将整个配置文件放到某 configMap 中的一个主键下面。
* 配置文件的主要用途是针对运行在集群中 Pod 内的程序，供后者依据文件数据配置自身行为。
* 文件的使用者期望以 Pod 内文件或者 Pod 内环境变量的形式来使用文件数据，
  而不是通过 Kubernetes API。
* 你希望当文件被更新时通过类似 Deployment 之类的资源完成滚动更新操作。
<!--
Use a  for sensitive data, which is similar to a configMap but more secure.
-->

请使用 Secret 来保存敏感数据。
Secret 类似于 configMap，但更为安全。
<!--
Use a custom resource (CRD or Aggregated API) if most of the following apply:
* You want to use Kubernetes client libraries and CLIs to create and update the new resource.
* You want top-level support from `kubectl`; for example, `kubectl get my-object object-name`.
* You want to build new automation that watches for updates on the new object, and then CRUD other objects, or vice versa.
* You want to write automation that handles updates to the object.
* You want to use Kubernetes API conventions like `.spec`, `.status`, and `.metadata`.
* You want the object to be an abstraction over a collection of controlled resources, or a summarization of other resources.
-->

如果以下条件中大多数都被满足，你应该使用定制资源（CRD 或者 聚合 API）：
* 你希望使用 Kubernetes 客户端库和 CLI 来创建和更改新的资源。
* 你希望 `kubectl` 能够直接支持你的资源；例如，`kubectl get my-object object-name`。
* 你希望构造新的自动化机制，监测新对象上的更新事件，并对其他对象执行 CRUD
  操作，或者监测后者更新前者。
* 你希望编写自动化组件来处理对对象的更新。
* 你希望使用 Kubernetes API 对诸如 `.spec`、`.status` 和 `.metadata` 等字段的约定。
* 你希望对象是对一组受控资源的抽象，或者对其他资源的归纳提炼。
<!--

## Adding custom resources
Kubernetes provides two ways to add custom resources to your cluster:
- CRDs are simple and can be created without any programming.
- [API Aggregation] requires programming, but allows more control over API behaviors like how data is stored and conversion between API versions.
-->

## 添加定制资源   
Kubernetes 提供了两种方式供你向集群中添加定制资源：
- CRD 相对简单，创建 CRD 可以不必编程。
- [API 聚合]
  需要编程，但支持对 API 行为进行更多的控制，例如数据如何存储以及在不同 API 版本间如何转换等。
<!--
Kubernetes provides these two options to meet the needs of different users, so that neither ease of use nor flexibility is compromised.
Aggregated APIs are subordinate API servers that sit behind the primary API server, which acts as a proxy. This arrangement is called [API Aggregation]. To users, the Kubernetes API is extended.
CRDs allow users to create new types of resources without adding another API server. You do not need to understand API Aggregation to use CRDs.
Regardless of how they are installed, the new resources are referred to as Custom Resources to distinguish them from built-in Kubernetes resources (like pods).
-->
Kubernetes 提供这两种选项以满足不同用户的需求，这样就既不会牺牲易用性也不会牺牲灵活性。

聚合 API 指的是一些下位的 API 服务器，运行在主 API 服务器后面；主 API

服务器以代理的方式工作。这种组织形式称作
[API 聚合（API Aggregation，AA）] 。

对用户而言，看起来仅仅是 Kubernetes API 被扩展了。
CRD 允许用户创建新的资源类别同时又不必添加新的 API 服务器。

使用 CRD 时，你并不需要理解 API 聚合。

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

## CustomResourceDefinitions
The [CustomResourceDefinition]
API resource allows you to define custom resources.
Defining a CRD object creates a new custom resource with a name and schema that you specify.
The Kubernetes API serves and handles the storage of your custom resource.
The name of a CRD object must be a valid
[DNS subdomain name].
-->

## CustomResourceDefinitions
[CustomResourceDefinition]
API 资源允许你定义定制资源。

定义 CRD 对象的操作会使用你所设定的名字和模式定义（Schema）创建一个新的定制资源，
Kubernetes API 负责为你的定制资源提供存储和访问服务。
CRD 对象的名称必须是合法的
[DNS 子域名]。
<!--
This frees you from writing your own API server to handle the custom resource,
but the generic nature of the implementation means you have less flexibility than with
[API server aggregation] api-server-aggregation
Refer to the [custom controller example](https://github.com/kubernetes/sample-controller)
for an example of how to register a new custom resource, work with instances of your new resource type,
and use a controller to handle events.
-->
CRD 使得你不必编写自己的 API 服务器来处理定制资源，不过其背后实现的通用性也意味着

你所获得的灵活性要比 [API 服务器聚合] api-server-aggregation

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

相关的例子可参见[定制控制器示例](https://github.com/kubernetes/sample-controller)。
<!--

## API server aggregation
Usually, each resource in the Kubernetes API requires code that handles REST requests and manages persistent storage of objects. The main Kubernetes API server handles built-in resources like *pods* and *services*, and can also generically handle custom resources through [CRDs] customresourcedefinitions
The [aggregation layer] allows you to provide specialized
implementations for your custom resources by writing and deploying your own API server.
The main API server delegates requests to your API server for the custom resources that you handle,
making them available to all of its clients.
-->

## API 服务器聚合  

通常，Kubernetes API 中的每个资源都需要处理 REST 请求和管理对象持久性存储的代码。
Kubernetes API 主服务器能够处理诸如 *pods* 和 *services* 这些内置资源，也可以

按通用的方式通过 [CRD] customresourcedefinitions
[聚合层（Aggregation Layer）]

使得你可以通过编写和部署你自己的 API 服务器来为定制资源提供特殊的实现。

主 API 服务器将针对你要处理的定制资源的请求全部委托给你自己的 API 服务器来处理，同时将这些资源

提供给其所有客户端。
<!--

## Choosing a method for adding custom resources
CRDs are easier to use. Aggregated APIs are more flexible. Choose the method that best meets your needs.
Typically, CRDs are a good fit if:
* You have a handful of fields
* You are using the resource within your company, or as part of a small open-source project (as opposed to a commercial product)
-->

## 选择添加定制资源的方法
CRD 更为易用；聚合 API 则更为灵活。请选择最符合你的需要的方法。

通常，如何存在以下情况，CRD 可能更合适：
* 定制资源的字段不多；
* 你在组织内部使用该资源或者在一个小规模的开源项目中使用该资源，而不是
  在商业产品中使用。
<!--

### Comparing ease of use
CRDs are easier to create than Aggregated APIs.
-->

### 比较易用性  
CRD 比聚合 API 更容易创建
<!--

-->

<!--

### Advanced features and flexibility
Aggregated APIs offer more advanced API features and customization of other features; for example, the storage layer.
-->

### 高级特性与灵活性  

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

-->

<!--

### Common Features
When you create a custom resource, either via a CRD or an AA, you get many features for your API, compared to implementing it outside the Kubernetes platform:
-->

### 公共特性  

与在 Kubernetes 平台之外实现定制资源相比，

无论是通过 CRD 还是通过聚合 API 来创建定制资源，你都会获得很多 API 特性：
<!--

-->

<!--

## Preparing to install a custom resource
There are several points to be aware of before adding a custom resource to your cluster.
-->

## 准备安装定制资源

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

### Third party code and new points of failure
While creating a CRD does not automatically add any new points of failure (for example, by causing third party code to run on your API server), packages (for example, Charts) or other installation bundles often include CRDs as well as a Deployment of third-party code that implements the business logic for a new custom resource.
Installing an Aggregated API server always involves running a new Deployment.
-->

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

尽管添加新的 CRD 不会自动带来新的失效点（Point of
Failure），例如导致第三方代码被在 API 服务器上运行，

类似 Helm Charts 这种软件包或者其他安装包通常在提供 CRD 的同时还包含带有第三方

代码的 Deployment，负责实现新的定制资源的业务逻辑。

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

### Storage
Custom resources consume storage space in the same way that ConfigMaps do. Creating too many custom resources may overload your API server's storage space.
Aggregated API servers may use the same storage as the main API server, in which case the same warning applies.
-->

### 存储

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

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

此警告。
<!--

### Authentication, authorization, and auditing
CRDs always use the same authentication, authorization, and audit logging as the built-in resources of your API server.
If you use RBAC for authorization, most RBAC roles will not grant access to the new resources (except the cluster-admin role or any role created with wildcard rules). You'll need to explicitly grant access to the new resources. CRDs and Aggregated APIs often come bundled with new role definitions for the types they add.
Aggregated API servers may or may not use the same authentication, authorization, and auditing as the primary API server.
-->

### 身份认证、鉴权授权以及审计
CRD 通常与 API 服务器上的内置资源一样使用相同的身份认证、鉴权授权

和审计日志机制。

如果你使用 RBAC 来执行鉴权授权，大多数 RBAC 角色都会授权对新资源的访问

（除了 cluster-admin 角色以及使用通配符规则创建的其他角色）。

你要显式地为新资源的访问授权。CRD 和聚合 API 通常在交付时会包含

针对所添加的类别的新的角色定义。

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

机制，也可能不会。
<!--

## Accessing a custom resource
Kubernetes [client libraries] can be used to access custom resources. Not all client libraries support custom resources. The _Go_ and _Python_ client libraries do.
When you add a custom resource, you can access it using:
- `kubectl`
- The Kubernetes dynamic client.
- A REST client that you write.
- A client generated using [Kubernetes client generation tools](https://github.com/kubernetes/code-generator) (generating one is an advanced undertaking, but some projects may provide a client along with the CRD or AA).
-->

## 访问定制资源
Kubernetes [客户端库]可用来访问定制资源。

并非所有客户端库都支持定制资源。_Go_ 和 _Python_ 客户端库是支持的。

当你添加了新的定制资源后，可以用如下方式之一访问它们：
- `kubectl`
- Kubernetes 动态客户端
- 你所编写的 REST 客户端
- 使用 [Kubernetes 客户端生成工具](https://github.com/kubernetes/code-generator)
  所生成的客户端。生成客户端的工作有些难度，不过某些项目可能会随着 CRD 或
  聚合 API 一起提供一个客户端
* 了解如何[使用聚合层扩展 Kubernetes API]
* 了解如何[使用 CustomResourceDefinition 来扩展 Kubernetes API]

## 文章列表
- [Kubernetes容器-镜像](https://www.oomspot.com/post/kubernetesrongqijingxiang)
- [Kubernetes容器-网络插件](https://www.oomspot.com/post/kubernetesrongqiwangluochajian)
- [Kubernetes容器-扩展 Kubernetes](https://www.oomspot.com/post/kubernetesrongqikuozhankubernetes)
- [Kubernetes容器-容器运行时类（Runtime Class）](https://www.oomspot.com/post/kubernetesrongqirongqiyunxingshileiruntimeclass)
- [Kubernetes容器-容器生命周期回调](https://www.oomspot.com/post/kubernetesrongqirongqishengmingzhouqihuidiao)
- [Kubernetes容器-容器环境](https://www.oomspot.com/post/kubernetesrongqirongqihuanjing)
- [Kubernetes容器-定制资源](https://www.oomspot.com/post/kubernetesrongqidingzhiziyuan)
- [Kubernetes容器-使用Kubernetes设备插件框架](https://www.oomspot.com/post/kubernetesrongqishiyongkubernetesshebeichajiankuan)
- [Kubernetes容器-Operator模式](https://www.oomspot.com/post/kubernetesrongqioperatormoshi)
- [Kubernetes容器-Kubernetes API 聚合层](https://www.oomspot.com/post/kubernetesrongqikubernetesapijuheceng)