Alauda Container Platform
  • 简体中文

    • Kubernetes API 使用指南

    目录

    文档设计标准 Kubernetes API 调用模式资源集合单个资源核心 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 调用模式

    Tip

    本节仅提供 Kubernetes API 使用模式的基础介绍。有关 Kubernetes API 的更全面和详细说明，请参阅 官方 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 部分。