Move Guide topic to Tasks: Downward API (#2439)
Steve Perry
GitHub
parent
4dee823504
commit
0da9c85fd4
|
|
@ -16,6 +16,7 @@ toc:
|
|||
- docs/tasks/configure-pod-container/configure-volume-storage.md
|
||||
- docs/tasks/configure-pod-container/configure-persistent-volume-storage.md
|
||||
- docs/tasks/configure-pod-container/environment-variable-expose-pod-information.md
|
||||
- docs/tasks/configure-pod-container/downward-api-volume-expose-pod-information.md
|
||||
- docs/tasks/configure-pod-container/distribute-credentials-secure.md
|
||||
- docs/tasks/configure-pod-container/pull-image-private-registry.md
|
||||
- docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md
|
||||
|
|
|
|||
|
|
@ -0,0 +1,54 @@
|
|||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: kubernetes-downwardapi-volume-example-2
|
||||
spec:
|
||||
containers:
|
||||
- name: client-container
|
||||
image: gcr.io/google_containers/busybox:1.24
|
||||
command: ["sh", "-c"]
|
||||
args:
|
||||
- while true; do
|
||||
echo -en '\n';
|
||||
if [[ -e /etc/cpu_limit ]]; then
|
||||
echo -en '\n'; cat /etc/cpu_limit; fi;
|
||||
if [[ -e /etc/cpu_request ]]; then
|
||||
echo -en '\n'; cat /etc/cpu_request; fi;
|
||||
if [[ -e /etc/mem_limit ]]; then
|
||||
echo -en '\n'; cat /etc/mem_limit; fi;
|
||||
if [[ -e /etc/mem_request ]]; then
|
||||
echo -en '\n'; cat /etc/mem_request; fi;
|
||||
sleep 5;
|
||||
done;
|
||||
resources:
|
||||
requests:
|
||||
memory: "32Mi"
|
||||
cpu: "125m"
|
||||
limits:
|
||||
memory: "64Mi"
|
||||
cpu: "250m"
|
||||
volumeMounts:
|
||||
- name: podinfo
|
||||
mountPath: /etc
|
||||
readOnly: false
|
||||
volumes:
|
||||
- name: podinfo
|
||||
downwardAPI:
|
||||
items:
|
||||
- path: "cpu_limit"
|
||||
resourceFieldRef:
|
||||
containerName: client-container
|
||||
resource: limits.cpu
|
||||
- path: "cpu_request"
|
||||
resourceFieldRef:
|
||||
containerName: client-container
|
||||
resource: requests.cpu
|
||||
- path: "mem_limit"
|
||||
resourceFieldRef:
|
||||
containerName: client-container
|
||||
resource: limits.memory
|
||||
- path: "mem_request"
|
||||
resourceFieldRef:
|
||||
containerName: client-container
|
||||
resource: requests.memory
|
||||
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: kubernetes-downwardapi-volume-example
|
||||
labels:
|
||||
zone: us-est-coast
|
||||
cluster: test-cluster1
|
||||
rack: rack-22
|
||||
annotations:
|
||||
build: two
|
||||
builder: john-doe
|
||||
spec:
|
||||
containers:
|
||||
- name: client-container
|
||||
image: gcr.io/google_containers/busybox
|
||||
command: ["sh", "-c"]
|
||||
args:
|
||||
- while true; do
|
||||
if [[ -e /etc/labels ]]; then
|
||||
echo -en '\n\n'; cat /etc/labels; fi;
|
||||
if [[ -e /etc/annotations ]]; then
|
||||
echo -en '\n\n'; cat /etc/annotations; fi;
|
||||
sleep 5;
|
||||
done;
|
||||
volumeMounts:
|
||||
- name: podinfo
|
||||
mountPath: /etc
|
||||
readOnly: false
|
||||
volumes:
|
||||
- name: podinfo
|
||||
downwardAPI:
|
||||
items:
|
||||
- path: "labels"
|
||||
fieldRef:
|
||||
fieldPath: metadata.labels
|
||||
- path: "annotations"
|
||||
fieldRef:
|
||||
fieldPath: metadata.annotations
|
||||
|
||||
|
|
@ -0,0 +1,242 @@
|
|||
---
|
||||
title: Exposing Pod Information to Containers Using a DownwardApiVolumeFile
|
||||
---
|
||||
|
||||
{% capture 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.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% capture prerequisites %}
|
||||
|
||||
{% include task-tutorial-prereqs.md %}
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
## The Downward API
|
||||
|
||||
There are two ways to expose Pod and Container fields to a running Container:
|
||||
|
||||
* [Environment variables](/docs/tasks/configure-pod-container/environment-variable-expose-pod-information/)
|
||||
* DownwardAPIVolumeFiles
|
||||
|
||||
Together, these two ways of exposing Pod and Container fields are called the
|
||||
*Downward API*.
|
||||
|
||||
## Storing Pod fields
|
||||
|
||||
In this exercise, you create a Pod that has one Container.
|
||||
Here is the configuration file for the Pod:
|
||||
|
||||
{% include code.html language="yaml" file="dapi-volume.yaml" ghlink="/docs/tasks/configure-pod-container/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`.
|
||||
|
||||
Look at the `items` array under `downwardAPI`. Each element of the array is a
|
||||
[DownwardAPIVolumeFile](/docs/resources-reference/v1.5/#downwardapivolumefile-v1).
|
||||
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`.
|
||||
|
||||
**Note**: The fields in this example are Pod fields. They are not
|
||||
fields of the Container in the Pod.
|
||||
|
||||
Create the Pod:
|
||||
|
||||
```shell
|
||||
kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/dapi-volume.yaml
|
||||
```
|
||||
|
||||
Verify that Container in the Pod is running:
|
||||
|
||||
```shell
|
||||
kubectl get pods
|
||||
```
|
||||
|
||||
View the Container's logs:
|
||||
|
||||
```shell
|
||||
kubectl logs kubernetes-downwardapi-volume-example
|
||||
```
|
||||
|
||||
The output shows the contents of the `labels` file and the `annotations` file:
|
||||
|
||||
```shell
|
||||
cluster="test-cluster1"
|
||||
rack="rack-22"
|
||||
zone="us-est-coast"
|
||||
|
||||
build="two"
|
||||
builder="john-doe"
|
||||
```
|
||||
|
||||
Get a shell into the Container that is running in your Pod:
|
||||
|
||||
```
|
||||
kubectl exec -it kubernetes-downwardapi-volume-example -- sh
|
||||
```
|
||||
|
||||
In your shell, view the `labels` file:
|
||||
|
||||
```shell
|
||||
/# cat /etc/labels
|
||||
```
|
||||
|
||||
The output shows that all of the Pod's labels have been written
|
||||
to the `labels` file:
|
||||
|
||||
```shell
|
||||
cluster="test-cluster1"
|
||||
rack="rack-22"
|
||||
zone="us-est-coast"
|
||||
```
|
||||
|
||||
Similarly, view the `annotations` file:
|
||||
|
||||
```shell
|
||||
/# cat /etc/annotations
|
||||
```
|
||||
|
||||
View the files in the `/etc` directory:
|
||||
|
||||
```shell
|
||||
/# ls -laR /etc
|
||||
```
|
||||
|
||||
In the output, you can see that the `labels` and `annotations` files
|
||||
are in a temporary subdirectory: in this example,
|
||||
`..2982_06_02_21_47_53.299460680`. In the `/etc` directory, `..data` is
|
||||
a symbolic link to the temporary subdirectory. Also in the `/etc` directory,
|
||||
`labels` and `annotations` are symbolic links.
|
||||
|
||||
```
|
||||
drwxr-xr-x ... Feb 6 21:47 ..2982_06_02_21_47_53.299460680
|
||||
lrwxrwxrwx ... Feb 6 21:47 ..data -> ..2982_06_02_21_47_53.299460680
|
||||
lrwxrwxrwx ... Feb 6 21:47 annotations -> ..data/annotations
|
||||
lrwxrwxrwx ... Feb 6 21:47 labels -> ..data/labels
|
||||
|
||||
/etc/..2982_06_02_21_47_53.299460680:
|
||||
total 8
|
||||
-rw-r--r-- ... Feb 6 21:47 annotations
|
||||
-rw-r--r-- ... Feb 6 21:47 labels
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
Exit the shell:
|
||||
|
||||
```shell
|
||||
/# exit
|
||||
```
|
||||
|
||||
## Storing Container fields
|
||||
|
||||
The preceding exercise, you stored Pod fields in a DownwardAPIVolumeFile.
|
||||
In this next exercise, you store Container fields. Here is the configuration
|
||||
file for a Pod that has one Container:
|
||||
|
||||
{% include code.html language="yaml" file="dapi-volume-resources.yaml" ghlink="/docs/tasks/configure-pod-container/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`.
|
||||
|
||||
Look at the `items` array under `downwardAPI`. Each element of the array is a
|
||||
DownwardAPIVolumeFile.
|
||||
|
||||
The first element specifies that in the Container named `client-container`,
|
||||
the value of the `limits.cpu` field
|
||||
`metadata.labels` field should be stored in a file named `cpu_limit`.
|
||||
|
||||
Create the Pod:
|
||||
|
||||
```shell
|
||||
kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/dapi-volume-resources.yaml
|
||||
```
|
||||
|
||||
Get a shell into the Container that is running in your Pod:
|
||||
|
||||
```
|
||||
kubectl exec -it kubernetes-downwardapi-volume-example-2 -- sh
|
||||
```
|
||||
|
||||
In your shell, view the `cpu_limit` file:
|
||||
|
||||
```shell
|
||||
/# cat /etc/cpu_limit
|
||||
```
|
||||
You can use similar commands to view the `cpu_request`, `mem_limit` and
|
||||
`mem_request` files.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture discussion %}
|
||||
|
||||
## Capabilities of the Downward API
|
||||
|
||||
The following information is available to Containers through environment
|
||||
variables and DownwardAPIVolumeFiles:
|
||||
|
||||
* The node’s name
|
||||
* The Pod’s name
|
||||
* The Pod’s namespace
|
||||
* The Pod’s IP address
|
||||
* The Pod’s service account name
|
||||
* A Container’s CPU limit
|
||||
* A container’s CPU request
|
||||
* A Container’s memory limit
|
||||
* A Container’s memory request
|
||||
|
||||
In addition, the following information is available through
|
||||
DownwardAPIVolumeFiles.
|
||||
|
||||
* The Pod's labels
|
||||
* The Pod's annotations
|
||||
|
||||
**Note**: If CPU and memory limits are not specified for a Container, the
|
||||
Downward API defaults to the node allocatable value for CPU and memory.
|
||||
|
||||
## Projecting keys to specific paths and file permissions
|
||||
|
||||
You can project keys to specific paths and specific permissions on a per-file
|
||||
basis. For more information, see
|
||||
[Secrets](/docs/user-guide/secrets/).
|
||||
|
||||
## 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.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% capture whatsnext %}
|
||||
|
||||
* [PodSpec](/docs/resources-reference/v1.5/#podspec-v1)
|
||||
* [Volume](/docs/resources-reference/v1.5/#volume-v1)
|
||||
* [DownwardAPIVolumeSource](/docs/resources-reference/v1.5/#downwardapivolumesource-v1)
|
||||
* [DownwardAPIVolumeFile](/docs/resources-reference/v1.5/#downwardapivolumefile-v1)
|
||||
* [ResourceFieldSelector](/docs/resources-reference/v1.5/#resourcefieldselector-v1)
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
|
||||
|
|
@ -26,6 +26,17 @@ Together, these two ways of exposing Pod and Container fields are called the
|
|||
|
||||
{% capture steps %}
|
||||
|
||||
## The Downward API
|
||||
|
||||
There are two ways to expose Pod and Container fields to a running Container:
|
||||
|
||||
* Environment variables
|
||||
* [DownwardAPIVolumeFiles](/docs/resources-reference/v1.5/#downwardapivolumefile-v1)
|
||||
|
||||
Together, these two ways of exposing Pod and Container fields are called the
|
||||
*Downward API*.
|
||||
|
||||
|
||||
## Using Pod fields as values for environment variables
|
||||
|
||||
In this exercise, you create a Pod that has one Container. Here is the
|
||||
|
|
@ -161,3 +172,4 @@ The output shows the values of selected environment variables:
|
|||
|
||||
|
||||
{% include templates/task.md %}
|
||||
|
||||
|
|
|
|||
|
|
@ -12,6 +12,8 @@ single thing, typically by giving a short sequence of steps.
|
|||
* [Defining a Command and Arguments for a Container](/docs/tasks/configure-pod-container/define-command-argument-container/)
|
||||
* [Assigning CPU and RAM Resources to a Container](/docs/tasks/configure-pod-container/assign-cpu-ram-container/)
|
||||
* [Configuring a Pod to Use a Volume for Storage](/docs/tasks/configure-pod-container/configure-volume-storage/)
|
||||
* [Exposing Pod Information to Containers Through Environment Variables](/docs/tasks/configure-pod-container/environment-variable-expose-pod-information/)
|
||||
* [Exposing Pod Information to Containers Using a DownwardAPIVolumeFile](/docs/tasks/configure-pod-container/downward-api-volume-expose-pod-information/)
|
||||
* [Distributing Credentials Securely](/docs/tasks/configure-pod-container/distribute-credentials-secure/)
|
||||
* [Pulling an Image from a Private Registry](/docs/tasks/configure-pod-container/pull-image-private-registry/)
|
||||
* [Configuring Liveness and Readiness Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
|
||||
|
|
@ -55,3 +57,4 @@ single thing, typically by giving a short sequence of steps.
|
|||
|
||||
If you would like to write a task page, see
|
||||
[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue