Kubernetes API Group

理解 Kubernetes API Group（API 组），关键是先理解 为什么 Kubernetes 要把 API 分类。

一句话概括：

API Group 就是 Kubernetes 按照资源功能划分的一组 API，每个 Group 管理一类资源。

1. 为什么需要 API Group？

假设 Kubernetes 没有 API Group。

所有资源都会放在一个地方：

/api/v1/pods
/api/v1/services
/api/v1/deployments
/api/v1/jobs
/api/v1/cronjobs
/api/v1/ingresses
/api/v1/networkpolicies
/api/v1/hpas
...

随着 Kubernetes 功能越来越多，会出现几个问题：

• API 数量庞大

• 不同模块耦合

• 无法独立演进版本

• 第三方扩展困难

因此 Kubernetes 引入了 API Group。

2. API Group 长什么样？

Kubernetes 的 API URL 一般有两种形式：

3. Core API（没有 Group）

/api/v1

例如：

GET /api/v1/pods
GET /api/v1/services
GET /api/v1/nodes

这些资源属于 Core Group。

4. Named API Group（有 Group）

格式：

/apis/<group>/<version>

例如：

/apis/apps/v1
/apis/batch/v1
/apis/networking.k8s.io/v1

例如 Deployment：

GET /apis/apps/v1/deployments

可以看到：

apis
   │
 apps
   │
  v1

5. Kubernetes API 的整体结构

可以把 Kubernetes API 想象成这样：

Kubernetes API
│
├── Core API
│      │
│      ├── Pod
│      ├── Service
│      ├── ConfigMap
│      ├── Secret
│      └── Namespace
│
├── apps
│      │
│      ├── Deployment
│      ├── StatefulSet
│      ├── DaemonSet
│      └── ReplicaSet
│
├── batch
│      │
│      ├── Job
│      └── CronJob
│
├── autoscaling
│      │
│      └── HPA
│
├── networking.k8s.io
│      │
│      ├── Ingress
│      └── NetworkPolicy
│
├── rbac.authorization.k8s.io
│      │
│      ├── Role
│      ├── ClusterRole
│      └── RoleBinding
│
└── storage.k8s.io
       │
       ├── StorageClass
       └── CSI

可以发现：

每一个 Group 管理一类资源。

6. 常见 API Group

下面是运维最常接触的几个 API Group：

7. YAML 中如何体现 API Group？

例如 Deployment：

apiVersion: apps/v1
kind: Deployment

这里：

apps/v1
│     │
│     └── Version
│
└──────── API Group

再例如：

apiVersion: batch/v1
kind: Job

表示：

Group

batch

↓

Version

v1

Pod：

apiVersion: v1
kind: Pod

为什么没有：

core/v1

因为：

Core Group 是特殊的，默认省略 group 名称。

实际上：

apiVersion: v1

等价于：

Core Group
Version=v1

8. Python SDK 与 API Group 的对应关系

Python SDK 中，不同的 API Group 对应不同的 API 类。

例如：

from kubernetes import client

core = client.CoreV1Api()
apps = client.AppsV1Api()
batch = client.BatchV1Api()

对应关系如下：

例如：

apps = client.AppsV1Api()

deploys = apps.list_namespaced_deployment("default")

实际上 SDK 会调用：

GET /apis/apps/v1/namespaces/default/deployments

9. kubectl 如何利用 API Group？

例如：

kubectl get deployment

kubectl 会知道：

Deployment

↓

apps/v1

↓

GET /apis/apps/v1/deployments

而：

kubectl get pod

则会调用：

GET /api/v1/pods

10. 自定义 API Group（CRD）

API Group 不仅是 Kubernetes 官方使用，你自己也可以创建。

例如编写一个 MySQL Operator，希望用户可以这样写：

apiVersion: database.example.com/v1
kind: MySQL
metadata:
  name: mysql-prod

这里：

database.example.com

就是你定义的 API Group。

Kubernetes 安装对应的 CRD 后，就会新增一个 API：

/apis/database.example.com/v1/mysqls

这也是为什么很多 Operator 都有自己的 API Group，例如：

apiVersion: monitoring.coreos.com/v1
kind: Prometheus

其中：

monitoring.coreos.com

就是由 Prometheus Operator 提供的 API Group。

11. 如何查看集群支持哪些 API Group？

可以使用：

kubectl api-resources

示例输出：

NAME           SHORTNAMES   APIVERSION
pods           po           v1
services       svc          v1
deployments    deploy       apps/v1
jobs                        batch/v1
ingresses      ing          networking.k8s.io/v1

如果想查看所有 API Group 和版本：

kubectl api-versions

示例：

v1
apps/v1
batch/v1
autoscaling/v2
networking.k8s.io/v1
rbac.authorization.k8s.io/v1
storage.k8s.io/v1

12. 总结

可以把 Kubernetes API 想象成一个大型图书馆：

• API Server 是图书馆。

• API Group 是不同的书架（如“应用”“网络”“存储”“权限”）。

• Version（v1、v2…） 是书架上同一类书的不同版本。

• Resource（Pod、Deployment、Job） 是具体的书。

因此，一个完整的 Kubernetes API 通常可以表示为：

API Server
    ↓
API Group（如 apps）
    ↓
Version（如 v1）
    ↓
Resource（如 deployments）

最终形成类似：

GET /apis/apps/v1/namespaces/default/deployments

而 Python SDK 中的 AppsV1Api()、BatchV1Api()、CoreV1Api() 等类，本质上就是对这些不同 API Group 的封装，每个类负责调用对应 Group 下的资源接口。