Move Guide topic to Tasks: Downward API (#2439)

_data/tasks.yml

@@ -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

docs/tasks/configure-pod-container/dapi-volume-resources.yaml

@@ -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
+

docs/tasks/configure-pod-container/dapi-volume.yaml

@@ -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
+

docs/tasks/configure-pod-container/downward-api-volume-expose-pod-information.md

@@ -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 %}
+

docs/tasks/configure-pod-container/environment-variable-expose-pod-information.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 %}
+

docs/tasks/index.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/).
+