---
url: /courses/kubernetes-cluster/04-resource-governance/index.md
---
# 第四节 标签、注解、API 与命名空间治理

::: tip 项目目标
为 Kubernetes 集群建立规范的声明式资源治理规则：创建 `yunfan-shop` 业务命名空间，遵循 Kubernetes 官方标准对资源元数据（`labels` 与 `annotations`）进行分类治理；掌握基于等值（Equality-based）与基于集合（Set-based）的标签选择器 Selector 查询方法；掌握 `kubectl api-resources` 与 `kubectl explain` API 探索技巧，并验证命令式修改与声明式回写的统一。
:::

## 4.1 治理需求：为什么必须引入资源治理

在集群建立初期，运行的对象很少，我们可以直接通过对象名称（如 `web-pod-1`）进行识别和管理。但随着业务和课次的增加，同一个集群内会涌现出成百上千个不同环境、不同应用层级、不同负责人的 Pod、Service、ConfigMap 等资源。

如果缺乏统一的元数据治理规范，将面临三大现实痛点：

* **无法进行多维度检索**：无法通过单一命令一次性找出“属于商城项目、生产环境且位于前端层的所有资源”。
* **控制器与 Service 无法精准关联**：Kubernetes 的 Service 和 Deployment 并不依赖固定的 Pod 名称，而是依赖标签选择器来动态发现和锁定后端 Pod 集合。
* **信息上下文丢失**：资源的发布时间、变更记录、负责人或用途说明散落在外部文档中，资源对象本身缺乏自我描述能力。

通过引入 **命名空间（Namespace）** 划分逻辑边界，使用 **标签（Label）** 构建可检索维度，使用 **注解（Annotation）** 存储非检索说明，可以建立高效有序的集群治理体系：

```mermaid
flowchart LR
  A[集群资源增加] --> B[Namespace 划分逻辑边界]
  B --> C[Label 构建检索维度]
  C --> D[Selector 动态绑定与过滤]
  D --> E[Annotation 补充元数据说明]
  E --> F[YAML 回写固化声明式真源]
```

## 4.2 标签与注解：元数据分类与底层索引机制

### 4.2.1 Label 与 Annotation 的本质区别

Kubernetes 资源对象的 `metadata` 中包含了 `labels` 和 `annotations` 两个极其相似但用途完全不同的键值对（Key-Value）映射表：

| 维度 | 标签 (Label) | 注解 (Annotation) |
| --- | --- | --- |
| **核心职责** | 标识与分类，构建资源集合 | 存储非检索性的扩展元数据与结构化说明 |
| **底层索引机制** | **建立倒排索引 (Indexed)**，支持高性能选择器检索 | **不建立检索索引 (Unindexed)**，无法被 Selector 查询 |
| **存储数据量** | 建议简短（Key/Value 通常不超过 63 个字符） | 格式宽松，支持存储较大的 JSON/YAML 字符串或长说明 |
| **典型使用场景** | `app.kubernetes.io/name: web``tier: frontend``env: prod` | `description: "购物车核心模块"``build-version: "v1.2.4-build88"``last-updated-by: "ops-team"` |

观察下面的交互面板，理解请求如何通过 Selector 对 Label 进行过滤，以及为什么不能将大段说明塞入 Label：

### 4.2.2 官方推荐标签标准 (`app.kubernetes.io/*`)

为了避免不同的开发团队任意发明标签键名，Kubernetes 官方制定了标准标签规范，建议在编写资源清单时统一遵循：

* `app.kubernetes.io/name`: 应用的官方名称（如 `nginx`, `mariadb`）。
* `app.kubernetes.io/instance`: 应用实例的唯一标识（如 `yunfan-web-v1`）。
* `app.kubernetes.io/version`: 应用的版本号（如 `1.27.0`）。
* `app.kubernetes.io/component`: 架构层级组件分类（如 `frontend`, `backend`, `database`）。
* `app.kubernetes.io/part-of`: 该资源所属的高层整体项目（如 `yunfan-mall`）。
* `app.kubernetes.io/managed-by`: 管理该资源的自动化工具（如 `helm`, `kubectl`）。

