Skip to content

Commit

Permalink
Merge pull request #35606 from yanrongshi/zh-cn]update-downward-api-v…
Browse files Browse the repository at this point in the history 
…olume-expose-pod-information.md

[zh-cn]Update downward-api-volume-expose-pod-information.md
  • Loading branch information
@k8s-ci-robot
k8s-ci-robot committed Aug 5, 2022
2 parents ef3de08 + d6868d0 commit 44cef08
Showing 1 changed file with 69 additions and 186 deletions.
255 changes: 69 additions & 186 deletions ...ocs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md
View file
Expand Up @@ -8,71 +8,68 @@ weight: 40

<!--
This page shows how a Pod can use a
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
to expose information about itself to Containers running in the Pod.
A `DownwardAPIVolumeFile` can expose Pod fields and Container fields.
[`downwardAPI` volume](/docs/concepts/storage/volumes/#downwardapi),
to expose information about itself to containers running in the Pod.
A `downwardAPI` volume can expose Pod fields and container fields.
-->
此页面描述 Pod 如何使用
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
[`downwardAPI` 卷](/zh-cn/docs/concepts/storage/volumes/#downwardapi)
把自己的信息呈现给 Pod 中运行的容器。
`DownwardAPIVolumeFile` 可以呈现 Pod 和容器的字段。

## {{% heading "prerequisites" %}}

{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}

<!-- steps -->
`downwardAPI` 可以呈现 Pod 和容器的字段。

<!--
## The Downward API
There are two ways to expose Pod and Container fields to a running Container:
In Kubernetes, there are two ways to expose Pod and container fields to a running container:
* [Environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
* Volume files
* Volume files, as explained in this task
Together, these two ways of exposing Pod and Container fields are called the
"Downward API".
Together, these two ways of exposing Pod and container fields are called the
_downward API_.
-->
## Downward API {#the-downward-api}

有两种方式可以将 Pod 和 Container 字段呈现给运行中的容器：
在 Kubernetes 中，有两种方式可以将 Pod 和容器字段呈现给运行中的容器：

* [环境变量](/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
* 卷文件
* 本页面所述的卷文件

这两种呈现 Pod 和容器字段的方式都称为 **downward API**。

## {{% heading "prerequisites" %}}

{{< include "task-tutorial-prereqs.md" >}}

这两种呈现 Pod 和 Container 字段的方式都称为 "Downward API"。

<!-- steps -->

<!--
## Store Pod fields
In this exercise, you create a Pod that has one Container.
Here is the configuration file for the Pod:
In this part of exercise, you create a Pod that has one container, and you
project Pod-level fields into the running container as files.
Here is the manifest for the Pod:
-->
## 存储 Pod 字段 {#store-pod-fields}

在这个练习中，你将创建一个包含一个容器的 Pod。Pod 的配置文件如下：
在这部分的练习中，你将创建一个包含一个容器的 Pod，并将 Pod 级别的字段作为文件映射到正在运行的容器中。
Pod 的清单如下：

{{< codenew file="pods/inject/dapi-volume.yaml" >}}

<!--
In the configuration file, you can see that the Pod has a `downwardAPI` Volume,
and the Container mounts the Volume at `/etc/podinfo`.
In the manifest, you can see that the Pod has a `downwardAPI` Volume,
and the container mounts the volume at `/etc/podinfo`.
Look at the `items` array under `downwardAPI`. Each element of the array is a
[DownwardAPIVolumeFile](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core).
Look at the `items` array under `downwardAPI`. Each element of the array
defines a `downwardAPI` volume.
The first element specifies that the value of the Pod's
`metadata.labels` field should be stored in a file named `labels`.
The second element specifies that the value of the Pod's `annotations`
field should be stored in a file named `annotations`.
-->
在配置文件中，你可以看到 Pod 有一个 `downwardAPI` 类型的卷，并且挂载到容器中的
在 Pod 清单中，你可以看到 Pod 有一个 `downwardAPI` 类型的卷，并且挂载到容器中的
`/etc/podinfo` 目录。

查看 `downwardAPI` 下面的 `items` 数组。
每个数组元素都是一个
[DownwardAPIVolumeFile](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
对象。
数组的每个元素定义一个 `downwardAPI` 卷。
第一个元素指示 Pod 的 `metadata.labels` 字段的值保存在名为 `labels` 的文件中。
第二个元素指示 Pod 的 `annotations` 字段的值保存在名为 `annotations` 的文件中。

Expand All @@ -81,7 +78,7 @@ The fields in this example are Pod fields. They are not
fields of the Container in the Pod.
-->
{{< note >}}
本示例中的字段是Pod字段，不是Pod中容器的字段。
本示例中的字段是 Pod 字段，不是 Pod 中容器的字段。
{{< /note >}}

<!--
Expand Down Expand Up @@ -227,47 +224,50 @@ Exit the shell:
```

<!--
## Store Container fields
## Store container fields
The preceding exercise, you stored Pod fields in a
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)..
In this next exercise, you store Container fields. Here is the configuration
file for a Pod that has one Container:
The preceding exercise, you made Pod-level fields accessible using the
downward API.
In this next exercise, you are going to pass fields that are part of the Pod
definition, but taken from the specific
[container](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container)
rather than from the Pod overall. Here is a manifest for a Pod that again has
just one container:
-->
## 存储容器字段 {#store-container-fields}

前面的练习中，你将 Pod 字段保存到
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
中。
接下来这个练习，你将存储 Container 字段。这里是包含一个容器的 Pod 的配置文件：
前面的练习中，你使用 downward API 使 Pod 级别的字段可以被 Pod 内正在运行的容器访问。
接下来这个练习，你将只传递由 Pod 定义的部分的字段到 Pod 内正在运行的容器中，但这些字段取自特定[容器](/zh-cn/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container)而不是整个 Pod。
下面是一个同样只有一个容器的 Pod 的清单：

{{< codenew file="pods/inject/dapi-volume-resources.yaml" >}}

<!--
In the configuration file, you can see that the Pod has a
In the manifest, you can see that the Pod has a
[`downwardAPI` volume](/docs/concepts/storage/volumes/#downwardapi),
and the Container mounts the volume at `/etc/podinfo`.
and that the single container in that Pod mounts the volume at `/etc/podinfo`.
Look at the `items` array under `downwardAPI`. Each element of the array is a
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core).
Look at the `items` array under `downwardAPI`. Each element of the array
defines a file in the downward API volume.
The first element specifies that in the Container named `client-container`,
The first element specifies that in the container named `client-container`,
the value of the `limits.cpu` field in the format specified by `1m` should be
stored in a file named `cpu_limit`. The `divisor` field is optional and has the
default value of `1` which means cores for cpu and bytes for memory.
published as a file named `cpu_limit`. The `divisor` field is optional and has the
default value of `1`. A divisor of 1 means cores for `cpu` resources, or
bytes for `memory` resources.
Create the Pod:
-->
在这个配置文件中，你可以看到 Pod 有一个
在这个清单中，你可以看到 Pod 有一个
[`downwardAPI` 卷](/zh-cn/docs/concepts/storage/volumes/#downwardapi)，
并且挂载到容器的 `/etc/podinfo` 目录。
并且这个会挂载到 Pod 内的单个容器的 `/etc/podinfo` 目录。

查看 `downwardAPI` 下面的 `items` 数组。每个数组元素都是一个
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)。
查看 `downwardAPI` 下面的 `items` 数组。
数组的每个元素定义一个 `downwardAPI` 卷。

第一个元素指定在名为 `client-container` 的容器中，
以 `1m` 所指定格式的 `limits.cpu` 字段的值应保存在名为 `cpu_limit` 的文件中。
`divisor` 字段是可选的，默认值为 `1`，表示 CPU 的核心和内存的字节。
以 `1m` 所指定格式的 `limits.cpu` 字段的值应推送到名为 `cpu_limit` 的文件中。
`divisor` 字段是可选的，默认值为 `1`，1 的除数表示 CPU 资源的核心或内存资源的字节。

创建Pod：

Expand All @@ -290,7 +290,8 @@ In your shell, view the `cpu_limit` file:
在 Shell 中，查看 `cpu_limit` 文件：

```shell
/# cat /etc/podinfo/cpu_limit
# 在容器内的 Shell 中运行
cat /etc/podinfo/cpu_limit
```

<!--
Expand All @@ -301,106 +302,6 @@ You can use similar commands to view the `cpu_request`, `mem_limit` and

<!-- discussion -->

<!-- TODO: This section should be extracted out of the task page. -->
<!--
## Capabilities of the Downward API
-->
## Downward API 的能力 {#capabilities-of-the-downward-api}

<!--
The following information is available to containers through environment
variables and `downwardAPI` volumes:
* Information available via `fieldRef`:
* `metadata.name` - the pod's name
* `metadata.namespace` - the pod's namespace
* `metadata.uid` - the pod's UID
* `metadata.labels['<KEY>']` - the value of the pod's label `<KEY>`
(for example, `metadata.labels['mylabel']`)
* `metadata.annotations['<KEY>']` - the value of the pod's annotation `<KEY>`
(for example, `metadata.annotations['myannotation']`)
-->
下面这些信息可以通过环境变量和 `downwardAPI` 卷提供给容器：

* 能通过 `fieldRef` 获得的：

* `metadata.name` - Pod 名称
* `metadata.namespace` - Pod 名字空间
* `metadata.uid` - Pod 的 UID
* `metadata.labels['<KEY>']` - Pod 标签 `<KEY>` 的值
（例如：`metadata.labels['mylabel']`）
* `metadata.annotations['<KEY>']` - Pod 的注解 `<KEY>` 的值
（例如：`metadata.annotations['myannotation']`）

<!--
* Information available via `resourceFieldRef`:
* A Container's CPU limit
* A Container's CPU request
* A Container's memory limit
* A Container's memory request
* A Container's hugepages limit (provided that the `DownwardAPIHugePages`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
* A Container's hugepages request (provided that the `DownwardAPIHugePages`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
* A Container's ephemeral-storage limit
* A Container's ephemeral-storage request
-->
* 能通过 `resourceFieldRef` 获得的：
* 容器的 CPU 约束值
* 容器的 CPU 请求值
* 容器的内存约束值
* 容器的内存请求值
* 容器的巨页限制值（前提是启用了 `DownwardAPIHugePages`
[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)）
* 容器的巨页请求值（前提是启用了 `DownwardAPIHugePages`
[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)）
* 容器的临时存储约束值
* 容器的临时存储请求值

<!--
In addition, the following information is available through
`downwardAPI` volume `fieldRef`:
-->
此外，以下信息可通过 `downwardAPI` 卷从 `fieldRef` 获得：

<!--
* `metadata.labels` - all of the pod's labels, formatted as `label-key="escaped-label-value"`
with one label per line
* `metadata.annotations` - all of the pod's annotations, formatted as
`annotation-key="escaped-annotation-value"` with one annotation per line
-->
* `metadata.labels` - Pod 的所有标签，以
`label-key="escaped-label-value"` 格式显示，每行显示一个标签
* `metadata.annotations` - Pod 的所有注解，以
`annotation-key="escaped-annotation-value"` 格式显示，每行显示一个标签

<!--
The following information is available through environment variables:
* `status.podIP` - the pod's IP address
* `spec.serviceAccountName` - the pod's service account name
* `spec.nodeName` - the name of the node to which the scheduler always attempts to
schedule the pod
* `status.hostIP` - the IP of the node to which the Pod is assigned
-->
以下信息可通过环境变量获得：

* `status.podIP` - Pod IP 地址
* `spec.serviceAccountName` - Pod 服务帐号名称
* `spec.nodeName` - 调度器总是尝试将 Pod 调度到的节点的名称
* `status.hostIP` - Pod 分配到的节点的 IP

<!--
If CPU and memory limits are not specified for a Container, the
Downward API defaults to the node allocatable value for CPU and memory.
-->
{{< note >}}
如果容器未指定 CPU 和内存限制，则 Downward API 默认将节点可分配值
视为容器的 CPU 和内存限制。
{{< /note >}}

<!--
## Project keys to specific paths and file permissions
Expand All @@ -413,35 +314,15 @@ basis. For more information, see
你可以将键名投射到指定路径并且指定每个文件的访问权限。
更多信息，请参阅 [Secret](/zh-cn/docs/concepts/configuration/secret/)。

<!--
## Motivation for the Downward API
It is sometimes useful for a container to have information about itself, without
being overly coupled to Kubernetes. The Downward API allows containers to consume
information about themselves or the cluster without using the Kubernetes client
or API server.
An example is an existing application that assumes a particular well-known
environment variable holds a unique identifier. One possibility is to wrap the
application, but that is tedious and error prone, and it violates the goal of low
coupling. A better option would be to use the Pod's name as an identifier, and
inject the Pod's name into the well-known environment variable.
-->
## Downward API 的动机 {#motivation-for-the-downward-api}

对于容器来说，有时候拥有自己的信息是很有用的，可避免与 Kubernetes 过度耦合。
Downward API 使得容器使用自己或者集群的信息，而不必通过 Kubernetes 客户端或
API 服务器来获得。

一个例子是有一个现有的应用假定要用一个非常熟悉的环境变量来保存一个唯一标识。
一种可能是给应用增加处理层，但这样是冗余和易出错的，而且它违反了低耦合的目标。
更好的选择是使用 Pod 名称作为标识，把 Pod 名称注入这个环境变量中。

## {{% heading "whatsnext" %}}

<!--
* Check the [`PodSpec`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core)
API definition which defines the desired state of a Pod.
* Read the [`spec`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec)
API definition for Pod. This includes the definition of Container (part of Pod).
* Read the list of [available fields](/docs/concepts/workloads/pods/downward-api/#available-fields) that you
can expose using the downward API.
Read about volumes in the legacy API reference:
* Check the [`Volume`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core)
API definition which defines a generic volume in a Pod for containers to access.
* Check the [`DownwardAPIVolumeSource`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core)
Expand All @@ -452,9 +333,11 @@ API 服务器来获得。
* Check the [`ResourceFieldSelector`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-v1-core)
API definition which specifies the container resources and their output format.
-->
* 参阅
[`PodSpec`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core)
API 定义，该 API 定义 Pod 所需状态。
* 参阅 Pod [`spec`](/zh-cn/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec)
API 的定义，其中包括了容器（Pod 的一部分）的定义。
* 参阅你可以使用 downward API 公开的[可用字段](/zh-cn/docs/concepts/workloads/pods/downward-api/#available-fields)列表。

阅读旧版的 API 参考中关于卷的内容：
* 参阅
[`Volume`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core)
API 定义，该 API 在 Pod 中定义通用卷以供容器访问。
Expand Down

0 comments on commit 44cef08

Please sign in to comment.