Skip to content

Commit 687b645

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #34801 from zhangxyjlu/downward-api
[zh-cn] Add downward-api.md chinese version
2 parents bc9e21d + 785a245 commit 687b645

File tree

2 files changed

+326
-0
lines changed

2 files changed

+326
-0
lines changed

‎content/zh-cn/docs/concepts/workloads/pods/downward-api.md

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
---
2+
title: Downward API
3+
content_type: concept
4+
description: >
5+
有两种方法可以将 Pod 和容器字段暴露给运行中的容器：环境变量和由特殊卷类型承载的文件。
6+
这两种暴露 Pod 和容器字段的方法统称为 Downward API。
7+
---
8+
<!--
9+
title: Downward API
10+
content_type: concept
11+
description: >
12+
There are two ways to expose Pod and container fields to a running container:
13+
environment variables, and as files that are populated by a special volume type.
14+
Together, these two ways of exposing Pod and container fields are called the downward API.
15+
-->
16+
17+
<!-- overview -->
18+
19+
<!--
20+
It is sometimes useful for a container to have information about itself, without
21+
being overly coupled to Kubernetes. The _downward API_ allows containers to consume
22+
information about themselves or the cluster without using the Kubernetes client
23+
or API server.
24+
-->
25+
对于容器来说，在不与 Kubernetes 过度耦合的情况下，拥有关于自身的信息有时是很有用的。
26+
**Downward API** 允许容器在不使用 Kubernetes 客户端或 API 服务器的情况下获得自己或集群的信息。
27+
28+
<!--
29+
An example is an existing application that assumes a particular well-known
30+
environment variable holds a unique identifier. One possibility is to wrap the
31+
application, but that is tedious and error-prone, and it violates the goal of low
32+
coupling. A better option would be to use the Pod's name as an identifier, and
33+
inject the Pod's name into the well-known environment variable.
34+
-->
35+
例如，现有应用程序假设某特定的周知的环境变量是存在的，其中包含唯一标识符。
36+
一种方法是对应用程序进行封装，但这很繁琐且容易出错，并且违背了低耦合的目标。
37+
更好的选择是使用 Pod 名称作为标识符，并将 Pod 名称注入到周知的环境变量中。
38+
39+
<!--
40+
In Kubernetes, there are two ways to expose Pod and container fields to a running container:
41+
42+
* as [environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
43+
* as [files in a `downwardAPI` volume](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
44+
-->
45+
在 Kubernetes 中，有两种方法可以将 Pod 和容器字段暴露给运行中的容器：
46+
47+
* 作为[环境变量](/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
48+
* 作为 [`downwardAPI` 卷中的文件](/zh-cn/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
49+
50+
<!--
51+
Together, these two ways of exposing Pod and container fields are called the
52+
_downward API_.
53+
-->
54+
这两种暴露 Pod 和容器字段的方式统称为 **Downward API**。
55+
56+
<!-- body -->
57+
58+
<!--
59+
## Available fields
60+
61+
Only some Kubernetes API fields are available through the downward API. This
62+
section lists which fields you can make available.
63+
-->
64+
## 可用字段 {#available-fields}
65+
66+
只有部分 Kubernetes API 字段可以通过 Downward API 使用。本节列出了你可以使用的字段。
67+
68+
<!--
69+
You can pass information from available Pod-level fields using `fieldRef`.
70+
At the API level, the `spec` for a Pod always defines at least one
71+
[Container](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container).
72+
You can pass information from available Container-level fields using
73+
`resourceFieldRef`.
74+
-->
75+
你可以使用 `fieldRef` 传递来自可用的 Pod 级字段的信息。在 API 层面，一个 Pod 的
76+
`spec` 总是定义了至少一个 [Container](/zh-cn/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container)。
77+
你可以使用 `resourceFieldRef` 传递来自可用的 Container 级字段的信息。
78+
79+
<!--
80+
### Information available via `fieldRef` {#downwardapi-fieldRef}
81+
82+
For most Pod-level fields, you can provide them to a container either as
83+
an environment variable or using a `downwardAPI` volume. The fields available
84+
via either mechanism are:
85+
-->
86+
### 可通过 `fieldRef` 获得的信息 {#downwardapi-fieldRef}
87+
88+
对于大多数 Pod 级别的字段，你可以将它们作为环境变量或使用 `downwardAPI` 卷提供给容器。
89+
通过这两种机制可用的字段有：
90+
91+
<!--
92+
`metadata.name`
93+
: the pod's name
94+
-->
95+
`metadata.name`
96+
: Pod 的名称
97+
98+
<!--
99+
`metadata.namespace`
100+
: the pod's {{< glossary_tooltip text="namespace" term_id="namespace" >}}
101+
-->
102+
`metadata.namespace`
103+
: Pod 的{{< glossary_tooltip text="命名空间" term_id="namespace" >}}
104+
105+
<!--
106+
`metadata.uid`
107+
: the pod's unique ID
108+
-->
109+
`metadata.uid`
110+
: Pod 的唯一 ID
111+
112+
<!--
113+
`metadata.annotations['<KEY>']`
114+
: the value of the pod's {{< glossary_tooltip text="annotation" term_id="annotation" >}} named `<KEY>` (for example, `metadata.annotations['myannotation']`)
115+
-->
116+
`metadata.annotations['<KEY>']`
117+
: Pod 的{{< glossary_tooltip text="注解" term_id="annotation" >}} `<KEY>` 的值（例如：`metadata.annotations['myannotation']`）
118+
119+
<!--
120+
`metadata.labels['<KEY>']`
121+
: the text value of the pod's {{< glossary_tooltip text="label" term_id="label" >}} named `<KEY>` (for example, `metadata.labels['mylabel']`)
122+
-->
123+
`metadata.labels['<KEY>']`
124+
: Pod 的{{< glossary_tooltip text="标签" term_id="label" >}} `<KEY>` 的值（例如：`metadata.labels['mylabel']`）
125+
126+
<!--
127+
`spec.serviceAccountName`
128+
: the name of the pod's {{< glossary_tooltip text="service account" term_id="service-account" >}}
129+
-->
130+
`spec.serviceAccountName`
131+
: Pod 的{{< glossary_tooltip text="服务账号" term_id="service-account" >}}名称
132+
133+
<!--
134+
`spec.nodeName`
135+
: the name of the {{< glossary_tooltip term_id="node" text="node">}} where the Pod is executing
136+
-->
137+
`spec.nodeName`
138+
: Pod 运行时所处的{{< glossary_tooltip term_id="node" text="节点">}}名称
139+
140+
<!--
141+
`status.hostIP`
142+
: the primary IP address of the node to which the Pod is assigned
143+
-->
144+
`status.hostIP`
145+
: Pod 所在节点的主 IP 地址
146+
147+
<!--
148+
`status.podIP`
149+
: the pod's primary IP address (usually, its IPv4 address)
150+
-->
151+
`status.podIP`
152+
: Pod 的主 IP 地址（通常是其 IPv4 地址）
153+
154+
<!--
155+
In addition, the following information is available through
156+
a `downwardAPI` volume `fieldRef`, but **not as environment variables**:
157+
-->
158+
此外，以下信息可以通过 `downwardAPI` 卷 `fieldRef` 获得，但**不能作为环境变量**获得：
159+
160+
<!--
161+
`metadata.labels`
162+
: all of the pod's labels, formatted as `label-key="escaped-label-value"` with one label per line
163+
-->
164+
`metadata.labels`
165+
: Pod 的所有标签，格式为 `标签键名="转义后的标签值"`，每行一个标签
166+
167+
<!--
168+
`metadata.annotations`
169+
: all of the pod's annotations, formatted as `annotation-key="escaped-annotation-value"` with one annotation per line
170+
-->
171+
`metadata.annotations`
172+
: Pod 的全部注解，格式为 `注解键名="转义后的注解值"`，每行一个注解
173+
174+
<!--
175+
### Information available via `resourceFieldRef` {#downwardapi-resourceFieldRef}
176+
177+
These container-level fields allow you to provide information about
178+
[requests and limits](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)
179+
for resources such as CPU and memory.
180+
-->
181+
### 可通过 `resourceFieldRef` 获得的信息 {#downwardapi-resourceFieldRef}
182+
183+
<!--
184+
`resource: limits.cpu`
185+
: A container's CPU limit
186+
-->
187+
`resource: limits.cpu`
188+
: 容器的 CPU 限制值
189+
190+
<!--
191+
`resource: requests.cpu`
192+
: A container's CPU request
193+
-->
194+
`resource: requests.cpu`
195+
: 容器的 CPU 请求值
196+
197+
<!--
198+
`resource: limits.memory`
199+
: A container's memory limit
200+
-->
201+
`resource: limits.memory`
202+
: 容器的内存限制值
203+
204+
<!--
205+
`resource: requests.memory`
206+
: A container's memory request
207+
-->
208+
`resource: requests.memory`
209+
: 容器的内存请求值
210+
211+
<!--
212+
`resource: limits.hugepages-*`
213+
: A container's hugepages limit (provided that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
214+
-->
215+
`resource: limits.hugepages-*`
216+
: 容器的巨页限制值（前提是启用了 `DownwardAPIHugePages`
217+
[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)）
218+
219+
<!--
220+
`resource: requests.hugepages-*`
221+
: A container's hugepages request (provided that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
222+
-->
223+
`resource: requests.hugepages-*`
224+
: 容器的巨页请求值（前提是启用了 `DownwardAPIHugePages`
225+
[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)）
226+
227+
<!--
228+
`resource: limits.ephemeral-storage`
229+
: A container's ephemeral-storage limit
230+
-->
231+
`resource: limits.ephemeral-storage`
232+
: 容器的临时存储的限制值
233+
234+
<!--
235+
`resource: requests.ephemeral-storage`
236+
: A container's ephemeral-storage request
237+
-->
238+
`resource: requests.ephemeral-storage`
239+
: 容器的临时存储的请求值
240+
241+
<!--
242+
#### Fallback information for resource limits
243+
244+
If CPU and memory limits are not specified for a container, and you use the
245+
downward API to try to expose that information, then the
246+
kubelet defaults to exposing the maximum allocatable value for CPU and memory
247+
based on the [node allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)
248+
calculation.
249+
-->
250+
#### 资源限制的后备信息 {#fallback-information-for-resource-limits}
251+
252+
如果没有为容器指定 CPU 和内存限制时尝试使用 Downward API 暴露该信息，那么 kubelet 默认会根据
253+
[节点可分配资源](/zh-cn/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)
254+
计算并暴露 CPU 和内存的最大可分配值。
255+
256+
257+
## {{% heading "whatsnext" %}}
258+
259+
<!--
260+
You can read about [`downwardAPI` volumes](/docs/concepts/storage/volumes/#downwardapi).
261+
262+
You can try using the downward API to expose container- or Pod-level information:
263+
* as [environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
264+
* as [files in `downwardAPI` volume](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
265+
-->
266+
你可以阅读有关 [`downwardAPI` 卷](/zh-cn/docs/concepts/storage/volumes/#downwardapi)的内容。
267+
268+
你可以尝试使用 Downward API 暴露容器或 Pod 级别的信息：
269+
* 作为[环境变量](/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
270+
* 作为 [`downwardAPI` 卷中的文件](/zh-cn/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)

‎content/zh-cn/docs/reference/glossary/downward-api.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Downward API
3+
id: downward-api
4+
date: 2022-03-21
5+
short_description: >
6+
将 Pod 和容器字段值暴露给容器中运行的代码的机制。
7+
aka:
8+
full_link: /docs/concepts/workloads/pods/downward-api/
9+
tags:
10+
- architecture
11+
---
12+
<!--
13+
title: Downward API
14+
id: downward-api
15+
date: 2022-03-21
16+
short_description: >
17+
A mechanism to expose Pod and container field values to code running in a container.
18+
aka:
19+
full_link: /docs/concepts/workloads/pods/downward-api/
20+
tags:
21+
- architecture
22+
-->
23+
<!--
24+
Kubernetes' mechanism to expose Pod and container field values to code running in a container.
25+
-->
26+
Kubernetes 将 Pod 和容器字段值暴露给容器中运行的代码的机制。
27+
<!--more-->
28+
<!--
29+
It is sometimes useful for a container to have information about itself, without
30+
needing to make changes to the container code that directly couple it to Kubernetes.
31+
-->
32+
在不需要修改容器代码的前提下让容器拥有关于自身的信息是很有用的。修改代码可能使容器直接耦合到 Kubernetes。
33+
34+
<!--
35+
The Kubernetes downward API allows containers to consume information about themselves
36+
or their context in a Kubernetes cluster. Applications in containers can have
37+
access to that information, without the application needing to act as a client of
38+
the Kubernetes API.
39+
-->
40+
Kubernetes Downward API 允许容器使用它们自己或它们在 Kubernetes 集群中所处环境的信息。
41+
容器中的应用程序可以访问该信息，而不需要以 Kubernetes API 客户端的形式执行操作。
42+
43+
<!--
44+
There are two ways to expose Pod and container fields to a running container:
45+
46+
- using [environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/)
47+
- using [a `downwardAPI` volume](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
48+
49+
Together, these two ways of exposing Pod and container fields are called the _downward API_.
50+
-->
51+
有两种方法可以将 Pod 和容器字段暴露给正在运行的容器：
52+
53+
* 使用[环境变量](/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information/)
54+
* 使用 [`downwardAPI` 卷](/zh-cn/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
55+
56+
这两种暴露 Pod 和容器字段的方式统称为 **Downward API**。

0 commit comments

Comments
 (0)