你正在查看的文档所针对的是 Kubernetes 版本: v1.28

Kubernetes v1.28 版本的文档已不再维护。你现在看到的版本来自于一份静态的快照。如需查阅最新文档,请点击 最新版本。

Downward API

有两种方法可以将 Pod 和容器字段暴露给运行中的容器:环境变量和由特殊卷类型承载的文件。 这两种暴露 Pod 和容器字段的方法统称为 Downward API。

对于容器来说,在不与 Kubernetes 过度耦合的情况下,拥有关于自身的信息有时是很有用的。 Downward API 允许容器在不使用 Kubernetes 客户端或 API 服务器的情况下获得自己或集群的信息。

例如,现有应用程序假设某特定的周知的环境变量是存在的,其中包含唯一标识符。 一种方法是对应用程序进行封装,但这很繁琐且容易出错,并且违背了低耦合的目标。 更好的选择是使用 Pod 名称作为标识符,并将 Pod 名称注入到周知的环境变量中。

在 Kubernetes 中,有两种方法可以将 Pod 和容器字段暴露给运行中的容器:

这两种暴露 Pod 和容器字段的方式统称为 Downward API

可用字段

只有部分 Kubernetes API 字段可以通过 Downward API 使用。本节列出了你可以使用的字段。

你可以使用 fieldRef 传递来自可用的 Pod 级字段的信息。在 API 层面,一个 Pod 的 spec 总是定义了至少一个 Container。 你可以使用 resourceFieldRef 传递来自可用的 Container 级字段的信息。

可通过 fieldRef 获得的信息

对于某些 Pod 级别的字段,你可以将它们作为环境变量或使用 downwardAPI 卷提供给容器。 通过这两种机制可用的字段有:

metadata.name
Pod 的名称
metadata.namespace
Pod 的命名空间
metadata.uid
Pod 的唯一 ID
metadata.annotations['<KEY>']
Pod 的注解 <KEY> 的值(例如:metadata.annotations['myannotation']
metadata.labels['<KEY>']
Pod 的标签 <KEY> 的值(例如:metadata.labels['mylabel']

以下信息可以通过环境变量获得,但不能作为 downwardAPIfieldRef 获得:

spec.serviceAccountName
Pod 的服务账号名称
spec.nodeName
Pod 运行时所处的节点名称
status.hostIP
Pod 所在节点的主 IP 地址
status.hostIPs
这组 IP 地址是 status.hostIP 的双协议栈版本,第一个 IP 始终与 status.hostIP 相同。 该字段在启用了 PodHostIPs 特性门控后可用。
status.podIP
Pod 的主 IP 地址(通常是其 IPv4 地址)
status.podIPs
这组 IP 地址是 status.podIP 的双协议栈版本, 第一个 IP 始终与 status.podIP 相同。

以下信息可以通过 downwardAPIfieldRef 获得,但不能作为环境变量获得:

metadata.labels
Pod 的所有标签,格式为 标签键名="转义后的标签值",每行一个标签
metadata.annotations
Pod 的全部注解,格式为 注解键名="转义后的注解值",每行一个注解

可通过 resourceFieldRef 获得的信息

resource: limits.cpu
容器的 CPU 限制值
resource: requests.cpu
容器的 CPU 请求值
resource: limits.memory
容器的内存限制值
resource: requests.memory
容器的内存请求值
resource: limits.hugepages-*
容器的巨页限制值
resource: requests.hugepages-*
容器的巨页请求值
resource: limits.ephemeral-storage
容器的临时存储的限制值
resource: requests.ephemeral-storage
容器的临时存储的请求值

资源限制的后备信息

如果没有为容器指定 CPU 和内存限制时尝试使用 Downward API 暴露该信息,那么 kubelet 默认会根据 节点可分配资源 计算并暴露 CPU 和内存的最大可分配值。

接下来

你可以阅读有关 downwardAPI的内容。

你可以尝试使用 Downward API 暴露容器或 Pod 级别的信息:

最后修改 August 26, 2023 at 9:53 PM PST: [zh] sync concepts/workloads/pods/downward-api.md (1a50f2320b)