#Kubernetes API 使用指南

#文档设计

在 Kubernetes APIs 文档中，我们有意侧重于资源的 schema 定义，而不是列出每个资源的具体 API 路径、参数和请求方法。此设计选择基于以下考虑：

1. 一致性：所有 Kubernetes API 资源遵循相同的 RESTful API 模式，重复列出每个资源的调用方式显得冗余。

2. 可读性：为每个资源记录完整的 API 细节会导致文档冗长且重复，难以浏览和理解。

3. 关注重点：对大多数用户而言，理解资源的 schema（有哪些字段及其含义）比了解 API 调用的 HTTP 细节更重要。

4. 工具兼容性：大多数用户通过 Kubernetes 客户端（kubectl、client-go 等）与这些 API 交互，而非直接发起 HTTP 请求，因此 HTTP 细节对日常操作的相关性较低。

虽然我们的 Kubernetes APIs 文档聚焦于资源的 schema 定义，本指南则补充说明 Kubernetes API 的通用使用模式和调用规范。在这里，您将学习如何构造 API 请求，理解常见的 HTTP 方法，并了解不同操作的标准 URL 路径——这些信息适用于所有 Kubernetes 资源。

#标准 Kubernetes API 调用模式

所有 Kubernetes API 资源均支持一组遵循 RESTful 规范的标准操作。以下是适用于我们 Kubernetes APIs 文档中所有资源的常见 API 调用模式：

#资源集合

针对资源集合（如 Pods、Deployments 等）：

操作	HTTP 方法	路径	描述
列出所有资源	GET	/apis/{group}/{version}/namespaces/{namespace}/{resource}	返回指定命名空间中的资源列表
列出所有资源（集群范围）	GET	/apis/{group}/{version}/{resource}	返回所有命名空间中的资源列表（适用于支持集群范围的资源）
创建资源	POST	/apis/{group}/{version}/namespaces/{namespace}/{resource}	在指定命名空间中创建新资源
创建资源（集群范围）	POST	/apis/{group}/{version}/{resource}	创建新的集群范围资源（适用于支持集群范围的资源）

#单个资源

针对单个资源实例：

操作	HTTP 方法	路径	描述
获取资源	GET	/apis/{group}/{version}/namespaces/{namespace}/{resource}/{name}	返回指定资源的详细信息
获取资源（集群范围）	GET	/apis/{group}/{version}/{resource}/{name}	返回指定集群范围资源的详细信息
更新资源	PUT	/apis/{group}/{version}/namespaces/{namespace}/{resource}/{name}	使用提供的定义替换整个资源
更新资源（集群范围）	PUT	/apis/{group}/{version}/{resource}/{name}	使用提供的定义替换整个集群范围资源
部分更新资源	PATCH	/apis/{group}/{version}/namespaces/{namespace}/{resource}/{name}	更新资源的特定字段
部分更新资源（集群范围）	PATCH	/apis/{group}/{version}/{resource}/{name}	更新集群范围资源的特定字段
删除资源	DELETE	/apis/{group}/{version}/namespaces/{namespace}/{resource}/{name}	删除指定资源
删除资源（集群范围）	DELETE	/apis/{group}/{version}/{resource}/{name}	删除指定集群范围资源

#核心 API 组

对于核心 API 组（v1）中的资源，路径略有不同：

操作	HTTP 方法	路径	描述
列出所有资源	GET	/api/v1/namespaces/{namespace}/{resource}	返回指定命名空间中的核心资源列表
获取资源	GET	/api/v1/namespaces/{namespace}/{resource}/{name}	返回指定核心资源的详细信息

#常用查询参数

Kubernetes API 支持多种常用查询参数，可添加到请求 URL 中：

参数	描述	示例
pretty=true	以更易读的格式返回响应	/api/v1/namespaces/default/pods?pretty=true
labelSelector	根据标签过滤资源	/api/v1/namespaces/default/pods?labelSelector=app=nginx
fieldSelector	根据字段值过滤资源	/api/v1/namespaces/default/pods?fieldSelector=status.phase=Running
watch=true	启动监视连接以监听变化	/api/v1/namespaces/default/pods?watch=true
resourceVersion	指定从哪个版本开始监视	/api/v1/namespaces/default/pods?watch=true&resourceVersion=12345
limit	限制返回结果的数量	/api/v1/namespaces/default/pods?limit=50
continue	用于继续之前列表请求的令牌	/api/v1/namespaces/default/pods?continue=eyJ2IjoibWV0Y...

#结论

通过遵循本文档描述的标准 Kubernetes API 模式，您可以与我们 Kubernetes APIs 部分记录的任何资源进行交互。API 文档中提供的 schema 告诉您可以发送和接收哪些数据，而本指南则说明如何构造 API 请求。

有关特定资源 schema 的详细信息，请参阅 Kubernetes APIs 部分。