### 4.2.3 实训：声明命名空间与治理样例配置文件

在项目根目录下直接创建治理配置文件 `governance.yaml`：

```yaml title="governance.yaml"
apiVersion: v1
kind: Namespace
metadata:
  name: yunfan-shop
  labels:
    app.kubernetes.io/part-of: yunfan-mall
    env: lab
    owner: dev-student
  annotations:
    yunfan.example/purpose: "云帆商城逻辑资源隔离边界"
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: governance-sample
  namespace: yunfan-shop
  labels:
    app.kubernetes.io/name: governance-sample
    app.kubernetes.io/part-of: yunfan-mall
    tier: platform
    env: lab
    owner: dev-student
  annotations:
    yunfan.example/change-note: "第四课声明式元数据治理配置样例"
data:
  lesson: "04"
  status: "configured"
```

在终端中应用该配置文件：

```bash
kubectl apply -f governance.yaml
```

**预期输出**：
系统将创建 `yunfan-shop` 命名空间，并在该命名空间内创建一个包含了标准 Label 和 Annotation 的 ConfigMap 资源。

## 4.3 选择器 (Selector) 高级查询实战

创建带有标签的资源后，我们需要使用 `kubectl` 配合 `-l` 或 `--selector` 参数执行各种维度检索。

### 4.3.1 两种选择器表达式语法对比

Kubernetes 支持两种选择器语法：**基于等值 (Equality-based)** 和 **基于集合 (Set-based)**。

| 选择器类型 | 匹配运算符 | 示例命令 | 说明与匹配逻辑 |
| --- | --- | --- | --- |
| **基于等值 (Equality-based)** | `=`, `==`, `!=` | `kubectl get pods -l env=lab,tier=frontend` | 匹配 `env` 为 `lab` **且** `tier` 为 `frontend` 的资源（逗号代表逻辑 AND）。 |
| **基于集合 (Set-based)** | `in`, `notin`, `exists` | `kubectl get cm -n yunfan-shop -l 'tier in (platform, frontend)'` | 匹配 `tier` 的值在集合 `[platform, frontend]` 中的所有资源。 |
| **存在性检查 (Exists)** | 仅写键名或 `!键名` | `kubectl get cm -n yunfan-shop -l 'owner'` | 匹配声明了 `owner` 标签的所有资源，无论其具体值为何。 |

### 4.3.2 标签查询实操演练

在终端中依次执行以下查询命令，对比输出结果：

**1. 查看资源的完整标签**

```bash
kubectl get namespace yunfan-shop --show-labels
kubectl get configmap -n yunfan-shop --show-labels
```

**命令解析**：`--show-labels` 会在输出表格的最右侧追加一列 `LABELS`，完整展示资源上的每一个标签键值对。

**2. 使用等值选择器过滤资源**

```bash
kubectl get configmap -n yunfan-shop -l app.kubernetes.io/part-of=yunfan-mall
```

**3. 使用集合与组合选择器高级过滤**

```bash
kubectl get configmap -n yunfan-shop -l 'tier in (platform, frontend),env=lab'
```

**命令解析**：匹配属于 `yunfan-shop` 命名空间、`tier` 属于 `platform` 或 `frontend`，**并且** `env` 精确等于 `lab` 的所有 ConfigMap。

## 4.4 命名空间：逻辑范围与作用域划分

### 4.4.1 Namespaced 资源与 Cluster-scoped 资源

命名空间（Namespace）在 Kubernetes 中提供了一种**逻辑隔离**机制。但必须明确：**并不是所有 Kubernetes 资源对象都属于命名空间**。

* **Namespaced 资源（受命名空间约束）**：Pod, Service, ConfigMap, Secret, Deployment, StatefulSet 等。这些资源在创建时必须指定命名空间，同名资源在不同命名空间中可共存。
* **Cluster-scoped 资源（集群级共享资源）**：Node, Namespace, PersistentVolume (PV), StorageClass, ClusterRole 等。这些资源属于整个集群，不能也不需要挂载到任何命名空间下。

