API 规约文档中介绍了总体 API 规约。
API 参考（敬请期待～～）中描述了 API 端点，资源类型和示例。
在 API 的访问控制文档（敬请期待～～）中讨论了对 API 的远程访问。
Kubernetes API 还充当系统的声明式配置架构的根基。kubectl 命令行工具可用于创建、更新、删除和获取 API 对象。
Kubernetes 还根据 API 资源存储其序列化状态（当前存储在 etcd 中）。
Kubernetes 本身被分解为多个组件，这些组件通过其 API 进行交互。
API 变更
根据官方的经验，任何成功的系统都需要随着新用例的出现或先用用例的变化而增长和变化。因此，官方希望 Kubernetes API 能够不断变化和发展。但是，官方打算在很长一段时间内不破坏与现有客户端的兼容性。通常，可以期望经常添加新的 API 资源和新的资源字段。消除资源或字段将需要遵循 API 弃用政策（敬请期待～～）。
API 变更文档详细说明了构成兼容更改的方式以及如何变更 API。
OpenAPI 和 Swagger 定义
使用 OpenAPI 记录了完整的 API 详细信息。
从 Kubernetes 1.10 开始，Kubernetes API 服务器通过 /openapi/v2 端点提供 OpenAPI 规范。通过设置 HTTP 标头指定请求的格式：
| 标头 | 可能的值 |
|---|---|
| Accept | application/json、application/[email protected]+protobuf（缺省内容类型为 */* 的 application/json 或不传递该标头） |
| Accept-Encoding | gzip（不传递该标头是可接受的） |
在 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 规范的示例：
| 在 1.10 之前 | 从 1.10 开始 |
|---|---|
| GET /swagger.json | GET /openapi/v2 Accept: application/json |
| GET /swagger-2.0.0.pb-v1 | GET /openapi/v2 Accept: application/[email protected]+protobuf |
| GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 Accept: application/[email protected]+protobuf Accept-Encoding: gzip |
Kubernetes 为 API 实现了一种替代的基于 Protobuf 的 API 序列化格式，该格式主要用于集群内部通信，在设计提案中进行了说明，每个方案的 IDL 文件位于定义 API 对象的 Go 包中。
在1.14 之前，Kubernetes apiserver 还公开了一个 API，该 API 可用于在 /swaggerapi 上检索 Swagger v1.2 Kubernetes API 规范。该端点已弃用，在 Kubernetes 1.14 中已删除。
API 版本控制
为了更轻松地消除字段或重组资源表示形式，Kubernetes 支持多个 API 版本，每个版本位于不同的 API 路径，例如 /api/v1 或 /apis/extensions/v1beta1。
我们选在在 API 级别而不是在资源或字段级别进行版本控制，以确保 API 呈现系统资源和行为的清晰一致的视图，并能够控制对寿命的终止和/或实验性 API 的访问。JSON 和 Protobuf 序列化架构遵循相同的架构变更准则 - 以下所有描述均涵盖了这两种格式。
请注意，API 版本和软件版本仅间接相关。API 和发行版本控制建议描述了 API 版本控制和软件版本控制之间的关系。
不同的 API 版本意味着不同级别的稳定性和支持。API 变更文档中更详细地介绍了每个级别的条件。它们总结如下：
-
阿尔法版：
- 版本名称包含 Alpha（例如 v1alpha1）；
- 可能会有漏洞。启用该特性可能会暴露漏洞。默认禁用；
- 功能支持可能会随时取消，恕不另行通知；
- 在以后的软件版本中，API 可能会以不兼容的方式进行变更，恕不另行通知；
- 建议将其仅用于短期测试集群中，因为这样会增加错误的风险，并且缺乏长期支持。
-
测试版：
- 版本名称包含 beta（例如 v2beta3）；
- 代码已经过测试。启用该特性被认为是安全的。默认启用；
- 尽管可能会改变细节，但不会放弃对整体功能的支持；
- 对象的架构和/或予以可能会在随后的 Beta 稳定版本中以不兼容的方式进行变更。发生这种情况时，我们将提供有关迁移到下一个版本的说明。这可能需要删除、编辑和重新创建 API 对象。编辑过程可能需要一些考量。对于依赖该特性的应用，可能需要停机；
- 建议仅用于非关键业务用途，因为在后续版本中可能会发生不兼容的变更。如果有多个可以独立升级的集群，则可以放宽该限制；
- 请尝试使用官方的测试版本特性并提供反馈！在它们退出测试版本后，官方不大可能对其做改动。
-
稳定版：
- 版本名称为 vX，其中 X 为整数；
- 稳定版本的特性将出现在许多后续版本的已发行软件中。
API 组
为了使扩展 Kubernetes API 更容易，我们实现了 API 组。API 组是在 REST 路径和序列化对象的 apiVersion 字段中指定的。
当前有几个正在使用的 API 组：
- 核心组（通常称为旧组）位于 REST 路径
/api/v1处，并使用apiVersion:v1； - 命名的组位于 REST 路径
/apis/#GROUP_NAME/$VERSION，并使用apiVersion:$GROUP_NAME/$VERSION（例如apiVersion:batch/v1）。支持的 API 组的完整列表可以在 Kubernetes API 参考（敬请期待～～）中找到。
有两种使用自定义资源（敬请期待～～）扩展 API 的受支持路径：
- CustomResourceDefinition（敬请期待～～） 适用于具有非常基本的 CRUD 需求的用户；
- 需要全套 Kubernetes API 语义的用户可以实现自己的 apiserver，并使用聚合器（敬请期待～～） 使其与客户端无缝结合。
启用或禁用 API 组
默认情况下，某些资源和 API 组处于启用状态。可以通过在 apiserver 上设置 --runtime-config 来启用或禁用它们。--runtime-config 接受逗号分隔的值。例如：要禁用 batch/v1，设置 --runtime-config=batch/v1=false，要启用 batch/v2alpha1，设置 --runtime-config=batch/v2alpha1。该标志接受逗号分隔的一组键=值对，描述了 apiserver 的运行时配置。
注意：启用或禁用组或资源需要重启 apiserver 和 controller-manager 来获取
--runtime-config变更。
在 extensions/v1beta1 组中启用特定资源
默认情况下，extensions/v1beta1 API 组中的 DaemonSet、Deployment、StatefulSet、NetworkPolicies、PodSecurityPolicies 和 ReplicaSet 是被禁用的。例如：要启用部署和守护进程集，请设置 --runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true。
注意：出于遗留原因，仅在
extensions/v1beta1API 组中支持单个资源的启用/禁用。
