API 概述
本节提供 Kubernetes API 的参考信息。
REST API 是 Kubernetes 的基本结构。组件之间的所有操作和通信,以及外部用户命令都是 API 服务器处理的 REST API 调用。 因此,Kubernetes 平台中的所有内容都被视为 API 对象,并在 API 中有相应的条目。
Kubernetes API 参考 列出了 Kubernetes v1.32 版本的 API。
有关一般背景信息,请阅读 Kubernetes API。 控制对 Kubernetes API 的访问 描述了客户端如何向 Kubernetes API 服务器进行身份验证,以及如何授权其请求。
API 版本控制
JSON 和 Protobuf 序列化模式遵循相同的模式更改指南。以下描述涵盖两种格式。
API 版本控制和软件版本控制间接相关。 API 和发布版本控制提案 描述了 API 版本控制和软件版本控制之间的关系。
不同的 API 版本表示不同的稳定性和支持级别。 您可以在API 更改文档中找到有关每个级别标准的更多信息。
以下是每个级别的摘要
Alpha
- 版本名称包含
alpha
(例如,v1alpha1
)。 - 默认情况下,内置的 alpha API 版本处于禁用状态,必须在
kube-apiserver
配置中显式启用才能使用。 - 该软件可能包含错误。 启用某项功能可能会暴露错误。
- 对 alpha API 的支持可能随时被取消,恕不另行通知。
- API 可能会在后续软件版本中以不兼容的方式更改,恕不另行通知。
- 由于错误风险增加和缺乏长期支持,建议仅在短期测试集群中使用该软件。
- 版本名称包含
Beta
版本名称包含
beta
(例如,v2beta3
)。默认情况下,内置的 beta API 版本处于禁用状态,必须在
kube-apiserver
配置中显式启用才能使用(除非在 Kubernetes 1.22 之前引入的 API 的 beta 版本,这些版本默认启用)。从引入到弃用,内置的 beta API 版本的最大生命周期为 9 个月或 3 个小版本(以较长者为准),从弃用到删除为 9 个月或 3 个小版本(以较长者为准)。
该软件经过充分测试。 启用某项功能被认为是安全的。
对某项功能的支持不会被取消,但细节可能会更改。
对象的架构和/或语义可能会在后续的 beta 或稳定 API 版本中以不兼容的方式更改。 当发生这种情况时,会提供迁移说明。 适应后续的 beta 或稳定 API 版本可能需要编辑或重新创建 API 对象,并且可能不简单。 迁移可能需要依赖该功能的应用程序停机。
不建议将该软件用于生产用途。 后续版本可能会引入不兼容的更改。 一旦 beta API 版本被弃用且不再提供服务,则需要使用 beta API 版本才能过渡到后续的 beta 或稳定 API 版本。
注意
请尝试使用 beta 功能并提供反馈。 在功能退出 beta 阶段后,再进行更多更改可能不切实际。稳定版
- 版本名称为
vX
,其中X
为整数。 - 在 Kubernetes 主要版本中的所有未来版本中,稳定版 API 版本将保持可用,并且目前没有计划对 Kubernetes 进行主要版本修订以删除稳定版 API。
- 版本名称为
API 组
API 组 使扩展 Kubernetes API 更加容易。 API 组在 REST 路径和序列化对象的 apiVersion
字段中指定。
Kubernetes 中有几个 API 组
- 核心(也称为旧版)组位于 REST 路径
/api/v1
。 核心组未指定为apiVersion
字段的一部分,例如,apiVersion: v1
。 - 命名组位于 REST 路径
/apis/$GROUP_NAME/$VERSION
,并使用apiVersion: $GROUP_NAME/$VERSION
(例如,apiVersion: batch/v1
)。 您可以在 Kubernetes API 参考 中找到受支持的 API 组的完整列表。
启用或禁用 API 组
默认情况下启用某些资源和 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
注意
当您启用或禁用组或资源时,需要重新启动 API 服务器和控制器管理器才能获取--runtime-config
更改。持久化
Kubernetes 通过将 API 资源写入 etcd 来存储其 API 资源的序列化状态。