title: 【AI 总结】Kubernetes API
categories:
- K8s
date: 2026-01-08 14:36:14
tags:
- K8s
- API
index_img:
banner_img:

Kubernetes API | AI 总结

一、核心定位与作用

Kubernetes 控制面的核心是API 服务器（kube-apiserver），其通过暴露 HTTP API 实现多主体间通信，具体功能包括：

1. 支持查询和操纵 Kubernetes 中的 API 对象（如 Pod、Namespace、ConfigMap、Event 等）状态。
2. 是 kubectl、kubeadm 等命令行工具的底层依赖（工具背后均调用 API），同时也支持通过 REST 调用直接访问。
3. 为开发者提供客户端库，便于编写基于 Kubernetes API 的应用。

{% fold danger @ kubectl 和 kubeadm 是什么 %}

在 Kubernetes（K8s）生态系统中，kubectl 和 kubeadm 是两个最核心的命令行工具，它们的作用如下：

1. kubectl (Kubernetes Command-Line Tool)

它是 Kubernetes 的日常操作工具，也是开发者和管理员最常用的工具。

• 用途：用于与 Kubernetes 集群进行交互。你可以用它来部署应用、查看资源（如 Pods、Nodes、Services）、查看日志、监控集群状态等。
• 原理：正如你代码中所写的，kubectl 本质上是一个 REST API 客户端。当你输入一个命令（如 kubectl get pods）时，它会将该命令转换成对 Kubernetes API Server 的 HTTP 调用。
• 类比：如果把 Kubernetes 比作一个操作系统，kubectl 就像是它的终端（Terminal）或 Shell。

2. kubeadm (Kubernetes Admin)

它是 Kubernetes 的集群生命周期管理工具。

• 用途：专门用于搭建（初始化）和管理 Kubernetes 集群。它简化了复杂的安装过程，通过标准化的步骤来创建符合最佳实践的集群。
• 常用命令：
  • kubeadm init：用于初始化一个 Master 节点（控制平面）。
  • kubeadm join：用于将 Worker 节点加入到现有的集群中。
  • kubeadm upgrade：用于升级集群版本。
• 类比：kubeadm 就像是操作系统的安装向导或系统的初始化脚本。

总结两者的区别：kubeadm 是用来盖房子的（创建和设置集群）。kubectl 是用来在房子里生活的（在集群里部署和管理应用）。

{% endfold %}

二、API 规范发布机制

Kubernetes 提供两种机制发布 API 规范，均用于实现自动互操作（如 kubectl 的命令行补全功能），具体对比如下：

{% fold danger @ 为什么要提供两种机制 %}

在 Kubernetes 中提供 Discovery API（发现 API） 和 OpenAPI 规范 这两种机制，主要是为了在性能效率、使用场景以及信息详情之间取得平衡。

具体原因可以归纳为以下几点：

1. 性能与体积的权衡 (Efficiency vs. Size)

• Discovery API 极其轻量：它只包含资源的概要信息（如 API 组、版本、资源名称及支持的操作等），不包含复杂的字段定义（Schema）。这使得 kubectl 等工具可以极快地下载并探测集群支持哪些资源，从而实现命令补全和基础路由。
• OpenAPI 规范体积庞大：Kubernetes 的全量 OpenAPI 文档通常有几十 MB。如果每次工具（如 kubectl）只是想知道集群里有没有 Deployment 资源，都要下载完整的规范，会对网络和内存造成巨大负担。

2. 使用场景的不同 (Different Use Cases)

• Discovery API 用于“动态发现”：主要面向通用的命令行工具或简单的客户端。解决“我能在这个集群里干什么？”的问题。支持聚合发现（Aggregated Discovery），可以一次性获取全量资源列表。
• OpenAPI 用于“结构化交互”：主要面向代码生成器（Client-gen）、深度验证工具或文档系统。解决“这个资源的每个字段是什么类型？有哪些验证规则？”的问题。它是行业标准，方便与外部生态系统（如 Swagger UI）对接。

3. 引导过程的需要 (Bootstrapping)

客户端通常需要一个“两步走”的过程：

• 第一步：通过 Discovery API 快速发现集群支持哪些 API 组和版本。
• 第二步：如果需要对某个特定资源进行强类型检查或代码生成，再根据发现的结果，去请求对应版本的 OpenAPI 详细定义（如 /openapi/v3/apis//）。

简单来说，Discovery API 是“导游图”（告诉你哪有景点，很快就能看完），而 OpenAPI 是“建筑图纸”（告诉你每个景点的砖头是怎么砌的，内容极其详细）。对于大多数日常操作，看一眼“导游图”就够了；只有在需要精确施工（如开发插件或生成代码）时，才需要查阅“建筑图纸”。

{% endfold %}

1. Discovery API 详解

（1）聚合的发现（Beta 阶段，需通过 AggregatedDiscoveryEndpoint 特性门控启用）

• 核心端点：/api 和 /apis，可一次性获取集群所有支持的资源，减少请求数量。
• 调用方式：需在请求头中添加 Accept: application/json;v=v2beta1;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList，否则默认返回非聚合文档。
• 额外特性：支持 ETag 和 protobuf 编码，内置资源的聚合发现文档可在 Kubernetes GitHub 仓库查询。

（2）非聚合的发现

