265 lines
12 KiB
Markdown
265 lines
12 KiB
Markdown
---
|
||
title: API 概述
|
||
content_type: concept
|
||
weight: 20
|
||
no_list: true
|
||
card:
|
||
name: reference
|
||
weight: 50
|
||
title: API 概述
|
||
---
|
||
|
||
<!--
|
||
title: API Overview
|
||
reviewers:
|
||
- erictune
|
||
- lavalamp
|
||
- jbeda
|
||
content_type: concept
|
||
weight: 20
|
||
no_list: true
|
||
card:
|
||
name: reference
|
||
weight: 50
|
||
title: Overview of API
|
||
-->
|
||
|
||
<!-- overview -->
|
||
|
||
<!--
|
||
This section provides reference information for the Kubernetes API.
|
||
-->
|
||
本文提供了 Kubernetes API 的参考信息。
|
||
|
||
<!--
|
||
The REST API is the fundamental fabric of Kubernetes. All operations and
|
||
communications between components, and external user commands are REST API
|
||
calls that the API Server handles. Consequently, everything in the Kubernetes
|
||
platform is treated as an API object and has a corresponding entry in the
|
||
[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||
-->
|
||
REST API 是 Kubernetes 的基本结构。
|
||
所有操作和组件之间的通信及外部用户命令都是调用 API 服务器处理的 REST API。
|
||
因此，Kubernetes 平台视一切皆为 API 对象，
|
||
且它们在 [API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/) 中有相应的定义。
|
||
|
||
<!--
|
||
The [Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
|
||
lists the API for Kubernetes version {{< param "version" >}}.
|
||
-->
|
||
[Kubernetes API 参考](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
|
||
列出了 Kubernetes {{< param "version" >}} 版本的 API。
|
||
|
||
<!--
|
||
For general background information, read
|
||
[The Kubernetes API](/docs/concepts/overview/kubernetes-api/).
|
||
[Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/)
|
||
describes how clients can authenticate to the Kubernetes API server, and how their
|
||
requests are authorized.
|
||
-->
|
||
如需了解一般背景信息，请查阅 [Kubernetes API](/zh-cn/docs/concepts/overview/kubernetes-api/)。
|
||
[Kubernetes API 控制访问](/zh-cn/docs/concepts/security/controlling-access/)描述了客户端如何向
|
||
Kubernetes API 服务器进行身份认证以及他们的请求如何被鉴权。
|
||
|
||
<!--
|
||
## API versioning
|
||
-->
|
||
## API 版本控制 {#api-versioning}
|
||
|
||
<!--
|
||
The JSON and Protobuf serialization schemas follow the same guidelines for
|
||
schema changes. The following descriptions cover both formats.
|
||
-->
|
||
JSON 和 Protobuf 序列化模式遵循相同的模式更改原则。
|
||
以下描述涵盖了这两种格式。
|
||
|
||
<!--
|
||
The API versioning and software versioning are indirectly related.
|
||
The [API and release versioning proposal](https://git.k8s.io/sig-release/release-engineering/versioning.md)
|
||
describes the relationship between API versioning and software versioning.
|
||
-->
|
||
API 版本控制和软件版本控制是间接相关的。
|
||
[API 和发布版本控制提案](https://git.k8s.io/sig-release/release-engineering/versioning.md)描述了
|
||
API 版本控制和软件版本控制间的关系。
|
||
|
||
<!--
|
||
Different API versions indicate different levels of stability and support. You
|
||
can find more information about the criteria for each level in the
|
||
[API Changes documentation](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)
|
||
中查看到更多的不同级别的判定标准。
|
||
|
||
<!--
|
||
Here's a summary of each level:
|
||
-->
|
||
下面是每个级别的摘要：
|
||
|
||
<!--
|
||
- Alpha:
|
||
- The version names contain `alpha` (for example, `v1alpha1`).
|
||
- Built-in alpha API versions are disabled by default and must be explicitly enabled in the `kube-apiserver` configuration to be used.
|
||
- The software may contain bugs. Enabling a feature may expose bugs.
|
||
- Support for an alpha API may be dropped at any time without notice.
|
||
- The API may change in incompatible ways in a later software release without notice.
|
||
- The software is recommended for use only in short-lived testing clusters,
|
||
due to increased risk of bugs and lack of long-term support.
|
||
-->
|
||
- Alpha：
|
||
- 版本名称包含 `alpha`（例如：`v1alpha1`）。
|
||
- 内置的 Alpha API 版本默认被禁用且必须在 `kube-apiserver` 配置中显式启用才能使用。
|
||
- 软件可能会有 Bug。启用某个特性可能会暴露出 Bug。
|
||
- 对某个 Alpha API 特性的支持可能会随时被删除，恕不另行通知。
|
||
- API 可能在以后的软件版本中以不兼容的方式更改，恕不另行通知。
|
||
- 由于缺陷风险增加和缺乏长期支持，建议该软件仅用于短期测试集群。
|
||
|
||
<!--
|
||
- Beta:
|
||
- The version names contain `beta` (for example, `v2beta3`).
|
||
- Built-in beta API versions are disabled by default and must be explicitly enabled in the `kube-apiserver` configuration to be used
|
||
(**except** for beta versions of APIs introduced prior to Kubernetes 1.22, which were enabled by default).
|
||
- Built-in beta API versions have a maximum lifetime of 9 months or 3 minor releases (whichever is longer) from introduction
|
||
to deprecation, and 9 months or 3 minor releases (whichever is longer) from deprecation to removal.
|
||
- The software is well tested. Enabling a feature is considered safe.
|
||
- The support for a feature will not be dropped, though the details may change.
|
||
-->
|
||
- Beta：
|
||
- 版本名称包含 `beta`（例如：`v2beta3`）。
|
||
- 内置的 Beta API 版本默认被禁用且必须在 `kube-apiserver` 配置中显式启用才能使用
|
||
（例外情况是 Kubernetes 1.22 之前引入的 Beta 版本的 API，这些 API 默认被启用）。
|
||
- 内置 Beta API 版本从引入到弃用的最长生命周期为 9 个月或 3 个次要版本（以较长者为准），
|
||
从弃用到移除的最长生命周期为 9 个月或 3 个次要版本（以较长者为准）。
|
||
- 软件被很好的测试过。启用某个特性被认为是安全的。
|
||
- 尽管一些特性会发生细节上的变化，但它们将会被长期支持。
|
||
|
||
<!--
|
||
- The schema and/or semantics of objects may change in incompatible ways in
|
||
a subsequent beta or stable API version. When this happens, migration
|
||
instructions are provided. Adapting to a subsequent beta or stable API version
|
||
may require editing or re-creating API objects, and may not be straightforward.
|
||
The migration may require downtime for applications that rely on the feature.
|
||
- The software is not recommended for production uses. Subsequent releases
|
||
may introduce incompatible changes. Use of beta API versions is
|
||
required to transition to subsequent beta or stable API versions
|
||
once the beta API version is deprecated and no longer served.
|
||
-->
|
||
- 在随后的 Beta 版或 Stable 版中，对象的模式和（或）语义可能以不兼容的方式改变。
|
||
当这种情况发生时，将提供迁移说明。
|
||
适配后续的 Beta 或 Stable API 版本可能需要编辑或重新创建 API 对象，这可能并不简单。
|
||
对于依赖此功能的应用程序，可能需要停机迁移。
|
||
- 该版本的软件不建议生产使用。
|
||
后续发布版本可能会有不兼容的变动。
|
||
一旦 Beta API 版本被弃用且不再提供服务，
|
||
则使用 Beta API 版本的用户需要转为使用后续的 Beta 或 Stable API 版本。
|
||
|
||
{{< note >}}
|
||
<!--
|
||
Please try beta features and provide feedback. After the features exit beta, it
|
||
may not be practical to make more changes.
|
||
-->
|
||
请尝试 Beta 版时特性时并提供反馈。
|
||
特性完成 Beta 阶段测试后，就可能不会有太多的变更了。
|
||
{{< /note >}}
|
||
|
||
<!--
|
||
- Stable:
|
||
- The version name is `vX` where `X` is an integer.
|
||
- Stable API versions remain available for all future releases within a Kubernetes major version,
|
||
and there are no current plans for a major version revision of Kubernetes that removes stable APIs.
|
||
-->
|
||
- Stable：
|
||
- 版本名称如 `vX`，其中 `X` 为整数。
|
||
- 特性的 Stable 版本会出现在后续很多版本的发布软件中。
|
||
Stable API 版本仍然适用于 Kubernetes 主要版本范围内的所有后续发布，
|
||
并且 Kubernetes 的主要版本当前没有移除 Stable API 的修订计划。
|
||
|
||
<!--
|
||
## API groups
|
||
-->
|
||
## API 组 {#api-groups}
|
||
|
||
<!--
|
||
[API groups](https://git.k8s.io/design-proposals-archive/api-machinery/api-group.md)
|
||
make it easier to extend the Kubernetes API.
|
||
The API group is specified in a REST path and in the `apiVersion` field of a
|
||
serialized object.
|
||
-->
|
||
[API 组](https://git.k8s.io/design-proposals-archive/api-machinery/api-group.md)能够简化对
|
||
Kubernetes API 的扩展。API 组信息出现在 REST 路径中，也出现在序列化对象的 `apiVersion` 字段中。
|
||
|
||
<!--
|
||
There are several API groups in Kubernetes:
|
||
|
||
* The *core* (also called *legacy*) group is found at REST path `/api/v1`.
|
||
The core group is not specified as part of the `apiVersion` field, for
|
||
example, `apiVersion: v1`.
|
||
* The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use
|
||
`apiVersion: $GROUP_NAME/$VERSION` (for example, `apiVersion: batch/v1`).
|
||
You can find the full list of supported API groups in
|
||
[Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#-strong-api-groups-strong-).
|
||
-->
|
||
以下是 Kubernetes 中的几个组：
|
||
* **核心（core）**（也被称为 **legacy**）组的 REST 路径为 `/api/v1`。
|
||
核心组并不作为 `apiVersion` 字段的一部分，例如， `apiVersion: v1`。
|
||
* 指定的组位于 REST 路径 `/apis/$GROUP_NAME/$VERSION`，
|
||
并且使用 `apiVersion: $GROUP_NAME/$VERSION` （例如，`apiVersion: batch/v1`）。
|
||
你可以在 [Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#-strong-api-groups-strong-)
|
||
中查看全部的 API 组。
|
||
|
||
<!--
|
||
## Enabling or disabling API groups {#enabling-or-disabling}
|
||
|
||
Certain resources and API groups are enabled by default. You can enable or
|
||
disable them by setting `--runtime-config` on the API server. The
|
||
`--runtime-config` flag accepts comma separated `<key>[=<value>]` pairs
|
||
describing the runtime configuration of the API server. If the `=<value>`
|
||
part is omitted, it is treated as if `=true` is specified. For example:
|
||
|
||
- to disable `batch/v1`, set `--runtime-config=batch/v1=false`
|
||
- to enable `batch/v2alpha1`, set `--runtime-config=batch/v2alpha1`
|
||
- to enable a specific version of an API, such as `storage.k8s.io/v1beta1/csistoragecapacities`, set `--runtime-config=storage.k8s.io/v1beta1/csistoragecapacities`
|
||
-->
|
||
## 启用或禁用 API 组 {#enabling-or-disabling}
|
||
|
||
资源和 API 组是在默认情况下被启用的。
|
||
你可以通过在 API 服务器上设置 `--runtime-config` 参数来启用或禁用它们。
|
||
`--runtime-config` 参数接受逗号分隔的 `<key>[=<value>]` 对，
|
||
来描述 API 服务器的运行时配置。如果省略了 `=<value>` 部分，那么视其指定为 `=true`。
|
||
例如：
|
||
|
||
- 禁用 `batch/v1`，对应参数设置 `--runtime-config=batch/v1=false`
|
||
- 启用 `batch/v2alpha1`，对应参数设置 `--runtime-config=batch/v2alpha1`
|
||
- 要启用特定版本的 API，如 `storage.k8s.io/v1beta1/csistoragecapacities`，可以设置
|
||
`--runtime-config=storage.k8s.io/v1beta1/csistoragecapacities`
|
||
|
||
{{< note >}}
|
||
<!--
|
||
When you enable or disable groups or resources, you need to restart the API
|
||
server and controller manager to pick up the `--runtime-config` changes.
|
||
-->
|
||
启用或禁用组或资源时，
|
||
你需要重启 API 服务器和控制器管理器来使 `--runtime-config` 生效。
|
||
{{< /note >}}
|
||
|
||
<!--
|
||
## Persistence
|
||
-->
|
||
## 持久化 {#persistence}
|
||
|
||
<!--
|
||
Kubernetes stores its serialized state in terms of the API resources by writing them into
|
||
{{< glossary_tooltip term_id="etcd" >}}.
|
||
-->
|
||
Kubernetes 通过 API 资源来将序列化的状态写到 {{< glossary_tooltip term_id="etcd" >}} 中存储。
|
||
|
||
## {{% heading "whatsnext" %}}
|
||
|
||
<!--
|
||
- Learn more about [API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
|
||
- Read the design documentation for
|
||
[aggregator](https://git.k8s.io/design-proposals-archive/api-machinery/aggregated-api-servers.md)
|
||
-->
|
||
- 进一步了解 [API 惯例](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
|
||
- 阅读[聚合器](https://git.k8s.io/design-proposals-archive/api-machinery/aggregated-api-servers.md)
|