Merge pull request #273 from janetkuo/update-kubectl-run-follow-up

Further update docs to reflect changes kubectl run

docs/admin/limitrange/index.md

@@ -22,7 +22,7 @@ may be too small to be useful, but big enough for the waste to be costly over th
 the cluster operator may want to set limits that a pod must consume at least 20% of the memory and cpu of their
 average node size in order to provide for more uniform scheduling and to limit waste.
 
-This example demonstrates how limits can be applied to a Kubernetes namespace to control
+This example demonstrates how limits can be applied to a Kubernetes [namespace](/docs/admin/namespaces/walkthrough/) to control
 min/max resource limits per pod.  In addition, this example demonstrates how you can
 apply default resource limits to pods in the absence of an end-user specified value.
 
@@ -41,12 +41,17 @@ This example will work in a custom namespace to demonstrate the concepts involve
 Let's create a new namespace called limit-example:
 
 ```shell
-$ kubectl create -f docs/admin/limitrange/namespace.yaml
+$ kubectl create namespace limit-example
-namespace "limit-example" created
+namespace "limit-example" created
+```
+
+Note that `kubectl` commands will print the type and name of the resource created or mutated, which can then be used in subsequent commands: 
+
+```shell
 $ kubectl get namespaces
-NAME            LABELS    STATUS    AGE
+NAME            STATUS    AGE
-default         <none>    Active    5m
+default         Active    51s
-limit-example   <none>    Active    53s
+limit-example   Active    45s
 ```
 
 ## Step 2: Apply a limit to the namespace
@@ -95,36 +100,45 @@ were previously created in a namespace.
 If a resource (cpu or memory) is being restricted by a limit, the user will get an error at time
 of creation explaining why.
 
-Let's first spin up a deployment that creates a single container pod to demonstrate
+Let's first spin up a [Deployment](/docs/user-guide/deployments) that creates a single container Pod to demonstrate
 how default values are applied to each pod.
 
 ```shell
 $ kubectl run nginx --image=nginx --replicas=1 --namespace=limit-example
 deployment "nginx" created
+```
+
+Note that `kubectl run` creates a Deployment named "nginx" on Kubernetes cluster >= v1.2. If you are running older versions, it creates replication controllers instead.
+If you want to obtain the old behavior, use `--generator=run/v1` to create replication controllers. See [`kubectl run`](/docs/user-guide/kubectl/kubectl_run/) for more details. 
+The Deployment manages 1 replica of single container Pod. Let's take a look at the Pod it manages. First, find the name of the Pod:
+
+```shell 
 $ kubectl get pods --namespace=limit-example
 NAME                     READY     STATUS    RESTARTS   AGE
 nginx-2040093540-s8vzu   1/1       Running   0          11s
-$ kubectl get pods nginx-2040093540-s8vzu --namespace=limit-example -o yaml | grep resources -C 8
 ```
 
-```yaml
+Let's print this Pod with yaml output format (using `-o yaml` flag), and then `grep` the `resources` field. Note that your pod name will be different. 
-  resourceVersion: "127"
+
-  selfLink: /api/v1/namespaces/limit-example/pods/nginx-aq0mf
+``` shell
-  uid: 51be42a7-7156-11e5-9921-286ed488f785
+$ kubectl get pods nginx-2040093540-s8vzu --namespace=limit-example -o yaml | grep resources -C 8
-spec:
+  resourceVersion: "57"
-  containers:
+  selfLink: /api/v1/namespaces/limit-example/pods/nginx-2040093540-ivimu
-  - image: nginx
+  uid: 67b20741-f53b-11e5-b066-64510658e388
-    imagePullPolicy: IfNotPresent
+spec:
-    name: nginx
+  containers:
-    resources:
+  - image: nginx
-      limits:
+    imagePullPolicy: Always
-        cpu: 300m
+    name: nginx
-        memory: 200Mi
+    resources:
-      requests:
+      limits:
-        cpu: 200m
+        cpu: 300m
-        memory: 100Mi
+        memory: 200Mi
-    terminationMessagePath: /dev/termination-log
+      requests:
-    volumeMounts:
+        cpu: 200m
+        memory: 100Mi
+    terminationMessagePath: /dev/termination-log
+    volumeMounts:
 ```
 
 Note that our nginx container has picked up the namespace default cpu and memory resource *limits* and *requests*.
@@ -141,37 +155,39 @@ Let's create a pod that falls within the allowed limit boundaries.
 ```shell
 $ kubectl create -f docs/admin/limitrange/valid-pod.yaml --namespace=limit-example
 pod "valid-pod" created
