Skip to content

Commit 3a0d817

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #32400 from sftim/20220321_document_downward_api_concept
Revise downward API documentation
2 parents 5050bed + 7f3604a commit 3a0d817

File tree

5 files changed

+252
-147
lines changed

5 files changed

+252
-147
lines changed

‎content/en/docs/concepts/storage/volumes.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -303,15 +303,17 @@ keyed with `log_level`.
303303

304304
### downwardAPI {#downwardapi}
305305

306-
A `downwardAPI` volume makes downward API data available to applications.
307-
It mounts a directory and writes the requested data in plain text files.
306+
A `downwardAPI` volume makes {{< glossary_tooltip term_id="downward-api" text="downward API" >}}
307+
data available to applications. Within the volume, you can find the exposed
308+
data as read-only files in plain text format.
308309

309310
{{< note >}}
310-
A container using the downward API as a [`subPath`](#using-subpath) volume mount will not
311-
receive downward API updates.
311+
A container using the downward API as a [`subPath`](#using-subpath) volume mount does not
312+
receive updates when field values change.
312313
{{< /note >}}
313314

314-
See the [downward API example](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/) for more details.
315+
See [Expose Pod Information to Containers Through Files](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
316+
to learn more.
315317

316318
### emptyDir {#emptydir}
317319

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: Downward API
3+
content_type: concept
4+
description: >
5+
There are two ways to expose Pod and container fields to a running container:
6+
environment variables, and as files that are populated by a special volume type.
7+
Together, these two ways of exposing Pod and container fields are called the downward API.
8+
---
9+
10+
<!-- overview -->
11+
12+
It is sometimes useful for a container to have information about itself, without
13+
being overly coupled to Kubernetes. The _downward API_ allows containers to consume
14+
information about themselves or the cluster without using the Kubernetes client
15+
or API server.
16+
17+
An example is an existing application that assumes a particular well-known
18+
environment variable holds a unique identifier. One possibility is to wrap the
19+
application, but that is tedious and error prone, and it violates the goal of low
20+
coupling. A better option would be to use the Pod's name as an identifier, and
21+
inject the Pod's name into the well-known environment variable.
22+
23+
In Kubernetes, there are two ways to expose Pod and container fields to a running container:
24+
25+
* as [environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
26+
* as [files in a `downwardAPI` volume](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
27+
28+
Together, these two ways of exposing Pod and container fields are called the
29+
_downward API_.
30+
31+
<!-- body -->
32+
33+
## Available fields
34+
35+
Only some Kubernetes API fields are available through the downward API. This
36+
section lists which fields you can make available.
37+
38+
You can pass information from available Pod-level fields using `fieldRef`.
39+
At the API level, the `spec` for a Pod always defines at least one
40+
[Container](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container).
41+
You can pass information from available Container-level fields using
42+
`resourceFieldRef`.
43+
44+
### Information available via `fieldRef` {#downwardapi-fieldRef}
45+
46+
For most Pod-level fields, you can provide them to a container either as
47+
an environment variable or using a `downwardAPI` volume. The fields available
48+
via either mechanism are:
49+
50+
`metadata.name`
51+
: the pod's name
52+
53+
`metadata.namespace`
54+
: the pod's {{< glossary_tooltip text="namespace" term_id="namespace" >}}
55+
56+
`metadata.uid`
57+
: the pod's unique ID
58+
59+
`metadata.annotations['<KEY>']`
60+
: the value of the pod's {{< glossary_tooltip text="annotation" term_id="annotation" >}} named `<KEY>` (for example, `metadata.annotations['myannotation']`)
61+
62+
`metadata.labels['<KEY>']`
63+
: the text value of the pod's {{< glossary_tooltip text="label" term_id="label" >}} named `<KEY>` (for example, `metadata.labels['mylabel']`)
64+
65+
`spec.serviceAccountName`
66+
: the name of the pod's {{< glossary_tooltip text="service account" term_id="service-account" >}}
67+
68+
`spec.nodeName`
69+
: the name of the {{< glossary_tooltip term_id="node" text="node">}} where the Pod is executing
70+
71+
`status.hostIP`
72+
: the primary IP address of the node to which the Pod is assigned
73+
74+
`status.podIP`
75+
: the pod's primary IP address (usually, its IPv4 address)
76+
77+
In addition, the following information is available through
78+
a `downwardAPI` volume `fieldRef`, but **not as environment variables**:
79+
80+
`metadata.labels`
81+
: all of the pod's labels, formatted as `label-key="escaped-label-value"` with one label per line
82+
83+
`metadata.annotations`
84+
: all of the pod's annotations, formatted as `annotation-key="escaped-annotation-value"` with one annotation per line
85+
86+
### Information available via `resourceFieldRef` {#downwardapi-resourceFieldRef}
87+
88+
These container-level fields allow you to provide information about
89+
[requests and limits](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)
90+
for resources such as CPU and memory.
91+
92+
93+
`resource: limits.cpu`
94+
: A container's CPU limit
95+
96+
`resource: requests.cpu`
97+
: A container's CPU request
98+
99+
`resource: limits.memory`
100+
: A container's memory limit
101+
102+
`resource: requests.memory`
103+
: A container's memory request
104+
105+
`resource: limits.hugepages-*`
106+
: A container's hugepages limit (provided that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
107+
108+
`resource: requests.hugepages-*`
109+
: A container's hugepages request (provided that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
110+
111+
`resource: limits.ephemeral-storage`
112+
: A container's ephemeral-storage limit
113+
114+
`resource: requests.ephemeral-storage`
115+
: A container's ephemeral-storage request
116+
117+
#### Fallback information for resource limits
118+
119+
If CPU and memory limits are not specified for a container, and you use the
120+
downward API to try to expose that information, then the
121+
kubelet defaults to exposing the maximum allocatable value for CPU and memory
122+
(based on the [node allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)
123+
calculation).
124+
125+
## {{% heading "whatsnext" %}}
126+
127+
You can read about [`downwardAPI` volumes](/docs/concepts/storage/volumes/#downwardapi).
128+
129+
You can try using the downward API to expose container- or Pod-level information:
130+
* as [environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
131+
* as [files in `downwardAPI` volume](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)

‎content/en/docs/reference/glossary/downward-api.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Downward API
3+
id: downward-api
4+
date: 2022-03-21
5+
short_description: >
6+
A mechanism to expose Pod and container field values to code running in a container.
7+
aka:
8+
full_link: /docs/concepts/workloads/pods/downward-api/
9+
tags:
10+
- architecture
11+
---
12+
Kubernetes' mechanism to expose Pod and container field values to code running in a container.
13+
<!--more-->
14+
It is sometimes useful for a container to have information about itself, without
15+
needing to make changes to the container code that directly couple it to Kubernetes.
16+
17+
The Kubernetes downward API allows containers to consume information about themselves
18+
or their context in a Kubernetes cluster. Applications in containers can have
19+
access to that information, without the application needing to act as a client of
20+
the Kubernetes API.
21+
22+
There are two ways to expose Pod and container fields to a running container:
23+
24+
- using [environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/)
25+
- using [a `downwardAPI` volume](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
26+
27+
Together, these two ways of exposing Pod and container fields are called the _downward API_.
28+

‎content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md

Lines changed: 43 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -7,46 +7,46 @@ weight: 40
77
<!-- overview -->
88

99
This page shows how a Pod can use a
10-
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core)
11-
to expose information about itself to Containers running in the Pod.
12-
A `DownwardAPIVolumeFile` can expose Pod fields and Container fields.
10+
[`downwardAPI` volume](/docs/concepts/storage/volumes/#downwardapi),
11+
to expose information about itself to containers running in the Pod.
12+
A `downwardAPI` volume can expose Pod fields and container fields.
1313

14-
## {{% heading "prerequisites" %}}
14+
In Kubernetes, there are two ways to expose Pod and container fields to a running container:
1515

16-
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
16+
* [Environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
17+
* Volume files, as explained in this task
1718

18-
<!-- steps -->
19+
Together, these two ways of exposing Pod and container fields are called the
20+
_downward API_.
1921

20-
## The Downward API
22+
## {{% heading "prerequisites" %}}
2123

22-
There are two ways to expose Pod and Container fields to a running Container:
24+
{{< include "task-tutorial-prereqs.md" >}}
2325

24-
* [Environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api)
25-
* Volume files
2626

27-
Together, these two ways of exposing Pod and Container fields are called the
28-
"Downward API".
27+
<!-- steps -->
2928

3029
## Store Pod fields
3130

32-
In this exercise, you create a Pod that has one Container.
33-
Here is the configuration file for the Pod:
31+
In this part of exercise, you create a Pod that has one container, and you
32+
project Pod-level fields into the running container as files.
33+
Here is the manifest for the Pod:
3434

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

37-
In the configuration file, you can see that the Pod has a `downwardAPI` Volume,
38-
and the Container mounts the Volume at `/etc/podinfo`.
37+
In the manifest, you can see that the Pod has a `downwardAPI` Volume,
38+
and the container mounts the volume at `/etc/podinfo`.
3939

40-
Look at the `items` array under `downwardAPI`. Each element of the array is a
41-
[DownwardAPIVolumeFile](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core).
40+
Look at the `items` array under `downwardAPI`. Each element of the array
41+
defines a `downwardAPI` volume.
4242
The first element specifies that the value of the Pod's
4343
`metadata.labels` field should be stored in a file named `labels`.
4444
The second element specifies that the value of the Pod's `annotations`
4545
field should be stored in a file named `annotations`.
4646

4747
{{< note >}}
4848
The fields in this example are Pod fields. They are not
49-
fields of the Container in the Pod.
49+
fields of the container in the Pod.
5050
{{< /note >}}
5151

5252
Create the Pod:
@@ -145,26 +145,30 @@ Exit the shell:
145145
/# exit
146146
```
147147

148-
## Store Container fields
148+
## Store container fields
149149

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

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

157-
In the configuration file, you can see that the Pod has a
160+
In the manifest, you can see that the Pod has a
158161
[`downwardAPI` volume](/docs/concepts/storage/volumes/#downwardapi),
159-
and the Container mounts the volume at `/etc/podinfo`.
162+
and that the single container in that Pod mounts the volume at `/etc/podinfo`.
160163

161-
Look at the `items` array under `downwardAPI`. Each element of the array is a
162-
[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core).
164+
Look at the `items` array under `downwardAPI`. Each element of the array
165+
defines a file in the downward API volume.
163166

164-
The first element specifies that in the Container named `client-container`,
167+
The first element specifies that in the container named `client-container`,
165168
the value of the `limits.cpu` field in the format specified by `1m` should be
166-
stored in a file named `cpu_limit`. The `divisor` field is optional and has the
167-
default value of `1` which means cores for cpu and bytes for memory.
169+
published as a file named `cpu_limit`. The `divisor` field is optional and has the
170+
default value of `1`. A divisor of 1 means cores for `cpu` resources, or
171+
bytes for `memory` resources.
168172

169173
Create the Pod:
170174

@@ -181,87 +185,29 @@ kubectl exec -it kubernetes-downwardapi-volume-example-2 -- sh
181185
In your shell, view the `cpu_limit` file:
182186

183187
```shell
184-
/# cat /etc/podinfo/cpu_limit
188+
# Run this in a shell inside the container
189+
cat /etc/podinfo/cpu_limit
185190
```
186191

187192
You can use similar commands to view the `cpu_request`, `mem_limit` and
188193
`mem_request` files.
189194

190195
<!-- discussion -->
191196

192-
<!-- TODO: This section should be extracted out of the task page. -->
193-
## Capabilities of the Downward API
194-
195-
The following information is available to containers through environment
196-
variables and `downwardAPI` volumes:
197-
198-
* Information available via `fieldRef`:
199-
200-
* `metadata.name` - the pod's name
201-
* `metadata.namespace` - the pod's namespace
202-
* `metadata.uid` - the pod's UID
203-
* `metadata.labels['<KEY>']` - the value of the pod's label `<KEY>`
204-
(for example, `metadata.labels['mylabel']`)
205-
* `metadata.annotations['<KEY>']` - the value of the pod's annotation `<KEY>`
206-
(for example, `metadata.annotations['myannotation']`)
207-
208-
* Information available via `resourceFieldRef`:
209-
210-
* A Container's CPU limit
211-
* A Container's CPU request
212-
* A Container's memory limit
213-
* A Container's memory request
214-
* A Container's hugepages limit (provided that the `DownwardAPIHugePages`
215-
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
216-
* A Container's hugepages request (provided that the `DownwardAPIHugePages`
217-
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled)
218-
* A Container's ephemeral-storage limit
219-
* A Container's ephemeral-storage request
220-
221-
In addition, the following information is available through
222-
`downwardAPI` volume `fieldRef`:
223-
224-
* `metadata.labels` - all of the pod's labels, formatted as `label-key="escaped-label-value"`
225-
with one label per line
226-
* `metadata.annotations` - all of the pod's annotations, formatted as
227-
`annotation-key="escaped-annotation-value"` with one annotation per line
228-
229-
The following information is available through environment variables:
230-
231-
* `status.podIP` - the pod's IP address
232-
* `spec.serviceAccountName` - the pod's service account name
233-
* `spec.nodeName` - the name of the node to which the scheduler always attempts to
234-
schedule the pod
235-
* `status.hostIP` - the IP of the node to which the Pod is assigned
236-
237-
{{< note >}}
238-
If CPU and memory limits are not specified for a Container, the
239-
Downward API defaults to the node allocatable value for CPU and memory.
240-
{{< /note >}}
241-
242197
## Project keys to specific paths and file permissions
243198

244199
You can project keys to specific paths and specific permissions on a per-file
245200
basis. For more information, see
246201
[Secrets](/docs/concepts/configuration/secret/).
247202

248-
## Motivation for the Downward API
249-
250-
It is sometimes useful for a container to have information about itself, without
251-
being overly coupled to Kubernetes. The Downward API allows containers to consume
252-
information about themselves or the cluster without using the Kubernetes client
253-
or API server.
254-
255-
An example is an existing application that assumes a particular well-known
256-
environment variable holds a unique identifier. One possibility is to wrap the
257-
application, but that is tedious and error prone, and it violates the goal of low
258-
coupling. A better option would be to use the Pod's name as an identifier, and
259-
inject the Pod's name into the well-known environment variable.
260-
261203
## {{% heading "whatsnext" %}}
262204

263-
* Check the [`PodSpec`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core)
264-
API definition which defines the desired state of a Pod.
205+
* Read the [`spec`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec)
206+
API definition for Pod. This includes the definition of Container (part of Pod).
207+
* Read the list of [available fields](/docs/concepts/workloads/pods/downward-api/#available-fields) that you
208+
can expose using the downward API.
209+
210+
Read about volumes in the legacy API reference:
265211
* Check the [`Volume`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core)
266212
API definition which defines a generic volume in a Pod for containers to access.
267213
* Check the [`DownwardAPIVolumeSource`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core)
@@ -271,4 +217,3 @@ inject the Pod's name into the well-known environment variable.
271217
populating a file in the Downward API volume.
272218
* Check the [`ResourceFieldSelector`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-v1-core)
273219
API definition which specifies the container resources and their output format.
274-

0 commit comments

Comments
 (0)