whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tweak the downward API volume task page

Browse Source 
This PR drops some outdated information about very old Kubernetes versions.
The last section is improved so that readers get a better idea why those pointers are provided.
This commit is contained in:
Qiming Teng
2022-03-13 21:08:39 +08:00
parent 1159c42559
commit 6149835647
1 changed files with 50 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md
+50 -46
View File
@@ -6,20 +6,15 @@ weight: 40
<!-- overview --> <!-- overview -->
This page shows how a Pod can use a DownwardAPIVolumeFile to expose information This page shows how a Pod can use a
about itself to Containers running in the Pod. A DownwardAPIVolumeFile can expose [`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
Pod fields and Container fields. to expose information about itself to Containers running in the Pod.
A `DownwardAPIVolumeFile` can expose Pod fields and Container fields.
## {{% heading "prerequisites" %}} ## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
<!-- steps --> <!-- steps -->
## The Downward API ## The Downward API
@@ -27,10 +22,10 @@ Pod fields and Container fields.
There are two ways to expose Pod and Container fields to a running Container: 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) * [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 Together, these two ways of exposing Pod and Container fields are called the
*Downward API*. "Downward API".
## Store Pod fields ## Store Pod fields
@@ -60,13 +55,13 @@ Create the Pod:
kubectl apply -f https://k8s.io/examples/pods/inject/dapi-volume.yaml 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:
```shell ```shell
kubectl get pods kubectl get pods
``` ```
View the Container's logs: View the container's logs:
```shell ```shell
kubectl logs kubernetes-downwardapi-volume-example kubectl logs kubernetes-downwardapi-volume-example
@@ -83,7 +78,7 @@ build="two"
builder="john-doe" 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:
```shell ```shell
kubectl exec -it kubernetes-downwardapi-volume-example -- sh kubectl exec -it kubernetes-downwardapi-volume-example -- sh
@@ -136,8 +131,7 @@ total 8
Using symbolic links enables dynamic atomic refresh of the metadata; updates are Using symbolic links enables dynamic atomic refresh of the metadata; updates are
written to a new temporary directory, and the `..data` symlink is updated written to a new temporary directory, and the `..data` symlink is updated
atomically using 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).
{{< note >}} {{< note >}}
A container using Downward API as a A container using Downward API as a
@@ -153,17 +147,19 @@ Exit the shell:
## Store Container fields ## Store Container fields
The preceding exercise, you stored Pod fields in a DownwardAPIVolumeFile. 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 In this next exercise, you store Container fields. Here is the configuration
file for a Pod that has one Container: file for a Pod that has one Container:
{{< codenew file="pods/inject/dapi-volume-resources.yaml" >}} {{< codenew file="pods/inject/dapi-volume-resources.yaml" >}}
In the configuration file, you can see that the Pod has a `downwardAPI` Volume, In the configuration file, you can see that the Pod has a
and the Container mounts the Volume at `/etc/podinfo`. [`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 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 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 the value of the `limits.cpu` field in the format specified by `1m` should be
@@ -176,7 +172,7 @@ Create the Pod:
kubectl apply -f https://k8s.io/examples/pods/inject/dapi-volume-resources.yaml 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 ```shell
kubectl exec -it kubernetes-downwardapi-volume-example-2 -- sh kubectl exec -it kubernetes-downwardapi-volume-example-2 -- sh
@@ -187,46 +183,56 @@ In your shell, view the `cpu_limit` file:
```shell ```shell
/# cat /etc/podinfo/cpu_limit /# cat /etc/podinfo/cpu_limit
``` ```
You can use similar commands to view the `cpu_request`, `mem_limit` and You can use similar commands to view the `cpu_request`, `mem_limit` and
`mem_request` files. `mem_request` files.
<!-- discussion --> <!-- discussion -->
<!-- TODO: This section should be extracted out of the task page. -->
## Capabilities of the Downward API ## Capabilities of the Downward API
The following information is available to containers through environment The following information is available to containers through environment
variables and `downwardAPI` volumes: variables and `downwardAPI` volumes:
* Information available via `fieldRef`: * Information available via `fieldRef`:
* `metadata.name` - the pod's name * `metadata.name` - the pod's name
* `metadata.namespace` - the pod's namespace * `metadata.namespace` - the pod's namespace
* `metadata.uid` - the pod's UID * `metadata.uid` - the pod's UID
* `metadata.labels['<KEY>']` - the value of the pod's label `<KEY>` (for example, `metadata.labels['mylabel']`) * `metadata.labels['<KEY>']` - the value of the pod's label `<KEY>`
* `metadata.annotations['<KEY>']` - the value of the pod's annotation `<KEY>` (for example, `metadata.annotations['myannotation']`) (for example, `metadata.labels['mylabel']`)
* `metadata.annotations['<KEY>']` - the value of the pod's annotation `<KEY>`
(for example, `metadata.annotations['myannotation']`)
* Information available via `resourceFieldRef`: * Information available via `resourceFieldRef`:
* A Container's CPU limit * A Container's CPU limit
* A Container's CPU request * A Container's CPU request
* A Container's memory limit * A Container's memory limit
* A Container's memory request * 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 limit (provided that the `DownwardAPIHugePages`
* A Container's hugepages request (providing that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) [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 limit
* A Container's ephemeral-storage request * A Container's ephemeral-storage request
In addition, the following information is available through In addition, the following information is available through
`downwardAPI` volume `fieldRef`: `downwardAPI` volume `fieldRef`:
* `metadata.labels` - all of the pod's labels, formatted as `label-key="escaped-label-value"` with one label per line * `metadata.labels` - all of the pod's labels, formatted as `label-key="escaped-label-value"`
* `metadata.annotations` - all of the pod's annotations, formatted as `annotation-key="escaped-annotation-value"` with one annotation per line 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
The following information is available through environment variables: The following information is available through environment variables:
* `status.podIP` - the pod's IP address * `status.podIP` - the pod's IP address
* `spec.serviceAccountName` - the pod's service account name, available since v1.4.0-alpha.3 * `spec.serviceAccountName` - the pod's service account name
* `spec.nodeName` - the node's name, available since v1.4.0-alpha.3 * `spec.nodeName` - the name of the node to which the scheduler always attempts to
* `status.hostIP` - the node's IP, available since v1.7.0-alpha.1 schedule the pod
* `status.hostIP` - the IP of the node to which the Pod is assigned
{{< note >}} {{< note >}}
If CPU and memory limits are not specified for a Container, the If CPU and memory limits are not specified for a Container, the
@@ -241,7 +247,7 @@ basis. For more information, see
## Motivation for the Downward API ## 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 being overly coupled to Kubernetes. The Downward API allows containers to consume
information about themselves or the cluster without using the Kubernetes client information about themselves or the cluster without using the Kubernetes client
or API server. or API server.
@@ -252,19 +258,17 @@ 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 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. inject the Pod's name into the well-known environment variable.
## {{% heading "whatsnext" %}} ## {{% heading "whatsnext" %}}
* Check the [`PodSpec`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core)
* [PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core) API definition which defines the desired state of a Pod.
* [Volume](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core) * Check the [`Volume`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core)
* [DownwardAPIVolumeSource](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core) API definition which defines a generic volume in a Pod for containers to access.
* [DownwardAPIVolumeFile](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core) * Check the [`DownwardAPIVolumeSource`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core)
* [ResourceFieldSelector](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-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.