-$ kubectl get pods valid-pod --namespace=limit-example -o yaml | grep -C 6 resources
 ```
 
-```yaml
+Now look at the Pod's resources field: 
- uid: 162a12aa-7157-11e5-9921-286ed488f785
+
-spec:
+```shell
-  containers:
+$ kubectl get pods valid-pod --namespace=limit-example -o yaml | grep -C 6 resources
-  - image: gcr.io/google_containers/serve_hostname
+  uid: 3b1bfd7a-f53c-11e5-b066-64510658e388
-    imagePullPolicy: IfNotPresent
+spec:
-    name: kubernetes-serve-hostname
+  containers:
-    resources:
+  - image: gcr.io/google_containers/serve_hostname
-      limits:
+    imagePullPolicy: Always
-        cpu: "1"
+    name: kubernetes-serve-hostname
-        memory: 512Mi
+    resources:
-      requests:
+      limits:
-        cpu: "1"
+        cpu: "1"
-        memory: 512Mi
+        memory: 512Mi
+      requests:
+        cpu: "1"
+        memory: 512Mi
 ```
 
 Note that this pod specifies explicit resource *limits* and *requests* so it did not pick up the namespace
 default values.
 
-Note: The *limits* for CPU resource are not enforced in the default Kubernetes setup on the physical node
+Note: The *limits* for CPU resource are enforced in the default Kubernetes setup on the physical node
 that runs the container unless the administrator deploys the kubelet with the folllowing flag:
 
 ```shell
 $ kubelet --help
 Usage of kubelet
 ....
-  --cpu-cfs-quota[=false]: Enable CPU CFS quota enforcement for containers that specify CPU limits
+  --cpu-cfs-quota[=true]: Enable CPU CFS quota enforcement for containers that specify CPU limits
-$ kubelet --cpu-cfs-quota=true ...
+$ kubelet --cpu-cfs-quota=false ...
 ```
 
 ## Step 4: Cleanup
@@ -182,8 +198,8 @@ To remove the resources used by this example, you can just delete the limit-exam
 $ kubectl delete namespace limit-example
 namespace "limit-example" deleted
 $ kubectl get namespaces
-NAME      LABELS    STATUS    AGE
+NAME            STATUS        AGE
-default   <none>    Active    20m
+default         Active        12m
 ```
 
 ## Summary

docs/admin/namespaces/index.md

@@ -142,4 +142,4 @@ across namespaces, you need to use the fully qualified domain name (FQDN).
 ## Design
 
 Details of the design of namespaces in Kubernetes, including a [detailed example](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/namespaces.md#example-openshift-origin-managing-a-kubernetes-namespace)
-can be found in the [namespaces design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/namespaces.md)
+can be found in the [namespaces design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/namespaces.md)

docs/admin/namespaces/walkthrough.md

@@ -28,8 +28,8 @@ Assuming you have a fresh cluster, you can introspect the available namespace's
 
 ```shell
 $ kubectl get namespaces
-NAME                LABELS
+NAME      STATUS    AGE
-default             <none>
+default   Active    13m
 ```
 
 ### Step Two: Create new namespaces
@@ -43,7 +43,7 @@ they use to build and run their application.  In this space, Kubernetes resource
 are relaxed to enable agile development.
 
 The operations team would like to maintain a space in the cluster where they can enforce strict procedures on who can or cannot manipulate the set of
-pods, services, and Deployments that run the production site.
+Pods, Services, and Deployments that run the production site.
 
 One pattern this organization could follow is to partition the Kubernetes cluster into two namespaces: development and production.
 
@@ -68,11 +68,11 @@ $ kubectl create -f docs/admin/namespaces/namespace-prod.json
 To be sure things are right, let's list all of the namespaces in our cluster.
 
 ```shell
