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

Revise downward API documentation

Browse Source 
- add a glossary entry
- add a concept page
- revise other documentation in light of above changes
This commit is contained in:
Tim Bannister
2022-03-21 22:29:53 +00:00
parent 6a89b98cc0
commit 7f3604a949
5 changed files with 255 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/tasks/inject-data-application/environment-variable-expose-pod-information.md
+44 -45
View File
@@ -7,50 +7,40 @@ weight: 30
<!-- overview -->
This page shows how a Pod can use environment variables to expose information
about itself to Containers running in the Pod. Environment variables can expose
Pod fields and Container fields.
about itself to containers running in the Pod, using the _downward API_.
You can use environment variables to expose Pod fields, container fields, or both.
In Kubernetes, there are two ways to expose Pod and container fields to a running container:
* _Environment variables_, as explained in this task
* [Volume files](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/)
Together, these two ways of exposing Pod and container fields are called the
downward API.
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
{{< include "task-tutorial-prereqs.md" >}}
<!-- steps -->
## The Downward API
There are two ways to expose Pod and Container fields to a running Container:
* Environment variables
* [Volume Files](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#the-downward-api)
Together, these two ways of exposing Pod and Container fields are called the
*Downward API*.
## Use Pod fields as values for environment variables
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 environment variables.
{{< codenew file="pods/inject/dapi-envars-pod.yaml" >}}
In the configuration file, you can see five environment variables. The `env`
In that manifest, you can see five environment variables. The `env`
field is an array of
[EnvVars](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#envvar-v1-core).
environment variable definitions.
The first element in the array specifies that the `MY_NODE_NAME` environment
variable gets its value from the Pod's `spec.nodeName` field. Similarly, the
other environment variables get their names from Pod fields.
{{< note >}}
The fields in this example are Pod fields. They are not fields of the
Container in the Pod.
container in the Pod.
{{< /note >}}
Create the Pod:
@@ -59,13 +49,14 @@ Create the Pod:
kubectl apply -f https://k8s.io/examples/pods/inject/dapi-envars-pod.yaml
```
Verify that the Container in the Pod is running:
Verify that the container in the Pod is running:
```shell
# If the new Pod isn't yet healthy, rerun this command a few times.
kubectl get pods
```
View the Container's logs:
View the container's logs:
```shell
kubectl logs dapi-envars-fieldref
@@ -82,10 +73,10 @@ default
```
To see why these values are in the log, look at the `command` and `args` fields
in the configuration file. When the Container starts, it writes the values of
in the configuration file. When the container starts, it writes the values of
five environment variables to stdout. It repeats this every ten seconds.
Next, get a shell into the Container that is running in your Pod:
Next, get a shell into the container that is running in your Pod:
```shell
kubectl exec -it dapi-envars-fieldref -- sh
@@ -94,7 +85,8 @@ kubectl exec -it dapi-envars-fieldref -- sh
In your shell, view the environment variables:
```shell
/# printenv
# Run this in a shell inside the container
printenv
```
The output shows that certain environment variables have been assigned the
@@ -111,22 +103,26 @@ MY_NODE_NAME=minikube
MY_POD_NAME=dapi-envars-fieldref
```
## Use Container fields as values for environment variables
## Use container fields as values for environment variables
In the preceding exercise, you used Pod fields as the values for environment
variables. In this next exercise, you use Container fields as the values for
environment variables. Here is the configuration file for a Pod that has one
container:
In the preceding exercise, you used information from Pod-level fields as the values
for environment variables.
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 another Pod that again has just one container:
{{< codenew file="pods/inject/dapi-envars-container.yaml" >}}
In the configuration file, you can see four environment variables. The `env`
In this manifest, you can see four environment variables. The `env`
field is an array of
[EnvVars](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#envvar-v1-core).
environment variable definitions.
The first element in the array specifies that the `MY_CPU_REQUEST` environment
variable gets its value from the `requests.cpu` field of a Container named
variable gets its value from the `requests.cpu` field of a container named
`test-container`. Similarly, the other environment variables get their values
from Container fields.
from fields that are specific to this container.
Create the Pod:
@@ -134,13 +130,14 @@ Create the Pod:
kubectl apply -f https://k8s.io/examples/pods/inject/dapi-envars-container.yaml
```
Verify that the Container in the Pod is running:
Verify that the container in the Pod is running:
```shell
# If the new Pod isn't yet healthy, rerun this command a few times.
kubectl get pods
```
View the Container's logs:
View the container's logs:
```shell
kubectl logs dapi-envars-resourcefieldref
@@ -155,18 +152,20 @@ The output shows the values of selected environment variables:
67108864
```
## {{% heading "whatsnext" %}}
* [Defining Environment Variables for a Container](/docs/tasks/inject-data-application/define-environment-variable-container/)
* Read [Defining Environment Variables for a Container](/docs/tasks/inject-data-application/define-environment-variable-container/)
* 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 Pods, containers and environment variables in the legacy API reference:
* [PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core)
* [Container](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#container-v1-core)
* [EnvVar](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#envvar-v1-core)
* [EnvVarSource](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#envvarsource-v1-core)
* [ObjectFieldSelector](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#objectfieldselector-v1-core)
* [ResourceFieldSelector](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-v1-core)