diff --git a/content/zh/docs/concepts/overview/kubernetes-api.md b/content/zh/docs/concepts/overview/kubernetes-api.md index 8594bdcfb4..99d65a572f 100644 --- a/content/zh/docs/concepts/overview/kubernetes-api.md +++ b/content/zh/docs/concepts/overview/kubernetes-api.md @@ -3,7 +3,7 @@ title: Kubernetes API content_type: concept weight: 30 description: > - Kubernetes API 使您可以查询和操纵 Kubernetes 中对象的状态。Kubernetes 控制平面的核心是 API 服务器和它暴露的 HTTP API。 用户、集群的不同部分以及外部组件都通过 API 服务器相互通信。 + Kubernetes API 使你可以查询和操纵 Kubernetes 中对象的状态。Kubernetes 控制平面的核心是 API 服务器和它暴露的 HTTP API。 用户、集群的不同部分以及外部组件都通过 API 服务器相互通信。 card: name: concepts weight: 30 @@ -12,135 +12,186 @@ card: -[API协议文档](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md)描述了主系统和API概念。 - -[API参考文档](/docs/reference)描述了API整体规范。 - -[访问文档](/docs/admin/accessing-the-api)讨论了通过远程访问API的相关问题。 - -Kubernetes API是系统描述性配置的基础。 [Kubectl](/docs/user-guide/kubectl/) 命令行工具被用于创建、更新、删除、获取API对象。 - -Kubernetes 通过API资源存储自己序列化状态(现在存储在[etcd](https://coreos.com/docs/distributed-configuration/getting-started-with-etcd/))。 - -Kubernetes 被分成多个组件，各部分通过API相互交互。 - +Kubernetes {{< glossary_tooltip text="控制面" term_id="control-plane" >}} +的核心是 {{< glossary_tooltip text="API 服务器" term_id="kube-apiserver" >}}。 +API 服务器负责提供 HTTP API，以供用户、集群中的不同部分和集群外部组件相互通信。 +Kubernetes API 使你可以查询和操纵 Kubernetes API +中对象（例如：Pod、Namespace、ConfigMap 和 Event）的状态。 +API 末端、资源类型以及示例都在[API 参考](/zh/docs/reference/kubernetes-api/)中描述。 -## API 变更 +## API 变更 {#api-changes} -根据经验，任何成功的系统都需要随着新的用例出现或现有用例发生变化的情况下，进行相应的进化与调整。因此，我们希望Kubernetes API也可以保持持续的进化和调整。同时，在较长一段时间内，我们也希望与现有客户端版本保持良好的向下兼容性。一般情况下，增加新的API资源和资源字段不会导致向下兼容性问题发生；但如果是需要删除一个已有的资源或者字段，那么必须通过[API废弃流程](/docs/reference/deprecation-policy/)来进行。 +任何成功的系统都要随着新的使用案例的出现和现有案例的变化来成长和变化。 +为此，Kubernetes 的功能特性设计考虑了让 Kubernetes API 能够持续变更和成长的因素。 +Kubernetes 项目的目标是 _不要_ 引发现有客户端的兼容性问题，并在一定的时期内 +维持这种兼容性，以便其他项目有机会作出适应性变更。 -参考[API变更文档](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md)，了解兼容性变更的要素以及如何变更API的流程。 +一般而言，新的 API 资源和新的资源字段可以被频繁地添加进来。 +删除资源或者字段则要遵从 +[API 废弃策略](/zh/docs/reference/using-api/deprecation-policy/)。 + +关于什么是兼容性的变更，如何变更 API 等详细信息，可参考 +[API 变更](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme)。 -## OpenAPI 和 API Swagger 定义 +## OpenAPI 规范 {#api-specification} -完整的 API 详细文档使用 [OpenAPI](https://www.openapis.org/)生成. +完整的 API 细节是用 [OpenAPI](https://www.openapis.org/) 来表述的。 -随着 Kubernetes 1.10 版本的正式启用，Kubernetes API 服务通过 `/openapi/v2` 接口提供 OpenAPI 规范。 -通过设置 HTTP 标头的规定了请求的结构。 - -Header | Possible Values ------- | --------------- -Accept | `application/json`, `application/com.github.proto-openapi.spec.v2@v1.0+protobuf` (the default content-type is `application/json` for `*/*` or not passing this header) -Accept-Encoding | `gzip` (not passing this header is acceptable) +Kubernetes API 服务器通过 `/openapi/v2` 末端提供 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 规范的例子**: - -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/com.github.proto-openapi.spec.v2@v1.0+protobuf -GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 **Accept**: application/com.github.proto-openapi.spec.v2@v1.0+protobuf **Accept-Encoding**: gzip + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
头部可选值说明
Accept-Encodinggzip不指定此头部也是可以的
Acceptapplication/com.github.proto-openapi.spec.v2@v1.0+protobuf主要用于集群内部
application/json默认值
*提供application/json
OpenAPI v2 查询请求的合法头部值
- -Kubernetes实现了另一种基于Protobuf的序列化格式，该格式主要用于集群内通信，并在[设计方案](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md)中进行了说明，每个模式的IDL文件位于定义API对象的Go软件包中。 -在 1.14 版本之前， Kubernetes apiserver 也提供 API 服务用于返回 -[Swagger v1.2](http://swagger.io/) Kubernetes API 规范通过 `/swaggerapi` 接口. -但是这个接口已经被废弃，并且在 Kubernetes 1.14 中已经被移除。 +Kubernetes 为 API 实现了一种基于 Protobuf 的序列化格式，主要用于集群内部的通信。 +相关文档位于[设计提案](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md)。 +每种 Schema 对应的 IDL 位于定义 API 对象的 Go 包中。 +## API 版本 {#api-versioning} -## API 版本 - -为了使删除字段或者重构资源表示更加容易，Kubernetes 支持 -多个API版本。每一个版本都在不同API路径下，例如 `/api/v1` 或者 -`/apis/extensions/v1beta1`。 +为了简化删除字段或者重构资源表示等工作，Kubernetes 支持多个 API 版本， +每一个版本都在不同 API 路径下，例如 `/api/v1` 或 +`/apis/rbac.authorization.k8s.io/v1alpha1`。 +版本化是在 API 级别而不是在资源或字段级别进行的，目的是为了确保 API +为系统资源和行为提供清晰、一致的视图，并能够控制对已废止的和/或实验性 API 的访问。 -我们选择在API级别进行版本化，而不是在资源或字段级别进行版本化，以确保API提供清晰，一致的系统资源和行为视图，并控制对已废止的API和/或实验性API的访问。 JSON和Protobuf序列化模式遵循架构更改的相同准则 - 下面的所有描述都同时适用于这两种格式。 - -请注意，API版本控制和软件版本控制只有间接相关性。 - [API和发行版本建议](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) 描述了API版本与软件版本之间的关系。 +JSON 和 Protobuf 序列化模式遵循 schema 更改的相同准则 - 下面的所有描述都同时适用于这两种格式。 +请注意，API 版本控制和软件版本控制只有间接相关性。 +[Kubernetes 发行版本提案](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) +中描述了 API 版本与软件版本之间的关系。 -不同的API版本名称意味着不同级别的软件稳定性和支持程度。 每个级别的标准在[API变更文档](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions)中有更详细的描述。 内容主要概括如下： +不同的 API 版本名称意味着不同级别的软件稳定性和支持程度。 +每个级别的判定标准在 +[API 变更文档](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions) +中有更详细的描述。 +这些标准主要概括如下： +- Alpha 级别： + - 版本名称包含 `alpha`（例如：`v1alpha1`） + - API 可能是有缺陷的。启用该功能可能会带来问题，默认情况是禁用的 + - 对相关功能的支持可能在没有通知的情况下随时终止 + - API 可能在将来的软件发布中出现不兼容性的变更，此类变更不会另行通知 + - 由于缺陷风险较高且缺乏长期支持，推荐仅在短暂的集群测试中使用 + + +- Beta 级别： + - 版本名称包含 `beta`（例如：`v2beta3`） + - 代码已经充分测试过。启用该功能被认为是安全的，功能默认已启用。 + - 所支持的功能作为一个整体不会被删除，尽管细节可能会发生变更。 + - 对象的模式和/或语义可能会在后续的 beta 发行版或稳定版中以不兼容的方式进行更改。 + 发生这种情况时，我们将提供如何迁移到新版本的说明。 + 迁移操作可能需要删除、编辑和重新创建 API 对象。 + 执行编辑操作时可能需要动些脑筋。 + 迁移过程中可能需要停用依赖该功能的应用程序。 + - 建议仅用于非业务关键性用途，因为后续版本中可能存在不兼容的更改。 + 如果你有多个可以独立升级的集群，则可以放宽此限制。 + - **请尝试我们的 beta 版本功能并且给出反馈！一旦它们结束 beta 阶段，进一步变更可能就不太现实了。** + -- Alpha 测试版本： - - 版本名称包含了 **`alpha`** (例如：**`v1alpha1`**)。 - - 可能是有缺陷的。启用该功能可能会带来隐含的问题，默认情况是关闭的。 - - 支持的功能可能在没有通知的情况下随时删除。 - - API的更改可能会带来兼容性问题，但是在后续的软件发布中不会有任何通知。 - - 由于bugs风险的增加和缺乏长期的支持，推荐在短暂的集群测试中使用。 -- Beta 测试版本： - - 版本名称包含了 **`beta`** (例如: **`v2beta3`**)。 - - 代码已经测试过。启用该功能被认为是安全的，功能默认已启用。 - - 所有已支持的功能不会被删除，细节可能会发生变化。 - - 对象的模式和/或语义可能会在后续的beta测试版或稳定版中以不兼容的方式进行更改。 发生这种情况时，我们将提供迁移到下一个版本的说明。 这可能需要删除、编辑和重新创建API对象。执行编辑操作时需要谨慎行事，这可能需要停用依赖该功能的应用程序。 - - 建议仅用于非业务关键型用途，因为后续版本中可能存在不兼容的更改。 如果您有多个可以独立升级的集群，则可以放宽此限制。 - - **请尝试我们的 beta 版本功能并且给出反馈！一旦他们退出 beta 测试版，我们可能不会做出更多的改变。** -- 稳定版本： - - 版本名称是 **`vX`**，其中 **`X`** 是整数。 +- 稳定级别： + - 版本名称是 `vX`，其中 `X` 是整数。 - 功能的稳定版本将出现在许多后续版本的发行软件中。 +## API 组 {#api-groups} -## API 组 - -为了更容易地扩展Kubernetes API，我们实现了[*`API组`*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md)。 -API组在REST路径和序列化对象的 **`apiVersion`** 字段中指定。 +为了更容易地扩展 Kubernetes API，Kubernetes 实现了 +[*`API组`*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md)。 +API 组在 REST 路径和序列化对象的 `apiVersion` 字段中指定。 +集群中存在若干 API 组： -目前有几个API组正在使用中： +1. *核心（Core）*组，通常被称为 *遗留（Legacy）* 组，位于 REST 路径 `/api/v1`， + 使用 `apiVersion: v1`。 -1. 核心组（通常被称为遗留组）位于REST路径 `/api/v1` 并使用 `apiVersion：v1`。 - -1. 指定的组位于REST路径 `/apis/$GROUP_NAME/$VERSION`，并使用 `apiVersion：$GROUP_NAME/$VERSION` - （例如 `apiVersion：batch/v1`）。 在[Kubernetes API参考](/docs/reference/)中可以看到支持的API组的完整列表。 +1. *命名（Named）* 组 REST 路径 `/apis/$GROUP_NAME/$VERSION`，使用 + `apiVersion: $GROUP_NAME/$VERSION`（例如 `apiVersion: batch/v1`）。 + [Kubernetes API 参考](/zh/docs/reference/kubernetes-api/)中枚举了可用的 API 组的完整列表。 +有两种途径来扩展 Kubernetes API 以支持 +[自定义资源](/zh/docs/concepts/extend-kubernetes/api-extension/custom-resources/)： -社区支持使用以下两种方式来提供自定义资源对API进行扩展[自定义资源](/docs/concepts/api-extension/custom-resources/)： +1. 使用 [CustomResourceDefinition](/zh/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)， + 你可以用声明式方式来定义 API 如何提供你所选择的资源 API。 -1. [CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/) - 适用于具有非常基本的CRUD需求的用户。 - -1. 需要全套Kubernetes API语义的用户可以实现自己的apiserver， - 并使用[聚合器](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) +1. 你也可以选择[实现自己的扩展 API 服务器](/zh/docs/tasks/extend-kubernetes/setup-extension-api-server/) + 并使用[聚合器](/zh/docs/tasks/extend-kubernetes/configure-aggregation-layer/) 为客户提供无缝的服务。 +## 启用或禁用 API 组 {#enabling-or-disabling-api-groups} -## 启用 API 组 - -某些资源和API组默认情况下处于启用状态。 可以通过在apiserver上设置 `--runtime-config` 来启用或禁用它们。 +某些资源和 API 组默认情况下处于启用状态。可以通过为 `kube-apiserver` +设置 `--runtime-config` 命令行选项来启用或禁用它们。 `--runtime-config` 接受逗号分隔的值。 -例如：要禁用batch/v1，请设置 `--runtime-config=batch/v1=false`，以启用batch/v2alpha1，请设置`--runtime-config=batch/v2alpha1`。 -该标志接受描述apiserver的运行时配置的逗号分隔的一组键值对。 +例如：要禁用 `batch/v1`，设置 `--runtime-config=batch/v1=false`； +要启用 `batch/v2alpha1`，设置`--runtime-config=batch/v2alpha1`。 +该标志接受逗号分隔的一组"key=value"键值对，用以描述 API 服务器的运行时配置。 {{< note >}} - -启用或禁用组或资源需要重新启动apiserver和控制器管理器来使得 `--runtime-config` 更改生效。 - +启用或禁用组或资源需要重新启动 `kube-apiserver` 和 `kube-controller-manager` +来使得 `--runtime-config` 更改生效。 {{< /note >}} +## 持久性 {#persistence} -## 启用 extensions/v1beta1 组中资源 +Kubernetes 也将其 API 资源的序列化状态保存起来，写入到 {{< glossary_tooltip term_id="etcd" >}}。 -在 `extensions/v1beta1` API 组中，DaemonSets，Deployments，StatefulSet, NetworkPolicies, PodSecurityPolicies 和 ReplicaSets 是默认禁用的。 -例如：要启用 deployments 和 daemonsets，请设置 `--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true`。 +## {{% heading "whatsnext" %}} -{{< note >}} + +* [控制 API 访问](/zh/docs/reference/access-authn-authz/controlling-access/) + 描述了集群如何为 API 访问管理身份认证和权限判定； +* 总体的 API 约定描述位于 [API 约定](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md)中； +* API 末端、资源类型和示例等均在 [API 参考文档](/zh/docs/reference/kubernetes-api/)中描述 -出于遗留原因，仅在 `extensions / v1beta1` API 组中支持各个资源的启用/禁用。 -{{< /note >}}