Kubernetes Downward API 实战：通过文件将 Pod 信息呈现给容器

Kubernetes Downward API 实战：通过文件将 Pod 信息呈现给容器

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website

前言

在 Kubernetes 集群中，容器有时需要获取自身运行环境的信息，比如 Pod 的标签、注解或者资源限制等。Kubernetes 提供了 Downward API 机制来实现这一需求。本文将详细介绍如何使用 Downward API 通过卷文件的方式将 Pod 和容器信息暴露给容器内部。

Downward API 简介

Downward API 是 Kubernetes 提供的一种特殊机制，它允许容器在不直接调用 Kubernetes API 的情况下获取自身 Pod 的信息。Downward API 提供了两种信息暴露方式：

1. 环境变量方式
2. 卷文件方式（本文重点）

这两种方式各有优势，卷文件方式特别适合需要动态更新或数据量较大的场景。

准备工作

在开始之前，请确保您已经：

1. 安装并配置了 Kubernetes 集群
2. 拥有集群操作权限
3. 熟悉基本的 Pod 和容器概念

实战一：暴露 Pod 级别字段

创建示例 Pod

首先，我们创建一个 Pod，通过 downwardAPI 卷将 Pod 的标签和注解信息暴露给容器：

apiVersion: v1
kind: Pod
metadata:
  name: downward-api-volume-example
  labels:
    zone: us-east-coast
    cluster: test-cluster
    rack: rack-22
  annotations:
    build: two
    builder: john-doe
spec:
  containers:
    - name: client-container
      image: registry.k8s.io/busybox
      command: ["sh", "-c"]
      args:
      - while true; do
          if [[ -e /etc/podinfo/labels ]]; then
            echo -en '\n\n'; cat /etc/podinfo/labels; fi;
          if [[ -e /etc/podinfo/annotations ]]; then
            echo -en '\n\n'; cat /etc/podinfo/annotations; fi;
          sleep 5;
        done;
      volumeMounts:
        - name: podinfo
          mountPath: /etc/podinfo
  volumes:
    - name: podinfo
      downwardAPI:
        items:
          - path: "labels"
            fieldRef:
              fieldPath: metadata.labels
          - path: "annotations"
            fieldRef:
              fieldPath: metadata.annotations

关键配置解析

1. volumes 部分：定义了一个名为 podinfo 的 downwardAPI 卷
2. items 数组：指定要暴露的字段
   • metadata.labels：Pod 的所有标签将写入 /etc/podinfo/labels 文件
   • metadata.annotations：Pod 的所有注解将写入 /etc/podinfo/annotations 文件

验证效果

创建 Pod 后，我们可以进入容器查看生成的文件：

kubectl exec -it downward-api-volume-example -- sh
cat /etc/podinfo/labels
cat /etc/podinfo/annotations

文件内容会实时反映 Pod 的当前状态，当 Pod 的标签或注解发生变化时，文件内容也会自动更新。

实战二：暴露容器资源字段

除了 Pod 级别的信息，我们还可以暴露容器自身的资源限制和请求：

apiVersion: v1
kind: Pod
metadata:
  name: downward-api-volume-resources-example
spec:
  containers:
    - name: client-container
      image: registry.k8s.io/busybox
      command: ["sh", "-c"]
      args:
      - while true; do
          if [[ -e /etc/podinfo/cpu_limit ]]; then
            echo -en '\n\n'; cat /etc/podinfo/cpu_limit; fi;
          sleep 5;
        done;
      resources:
        requests:
          memory: "32Mi"
          cpu: "125m"
        limits:
          memory: "64Mi"
          cpu: "250m"
      volumeMounts:
        - name: podinfo
          mountPath: /etc/podinfo
  volumes:
    - name: podinfo
      downwardAPI:
        items:
          - path: "cpu_limit"
            resourceFieldRef:
              containerName: client-container
              resource: limits.cpu
              divisor: 1m
          - path: "cpu_request"
            resourceFieldRef:
              containerName: client-container
              resource: requests.cpu
              divisor: 1m
          - path: "mem_limit"
            resourceFieldRef:
              containerName: client-container
              resource: limits.memory
          - path: "mem_request"
            resourceFieldRef:
              containerName: client-container
              resource: requests.memory

关键配置解析

1. resourceFieldRef：用于指定容器资源字段
   • containerName：指定目标容器名称
   • resource：要暴露的资源字段（如 limits.cpu、requests.memory 等）
   • divisor：格式化除数（可选），对于 CPU 可以指定 1m 表示毫核

验证效果

创建 Pod 后，我们可以检查各个资源文件：

kubectl exec -it downward-api-volume-resources-example -- sh
cat /etc/podinfo/cpu_limit  # 显示 250
cat /etc/podinfo/cpu_request  # 显示 125
cat /etc/podinfo/mem_limit  # 显示 67108864 (64Mi in bytes)
cat /etc/podinfo/mem_request  # 显示 33554432 (32Mi in bytes)

技术细节与注意事项

1. 动态更新机制：

   • Downward API 卷使用符号链接实现原子更新
   • 实际文件存储在临时目录（如 ..2982_06_02_21_47_53.299460680）
   • ..data 是指向当前有效临时目录的符号链接
   • 文件更新时，会先写入新临时目录，然后原子切换 ..data 链接

2. subPath 限制：

   • 如果使用 subPath 挂载 Downward API 卷，容器将无法接收更新
   • 这是因为 subPath 会创建文件的静态副本

3. 可用字段：

   • Pod 级别：metadata.name、metadata.namespace、metadata.labels、metadata.annotations 等
   • 容器级别：资源请求和限制（requests.cpu、limits.memory 等）

最佳实践

1. 敏感信息处理：虽然 Downward API 方便，但不适合暴露敏感信息（考虑使用 Secret）
2. 文件权限控制：可以配置文件的访问权限（类似 Secret 的配置方式）
3. 更新频率：理解 Downward API 的更新不是实时的，会有轻微延迟
4. 资源格式化：合理使用 divisor 参数格式化资源值，提高可读性

总结

Downward API 卷提供了一种优雅的方式将 Pod 和容器信息暴露给运行中的容器，无需容器直接调用 Kubernetes API。通过本文的实战示例，您应该已经掌握了如何使用 downwardAPI 卷来暴露各类信息。根据实际需求，您可以选择暴露 Pod 级别的元数据或容器级别的资源限制，为容器提供必要的运行时环境信息。

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website