[zh] Sync kubelet-credential-provider.md and downward-api-volume-expose-pod-information.md

Signed-off-by: Guangwen Feng <fenggw-fnst@fujitsu.com>
This commit is contained in:
Guangwen Feng
2022-05-24 15:28:15 +08:00
parent 51a87fab44
commit adbf29ff8d
2 changed files with 155 additions and 74 deletions
@@ -7,12 +7,15 @@ weight: 40
<!-- overview -->
<!--
This page shows how a Pod can use a DownwardAPIVolumeFile to expose information
about itself to Containers running in the Pod. A DownwardAPIVolumeFile can expose
Pod fields and Container fields.
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.
-->
此页面描述 Pod 如何使用 DownwardAPIVolumeFile 把自己的信息呈现给 Pod 中运行的容器。
DownwardAPIVolumeFile 可以呈现 Pod 的字段和容器字段。
此页面描述 Pod 如何使用
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
把自己的信息呈现给 Pod 中运行的容器。
`DownwardAPIVolumeFile` 可以呈现 Pod 和容器的字段。
## {{% heading "prerequisites" %}}
@@ -26,16 +29,19 @@ DownwardAPIVolumeFile 可以呈现 Pod 的字段和容器字段。
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
Together, these two ways of exposing Pod and Container fields are called the
"Downward API".
-->
## Downward API
## Downward API {#the-downward-api}
有两种方式可以将 Pod 和 Container 字段呈现给运行中的容器:
* [环境变量](/zh/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
* 卷文件
这两种呈现 Pod 和 Container 字段的方式都称为 *Downward API*
这两种呈现 Pod 和 Container 字段的方式都称为 "Downward API"
<!--
## Store Pod fields
@@ -43,7 +49,7 @@ There are two ways to expose Pod and Container fields to a running Container:
In this exercise, you create a Pod that has one Container.
Here is the configuration file for the Pod:
-->
## 存储 Pod 字段
## 存储 Pod 字段 {#store-pod-fields}
在这个练习中,你将创建一个包含一个容器的 Pod。Pod 的配置文件如下:
@@ -88,7 +94,7 @@ kubectl apply -f https://k8s.io/examples/pods/inject/dapi-volume.yaml
```
<!--
Verify that the Container in the Pod is running:
Verify that the container in the Pod is running:
-->
验证Pod中的容器运行正常:
@@ -97,7 +103,7 @@ kubectl get pods
```
<!--
View the Container's logs:
View the container's logs:
-->
查看容器的日志:
@@ -120,7 +126,7 @@ builder="john-doe"
```
<!--
Get a shell into the Container that is running in your Pod:
Get a shell into the container that is running in your Pod:
-->
进入 Pod 中运行的容器,打开一个 Shell:
@@ -194,11 +200,10 @@ total 8
<!--
Using symbolic links enables dynamic atomic refresh of the metadata; updates are
written to a new temporary directory, and the `..data` symlink is updated
atomically using
[rename(2)](http://man7.org/linux/man-pages/man2/rename.2.html).
atomically using [rename(2)](http://man7.org/linux/man-pages/man2/rename.2.html).
-->
用符号链接可实现元数据的动态原子性刷新;更新将写入一个新的临时目录,
然后通过使用[rename(2)](http://man7.org/linux/man-pages/man2/rename.2.html)
然后通过使用 [rename(2)](http://man7.org/linux/man-pages/man2/rename.2.html)
完成 `..data` 符号链接的原子性更新。
<!--
@@ -218,24 +223,30 @@ Downward API,则该容器无法收到更新事件。
/# exit
```
## 存储容器字段
<!--
The preceding exercise, you stored Pod fields in a DownwardAPIVolumeFile.
## 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:
-->
前面的练习中,你将 Pod 字段保存到 DownwardAPIVolumeFile 中。
## 存储容器字段 {#store-container-fields}
前面的练习中,你将 Pod 字段保存到
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
中。
接下来这个练习,你将存储 Container 字段。这里是包含一个容器的 Pod 的配置文件:
{{< codenew file="pods/inject/dapi-volume-resources.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 configuration file, you can see that the Pod has a
[`downwardAPI` volume](/concepts/storage/volumes/#downwardapi),
and the Container mounts the volume at `/etc/podinfo`.
Look at the `items` array under `downwardAPI`. Each element of the array is a
DownwardAPIVolumeFile.
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core).
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
@@ -244,13 +255,16 @@ default value of `1` which means cores for cpu and bytes for memory.
Create the Pod:
-->
在这个配置文件中,你可以看到 Pod 有一个 `downwardAPI` 类型的卷,并且挂载到容器的
`/etc/podinfo` 目录。
在这个配置文件中,你可以看到 Pod 有一个
[`downwardAPI` 卷](/zh/docs/concepts/storage/volumes/#downwardapi)
并且挂载到容器的 `/etc/podinfo` 目录。
查看 `downwardAPI` 下面的 `items` 数组。每个数组元素都是一个 DownwardAPIVolumeFile。
查看 `downwardAPI` 下面的 `items` 数组。每个数组元素都是一个
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)。
第一个元素指定名为 `client-container` 的容器中 `limits.cpu` 字段的值应保存在名为
`cpu_limit` 的文件中。
第一个元素指定名为 `client-container` 的容器中
`1m` 所指定格式的 `limits.cpu` 字段的值应保存在名为 `cpu_limit` 的文件中。
`divisor` 字段是可选的,默认值为 `1`,表示 CPU 的核心和内存的字节。
创建Pod
@@ -259,7 +273,7 @@ kubectl apply -f https://k8s.io/examples/pods/inject/dapi-volume-resources.yaml
```
<!--
Get a shell into the Container that is running in your Pod:
Get a shell into the container that is running in your Pod:
-->
打开一个 Shell,进入 Pod 中运行的容器:
@@ -283,39 +297,50 @@ You can use similar commands to view the `cpu_request`, `mem_limit` and
你可以使用同样的命令查看 `cpu_request``mem_limit``mem_request` 文件.
<!-- discussion -->
<!-- TODO: This section should be extracted out of the task page. -->
<!--
## Capabilities of the Downward API
-->
## 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']`)
* `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']`
* `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 (providing that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
* A Container's hugepages request (providing that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
* 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
-->
@@ -324,8 +349,10 @@ variables and `downwardAPI` volumes:
* 容器的 CPU 请求值
* 容器的内存约束值
* 容器的内存请求值
* 容器的巨页限制值(前提是启用了 `DownwardAPIHugePages` [特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)
* 容器的巨页请求值(前提是启用了 `DownwardAPIHugePages` [特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)
* 容器的巨页限制值(前提是启用了 `DownwardAPIHugePages`
[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)
* 容器的巨页请求值(前提是启用了 `DownwardAPIHugePages`
[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)
* 容器的临时存储约束值
* 容器的临时存储请求值
@@ -334,23 +361,33 @@ In addition, the following information is available through
`downwardAPI` volume `fieldRef`:
-->
此外,以下信息可通过 `downwardAPI` 卷从 `fieldRef` 获得:
<!--
* `metadata.labels` - all of the pods labels, formatted as `label-key="escaped-label-value"` with one label per line
* `metadata.annotations` - all of the pods annotations, formatted as `annotation-key="escaped-annotation-value"` with one annotation per line
* `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"`
格式显示,每行显示一个标签
* `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` - 节点 IP
* `spec.serviceAccountName` - Pod 服务帐号名称, 版本要求 v1.4.0-alpha.3
* `spec.nodeName` - 节点名称, 版本要求 v1.4.0-alpha.3
* `status.hostIP` - 节点 IP, 版本要求 v1.7.0-alpha.1
* `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
@@ -368,7 +405,7 @@ You can project keys to specific paths and specific permissions on a per-file
basis. For more information, see
[Secrets](/docs/concepts/configuration/secret/).
-->
## 投射键名到指定路径并且指定文件权限
## 投射键名到指定路径并且指定文件权限 {#project-keys-to-specific-paths-and-file-permissions}
你可以将键名投射到指定路径并且指定每个文件的访问权限。
更多信息,请参阅[Secrets](/zh/docs/concepts/configuration/secret/).
@@ -376,7 +413,7 @@ basis. For more information, see
<!--
## Motivation for the Downward API
It is sometimes useful for a Container to have information about itself, without
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.
@@ -387,7 +424,7 @@ application, but that is tedious and error prone, and it violates the goal of lo
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的动机
## Downward API 的动机 {#motivation-for-the-downward-api}
对于容器来说,有时候拥有自己的信息是很有用的,可避免与 Kubernetes 过度耦合。
Downward API 使得容器使用自己或者集群的信息,而不必通过 Kubernetes 客户端或
@@ -399,9 +436,32 @@ API 服务器来获得。
## {{% heading "whatsnext" %}}
* [PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core)
* [Volume](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core)
* [DownwardAPIVolumeSource](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core)
* [DownwardAPIVolumeFile](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
* [ResourceFieldSelector](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-v1-core)
<!--
* Check the [`PodSpec`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core)
API definition which defines the desired state of a Pod.
* 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)
API definition which defines a volume that contains Downward API information.
* Check the [`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
API definition which contains references to object or resource fields for
populating a file in the Downward API volume.
* 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 所需状态。
* 参阅
[`Volume`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core)
API 定义,该 API 在 Pod 中定义通用卷以供容器访问。
* 参阅
[`DownwardAPIVolumeSource`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core)
API 定义,该 API 定义包含 Downward API 信息的卷。
* 参阅
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
API 定义,该 API 包含对对象或资源字段的引用,用于在 Downward API 卷中填充文件。
* 参阅
[`ResourceFieldSelector`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-v1-core)
API 定义,该 API 指定容器资源及其输出格式。
@@ -48,7 +48,7 @@ This guide demonstrates how to configure the kubelet's image credential provider
<!--
* The kubelet image credential provider is introduced in v1.20 as an alpha feature. As with other alpha features,
a feature gate `KubeletCredentialProviders` must be enabled on only the kubelet for the feature to work.
a feature gate `KubeletCredentialProviders` must be enabled on only the kubelet for the feature to work.
* A working implementation of a credential provider exec plugin. You can build your own plugin or use one provided by cloud providers.
-->
* kubelet 镜像凭证提供程序在 v1.20 版本作为 alpha 功能引入。
@@ -73,12 +73,14 @@ every node in your cluster and stored in a known directory. The directory will b
## Configuring the Kubelet
In order to use this feature, the kubelet expects two flags to be set:
* `--image-credential-provider-config` - the path to the credential provider plugin config file.
* `--image-credential-provider-bin-dir` - the path to the directory where credential provider plugin binaries are located.
-->
## 配置 kubelet {#configuring-the-kubelet}
为了使用这个特性,kubelet 需要设置以下两个标志:
* `--image-credential-provider-config` —— 凭据提供程序插件配置文件的路径。
* `--image-credential-provider-bin-dir` —— 凭据提供程序插件二进制文件所在目录的路径。
@@ -86,18 +88,19 @@ In order to use this feature, the kubelet expects two flags to be set:
### Configure a kubelet credential provider
The configuration file passed into `--image-credential-provider-config` is read by the kubelet to determine which exec plugins
should be invoked for which container images. Here's an example configuration file you may end up using if you are using the [ECR](https://aws.amazon.com/ecr/)-based plugin:
should be invoked for which container images. Here's an example configuration file you may end up using if you are using the
[ECR](https://aws.amazon.com/ecr/)-based plugin:
-->
### 配置 kubelet 凭据提供程序 {#configure-a-kubelet-credential-provider}
kubelet 会读取传入 `--image-credential-provider-config` 的配置文件文件
kubelet 会读取传入 `--image-credential-provider-config` 的配置文件,
以确定应该为哪些容器镜像调用哪些 exec 插件。
如果你正在使用基于 [ECR](https://aws.amazon.com/ecr/) 插件,
如果你正在使用基于 [ECR](https://aws.amazon.com/ecr/) 插件,
这里有个样例配置文件你可能最终会使用到:
```yaml
kind: CredentialProviderConfig
apiVersion: kubelet.config.k8s.io/v1alpha1
kind: CredentialProviderConfig
# providers 是将由 kubelet 启用的凭证提供程序插件列表。
# 多个提供程序可能与单个镜像匹配,在这种情况下,来自所有提供程序的凭据将返回到 kubelet。
# 如果为单个镜像调用多个提供程序,则结果会合并。
@@ -130,11 +133,11 @@ providers:
# - *.*.registry.io
# - registry.io:8080/path
matchImages:
- "*.dkr.ecr.*.amazonaws.com"
- "*.dkr.ecr.*.amazonaws.cn"
- "*.dkr.ecr-fips.*.amazonaws.com"
- "*.dkr.ecr.us-iso-east-1.c2s.ic.gov"
- "*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov"
- "*.dkr.ecr.*.amazonaws.com"
- "*.dkr.ecr.*.amazonaws.cn"
- "*.dkr.ecr-fips.*.amazonaws.com"
- "*.dkr.ecr.us-iso-east-1.c2s.ic.gov"
- "*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov"
# defaultCacheDuration 是插件将在内存中缓存凭据的默认持续时间
# 如果插件响应中未提供缓存持续时间。此字段是必需的。
defaultCacheDuration: "12h"
@@ -145,30 +148,36 @@ providers:
# 执行命令时传递给命令的参数。
# +可选
args:
- get-credentials
- get-credentials
# env 定义了额外的环境变量以暴露给进程。
# 这些与主机环境以及 client-go 用于将参数传递给插件的变量结合在一起。
# +可选
env:
- name: AWS_PROFILE
value: example_profile
- name: AWS_PROFILE
value: example_profile
```
<!--
The `providers` field is a list of enabled plugins used by the kubelet. Each entry has a few required fields:
* `name`: the name of the plugin which MUST match the name of the executable binary that exists in the directory passed into `--image-credential-provider-bin-dir`.
* `matchImages`: a list of strings used to match against images in order to determine if this provider should be invoked. More on this below.
* `defaultCacheDuration`: the default duration the kubelet will cache credentials in-memory if a cache duration was not specified by the plugin.
* `apiVersion`: the api version that the kubelet and the exec plugin will use when communicating.
Each credential provider can also be given optional args and environment variables as well. Consult the plugin implementors to determine what set of arguments and environment variables are required for a given plugin.
* `name`: the name of the plugin which MUST match the name of the executable binary that exists
in the directory passed into `--image-credential-provider-bin-dir`.
* `matchImages`: a list of strings used to match against images in order to determine
if this provider should be invoked. More on this below.
* `defaultCacheDuration`: the default duration the kubelet will cache credentials in-memory
if a cache duration was not specified by the plugin.
* `apiVersion`: the API version that the kubelet and the exec plugin will use when communicating.
Each credential provider can also be given optional args and environment variables as well.
Consult the plugin implementors to determine what set of arguments and environment variables are required for a given plugin.
-->
`providers` 字段是 kubelet 使用的已启用插件列表。每个条目都有几个必填字段:
* `name`:插件的名称,必须与传入`--image-credential-provider-bin-dir`
的目录中存在的可执行二进制文件的名称相匹配。
* `matchImages`:用于匹配像以确定是否应调用此提供程序的字符串列表。更多相关信息如下。
* `matchImages`:用于匹配像以确定是否应调用此提供程序的字符串列表。更多相关信息如下。
* `defaultCacheDuration`:如果插件未指定缓存持续时间,kubelet 将在内存中缓存凭据的默认持续时间。
* `apiVersion`kubelet 和 exec 插件在通信时将使用的 api 版本。
* `apiVersion`kubelet 和 exec 插件在通信时将使用的 API 版本。
每个凭证提供程序也可以被赋予可选的参数和环境变量。
咨询插件实现者以确定给定插件需要哪些参数和环境变量集。
@@ -207,8 +216,20 @@ Some example values of `matchImages` patterns are:
* 如果 imageMatch 包含端口,则该端口也必须在镜像中匹配。
`matchImages` 模式的一些示例值:
* `123456789.dkr.ecr.us-east-1.amazonaws.com`
* `*.azurecr.io`
* `gcr.io`
* `*.*.registry.io`
* `foo.registry.io:8080/path`
## {{% heading "whatsnext" %}}
<!--
* Read the details about `CredentialProviderConfig` in the
[kubelet configuration API (v1alpha1) reference](/docs/reference/config-api/kubelet-config.v1alpha1/).
* Read the [kubelet credential provider API reference (v1alpha1)](/docs/reference/config-api/kubelet-credentialprovider.v1alpha1/).
-->
* 阅读 [kubelet 配置 API (v1alpha1) 参考](/zh/docs/reference/config-api/kubelet-config.v1alpha1/)中有关 `CredentialProviderConfig` 的详细信息。
* 阅读 [kubelet 凭据提供程序 API 参考 (v1alpha1)](/docs/reference/config-api/kubelet-credentialprovider.v1alpha1/)。