Overall API conventions are described in the API文档描述及约定规范 API conventions doc.

API endpoints, 资源类型和示例在api引用中进行了描述。

Remote access to the API is discussed in the api文档远程访问  Controlling API Access doc.

kubernetes api还充当系统声明性配置模式的基础。kubectl命令行工具可用于创建、更新、删除和获取api对象。

kubernetes还根据api资源存储其序列化状态（当前在etcd中）。
kubernetes本身被分解为多个组件，这些组件通过其api进行交互。

• API changes
• OpenAPI and Swagger definitions
• API versioning
• API groups
• Enabling API groups
• Enabling resources in the groups

api-changes

根据我们的经验，任何成功的系统都需要随着新用例的出现或现有用例的改变而增长和改变。因此，我们期望kubernetes api不断变化和增长。但是，我们打算在很长一段时间内不破坏与现有客户机的兼容性。通常，新的API资源和新的资源字段可以被频繁地添加。消除资源或字段将需要遵循API弃用策略。
什么构成兼容的更改以及如何更改api由api更改文档详细说明。

简而言之api的规范
修改策略
API change document.
遗弃策略
API deprecation policy

openapi和swagger定义

OpenAPI详细介绍.

在1.14之前，格式分离的端点（/swagger.json，/swagger-2.0.0.json，/swagger-2.0.0.pb-v1，/swagger-2.0.0.pb-v1.gz）以不同的格式提供openapi规范。这些端点已弃用，并在Kubernetes 1.14中删除。
获取openapi规范的示例：

kubernetes为api实现了另一种基于protobuf的序列化格式，该格式主要用于集群内通信，在设计方案中有记录，每个模式的idl文件位于定义api对象的go包中。
在1.14之前，Kubernetes apiserve还公开了一个API，可以用来检索Swagger v1.2 Kubernetes API规范//swaggerapi。此方法已弃用，并将在Kubernetes 1.14中删除。

API版本控制

为了更容易消除字段或重新构造资源表示，kubernetes支持多个api版本，每个版本位于不同的api路径，例如/api/v1 or /apis/extensions/v1beta1.

我们选择在api级别而不是在资源或字段级别进行版本转换，以确保api呈现出系统资源和行为的清晰、一致的视图，并允许控制对生命周期结束和/或实验性api的访问。json和protobuf序列化模式遵循相同的模式更改准则-下面的所有描述都涵盖这两种格式。

注意，api版本控制和软件版本控制只是间接相关的。api和发布版本控制建议描述了api版本控制和软件版本控制之间的关系。
不同的api版本意味着不同的稳定性和支持级别。每个级别的标准在api更改文档中有更详细的描述。总结如下：

Alpha level:

• 版本名包含alpha (e.g. v1alpha1).
• 可能有很多bug.启用此功能可能会暴露错误. 默认是禁止
• 对功能的支持随时可能被放弃,恕不另行通知.
• 在以后的软件版本中，API可能会以不兼容的方式更改，恕不另行通知.
• 由于错误风险增加和缺乏长期支持，建议仅在短期测试集群中使用.

Beta level:

• 版本名包含beta (e.g. v2beta3).
• 代码经过测试.启用该功能被认为是安全的。默认情况下启用
• 对整体功能的支持不会被放弃，尽管细节可能会改变
• 在随后的beta版或稳定版中，对象的模式和/或语义可能会以不兼容的方式发生变化。当这种情况发生时，我们将提供迁移到下一个版本的说明。这可能需要删除、编辑和重新创建api对象。编辑过程可能需要一些思考。对于依赖于该功能的应用程序，这可能需要停机。
• 建议仅用于非业务关键型用途，因为后续版本中可能会发生不兼容的更改。如果你有多个可以独立升级的集群，你可以放松这个限制。
• 请尝试我们的测试版功能并给出反馈！一旦他们退出beta版，我们可能就不太现实了.

Stable level(稳定版):

• 版本名为“vx”，其中“x”是整数。
• 功能的稳定版本将出现在许多后续版本的发布软件中。

API groups

为了更容易扩展kubernetes api，我们实现了api组 API groups。api组在rest路径和序列化对象的apiversion字段中指定。
目前有几个API组正在使用：

• 核心组: is at the REST path /api/v1 and uses apiVersion: v1
• api组位于REST path /apis/$GROUP_NAME/$VERSION, 资源定义使用apiVersion: $GROUP_NAME/$VERSION (e.g. apiVersion: batch/v1)所有的api组Kubernetes API reference

我们有两种方式自定义API扩展:

1. CustomResourceDefinition 给用户提供基本的增删改查而设计的
2. 需要完整的Kubernetes API语义的用户可以实现自己的ApServer，并使用 aggregator 来为客户端无缝连接。

启用api group

默认情况下会启用某些资源和API组. 可以通过 --runtime-config 来设置在apiserver启动时r. --runtime-config 接受逗号分隔的值. 例如: 禁用 batch/v1, 设置--runtime-config=batch/v1=false, 启用 batch/v2alpha1, 设置 --runtime-config=batch/v2alpha1. 该参数接收以逗号分隔 key=value 在apiserver启动时进行传参

重要提示: 启用或禁用组或资源需要重新启动APIServer和控制器管理器以获取--runtime配置更改。

Enabling resources in the groups (禁用启用)

DaemonSets, Deployments, HorizontalPodAutoscalers,Ingresses, Jobs and ReplicaSets 默认是启用的,可以通过设置启用其他扩展资源 --runtime-config, 在apiserver启动前接收以逗号分隔方式进行传参; 例如:要禁用 Deployments和Ingresses可以这样传参 --runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/ingresses=false

本作品采用《CC 协议》，转载必须注明作者和本文链接