• 根端点：/api 和 /apis，仅返回集群支持的所有组版本列表（示例含 apiregistration.k8s.io/v1、apps/v1 等）。
• 资源详情获取：需额外请求 /apis/<group>/<version>（如 /apis/rbac.authorization.k8s.io/v1alpha1），kubectl 依赖此方式获取资源列表。

{% fold danger @ 什么是聚合和非聚合 %}

在 Kubernetes API 的语境下，“聚合”（Aggregated）和“非聚合”（Non-aggregated）主要出现在 Discovery API（发现 API） 和 API 扩展机制这两个场景中。

1. Discovery API（发现 API）中的聚合与非聚合

这是 kubectl 等客户端用来了解集群支持哪些资源（如 Pod, Deployment 等）的机制。

• 非聚合的发现 (Non-aggregated Discovery)
  • 工作方式：它是分级查询的。你先访问 /api 或 /apis 获取所有“API 组版本”列表（如 apps/v1、v1），然后需要再次发起额外的请求（如 /apis/apps/v1）才能看到该版本下具体的资源列表。
  • 缺点：如果集群资源很多，客户端需要发送大量 HTTP 请求才能获取完整的资源图谱。
• 聚合的发现 (Aggregated Discovery)
  • 工作方式：通过在请求头中加入特定的 Accept 参数，API Server 会一次性返回集群中所有支持的资源列表。
  • 优点：大幅减少了网络请求次数，提高了 kubectl 等工具的启动和响应速度。这是 Kubernetes 的一个较新的特性（Beta 阶段）。

2. API Server 的聚合层 (Aggregation Layer)

这是 Kubernetes 的一种架构模式，用于扩展 API。

• 非聚合（内置 API / CRD）
  标准的 API（如 Pod）或通过 CRD（Custom Resource Definition）定义的资源。它们直接由 Kubernetes 核心 API Server 处理，数据存储在 etcd 中。

• 聚合层 (Aggregation Layer / API Aggregation)

  • 含义：允许你运行一个自定义的 API Server（称为 Extension API Server），并将其“挂载”到主 API Server 的路径下。
  • 效果：对于用户来说，通过主 API Server 的统一入口就能访问到你的自定义 API，主 API Server 负责将请求转发（代理）给你的自定义 API Server。
  • 应用场景：当你需要比 CRD 更复杂的逻辑（如自定义存储、高性能要求或特殊的 API 行为）时，会使用这种方式。例如 Metrics Server 就是通过聚合层提供指标数据的。

总结

• 发现 API 的“聚合”：关注的是获取信息的效率（一次性拿走 vs 分次拿走）。
• 架构上的“聚合层”：关注的是功能的扩展性（将多个独立的 API Server 逻辑上合并为一个整体入口）。

{% endfold %}

2. OpenAPI 接口定义详解

（1）OpenAPI v2

• 核心端点：/openapi/v2（聚合式规范）。
• 支持请求头：

  头部	可选值	说明
  Accept-Encoding	gzip	不指定也可正常响应
  Accept	application/com.github.proto-openapi.spec.v2@v1.0+protobuf（集群内部用）、application/json（默认）、*（返回 application/json）	-

• 注意事项：发布的校验规则不完整，精确验证需使用 kubectl apply --dry-run=server（触发所有校验及准入检查）。

（2）OpenAPI v3（需通过 OpenAPIV3 特性门控启用，为首选方式）

• 发现端点：/openapi/v3，仅返回 JSON 格式的组版本列表（含各版本对应的 serverRelativeURL）。
• 规范获取端点：/openapi/v3/apis/<group>/<version>?hash=<hash>，URL 不可变且支持缓存（Expires 设为未来 1 年，Cache-Control 为 immutable），过时 URL 会重定向到最新地址。
• 支持请求头：与 OpenAPI v2 类似，Accept 支持 protobuf 格式（集群内部）、JSON（默认）等。
• 工具支持：Golang 可通过 k8s.io/client-go/openapi3 包获取规范，当前无支持 OpenAPI v3.1 的计划。

（3）Protobuf 序列化

• 用途：主要用于 Kubernetes 集群内部通信。
• 相关资源：序列化格式细节参考 Kubernetes Protobuf 序列化设计提案，接口描述语言（IDL）位于定义 API 对象的 Go 包中。

三、持久化机制

Kubernetes 将 API 对象的序列化状态存储在 etcd（集群的键值存储系统）中，实现数据持久化。

四、API 组与版本控制

1. 核心设计思路

• 版本控制粒度：在 API 级别（而非资源/字段级别），确保 API 视图一致，便于控制废弃/实验性 API 访问。
• API 组作用：支持 API 演进与扩展，可按需启用/禁用，资源通过“API 组 + 资源类型 + 名字空间（命名空间作用域资源）+ 名称”唯一标识。
• 版本转换：API 服务器自动处理不同版本间的转换，底层持久化数据相同（如 v1beta1 创建的对象，可通过 v1 版本读写，直到 v1beta1 被废弃）。

2. API 变更规则

五、API 扩展方式

1. 自定义资源（Custom Resource）：通过声明式方式定义 API 服务器如何提供自定义资源的 API。
2. 聚合层（Aggregation Layer）：自行实现聚合层，扩展 Kubernetes API 功能。