-$ kubectl get namespaces
+$ kubectl get namespaces --show-labels
-NAME          LABELS             STATUS
+NAME          STATUS    AGE       LABELS
-default       <none>             Active
+default       Active    32m       <none>
-development   name=development   Active
+development   Active    29s       name=development
-production    name=production    Active
+production    Active    23s       name=production
 ```
 
 ### Step Three: Create pods in each namespace
@@ -85,7 +85,8 @@ To demonstrate this, let's spin up a simple Deployment and Pods in the developme
 
 We first check what is the current context:
 
-```yaml
+```shell
+$ kubectl config view
 apiVersion: v1
 clusters:
 - cluster:
@@ -110,6 +111,9 @@ users:
   user:
     password: h5M0FtUUIflBSdI7
     username: admin
+
+$ kubectl config current-context
+lithe-cocoa-92103_kubernetes
 ```
 
 The next step is to define a context for the kubectl client to work in each namespace. The value of "cluster" and "user" fields are copied from the current context.
@@ -131,44 +135,8 @@ $ kubectl config use-context dev
 You can verify your current context by doing the following:
 
 ```shell
-$ kubectl config view
+$ kubectl config current-context
-```
+dev
-
-```yaml
-apiVersion: v1
-clusters:
-- cluster:
-    certificate-authority-data: REDACTED
-    server: https://130.211.122.180
-  name: lithe-cocoa-92103_kubernetes
-contexts:
-- context:
-    cluster: lithe-cocoa-92103_kubernetes
-    namespace: development
-    user: lithe-cocoa-92103_kubernetes
-  name: dev
-- context:
-    cluster: lithe-cocoa-92103_kubernetes
-    user: lithe-cocoa-92103_kubernetes
-  name: lithe-cocoa-92103_kubernetes
-- context:
-    cluster: lithe-cocoa-92103_kubernetes
-    namespace: production
-    user: lithe-cocoa-92103_kubernetes
-  name: prod
-current-context: dev
-kind: Config
-preferences: {}
-users:
-- name: lithe-cocoa-92103_kubernetes
-  user:
-    client-certificate-data: REDACTED
-    client-key-data: REDACTED
-    token: 65rZW78y8HbwXXtSXuUw9DbP4FLjHi4b
-- name: lithe-cocoa-92103_kubernetes-basic-auth
-  user:
-    password: h5M0FtUUIflBSdI7
-    username: admin
 ```
 
 At this point, all requests we make to the Kubernetes cluster from the command line are scoped to the development namespace.
@@ -180,6 +148,7 @@ $ kubectl run snowflake --image=kubernetes/serve_hostname --replicas=2
 ```
 We have just created a deployment whose replica size is 2 that is running the pod called snowflake with a basic container that just serves the hostname. 
 Note that `kubectl run` creates deployments only on kubernetes cluster >= v1.2. If you are running older versions, it creates replication controllers instead.
+If you want to obtain the old behavior, use `--generator=run/v1` to create replication controllers. See [`kubectl run`](/docs/user-guide/kubectl/kubectl_run/) for more details. 
 
 ```shell
 $ kubectl get deployment

docs/admin/resourcequota/index.md

