#Kubernetes API 使用指南

#文档设计

在 Kubernetes APIs 文档中，我们采取了一个明确的方式，关注资源的模式定义，而不是列出每个资源的具体 API 路径、参数和请求方法。这一设计选择基于以下考虑：

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

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

3. 关注重要内容：对于大多数用户来说，理解资源模式（可用字段及其含义）比 API 调用的 HTTP 机制更为重要。

4. 与工具的兼容性：大多数用户通过 Kubernetes 客户端（如 kubectl、client-go 等）与这些 API 进行交互，而不是直接进行 HTTP 调用，因此 HTTP 细节对日常操作来说不那么重要。

尽管我们的 Kubernetes APIs 文档专注于资源的模式定义，但本指南通过解释 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 APIs 支持多种常见查询参数，可添加到请求 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 文档中提供的模式告诉您可以发送和接收哪些数据，而本指南则解释了如何构建 API 请求。

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