观察下面的交互面板，理解集群级资源与命名空间资源的作用域区别：

### 4.4.2 实训：查询资源作用域与修改上下文默认命名空间

**1. 使用 `kubectl api-resources` 区分作用域**

```bash
# 查看所有受命名空间约束的资源类型
kubectl api-resources --namespaced=true

# 查看所有集群级别的资源类型
kubectl api-resources --namespaced=false
```

**2. 切换当前上下文的默认命名空间**

默认情况下，`kubectl` 命令会对 `default` 命名空间生效。为了避免每次都手动输入 `-n yunfan-shop`，可以修改当前 context 的默认命名空间：

```bash
# 将当前上下文的默认命名空间绑定为 yunfan-shop
kubectl config set-context --current --namespace=yunfan-shop

# 验证当前上下文配置
kubectl config view --minify | grep namespace:
```

配置后，直接运行 `kubectl get configmap` 即可默认查询 `yunfan-shop` 命名空间中的资源。

## 4.5 API 发现与帮助文档：`api-resources` 与 `explain`

在编写复杂的 Kubernetes YAML 配置文件时，我们不需要死记硬背每个资源的字段嵌套关系。Kubernetes 内置了强大的 API 发现与自我描述工具。

### 4.5.1 `kubectl api-resources` 读表方法

运行以下命令，查看当前集群支持的所有 API 资源类型：

```bash
kubectl api-resources
```

**输出表格核心列深度解读**：

* `NAME`: 资源的复数全称（如 `deployments`, `configmaps`）。
* `SHORTNAMES`: 资源的命令行简写（如 `deploy` 代表 `deployments`，`cm` 代表 `configmaps`，`ns` 代表 `namespaces`）。
* `APIVERSION`: 该资源当前对应的 API 组和版本（如 `apps/v1`, `v1`）。在编写 YAML 时，`apiVersion` 字段必须与此列完全一致。
* `NAMESPACED`: `true` 表示属于命名空间资源，`false` 表示集群级资源。
* `KIND`: 资源在 YAML 配置文件中 `kind` 字段必须填写的拼写名称（区分大小写，如 `Deployment`）。

### 4.5.2 使用 `kubectl explain` 检索字段层级与定义

`kubectl explain` 可以直接读取集群 API Server 实时导出的 OpenAPI Schema 帮助文档。

**1. 检索资源的顶层字段**：

```bash
kubectl explain configmap
```

**2. 逐层深入检索嵌套字段**：

```bash
kubectl explain configmap.metadata
```

**3. 使用 `--recursive` 查看完整字段树结构**：

```bash
kubectl explain deployment.spec.template.spec.containers --recursive
```

**命令解析**：递归列出 `containers` 对象下所有可用的子字段（如 `image`, `ports`, `env`, `volumeMounts` 等）及其数据类型。在面对陌生资源类型时，此方法能快速查明字段语法。

## 4.6 元数据动态修改：命令式操作与声明式回写

在日常运维调试中，我们经常需要临时给资源打上标记，或者删除旧的废弃标签。

### 4.6.1 给资源动态添加与覆盖标签/注解

在终端中执行以下命令，为 `yunfan-worker` 节点添加用途标签，并为 ConfigMap 增加审核注解：

```bash
# 给节点 yunfan-worker 添加标签（覆盖已有键时需要 --overwrite）
kubectl label node yunfan-worker yunfan.example/node-purpose=general --overwrite

# 给 ConfigMap 动态添加注解
kubectl annotate configmap governance-sample -n yunfan-shop yunfan.example/reviewed=true --overwrite
```

**验证命令**：

```bash
kubectl get node yunfan-worker --show-labels
kubectl get configmap governance-sample -n yunfan-shop -o yaml
```

### 4.6.2 删除标签与注解的语法（减号 `-` 原理）

