3. K8s资源对象与etcd映射：Pod、Service、ConfigMap等资源在etcd中的存储路径与数据结构

Kubernetes 将所有资源对象的状态持久化存储在 etcd 中。理解资源对象在 etcd 中的存储路径与数据结构，是进行一致性复核、故障排查和压测分析的基础。本章将深入剖析 Pod、Service、ConfigMap 等核心资源在 etcd 中的存储机制。

3.1 存储路径结构：/registry/ 前缀与资源分组

所有 K8s 资源对象均存储在 etcd 的 /registry/ 根路径下，遵循统一的层级结构：

/registry/<资源组>/<资源类型>/<命名空间>/<资源名称>

3.2 数据结构：序列化与版本控制

etcd 中存储的 K8s 资源对象以 Protobuf 序列化 格式保存，并通过 etcd v3 的 key-value 模型 管理。每个资源对象包含以下核心字段：

• Key：资源路径，如 /registry/pods/default/nginx-pod
• Value：Protobuf 编码的完整资源对象，包含 metadata、spec、status 等
• CreateRevision：该 key 创建时的 etcd 全局修订版本号
• ModRevision：该 key 最后一次修改时的修订版本号
• Version：K8s 资源对象的内部版本号（resourceVersion）
• Lease：关联的 etcd lease ID（用于 TTL 自动清理）

3.3 Pod 资源在 etcd 中的完整数据结构

以 Pod 为例，其 etcd 存储的 Protobuf 结构（简化后）如下：

{
  "metadata": {
    "name": "nginx-pod",
    "namespace": "default",
    "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resourceVersion": "123456",
    "creationTimestamp": "2025-01-15T10:30:00Z",
    "labels": {"app": "nginx"}
  },
  "spec": {
    "containers": [{
      "name": "nginx",
      "image": "nginx:1.25",
      "ports": [{"containerPort": 80}]
    }],
    "nodeName": "node-01"
  },
  "status": {
    "phase": "Running",
    "podIP": "10.244.1.5",
    "conditions": [
      {"type": "Ready", "status": "True"}
    ]
  }
}

3.4 资源对象与 etcd 映射关系图

下图展示了 K8s 核心资源在 etcd 中的存储路径层级与数据流向：

3.5 资源对象版本号与 etcd 修订版本的关系

K8s 资源对象的 resourceVersion 与 etcd 的 ModRevision 存在直接映射关系：

3.6 Service 的特殊存储结构：specs 与 endpoints 分离

Service 资源在 etcd 中采用双路径存储设计，这是 K8s 中唯一一个将规格与状态分离存储的资源类型：

• /registry/services/specs/<namespace>/<service-name>：存储 Service 的规格定义（ClusterIP、端口映射、选择器等）
• /registry/services/endpoints/<namespace>/<service-name>：存储 Service 对应的端点列表（Pod IP + 端口）

这种分离设计带来的优势：

• 端点变更（Pod 扩缩容、重启）不会触发 Service 规格的版本更新
• 减少不必要的 etcd 写入和 watch 事件
• 端点控制器可以独立更新 endpoints 路径，不影响 Service 规格

3.7 ConfigMap 与 Secret 的存储特点

ConfigMap 和 Secret 作为配置类资源，在 etcd 中具有以下存储特点：

3.8 资源对象在 etcd 中的生命周期状态机

下图展示了 K8s 资源对象从创建到删除在 etcd 中的状态转换：

3.9 一致性复核实践：etcd 与 K8s 资源映射验证

在压测沙盘中，可以通过以下步骤验证 K8s 资源对象与 etcd 存储的一致性：

1. 获取 K8s 资源列表：使用 kubectl get pods -o json 获取所有 Pod 的 resourceVersion
2. 获取 etcd 对应 key 列表：使用 etcdctl get /registry/pods/ --prefix --keys-only 获取所有 Pod 的 etcd key
3. 对比数量：确保 K8s 资源数量与 etcd key 数量一致
4. 对比版本号：随机抽取资源，对比 resourceVersion 与 etcd 的 ModRevision 是否匹配
5. 检查孤儿资源：查找 etcd 中存在但 K8s 中不存在的资源（或反之）

#!/bin/bash
# 一致性复核：对比 K8s Pod 与 etcd 存储
K8S_PODS=$(kubectl get pods --all-namespaces -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | sort)
ETCD_PODS=$(etcdctl get /registry/pods/ --prefix --keys-only | sed 's|/registry/pods/||' | sort)

# 对比数量
echo "K8s Pods count: $(echo "$K8S_PODS" | wc -l)"
echo "etcd Pods count: $(echo "$ETCD_PODS" | wc -l)"

# 查找差异
diff <(echo "$K8S_PODS") <(echo "$ETCD_PODS") || echo "差异发现！"