卷形式能拿到什么
Downward API 有两种投递方式：环境变量与投影文件。卷形式把 Pod 自身的元数据写成文件挂进容器，内容覆盖 metadata.name、namespace、labels、annotations 等，其中标签与注解会随 kubelet 的同步周期刷新。它适合「容器需要知道自己被打了什么标签、属于哪个命名空间」的场景；而节点名、Pod IP、容器资源限额这类字段在卷形式里拿不到，必须走环境变量。
基本信息
| 适用平台 | Kubernetes 各版本（downwardAPI 卷类型） |
|---|---|
| 字段来源 | fieldRef.fieldPath 指定字段；resourceFieldRef 用于资源类字段（env 形式） |
| 刷新行为 | labels/annotations 周期性同步，其余字段创建后不变 |
| 典型挂载点 | /etc/podinfo，只读卷 |
| 权限要求 | 普通用户即可读取，无需额外 RBAC |
典型使用场景
- 日志与指标打标：把 Pod 名称、命名空间写进文件，供应用附加到输出上
- 按标签自适应行为：运维改标签后应用读取刷新后的文件切换运行模式
- 注解驱动的灰度开关：把注解挂成文件，避免为改一个值重建 Pod
- 审计与上报：容器把自身身份信息随请求带上，便于链路追踪
- 与探针或采集器配合：采集器读取挂载的元数据文件补充标签
- 分环境行为差异：用命名空间文件判断当前是测试还是生产环境
卷形式示例
卷形式示例
volumes:
- name: podinfo
downwardAPI:
items:
- path: labels # 落盘文件名
fieldRef:
fieldPath: metadata.labels
- path: annotations
fieldRef:
fieldPath: metadata.annotations
containers:
- name: app
image: registry.example.com/app:1.2.0
volumeMounts:
- name: podinfo
mountPath: /etc/podinfo
readOnly: true验证内容
验证内容
kubectl exec -it web-x -- cat /etc/podinfo/labels # 形如 app="web" tier="front"
kubectl exec -it web-x -- sh -c 'cat /etc/podinfo/labels | tr "\n" ";"'
kubectl get pod web-x -o jsonpath='{.metadata.labels}' # 与文件内容对照字段支持矩阵
| 字段 | 卷形式 | 环境变量形式 |
|---|---|---|
| metadata.name / namespace | 支持 | 支持 |
| metadata.labels / annotations | 支持，随同步刷新 | 支持，但创建后固定 |
| metadata.uid | 不支持 | 支持 |
| spec.nodeName | 不支持 | 支持 |
| status.podIP | 不支持 | 支持 |
| 资源 requests / limits | 不支持 | 支持 |
卷形式的标签与注解是周期同步的，落盘内容为 key="value" 逐行文本，解析程序要按这个格式写，不能当 JSON 读。
fieldPath 写错（例如把 metadata.labels 写成 metadata.label）会让容器卡在 CreateContainerConfigError，报错信息里能看到具体字段名。
卷形式与 env 形式可以同时使用：元数据类走卷，节点名、Pod IP、资源限额走 env，两者互补而不冲突。