当需要从对象上移除某个标签或注解时，**只需在键名末尾加上减号 `-`**：

```bash
# 删除节点上的 yunfan.example/node-purpose 标签
kubectl label node yunfan-worker yunfan.example/node-purpose-

# 删除 ConfigMap 上的 yunfan.example/reviewed 注解
kubectl annotate configmap governance-sample -n yunfan-shop yunfan.example/reviewed-
```

**声明式最佳实践原则**：
命令式 `kubectl label` / `kubectl annotate` 仅用于紧急调试。一旦验证成功，**必须将改动手动回写到 `governance.yaml` 声明式文件中**，并通过 `kubectl apply -f governance.yaml` 重新提交，保证 Git 仓库中的 YAML 始终是集群的唯一真源（Single Source of Truth）。

## 4.7 阶段验收与排错速查

### 4.7.1 本课提交成果清单

完成本课实训后，提交以下三项成果即可：

1. **配置文件**：项目根目录下的 `governance.yaml`。
2. **第一张截图 `04-selector-results.png`**：同一终端画面中包含 `kubectl get configmap --show-labels` 与使用 `-l` 进行选择器检索（包含集合检索）的执行命令与关键输出。
3. **第二张截图 `04-api-explain.png`**：同一终端画面中包含 `kubectl api-resources` 以及 `kubectl explain configmap.metadata` 的命令行输出。

{{reflection-checkpoint:resource-governance-check}}

### 4.7.2 常见错误与排错矩阵

| 故障现象 | 可能原因 | 修复排查路径 |
| --- | --- | --- |
| `-l` 检索返回 `No resources found` | 标签拼写错误或选择器逻辑不匹配 | 先运行 `kubectl get <resource> --show-labels`，逐字符核对标签 Key 和 Value 是否拼写一致。 |
| Annotation 存在但选择器选不中 | 误将筛选条件写入了 `annotations` | 检查 YAML 文件，确认用于 Selector 查询的键值对放置在 `labels` 字段中而非 `annotations`。 |
| `kubectl explain` 报错 `field not found` | 字段路径拼写错误或层级跳跃 | 运行 `kubectl explain <resource>` 从顶层开始逐级向下查询，确保属性路径完整。 |
| 给集群级对象加 `-n` 报错或查不到 | 对象属于 Cluster-scoped | 运行 `kubectl api-resources` 确认 `NAMESPACED` 列，若为 `false` 则移除 `-n` 参数。 |

::: details 挑战任务：探索 Pod 模板标签匹配校验规则
尝试使用 `kubectl explain deployment.spec.selector` 查看说明。思考并回答：为什么 Deployment 的 `spec.selector.matchLabels` 必须与 `spec.template.metadata.labels` 中的标签完全一致？如果两者不一致，`kubectl apply` 时会触发什么报错？
:::

## 本章小测

{{assessment:resource-governance}}

## 本章小结

完成本课后，你已经掌握了：

1. **元数据治理基本规范**：理解了 Label（倒排索引，用于检索）与 Annotation（不建索引，用于说明）的底层差异，并掌握了 `app.kubernetes.io/*` 官方标准标签。
2. **选择器 Selector 检索技巧**：熟练运用了基于等值（Equality-based）和基于集合（Set-based）的高级标签过滤表达式。
3. **资源作用域与 Namespace 边界**：清醒认识到 Namespace 属于逻辑分组，并能准确区分 Namespaced 资源与 Cluster-scoped 集群级资源。
4. **API 自自我描述工具**：掌握了通过 `kubectl api-resources` 查找 API 组与 Kind，以及通过 `kubectl explain` 递归检索属性字段的方法。
5. **元数据改写与真源维护**：掌握了 `kubectl label/annotate` 命令式覆写与 `key-` 减号删除语法，并养成了调试后回写 YAML 声明式真源的良好习惯。

下一课中，我们将深入 `yunfan-shop` 命名空间编写可诊断的 Pod 对象，探究资源请求限制（Requests/Limits）、Init 初始化容器以及静态 Pod 的运维边界！