@@ -151,4 +151,4 @@ See a [detailed example for how to use resource quota](/docs/admin/resourcequota
 
 ## Read More
 
-See [ResourceQuota design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/admission_control_resource_quota.md) for more information.
+See [ResourceQuota design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/admission_control_resource_quota.md) for more information.

docs/admin/resourcequota/walkthrough.md

@@ -14,12 +14,17 @@ This example will work in a custom namespace to demonstrate the concepts involve
 Let's create a new namespace called quota-example:
 
 ```shell
-$ kubectl create -f docs/admin/resourcequota/namespace.yaml
+$ kubectl create namespace quota-example
 namespace "quota-example" created
+```
+
+Note that `kubectl` commands will print the type and name of the resource created or mutated, which can then be used in subsequent commands: 
+
+```shell
 $ kubectl get namespaces
-NAME            LABELS    STATUS    AGE
+NAME            STATUS    AGE
-default         <none>    Active    2m
+default         Active    50m
-quota-example   <none>    Active    39s
+quota-example   Active    2s
 ```
 
 ## Step 2: Apply a quota to the namespace
@@ -85,6 +90,7 @@ NAME      READY     STATUS    RESTARTS   AGE
 
 What happened?  I have no pods!  Let's describe the ReplicaSet managed by the nginx Deployment to get a view of what is happening.
 Note that `kubectl describe rs` works only on kubernetes cluster >= v1.2. If you are running older versions, use `kubectl describe rc` instead.
+If you want to obtain the old behavior, use `--generator=run/v1` to create replication controllers. See [`kubectl run`](/docs/user-guide/kubectl/kubectl_run/) for more details. 
 
 ```shell
 $ kubectl describe rs -l run=nginx --namespace=quota-example

docs/user-guide/debugging-services.md

@@ -40,37 +40,27 @@ OUTPUT
 ## Running commands in a Pod
 
 For many steps here you will want to see what a `Pod` running in the cluster
-sees.  Kubernetes does not directly support interactive `Pod`s (yet), but you can
+sees.  You can start a busybox `Pod` and run commands in it:
-approximate it:
 
 ```shell
-$ cat <<EOF | kubectl create -f -
+$ kubectl run -i --tty busybox --image=busybox --generator="run-pod/v1"
-apiVersion: v1
+Waiting for pod default/busybox to be running, status is Pending, pod ready: false
-kind: Pod
+
-metadata:
+Hit enter for command prompt
-  name: busybox-sleep
+
-spec:
+/ #
-  containers:
-  - name: busybox
-    image: busybox
-    args:
-    - sleep
-    - "1000000"
-EOF
-pods/busybox-sleep
 ```
 
-Now, when you need to run a command (even an interactive shell) in a `Pod`-like
+If you already have a running `Pod`, run a command in it using:
-context, use:
 
 ```shell
-$ kubectl exec busybox-sleep -- <COMMAND>
+$ kubectl exec <POD-NAME> -c <CONTAINER-NAME> -- <COMMAND>
 ```
 
-or
+or run an interactive shell with:
 
 ```shell
-$ kubectl exec -ti busybox-sleep sh
+$ kubectl exec -ti <POD-NAME> -c <CONTAINER-NAME> sh
 / #
 ```
 
@@ -88,6 +78,7 @@ $ kubectl run hostnames --image=gcr.io/google_containers/serve_hostname \
 deployment "hostnames" created
 ```
 
+`kubectl` commands will print the type and name of the resource created or mutated, which can then be used in subsequent commands. 
 Note that this is the same as if you had started the `Deployment` with
 the following YAML:
 

docs/user-guide/docker-cli-to-kubectl.md

@@ -26,6 +26,13 @@ With kubectl:
 # start the pod running nginx
 $ kubectl run --image=nginx nginx-app --port=80 --env="DOMAIN=cluster"
 deployment "nginx-app" created
+```
+
+`kubectl run` creates a Deployment named "nginx" on Kubernetes cluster >= v1.2. If you are running older versions, it creates replication controllers instead.
+If you want to obtain the old behavior, use `--generator=run/v1` to create replication controllers. See [`kubectl run`](/docs/user-guide/kubectl/kubectl_run/) for more details. 
+Note that `kubectl` commands will print the type and name of the resource created or mutated, which can then be used in subsequent commands. Now, we can expose a new Service with the deployment created above:
+
+```shell
 # expose a port through with a service
 $ kubectl expose deployment nginx-app --port=80 --name=nginx-http
 service "nginx-http" exposed

docs/user-guide/pods/single-container.md

@@ -35,6 +35,7 @@ $ kubectl run NAME
 
 Where:
 
+* `kubectl run` creates a Deployment named "nginx" on Kubernetes cluster >= v1.2. If you are running older versions, it creates replication controllers instead. If you want to obtain the old behavior, use `--generator=run/v1` to create replication controllers. See [`kubectl run`](/docs/user-guide/kubectl/kubectl_run/) for more details. 
 * `NAME` (required) is the name of the container to create. This value is also
   applied as the name of the Deployment, and as the prefix of the
   pod name. For example: