diff --git a/content/zh/docs/concepts/overview/_index.md b/content/zh/docs/concepts/overview/_index.md index 8c8aff7531..03941b849d 100644 --- a/content/zh/docs/concepts/overview/_index.md +++ b/content/zh/docs/concepts/overview/_index.md @@ -1,7 +1,14 @@ --- title: 概述 weight: 20 -description: 获得 Kubernetes 及其构件的高层次概要。 +description: 了解 Kubernetes 及其构件的高层次概要。 sitemap: priority: 0.9 --- + diff --git a/content/zh/docs/concepts/overview/kubernetes-api.md b/content/zh/docs/concepts/overview/kubernetes-api.md index 17e0c45000..61cf1a2c2e 100644 --- a/content/zh/docs/concepts/overview/kubernetes-api.md +++ b/content/zh/docs/concepts/overview/kubernetes-api.md @@ -23,7 +23,7 @@ The Kubernetes API lets you query and manipulate the state of API objects in Kub (for example: Pods, Namespaces, ConfigMaps, and Events). Most operations can be performed through the -[kubectl](/docs/reference/kubectl/overview/) command-line interface or other +[kubectl](/docs/reference/kubectl/) command-line interface or other command-line tools, such as [kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the API. However, you can also access the API directly using REST calls. @@ -35,7 +35,7 @@ API 服务器负责提供 HTTP API,以供用户、集群中的不同部分和 Kubernetes API 使你可以查询和操纵 Kubernetes API 中对象(例如:Pod、Namespace、ConfigMap 和 Event)的状态。 -大部分操作都可以通过 [kubectl](/zh/docs/reference/kubectl/overview/) 命令行接口或 +大部分操作都可以通过 [kubectl](/zh/docs/reference/kubectl/) 命令行接口或 类似 [kubeadm](/zh/docs/reference/setup-tools/kubeadm/) 这类命令行工具来执行, 这些工具在背后也是调用 API。不过,你也可以使用 REST 调用来访问这些 API。 @@ -53,14 +53,19 @@ if you are writing an application using the Kubernetes API. Complete API details are documented using [OpenAPI](https://www.openapis.org/). -The Kubernetes API server serves an OpenAPI spec via the `/openapi/v2` endpoint. -You can request the response format using request headers as follows: +### OpenAPI V2 + +The Kubernetes API server serves an aggregated OpenAPI v2 spec via the +`/openapi/v2` endpoint. You can request the response format using +request headers as follows: --> ## OpenAPI 规范 {#api-specification} 完整的 API 细节是用 [OpenAPI](https://www.openapis.org/) 来表述的。 -Kubernetes API 服务器通过 `/openapi/v2` 末端提供 OpenAPI 规范。 +### OpenAPI V2 + +Kubernetes API 服务器通过 `/openapi/v2` 端点提供聚合的 OpenAPI v2 规范。 你可以按照下表所给的请求头部,指定响应的格式: +Kubernetes v1.23 提供将其 API 以 OpenAPI v3 形式发布的初始支持;这一功能特性处于 Alpha +状态,默认被禁用。 +你可以通过为 kube-apiserver 组件启用 `OpenAPIV3` +[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)来启用此 +Alpha 特性。 + + +特性被启用时,Kubernetes API 服务器会在端点 `/openapi/v3/apis//` +提供按 Kubernetes 组版本聚合的 OpenAPI v3 规范。 +请参阅下表了解可接受的请求头部。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OpenAPI v3 查询的合法请求头部值
头部可选值说明
Accept-Encodinggzip不提供此头部也是可接受的
Acceptapplication/com.github.proto-openapi.spec.v3@v1.0+protobuf主要用于集群内部使用
application/json默认
* application/json 形式返回
+ + +发现端点 `/openapi/v3` 被提供用来查看可用的所有组、版本列表。 +此列表仅返回 JSON。 + ## API 变更 {#api-changes} @@ -160,67 +223,44 @@ What constitutes a compatible change, and how to change the API, are detailed in Kubernetes 项目的目标是 _不要_ 引发现有客户端的兼容性问题,并在一定的时期内 维持这种兼容性,以便其他项目有机会作出适应性变更。 + 一般而言,新的 API 资源和新的资源字段可以被频繁地添加进来。 删除资源或者字段则要遵从 [API 废弃策略](/zh/docs/reference/using-api/deprecation-policy/)。 -关于什么是兼容性的变更、如何变更 API 等详细信息,可参考 -[API 变更](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme)。 - -## API 组和版本 {#api-groups-and-versioning} - -为了简化删除字段或者重构资源表示等工作,Kubernetes 支持多个 API 版本, -每一个版本都在不同 API 路径下,例如 `/api/v1` 或 -`/apis/rbac.authorization.k8s.io/v1alpha1`。 +Kubernetes 对维护达到正式发布(GA)阶段的官方 API 的兼容性有着很强的承诺, +通常这一 API 版本为 `v1`。此外,Kubernetes 在可能的时候还会保持 Beta API +版本的兼容性:如果你采用了 Beta API,你可以继续在集群上使用该 API, +即使该功能特性已进入稳定期也是如此。 +{{< note >}} -版本化是在 API 级别而不是在资源或字段级别进行的,目的是为了确保 API -为系统资源和行为提供清晰、一致的视图,并能够控制对已废止的和/或实验性 API 的访问。 - - -为了便于演化和扩展其 API,Kubernetes 实现了 -可被[启用或禁用](/zh/docs/reference/using-api/#enabling-or-disabling)的 -[API 组](/zh/docs/reference/using-api/#api-groups)。 - - -API 资源之间靠 API 组、资源类型、名字空间(对于名字空间作用域的资源而言)和 -名字来相互区分。API 服务器可能通过多个 API 版本来向外提供相同的下层数据, -并透明地完成不同 API 版本之间的转换。所有这些不同的版本实际上都是同一资源 -的(不同)表现形式。例如,假定同一资源有 `v1` 和 `v1beta1` 版本, -使用 `v1beta1` 创建的对象则可以使用 `v1beta1` 或者 `v1` 版本来读取、更改 -或者删除。 +尽管 Kubernetes 也努力为 Alpha API 版本维护兼容性,在有些场合兼容性是无法做到的。 +如果你使用了任何 Alpha API 版本,需要在升级集群时查看 Kubernetes 发布说明, +以防 API 的确发生变更。 +{{< /note >}} -关于 API 版本级别的详细定义,请参阅 -[API 版本参考](/zh/docs/reference/using-api/#api-versioning)。 +关于 API 版本分级的定义细节,请参阅 +[API 版本参考](/zh/docs/reference/using-api/#api-versioning)页面。 - 了解如何通过添加你自己的 [CustomResourceDefinition](/zh/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) 来扩展 Kubernetes API。 -- [控制 Kubernetes API 访问](/zh/docs/concepts/security/controlling-access/) - 页面描述了集群如何针对 API 访问管理身份认证和鉴权。 -- 通过阅读 [API 参考](/zh/docs/reference/kubernetes-api/) - 了解 API 端点、资源类型以及示例。 +- [控制 Kubernetes API 访问](/zh/docs/concepts/security/controlling-access/)页面描述了集群如何针对 + API 访问管理身份认证和鉴权。 +- 通过阅读 [API 参考](/zh/docs/reference/kubernetes-api/)了解 API 端点、资源类型以及示例。 +- 阅读 [API 变更(英文)](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme) + 以了解什么是兼容性的变更以及如何变更 API。