Merge branch 'master' of https://github.com/kubernetes/kubernetes.github.io into release-1.6

* 'master' of https://github.com/kubernetes/kubernetes.github.io: (22 commits) Revert "Document new optional support for ConfigMap and Secret" Revert "mend" modify one word fix typo Fix typos in running zookeeper article Add note about moved content. (#2563) Move Guide topic to Tasks: Downward API (#2439) modify typora fix etcd disaster-recovery hyperlink replace kubernetes.d with kubelet.d remove its name from file content Let's put kubectl in ~/bin. Move Guide toic to Tasks: kubectl exec. Fix travis and add comments Move Pod Lifecycle to Concepts. (#2420) Update deployment completeness documentation rollback PR #2522 kubectl_apply.md-change it for label key Update the links of Deployment User Guide #2534 mark openstack-heat as standalone-salt-conf ... # Conflicts: # docs/user-guide/configmap/index.md
2017-02-17 10:36:54 -08:00
parent 6e9fc80694 4635787521
commit 7673131c02
27 changed files with 876 additions and 579 deletions
@@ -156,7 +156,7 @@ The output is:

 Verify that the replica count is zero:

-    kubectl get deployment --namespace-kube-system
+    kubectl get deployment --namespace=kube-system

 The output displays 0 in the DESIRED and CURRENT columns:

@@ -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/).
+
@@ -0,0 +1,148 @@
+---
+assignees:
+- caesarxuchao
+- mikedanese
+title: Getting a Shell to a Running Container
+---
+
+{% capture overview %}
+
+This page shows how to use `kubectl exec` to get a shell to a
+running Container.
+
+{% endcapture %}
+
+
+{% capture prerequisites %}
+
+{% include task-tutorial-prereqs.md %}
+
+{% endcapture %}
+
+
+{% capture steps %}
+
+## Getting a shell to a Container
+
+In this exercise, you create a Pod that has one Container. The Container
+runs the nginx image. Here is the configuration file for the Pod:
+
+{% include code.html language="yaml" file="shell-demo.yaml" ghlink="/docs/tasks/kubectl/shell-demo.yaml" %}
+
+Create the Pod:
+
+```shell
+kubectl create -f https://k8s.io/docs/tasks/kubectl/shell-demo.yaml
+```
+
+Verify that the Container is running:
+
+```shell
+kubectl get pod shell-demo
+```
+
+Get a shell to the running Container:
+
+```shell
+kubectl exec -it shell-demo -- /bin/bash
+```
+
+In your shell, list the running processes:
+
+```shell
+root@shell-demo:/# ps aux
+```
+
+In your shell, list the nginx processes:
+
+```shell
+root@shell-demo:/# ps aux | grep nginx
+```
+
+In your shell, experiment with other commands. Here are
+some examples:
+
+```shell
+root@shell-demo:/# ls /
+root@shell-demo:/# cat /proc/mounts
+root@shell-demo:/# cat /proc/1/maps
+root@shell-demo:/# apt-get update
+root@shell-demo:/# apt-get install tcpdump
+root@shell-demo:/# tcpdump
+root@shell-demo:/# apt-get install lsof
+root@shell-demo:/# lsof
+```
+
+## Writing the root page for nginx
+
+Look again at the configuration file for your Pod. The Pod
+has an `emptyDir` volume, and the Container mounts the volume
+at `/usr/share/nginx/html`.
+
+In your shell, create an `index.html` file in the `/usr/share/nginx/html`
+directory:
+
+```shell
+root@shell-demo:/# echo Hello shell demo > /usr/share/nginx/html/index.html
+```
+
+In your shell, send a GET request to the nginx server:
+
+```shell
+root@shell-demo:/# apt-get update
+root@shell-demo:/# apt-get install curl
+root@shell-demo:/# curl localhost
+```
+
+The output shows the text that you wrote to the `index.html` file:
+
+```shell
+Hello shell demo
+```
+
+When you are finished with your shell, enter `exit`.
+
+## Running individual commands in a Container
+
+In an ordinary command window, not your shell, list the environment
+variables in the running Container:
+
+```shell
+kubectl exec shell-demo env
+```
+
+Experiment running other commands. Here are some examples:
+
+```shell
+kubectl exec shell-demo ps aux
+kubectl exec shell-demo ls /
+kubectl exec shell-demo cat /proc/1/mounts
+```
+
+{% endcapture %}
+
+{% capture discussion %}
+
+## Opening a shell when a Pod has more than one Container
+
+If a Pod has more than one Container, use `--container` or `-c` to
+specify a Container in the `kubectl exec` command. For example,
+suppose you have a Pod named my-pod, and the Pod has two containers
+named main-app and helper-app. The following command would open a
+shell to the main-app Container.
+
+```shell
+kubectl exec -it my-pod --container main-app -- /bin/bash
+```
+
+{% endcapture %}
+
+
+{% capture whatsnext %}
+
+* [kubectl exec](/docs/user-guide/kubectl/v1.5/#exec)
+
+{% endcapture %}
+
+
+{% include templates/task.md %}
@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: shell-demo
+spec:
+  volumes:
+  - name: shared-data
+    emptyDir: {}
+  containers:
+  - name: nginx
+    image: nginx
+    volumeMounts:
+    - name: shared-data
+      mountPath: /usr/share/nginx/html