Document examples of downward API exposing container resources via

environment variables and volumes.
2016-06-01 16:15:50 -04:00
parent ee396b4439
commit d45e0ce4df
5 changed files with 194 additions and 11 deletions
@@ -0,0 +1,40 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: kubernetes-downwardapi-volume-example
+spec:
+  containers:
+    - name: client-container
+      image: gcr.io/google_containers/busybox:1.24
+      command: ["sh", "-c", "while true; do echo; if [[ -e /etc/cpu_limit ]]; then cat /etc/cpu_limit; fi; if [[ -e /etc/cpu_request ]]; then cat /etc/cpu_request; fi; if [[ -e /etc/mem_limit ]]; then cat /etc/mem_limit; fi; if [[ -e /etc/mem_request ]]; then 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
@@ -2,7 +2,7 @@
 ---

 Following this example, you will create a pod with a downward API volume.
-A downward API volume is a k8s volume plugin with the ability to save some pod information in a plain text file. The pod information can be  for example some [metadata](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#metadata).
+A downward API volume is a k8s volume plugin with the ability to save some pod information in a plain text file. The pod information can be for example some [metadata](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#metadata) or a container's [resources](/docs/user-guide/compute-resources).

 Supported metadata fields:

@@ -11,6 +11,13 @@ Supported metadata fields:
 3. `metadata.name`
 4. `metadata.labels`

+Supported container's resources:
+
+1. `limits.cpu`
+2. `limits.memory`
+3. `requests.cpu`
+4. `requests.memory`
+
 ### Step Zero: Prerequisites

 This example assumes you have a Kubernetes cluster installed and running, and the `kubectl` command line tool somewhere in your path. Please see the [gettingstarted](/docs/getting-started-guides/) for installation instructions for your platform.
@@ -64,3 +71,48 @@ drwxrwxrwt    3 0        0              120 Jun  1 19:55 ..
 ```

 The file `labels` is stored in a temporary directory (`..6986_01_06_15_55_10.473583074` in the example above) which is symlinked to by `..data`. Symlinks for annotations and labels in `/etc` point to files containing the actual metadata through the `..data` indirection.  This structure allows for dynamic atomic refresh of the metadata: updates are written to a new temporary directory, and the `..data` symlink is updated atomically using `rename(2)`.
+
+## Example of downward API volume with container resources
+
+Use the `docs/user-guide/downward-api/volume/dapi-volume-resources.yaml` file to create a Pod with a downward API volume which stores its container's limits and requests in /etc.
+
+```shell
+$ kubectl create -f  docs/user-guide/downward-api/volume/dapi-volume-resources.yaml
+```
+
+### Examine pod/container output
+
+In pod's `/etc` directory one may find the files created by the plugin:
+
+```shell
+$ kubectl exec kubernetes-downwardapi-volume-example -i -t -- sh
+/ # ls -alR /etc
+/etc:
+total 4
+drwxrwxrwt    3 0        0              160 Jun  1 19:47 .
+drwxr-xr-x   17 0        0             4096 Jun  1 19:48 ..
+drwxr-xr-x    2 0        0              120 Jun  1 19:47 ..6986_01_06_15_47_23.076909525
+lrwxrwxrwx    1 0        0               31 Jun  1 19:47 ..data -> ..6986_01_06_15_47_23.076909525
+lrwxrwxrwx    1 0        0               16 Jun  1 19:47 cpu_limit -> ..data/cpu_limit
+lrwxrwxrwx    1 0        0               18 Jun  1 19:47 cpu_request -> ..data/cpu_request
+lrwxrwxrwx    1 0        0               16 Jun  1 19:47 mem_limit -> ..data/mem_limit
+lrwxrwxrwx    1 0        0               18 Jun  1 19:47 mem_request -> ..data/mem_request
+
+/etc/..6986_01_06_15_47_23.076909525:
+total 16
+drwxr-xr-x    2 0        0              120 Jun  1 19:47 .
+drwxrwxrwt    3 0        0              160 Jun  1 19:47 ..
+-rw-r--r--    1 0        0                1 Jun  1 19:47 cpu_limit
+-rw-r--r--    1 0        0                1 Jun  1 19:47 cpu_request
+-rw-r--r--    1 0        0                8 Jun  1 19:47 mem_limit
+-rw-r--r--    1 0        0                8 Jun  1 19:47 mem_request
+
+/ # cat /etc/cpu_limit
+1
+/ # cat /etc/mem_limit
+67108864
+/ # cat /etc/cpu_request
+1
+/ # cat /etc/mem_request
+33554432
+```