Kubernetes API 概述：API 组、API 版本、资源类型、动词与操作映射
Kubernetes 的所有功能都通过 API 暴露。理解 API 的组织结构是掌握 RBAC 权限控制的前提——因为权限策略本质上就是定义“谁”可以对“哪些 API 资源”执行“哪些操作”。本章将系统梳理 API 组、版本、资源类型及动词体系，并建立它们与 RBAC 权限规则的映射关系。
1. API 组（API Group）与 API 版本
Kubernetes API 按功能领域划分为多个 API 组，每个组内包含一组相关的资源类型。API 组通过 URL 路径中的 /apis/<group>/<version> 区分，核心组（Core Group）则直接位于 /api/v1 下。
| API 组 | 路径示例 | 包含资源（部分） | 说明 |
|---|---|---|---|
| Core（核心组） | /api/v1 |
Pod, Service, ConfigMap, Secret, Node, Namespace | 最基础、最常用的资源，无 group 名称 |
| apps | /apis/apps/v1 |
Deployment, StatefulSet, DaemonSet, ReplicaSet | 工作负载管理 |
| batch | /apis/batch/v1 |
Job, CronJob | 批处理与定时任务 |
| networking.k8s.io | /apis/networking.k8s.io/v1 |
Ingress, NetworkPolicy | 网络策略与入站流量 |
| rbac.authorization.k8s.io | /apis/rbac.authorization.k8s.io/v1 |
Role, ClusterRole, RoleBinding, ClusterRoleBinding | RBAC 权限控制自身 |
| autoscaling | /apis/autoscaling/v2 |
HorizontalPodAutoscaler | 自动扩缩容 |
每个 API 组可以包含多个 版本（如 v1、v1beta1、v2），版本标识了资源的稳定性和演进阶段：
- Alpha（v1alpha1）：默认关闭，可能包含缺陷，随时可能变更。
- Beta（v1beta1）：默认开启，经过测试，但语义可能微调。
- Stable（v1）：生产就绪，长期支持。
apiGroups 字段必须与资源所属的 API 组精确匹配。核心组资源使用空字符串 "" 表示，而非 "core" 或 "v1"。
2. 资源类型（Resource Types）与子资源
资源类型是 Kubernetes API 中的核心操作对象。每个资源类型对应一组 RESTful 端点，例如 pods、deployments、services。在 RBAC 中，resources 字段指定目标资源类型。
除了主资源外，Kubernetes 还定义了 子资源（Subresource），用于访问资源的特定方面。常见的子资源包括：
| 主资源 | 子资源 | 用途 | RBAC 写法 |
|---|---|---|---|
| pods | log | 获取 Pod 日志 | pods/log |
| pods | exec | 进入 Pod 执行命令 | pods/exec |
| pods | status | 读取/更新 Pod 状态 | pods/status |
| deployments | scale | 手动扩缩副本数 | deployments/scale |
| nodes | proxy | 通过代理访问节点 | nodes/proxy |
资源/子资源 格式（如 pods/log），不能只写 pods 然后期望自动包含子资源。主资源权限与子资源权限是独立的。
3. 动词（Verbs）与 HTTP 方法映射
RBAC 中的 动词（Verb） 对应 Kubernetes API 的 HTTP 方法。每个动词映射到一个或多个 RESTful 操作。理解这个映射是编写精确权限策略的基础。
| RBAC 动词 | HTTP 方法 | 对应操作 | 说明 |
|---|---|---|---|
get |
GET | 获取单个资源 | 读取特定名称的资源详情 |
list |
GET | 获取资源列表 | 读取某类型所有资源（通常需要 list 和 watch 配合） |
watch |
GET | 监听资源变更 | 建立长连接，实时推送变更事件 |
create |
POST | 创建新资源 | 提交资源定义到 API Server |
update |
PUT | 全量更新资源 | 替换整个资源对象 |
patch |
PATCH | 部分更新资源 | 仅修改指定字段（JSON Patch / Merge Patch） |
delete |
DELETE | 删除单个资源 | 立即删除或优雅删除 |
deletecollection |
DELETE | 批量删除资源 | 按标签选择器删除多个资源 |
verbs 字段的值。一个规则可以包含多个动词，例如 ["get", "list", "watch"] 赋予只读权限。注意 list 和 watch 虽然都是 GET 请求，但作用域不同——list 返回当前快照，watch 持续推送变更。
4. 动词、资源与 API 组的映射关系图
下图展示了 RBAC 策略中 apiGroups、resources、verbs 三个核心字段如何组合，形成一条完整的权限规则，并映射到具体的 API 请求路径。
5. 核心动词组合模式
在实际 RBAC 配置中，某些动词组合频繁出现，形成了典型的权限模式。下表总结了最常见的组合及其适用场景：
| 权限模式 | 动词组合 | 适用场景 | 示例 |
|---|---|---|---|
| 只读 | get, list, watch |
监控、审计、只读查看器 | 开发人员查看 Pod 状态 |
| 读写（不含删除） | get, list, watch, create, update, patch |
应用运维、CI/CD 系统 | 部署工具创建和更新 Deployment |
| 完全控制 | get, list, watch, create, update, patch, delete |
集群管理员、命名空间管理员 | 管理员管理命名空间内所有资源 |
| 仅创建 | create |
事件发布器、日志收集器 | 只允许创建 Event 资源 |
| 仅删除 | delete, deletecollection |
清理任务、垃圾回收 | 定时清理过期 Job |
6. 特殊动词与操作
除了标准 CRUD 动词，Kubernetes 还支持一些特殊动词，用于非资源请求或跨资源操作：
*（通配符）：表示所有动词。在verbs字段中使用["*"]表示允许对该资源的所有操作。谨慎使用。impersonate：允许一个用户模拟另一个用户或组。用于授权代理或审计系统。对应/apis/authentication.k8s.io/v1/tokenreviews等端点。bind：允许绑定特定 ClusterRole（用于 ClusterRoleBinding 的 subjects）。仅适用于clusterroles资源。escalate：允许创建或更新权限高于自身已有权限的 Role/ClusterRole。用于权限委派场景。
impersonate、bind、escalate 是高风险动词。授予这些权限前必须严格评估，避免权限提升漏洞。通常只应授予集群管理员或专门的认证服务账户。
7. 非资源 URL 与 RBAC
Kubernetes API 中还存在一些 非资源 URL（Non-Resource URL），它们不关联具体的资源类型，例如 /healthz、/version、/api、/apis。这些端点通过 ClusterRole 中的 nonResourceURLs 字段进行授权。
| 非资源 URL | 用途 | RBAC 配置示例 |
|---|---|---|
/healthz |
API Server 健康检查 | nonResourceURLs: ["/healthz"]; verbs: ["get"] |
/version |
获取集群版本信息 | nonResourceURLs: ["/version"]; verbs: ["get"] |
/api, /apis |
发现 API 组和版本 | nonResourceURLs: ["/api", "/apis"]; verbs: ["get"] |
/openapi/v2 |
获取 OpenAPI 规范 | nonResourceURLs: ["/openapi/*"]; verbs: ["get"] |
get 访问 /healthz、/version、/api、/apis 的权限。这不会带来安全风险，但能避免客户端因无法发现 API 版本而报错。
8. 动词与资源组合的完整示例
以下是一个完整的 RBAC 规则示例，展示了如何将本章所学概念组合成一条实际的权限策略：
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: production
name: pod-reader
rules:
- apiGroups: [""] # 核心 API 组
resources: ["pods", "pods/log"] # 主资源 + 子资源
verbs: ["get", "list", "watch"] # 只读操作
- apiGroups: ["apps"] # apps API 组
resources: ["deployments"] # Deployment 资源
verbs: ["get", "list"] # 仅允许查看，不允许修改
- apiGroups: ["batch"] # batch API 组
resources: ["jobs"] # Job 资源
verbs: ["get", "list", "watch"] # 只读操作
该规则允许 production 命名空间内的主体：读取 Pod 详情和日志、列出并监听 Pod 变更、查看 Deployment 和 Job 的列表与详情。但不允许创建、更新或删除任何资源。