Kubernetes API(个人翻译）

API端点、资源类型和示例写在API Reference。

Kubernetes API也作为系统描述式配置的基础。kubectl命令行工具被用来新建、更新、删除和获得API对象。

Kubernetes也通过API资源存储它的序列化状态（目前存在etcd）。

Kubernetes被分解为多个通过API交互的组件。

API 变化

根据经验，任何成功的系统都需要随着新出现的用例和现有用例的改变，而不停成长与改变。因此，我们希望Kubernetes API可以不停成长和改变。然而，在较长的一段时间内，我们不打算破坏与已有客户端的兼容性。总的来说，新的API资源和资源字段将频繁的增加。淘汰资源和字段需要遵守API deprecation policy（API废弃策略）。

变化兼容的要素和如何改变API可以在 API change document看到详情。

开放API和Swagger定义

API的详细内容请参考OpenAPI。

从Kubernetes 1.10开始，Kubernetes API服务器通过/openapi/v2端点提供API规范。请求格式通过设置HTTP头部指定。

在1.14之前，格式分离端点(/swagger.json, /swagger-2.0.0.json, /swagger-2.0.0.pb-v1, /swagger-2.0.0.pb-v1.gz)提供不同格式的OpenAPI规范。这些端点是过时的，将会在Kubernetes1.14去除。

获得OpenAPI规范的例子：

Kubernetes为API基于Protobuf实现了另类的序列化格式，主要用于集群内交流，在设计方案（design proposal ）中记录且每个模式的IDL文件都位于定义API对象的Go软件包里。

在1.14之前，Kubernetes服务器也暴露了一些API，能用来找回在/swaggerapi上的Swagger v1.2 Kubernetes API。这端点是过时的，将会在Kubernetes1.14去除。

API版本

为了使删除字段和重构资源表现更简单，Kubernetes支持使用不同路径的多个API版本。如/api/v1 或 /apis/extensions/v1beta1。

我们选择在API级别进行版本控制而非资源或字段级别，以确保API表现一个清晰、一致的系统资源和行为视图，并且控制对过期API和实验性API的访问。JSON和Protobuf序列化模式遵循同样的模式变化准则，下面的所有描述对两者格式都适用。

注意，API 版本和软件版本至少间接相关。API和发布建议（API and release versioning proposal）描述了API版本和软件版本的关系。

不同的API版本说明了不同的稳定性和支持等级。每个等级的标准在API变更文档（API Changes documentation）中详细介绍。内容概括如下：

Alpha级别：

版本名称包括alpha（如v1alpha1）。
可能有很多问题，启动用能会带来bug。默认禁用。
功能的支持可能在任意时间未经提醒就丢弃。
API可能在软件发布的时候，未经提醒就以不兼容的方式变化。
由于增加bug的风险和缺乏长期支持，只推荐在短期测试集群的用户使用。

Beta级别：

版本名称包括beta（如v2beta3）。
代码经过良好测试。启动功能被认为是安全的，默认启用。
所有功能的支持都不会被丢弃，但细节可能会变化。
在随后的beta或稳定发布中，对象的模式或语义可能会以不兼容的方式改变。这种情况下，我们会给出迁移到下个版本的指导。这可能需要删除、编辑或重建API对象。编辑过程可能需要一些思考。依赖这些功能的应用可能需要停运时间。
由于在接下来的发布中可能会有非兼容的变化，只建议非重要业务的用户使用。如果你有可以独立升级的多个集群，可以放松这个限制。
请尝试我们的beta功能并给出建议。一旦beta结束，我们将难以做出更多变化。

稳定级别

版本名是vX，X是一个整数。
稳定版本的功能将会在后续多个版本的发布软件中出现。

API组

为了更易于扩展Kubernetes API，我们实现了API组（API groups）。API组在REST路径和序列化对象的apiVersion中指定。

目前有数个API组在用：

1。核心组（core group），又称为遗留（legacy group）组，位于/api/v1 REST路径并使用apiVersion: v1。

2。指定的组位于/apis/$GROUP_NAME/$VERSION REST路径，并使用apiVersion: $GROUP_NAME/$VERSION(如apiVersion: batch/v1）.支持的API组完整列表可以在Kubernetes API reference查看。

支持使用两种方式以自定义资源（custom resources）来扩展API：

1。自定义资源定义（CustomResourceDefinition）适用于非常基础的CRUD需求的用户。

2。需要完整的Kubernetes API语义的用户可以实现他们自己的API服务器，并使用聚合器（aggregator）来使用户服务变得无缝。

启动API组

某些资源和API组默认启用。它们可以在API server设置--runtime-config来启用或禁用。--runtime-config接受逗号分隔的值。如:设置--runtime-config=batch/v1=false来禁用batch/v1，设置--runtime-config=batch/v2alpha1来启用 batch/v2alpha1。该标志接受逗号分隔的key=value对，来描述在API服务器上运行时的配置。

重要提醒：启用或禁用API组需要重启API服务器和控制器管理器（controller-manager）来获取--runtime-config更改。

启用组里的资源

DaemonSets, Deployments, HorizontalPodAutoscalers, Ingresses, Jobs和ReplicaSets默认启用。其他的扩展资源可以通过在API服务器上设置--runtime-config来启用。--runtime-config接受逗号分隔的值。如，要禁用deployments和ingress，设置--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/ingresses=false