apiserver中api的层级与完整构成

一、API 整体层级（5 层结构）

K8s API 的设计遵循API Group → API Version → Resource → Namespace → Resource Name。

1. 第一层：API Group（分组）

• Core Group（核心 / 遗留组）

  • 无显式 Group 名（空组）
  • 路径：/api/v1
  • apiVersion：v1（不写 group）
  • 包含：Pod、Service、ConfigMap、Secret、Namespace、Node、Event 等

• Named Groups（命名组 / 扩展组）

  • 格式：group/version
  • 路径：/apis/<group>/<version>
  • apiVersion：<group>/<version>
  • 示例：
    • apps/v1（Deployment、StatefulSet、DaemonSet）
    • batch/v1（Job、CronJob）
    • networking.k8s.io/v1（Ingress、NetworkPolicy）
    • rbac.authorization.k8s.io/v1（Role、ClusterRole）

2. 第二层：API Version（版本）

版本控制在API 级别（非字段级别）Kubernetes，分为三类：

• GA（v1）：正式稳定，永不破坏性变更
• Beta（v1beta1）：稳定但可能调整，数据兼容
• Alpha（v1alpha1）：实验性，无兼容性保证

3. 第三层：Resource（资源类型）

• 每个 Group+Version 下定义一组资源（Kind）
• 示例：apps/v1 → Deployment、ReplicaSet、StatefulSet、DaemonSet

4. 第四层：Namespace（命名空间）

• 命名空间资源：需要指定 namespace（如 Pod、Deployment）
• 集群级资源：无 namespace（如 Node、Namespace、ClusterRole）

5. 第五层：Resource Name（资源名称）

• 资源的唯一标识（同一 namespace 内唯一）

二、完整 API 路径（两种格式）

1. Core Group（/api/v1）

• 命名空间资源：

  /api/v1/namespaces/<ns>/<resource>/<name>#例：
  /api/v1/namespaces/default/pods/my-pod
  

• 集群级资源：

  /api/v1/<resource>/<name>#例：
  /api/v1/nodes/node-1
  

2. Named Group（/apis/<group>/<version>）

• 命名空间资源：

  /apis/<group>/<version>/namespaces/<ns>/<resource>/<name>#例：
  /apis/apps/v1/namespaces/default/deployments/my-deploy
  

• 集群级资源：

  /apis/<group>/<version>/<resource>/<name>#例：
  /apis/rbac.authorization.k8s.io/v1/clusterroles/admin
  

三、核心 API 分组

1. Core（v1）

• /api/v1
• 资源：Pod、Service、ConfigMap、Secret、Namespace、Node、Event、PersistentVolume、PersistentVolumeClaim

2. apps/v1（工作负载）

• /apis/apps/v1
• Deployment、ReplicaSet、StatefulSet、DaemonSet

3. batch/v1（批处理）

• /apis/batch/v1
• Job、CronJob

4. networking.k8s.io/v1（网络）

• /apis/networking.k8s.io/v1
• Ingress、NetworkPolicy、Service（部分）

5. rbac.authorization.k8s.io/v1（权限）

• /apis/rbac.authorization.k8s.io/v1
• Role、ClusterRole、RoleBinding、ClusterRoleBinding

6. storage.k8s.io/v1（存储）

• /apis/storage.k8s.io/v1
• StorageClass、CSIDriver、CSINode

7. apiextensions.k8s.io/v1（CRD）

• /apis/apiextensions.k8s.io/v1
• CustomResourceDefinition（CRD）

四、API 构成：从请求到存储（完整链路）

1. 请求入口

• kubectl → HTTP → APIServer（8080/6443）

2. 认证（AuthN）

• 证书、Token、ServiceAccount、OIDC

3. 授权（AuthZ）

• RBAC（最常用）、ABAC、Node、Webhook

4. 准入控制（Admission）

• 验证（Validating）、修改（Mutating）

5. 版本转换（Conversion）

• 透明转换：v1beta1 ↔ v1

6. 资源存储（RESTStorage）

• 每个资源对应 RESTStorage（CRUD 实现）

7. 持久化（etcd）

• APIServer 是 etcd 唯一写入入口

8. Watch 机制

• 客户端监听资源变化（控制器、kubelet）

常用命令

# 查看所有 API 版本
kubectl api-versions# 查看指定 Group 资源
kubectl api-resources --api-group=apps# 查看资源的完整 API 路径
kubectl explain deployment --api-version=apps/v1# 直接调用 API（curl）
curl -k https://127.0.0.1:6443/apis/apps/v1/deployments -H "Authorization: Bearer $TOKEN"