website/content/zh/docs/reference/using-api/api-overview.md

title, reviewers, content_template, weight, card

title	reviewers	content_template	weight	card
Kubernetes API 总览	erictune lavalamp jbeda	templates/concept	10	name weight title reference 50 API 总览

{{% capture overview %}}

此页提供 Kubernetes API 的总览

{{% /capture %}}

{{% capture body %}}

REST API 是 Kubernetes 的基础架构。组件之间的所有操作和通信，以及外部用户命令都是 API Server 处理的 REST API 调用。因此，Kubernetes 平台中的所有资源被视为 API 对象，并且在 [API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/) 中都有对应的定义项。

大多数操作可以通过 kubectl 命令行界面或其他命令行工具执行，例如 kubeadm，它们本身也使用 API。但是，您也可以使用 REST 调用直接访问 API。

如果您正在使用 Kubernetes API 编写应用程序，请考虑使用 客户端库。

API 版本控制

为了消除字段或重组资源表示形式，Kubernetes 支持多个 API 版本，每个版本在不同的 API 路径下。例如：/api/v1 或者 /apis/extensions/v1beta1。

版本是在 API 级别而非资源或字段级别配置的：

• 确保 API 呈现出清晰一致的系统资源和行为视图。
• 允许控制对已寿终正寝的 API 和/或实验性 API 的访问。

JSON 和 Protobuf 序列化模式在出现模式变更时均遵循这些准则。以下说明同时适用于这两种格式。

{{< note >}}

API 版本和软件版本是间接相关的。API 和发布版本建议 描述了 API 版本和软件版本之间的关系。

{{< /note >}}

不同的 API 版本表示不同级别的稳定性和支持级别。您可以在 API 变更文档 中找到有关每个级别的条件的更多信息。

以下是每个级别的摘要：

• Alpha：

  • 版本名称包含 alpha（例如，v1alpha1）。
  • 该软件可能包含错误。启用功能可能会暴露错误。默认情况下，功能可能被禁用。
  • 对功能的支持随时可能被删除，但不另行通知。
  • 在以后的软件版本中，API 可能会以不兼容的方式更改，亦不另行通知。
  • 由于存在更高的错误风险和缺乏长期支持，建议仅在短期测试集群中使用该软件。

• Beta：

  • 版本名称包含beta（例如，v2beta3）。
  • 该软件已经过充分测试。启用功能被认为是安全的。默认情况下启用功能。
  • 尽管细节可能会发生变更，对应功能不会被废弃。
  • 在随后的 Beta 或稳定版本中，对象的模式和/或语义可能会以不兼容的方式更改。发生这种情况时，将提供迁移说明。迁移时可能需要删除、编辑和重新创建 API 对象。编辑过程可能需要一些思考。对于依赖该功能的应用程序，可能需要停机。
  • 该软件仅建议用于非关键业务用途，因为在后续版本中可能会发生不兼容的更改。如果您有多个可以独立升级的群集，则可以放宽此限制。

{{< note >}}

请试用 Beta 版功能并提供反馈。功能结束 Beta 版之后，再进行变更可能是不切实际的。

{{< /note >}}

• 稳定版：
  • 版本名称为 vX，其中X为整数。
  • 功能特性的稳定版本会持续出现在许多后续版本的发行软件中。

API 组

API 组 使扩展 Kubernetes API 更容易。API 组在 REST 路径和序列化对象的 apiVersion 字段中指定。

当前，有几个正在使用的 API 组：

• core（也称为 legacy）组，它位于 REST 路径/api/v1上，未指定为 apiVersion 字段的一部分，例如apiVersion: v1。
• 特定名称的组位于 REST 路径/apis/$GROUP_NAME/$VERSION下，并使用apiVersion:$GROUP_NAME/$VERSION（例如，apiVersion:batch/v1）。您可以在 Kubernetes API 参考 中找到受支持的 API Group 的完整列表。

有两种途径来使用 自定义资源 扩展 API，分别是：

• CustomResourceDefinition 提供基本的 CRUD 需求。
• 聚合器（Aggregator）具有完整的 Kubernetes API 语义，用以实现用户自己的 apiserver。

启用 API 组

默认情况下，某些资源和 API 组处于启用状态。您可以通过设置--runtime-config来启用或禁用它们。 --runtime-config 接受逗号分隔的值。例如：

• 要禁用 batch/v1，请配置--runtime-config=batch/v1=false
• 要启用 batch/2alpha1，请配置--runtime-config=batch/v2alpha1 该标志接受描述 apiserver 的运行时配置的以逗号分隔的key=value 对集合。

{{< note >}}

启用或禁用组或资源时，需要重新启动 apiserver 和控制器管理器以刷新 --runtime-config 的更改。

{{< /note >}}

启用组中的资源

默认情况下 DaemonSet、Deployment、Horizo​​ntalPodAutoscalers、Ingress、Jobs 和 ReplicaSets 是被启用的。 您可以通过在 apiserver 上设置--runtime-config来启用其他扩展资源。--runtime-config接受逗号分隔的值。 例如，要禁用 Deployments 和 Jobs，请设置 --runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/jobs=false

{{% /capture %}}