Merge branch 'master' into patch-1

2016-11-21 13:27:14 -08:00
parent e34352c152 5d6460b979
commit b8a1f1bdef
167 changed files with 22291 additions and 3613 deletions
@@ -129,7 +129,7 @@ To use it,
 * Write an application atop of the client-go clients. Note that client-go defines its own API objects, so if needed, please import API definitions from client-go rather than from the main repository, e.g., `import "k8s.io/client-go/1.4/pkg/api/v1"` is correct.

 The Go client can use the same [kubeconfig file](/docs/user-guide/kubeconfig-file)
-as the kubectl CLI does to locate and authenticate to the apiserver. See this [example](https://github.com/kubernetes/client-go/examples/out-of-cluster.go):
+as the kubectl CLI does to locate and authenticate to the apiserver. See this [example](https://github.com/kubernetes/client-go/blob/master/examples/out-of-cluster/main.go):

 ```golang
 import (
@@ -183,7 +183,8 @@ From within a pod the recommended ways to connect to API are:
    in any container of the pod can access it.  See this [example of using kubectl proxy
    in a pod](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/kubectl-container/).
  - use the Go client library, and create a client using the `client.NewInCluster()` factory.
-    This handles locating and authenticating to the apiserver. [example](https://github.com/kubernetes/client-go/examples/in-cluster.go)
+    This handles locating and authenticating to the apiserver. See this [example of using Go client
+    library in a pod](https://github.com/kubernetes/client-go/blob/master/examples/in-cluster/main.go).

 In each case, the credentials of the pod are used to communicate securely with the apiserver.

@@ -64,12 +64,12 @@ healthy backend service endpoint at all times, even in the event of
 pod, cluster,
 availability zone or regional outages.

-Note that in the
-   case of Google Cloud, the logical L7 load balancer is not a single physical device (which
-   would present both a single point of failure, and a single global
-   network routing choke point), but rather a [truly global, highly available
-   load balancing managed service](https://cloud.google.com/load-balancing/),
-   globally reachable via a single, static IP address.
+Note that in the case of Google Cloud, the logical L7 load balancer is
+not a single physical device (which would present both a single point
+of failure, and a single global network routing choke point), but
+rather a
+[truly global, highly available load balancing managed service](https://cloud.google.com/load-balancing/),
+globally reachable via a single, static IP address.

 Clients inside your federated Kubernetes clusters (i.e. Pods) will be 
 automatically  routed to the cluster-local shard of the Federated Service
@@ -86,13 +86,13 @@ You can create a federated ingress in any of the usual ways, for example using k
 ``` shell
 kubectl --context=federation-cluster create -f myingress.yaml
 ```
-
+For example ingress YAML configurations, see the [Ingress User Guide](/docs/user-guide/ingress/)
 The '--context=federation-cluster' flag tells kubectl to submit the
 request to the Federation API endpoint, with the appropriate
 credentials. If you have not yet configured such a context, visit the
 [federation admin guide](/docs/admin/federation/) or one of the
 [administration tutorials](https://github.com/kelseyhightower/kubernetes-cluster-federation)
-to find out how to do so.  TODO: Update links
+to find out how to do so.

 As described above, the Federated Ingress will automatically create
 and maintain matching Kubernetes ingresses in all of the clusters
@@ -147,17 +147,28 @@ Events:
  2m        2m      1   {loadbalancer-controller }          Normal      CREATE  ip: 130.211.5.194
 ```

-Note the address of your Federated Ingress
+Note that:
+
+1. the address of your Federated Ingress
 corresponds with the address of all of the
 underlying Kubernetes ingresses (once these have been allocated - this
 may take up to a few minutes).
-
-Note also that we have not yet provisioned any backend Pods to receive
+2. we have not yet provisioned any backend Pods to receive
 the network traffic directed to this ingress (i.e. 'Service
 Endpoints' behind the service backing the Ingress), so the Federated Ingress does not yet consider these to
 be healthy shards and will not direct traffic to any of these clusters.
+3. the federation control system will
+automatically reconfigure the load balancer controllers in all of the
+clusters in your federation to make them consistent, and allow
+them to share global load balancers.  But this reconfiguration can
+only complete successfully if there are no pre-existing Ingresses in
+those clusters (this is a safety feature to prevent accidental
+breakage of existing ingresses).  So to ensure that your federated
+ingresses function correctly, either start with new, empty clusters, or make
+sure that you delete (and recreate if necessary) all pre-existing
+Ingresses in the clusters comprising your federation.

-## Adding backend services and pods
+#Adding backend services and pods

 To render the underlying ingress shards healthy, we need to add
 backend Pods behind the service upon which the Ingress is based.  There are several ways to achieve this, but
@@ -175,6 +186,16 @@ kubectl --context=federation-cluster create -f services/nginx.yaml
  kubectl --context=federation-cluster create -f myreplicaset.yaml
 ```

+Note that in order for your federated ingress to work correctly on
+Google Cloud, the node ports of all of the underlying cluster-local
+services need to be identical.  If you're using a federated service
+this is easy to do.  Simply pick a node port that is not already
+being used in any of your clusters, and add that to the spec of your
+federated service.  If you do not specify a node port for your
+federated service, each cluster will choose it's own node port for
+its cluster-local shard of the service, and these will probably end
+up being different, which is not what you want.
+  
 You can verify this by checking in each of the underlying clusters, for example:

 ``` shell
@@ -258,6 +279,35 @@ Check that:
   `service-controller` or `replicaset-controller`,
   errors in the output of `kubectl logs federation-controller-manager --namespace federation`).

+#### I can create a federated ingress successfully, but request load is not correctly distributed across the underlying clusters
+
+Check that:
+
+1. the services underlying your federated ingress in each cluster have
+    identical node ports.  See [above](#creating_a_federated_ingress) for further explanation.
+2. the load balancer controllers in each of your clusters are of the
+   correct type ("GLBC") and have been correctly reconfigured by the
+   federation control plane to share a global GCE load balancer (this
+   should happen automatically).  If they of the correct type, and
+   have been correctly reconfigured, the UID data item in the GLBC
+   configmap in each cluster will be identical across all clusters.
+   See
+   [the GLBC docs](https://github.com/kubernetes/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid)
+   for further details.
+   If this is not the case, check the logs of your federation
+   controller manager to determine why this automated reconfiguration
+   might be failing.
+3. no ingresses have been manually created in any of your clusters before the above
+    reconfiguration of the load balancer controller completed
+    successfully.  Ingresses created before the reconfiguration of
+    your GLBC will interfere with the behavior of your federated
+    ingresses created after the reconfiguration (see
+    [the GLBC docs](https://github.com/kubernetes/contrib/blob/master/ingress/controllers/gce/BETA_LIMITATIONS.md#changing-the-cluster-uid)
+    for further information. To remedy this,
+    delete any ingresses created before the cluster joined the
+    federation (and had it's GLBC reconfigured), and recreate them if
+    necessary.
+	
 #### This troubleshooting guide did not help me solve my problem

 Please use one of our  [support channels](http://kubernetes.io/docs/troubleshooting/) to seek assistance.
@@ -4,22 +4,15 @@ assignees:

 ---

-* TOC
-{:toc}
+The Kubernetes **Guides** can help you work with various aspects of the Kubernetes system.

+* The Kubernetes [User Guide](#user-guide-internal) can help you run programs and services on an existing Kubernetes cluster.
+* The [Cluster Admin Guide](/docs/admin/) can help you set up and administrate your own Kubernetes cluster. 
+* The [Developer Guide](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel) can help you either write code to directly access the Kubernetes API, or to contribute directly to the Kubernetes project.

-The user guide is intended for anyone who wants to run programs and services on an existing Kubernetes cluster.  Setup and administration of a Kubernetes cluster is described in the [Cluster Admin Guide](/docs/admin/). The [Developer Guide](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel) is for anyone wanting to either write code which directly accesses the Kubernetes API, or to contribute directly to the Kubernetes project.
+## <a name="user-guide-internal"></a>Kubernetes User Guide

-Please ensure you have completed the [prerequisites for running examples from the user guide](/docs/user-guide/prereqs/).
-
-## Quick walkthrough
-
-1. [Kubernetes 101](/docs/user-guide/walkthrough/)
-1. [Kubernetes 201](/docs/user-guide/walkthrough/k8s201/)
-
-## Thorough walkthrough
-
-If you don't have any familiarity with Kubernetes, we recommend you read the following sections in order:
+The following topics in the Kubernetes User Guide can help you run applications and services on a Kubernetes cluster:

 1. [Quick start: launch and expose an application](/docs/user-guide/quick-start/)
 1. [Configuring and launching containers: configuring common container parameters](/docs/user-guide/configuring-containers/)
@@ -35,7 +28,9 @@ If you don't have any familiarity with Kubernetes, we recommend you read the fol
    1. [Connecting to containers via proxies](/docs/user-guide/connecting-to-applications-proxy/)
    1. [Connecting to containers via port forwarding](/docs/user-guide/connecting-to-applications-port-forward/)

-## Concept guide
+Before running examples in the user guides, please ensure you have completed the [prerequisites](/docs/user-guide/prereqs/).
+
+## Kubernetes Concepts

 [**Cluster**](/docs/admin/)
 : A cluster is a set of physical or virtual machines and other infrastructure resources used by Kubernetes to run your applications.
@@ -82,7 +82,7 @@ kubectl
 * [kubectl uncordon](kubectl_uncordon.md)	 - Mark node as schedulable
 * [kubectl version](kubectl_version.md)	 - Print the client and server version information

-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -16,11 +16,32 @@ It is intended to store non-identifying auxiliary data, especially data manipula
 If --overwrite is true, then existing annotations can be overwritten, otherwise attempting to overwrite an annotation will result in an error.
 If --resource-version is specified, then updates will use this resource version, otherwise the existing resource-version will be used.

-Possible resources include (case insensitive):
-  pod (po), service (svc), replicationcontroller (rc),
-  node (no), event (ev), componentstatuse (cs),
-  limitrange (limits), persistentvolume (pv), persistentvolumeclaim (pvc),
-  horizontalpodautoscaler (hpa), resourcequota (quota), secret
+Valid resource types include:
+   * clusters (valid only for federation apiservers)
+   * componentstatuses (aka 'cs')
+   * configmaps (aka 'cm')
+   * daemonsets (aka 'ds')
+   * deployments (aka 'deploy')
+   * events (aka 'ev')
+   * endpoints (aka 'ep')
+   * horizontalpodautoscalers (aka 'hpa')
+   * ingress (aka 'ing')
+   * jobs
+   * limitranges (aka 'limits')
+   * nodes (aka 'no')
+   * namespaces (aka 'ns')
+   * petsets (alpha feature, may be unstable)
+   * pods (aka 'po')
+   * persistentvolumes (aka 'pv')
+   * persistentvolumeclaims (aka 'pvc')
+   * quota
+   * resourcequotas (aka 'quota')
+   * replicasets (aka 'rs')
+   * replicationcontrollers (aka 'rc')
+   * secrets
+   * serviceaccounts (aka 'sa')
+   * services (aka 'svc')
+

 ```
 kubectl annotate [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]
@@ -100,7 +121,7 @@ kubectl annotate pods foo description-



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl api-versions



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -72,7 +72,7 @@ cat pod.json | kubectl apply -f -



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -66,7 +66,7 @@ kubectl attach 123456-7890 -c ruby-container -i -t



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -21,6 +21,7 @@ kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MA
 ### Examples

 ```
+
 # Auto scale a deployment "foo", with the number of pods between 2 and 10, target CPU utilization specified so a default autoscaling policy will be used:
 kubectl autoscale deployment foo --min=2 --max=10

@@ -80,7 +81,7 @@ kubectl autoscale rc foo --max=5 --cpu-percent=80



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -50,7 +50,7 @@ kubectl cluster-info



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -75,7 +75,7 @@ kubectl cluster-info dump --namespaces default,kube-system --output-directory=/p



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -68,7 +68,7 @@ $ source <(kubectl completion zsh)



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -54,7 +54,7 @@ kubectl config SUBCOMMAND



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -52,7 +52,7 @@ kubectl config current-context



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl config delete-cluster NAME



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl config delete-context NAME



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl config get-clusters



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -60,7 +60,7 @@ kubectl config get-contexts my-context



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -66,7 +66,7 @@ kubectl config set-cluster e2e --insecure-skip-tls-verify=true



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -58,7 +58,7 @@ kubectl config set-context gce --user=cluster-admin



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -89,7 +89,7 @@ kubectl config set-credentials cluster-admin --auth-provider=oidc --auth-provide



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -52,7 +52,7 @@ kubectl config set PROPERTY_NAME PROPERTY_VALUE



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -45,7 +45,7 @@ kubectl config unset PROPERTY_NAME



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl config use-context CONTEXT_NAME



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -73,7 +73,7 @@ kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -87,7 +87,7 @@ kubectl convert -f . | kubectl create -f -



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -54,7 +54,7 @@ kubectl cordon foo



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -70,7 +70,7 @@ cat pod.json | kubectl create -f -



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -87,7 +87,7 @@ kubectl create configmap my-config --from-literal=key1=config1 --from-literal=ke



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -70,7 +70,7 @@ kubectl create deployment my-dep --image=busybox



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -69,7 +69,7 @@ kubectl create namespace my-namespace



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -73,7 +73,7 @@ kubectl create quota NAME [--hard=key1=value1,key2=value2] [--scopes=Scope1,Scop



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl create secret



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -85,7 +85,7 @@ kubectl create secret docker-registry my-secret --docker-server=DOCKER_REGISTRY_



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -88,7 +88,7 @@ kubectl create secret generic my-secret --from-literal=key1=supersecret --from-l



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -73,7 +73,7 @@ kubectl create secret tls tls-secret --cert=path/to/tls.cert --key=path/to/tls.k



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl create service



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -74,7 +74,7 @@ kubectl create service clusterip my-cs --clusterip="None"



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -70,7 +70,7 @@ kubectl create service loadbalancer my-lbs --tcp=5678:8080



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -70,7 +70,7 @@ kubectl create service nodeport my-ns --tcp=5678:8080



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -70,7 +70,7 @@ $ kubectl create serviceaccount my-service-account



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -62,7 +62,7 @@ kubectl delete pods --all
  -o, --output string           Output mode. Use "-o name" for shorter output (resource/name).
  -R, --recursive               Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
  -l, --selector string         Selector (label query) to filter on.
-      --timeout duration        The length of time to wait before giving up on a delete, zero means determine a timeout from the size of the object
+      --timeout duration        The length of time to wait before giving up on a delete, zero means determine a timeout from the size of the object (default 0s)
 ```

 ### Options inherited from parent commands
@@ -94,7 +94,7 @@ kubectl delete pods --all



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -113,7 +113,7 @@ kubectl describe pods frontend



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -12,13 +12,13 @@ Drain node in preparation for maintenance
 Drain node in preparation for maintenance.

 The given node will be marked unschedulable to prevent new pods from arriving.
-The `drain` deletes all pods except mirror pods (which cannot be deleted through
+Then drain deletes all pods except mirror pods (which cannot be deleted through
 the API server).  If there are DaemonSet-managed pods, drain will not proceed
 without --ignore-daemonsets, and regardless it will not delete any
 DaemonSet-managed pods, because those pods would be immediately replaced by the
 DaemonSet controller, which ignores unschedulable markings.  If there are any
-pods that are neither mirror pods nor managed by ReplicationController,
-ReplicaSet, DaemonSet or Job, then drain will not delete any pods unless you
+pods that are neither mirror pods nor managed--by ReplicationController,
+ReplicaSet, DaemonSet or Job--, then drain will not delete any pods unless you
 use --force.

 When you are ready to put the node back into service, use kubectl uncordon, which
@@ -81,7 +81,7 @@ $ kubectl drain foo --grace-period=900



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -91,7 +91,7 @@ kubectl edit svc/docker-registry --output-version=v1 -o json



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -67,7 +67,7 @@ kubectl exec 123456-7890 -c ruby-container -i -t -- bash -il



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -89,7 +89,7 @@ kubectl explain pods.spec.containers



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -20,7 +20,7 @@ labels are specified, the new service will re-use the labels from the resource i

 Possible resources include (case insensitive):
 pod (po), service (svc), replicationcontroller (rc),
-deployment, replicaset (rs)
+deployment (deploy), replicaset (rs)


 ```
@@ -112,7 +112,7 @@ kubectl expose deployment nginx --port=80 --target-port=8000



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -12,7 +12,6 @@ Display one or many resources
 Display one or many resources.

 Valid resource types include:
-
   * clusters (valid only for federation apiservers)
   * componentstatuses (aka 'cs')
   * configmaps (aka 'cm')
@@ -69,9 +68,7 @@ kubectl get -o json pod web-pod-13je7
 kubectl get -f pod.yaml -o json

 # Return only the phase value of the specified pod.
-{% raw %}
 kubectl get -o template pod/web-pod-13je7 --template={{.status.phase}}
-{% endraw %}

 # List all replication controllers and services together in ps output format.
 kubectl get rc,services
@@ -132,7 +129,7 @@ kubectl get rc/web service/frontend pods/web-pod-13je7



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -93,7 +93,7 @@ kubectl label pods foo bar-



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -42,7 +42,7 @@ kubectl logs --since=1h nginx
      --include-extended-apis   If true, include definitions of new APIs via calls to the API server. [default true] (default true)
      --limit-bytes int         Maximum bytes of logs to return. Defaults to no limit.
  -p, --previous                If true, print the logs for the previous instance of the container in a pod if it exists.
-      --since duration          Only return logs newer than a relative duration like 5s, 2m, or 3h. Defaults to all logs. Only one of since-time / since may be used.
+      --since duration          Only return logs newer than a relative duration like 5s, 2m, or 3h. Defaults to all logs. Only one of since-time / since may be used. (default 0s)
      --since-time string       Only return logs after a specific date (RFC3339). Defaults to all logs. Only one of since-time / since may be used.
      --tail int                Lines of recent log file to display. Defaults to -1, showing all log lines. (default -1)
      --timestamps              Include timestamps on each line in the log output
@@ -77,7 +77,7 @@ kubectl logs --since=1h nginx



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl namespace [namespace]



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -43,7 +43,7 @@ kubectl options



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -85,7 +85,7 @@ kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -66,7 +66,7 @@ kubectl port-forward  mypod 0:5000



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -91,7 +91,7 @@ kubectl proxy --api-prefix=/k8s-api



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -51,7 +51,7 @@ kubectl replace --force -f ./pod.json
  -R, --recursive                 Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
      --save-config               If true, the configuration of current object will be saved in its annotation. This is useful when you want to perform kubectl apply on this object in the future.
      --schema-cache-dir string   If non-empty, load/store cached API schemas in this directory, default is '$HOME/.kube/schema' (default "~/.kube/schema")
-      --timeout duration          Only relevant during a force replace. The length of time to wait before giving up on a delete of the old resource, zero means determine a timeout from the size of the object. Any other values should contain a corresponding time unit (e.g. 1s, 2m, 3h).
+      --timeout duration          Only relevant during a force replace. The length of time to wait before giving up on a delete of the old resource, zero means determine a timeout from the size of the object. Any other values should contain a corresponding time unit (e.g. 1s, 2m, 3h). (default 0s)
      --validate                  If true, use a schema to validate the input before sending it (default true)
 ```

@@ -84,7 +84,7 @@ kubectl replace --force -f ./pod.json



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -15,6 +15,9 @@ Replaces the specified replication controller with a new replication controller
 new PodTemplate. The new-controller.json must specify the same namespace as the
 existing replication controller and overwrite at least one (common) label in its replicaSelector.

+![Workflow](http://kubernetes.io/images/docs/kubectl_rollingupdate.svg)
+
+
 ```
 kubectl rolling-update OLD_CONTROLLER_NAME ([NEW_CONTROLLER_NAME] --image=NEW_CONTAINER_IMAGE | -f NEW_CONTROLLER_SPEC)
 ```
@@ -95,7 +98,7 @@ kubectl rolling-update frontend-v1 frontend-v2 --rollback



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -52,7 +52,7 @@ kubectl rollout undo deployment/abc



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -63,7 +63,7 @@ kubectl rollout history deployment/abc --revision=3



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -65,7 +65,7 @@ kubectl rollout pause deployment/nginx



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -63,7 +63,7 @@ kubectl rollout resume deployment/nginx



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -59,7 +59,7 @@ kubectl rollout status deployment/nginx



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -63,7 +63,7 @@ kubectl rollout undo deployment/abc --to-revision=3



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -122,7 +122,7 @@ kubectl run pi --schedule="0/5 * * * ?" --image=perl --restart=OnFailure -- perl



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -51,7 +51,7 @@ kubectl scale --replicas=3 job/cron
  -R, --recursive                 Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
      --replicas int              The new desired number of replicas. Required. (default -1)
      --resource-version string   Precondition for resource version. Requires that the current resource version match this value in order to scale.
-      --timeout duration          The length of time to wait before giving up on a scale operation, zero means don't wait. Any other values should contain a corresponding time unit (e.g. 1s, 2m, 3h).
+      --timeout duration          The length of time to wait before giving up on a scale operation, zero means don't wait. Any other values should contain a corresponding time unit (e.g. 1s, 2m, 3h). (default 0s)
 ```

 ### Options inherited from parent commands
@@ -83,7 +83,7 @@ kubectl scale --replicas=3 job/cron



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -46,7 +46,7 @@ kubectl set SUBCOMMAND



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -12,7 +12,7 @@ Update image of a pod template
 Update existing container image(s) of resources.

 Possible resources include (case insensitive):
-  pod (po), replicationcontroller (rc), deployment, daemonset (ds), job, replicaset (rs)
+  pod (po), replicationcontroller (rc), deployment (deploy), daemonset (ds), job, replicaset (rs)

 ```
 kubectl set image (-f FILENAME | TYPE NAME) CONTAINER_NAME_1=CONTAINER_IMAGE_1 ... CONTAINER_NAME_N=CONTAINER_IMAGE_N
@@ -82,7 +82,7 @@ kubectl set image -f path/to/file.yaml nginx=nginx:1.9.1 --local -o yaml



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -83,7 +83,7 @@ kubectl taint nodes foo dedicated-



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -46,7 +46,7 @@ kubectl top



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -63,7 +63,7 @@ kubectl top node NODE_NAME



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -74,7 +74,7 @@ kubectl top pod -l name=myLabel



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -54,7 +54,7 @@ $ kubectl uncordon foo



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -49,7 +49,7 @@ kubectl version



-###### Auto generated by spf13/cobra on 2-Sep-2016
+###### Auto generated by spf13/cobra on 24-Oct-2016



@@ -3,7 +3,7 @@ kind: Pod
 metadata:
  name: nginx
  annotations:
-    pod.alpha.kubernetes.io/init-containers: '[
+    pod.beta.kubernetes.io/init-containers: '[
        {
            "name": "install",
            "image": "busybox",
@@ -173,7 +173,7 @@ on node N if node N has a label with key `failure-domain.beta.kubernetes.io/zone
 such that there is at least one node in the cluster with key `failure-domain.beta.kubernetes.io/zone` and
 value V that is running a pod that has a label with key "security" and value "S1".) The pod anti-affinity
 rule says that the pod cannot schedule onto a node if that node is already running a pod with label
-having key "security" and value "S2". (If the `topologyKey` were `failure-domain.beta.kuberntes.io/zone` then
+having key "security" and value "S2". (If the `topologyKey` were `failure-domain.beta.kubernetes.io/zone` then
 it would mean that the pod cannot schedule onto a node if that node is in the same zone as a pod with
 label having key "security" and value "S2".) See the [design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/podaffinity.md).
 for many more examples of pod affinity and anti-affinity, both the `requiredDuringSchedulingIgnoredDuringExecution`
@@ -88,7 +88,7 @@ vm-1 # printf "GET / HTTP/1.0\r\n\r\n" | netcat vm-0.ub 80
 It's worth exploring what just happened. Init containers run sequentially *before* the application container. In this example we used the init container to copy shared libraries from the rootfs, while preserving user installed packages across container restart.

 ```yaml
-pod.alpha.kubernetes.io/init-containers: '[
+pod.beta.kubernetes.io/init-containers: '[
    {
        "name": "rootfs",
        "image": "ubuntu:15.10",
@@ -29,7 +29,7 @@ spec:
        app: nginx
      annotations:
        pod.alpha.kubernetes.io/initialized: "true"
-        pod.alpha.kubernetes.io/init-containers: '[
+        pod.beta.kubernetes.io/init-containers: '[
            {
                "name": "peerfinder",
                "image": "gcr.io/google_containers/peer-finder:0.1",
@@ -66,8 +66,8 @@ The possible values for RestartPolicy are `Always`, `OnFailure`, or `Never`. If
 Three types of controllers are currently available:

 - Use a [`Job`](/docs/user-guide/jobs/) for pods which are expected to terminate (e.g. batch computations).
- Use a [`ReplicationController`](/docs/user-guide/replication-controller/) for pods which are not expected to
-  terminate (e.g. web servers).
+- Use a [`ReplicationController`](/docs/user-guide/replication-controller/) or  [`Deployment`](/docs/user-guide/deployments/)
+  for pods which are not expected to terminate (e.g. web servers).
 - Use a [`DaemonSet`](/docs/admin/daemons/): Use for pods which need to run 1 per machine because they provide a
  machine-specific system service.
 If you are unsure whether to use ReplicationController or Daemon, then see [Daemon Set versus
@@ -89,6 +89,40 @@ If a node dies or is disconnected from the rest of the cluster, some entity with

 ## Examples

+### Advanced livenessProbe example
+
+Liveness probes are executed by `kubelet`, so all requests will be made within kubelet network namespace.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  labels:
+    test: liveness
+  name: liveness-http
+spec:
+  containers:
+  - args:
+    - /server
+    image: gcr.io/google_containers/liveness
+    livenessProbe:
+      httpGet:
+        # when "host" is not defined, "PodIP" will be used
+        # host: my-host
+        # when "scheme" is not defined, "HTTP" scheme will be used. Only "HTTP" and "HTTPS" are allowed
+        # scheme: HTTPS
+        path: /healthz
+        port: 8080
+        httpHeaders:
+          - name: X-Custom-Header
+            value: Awesome
+      initialDelaySeconds: 15
+      timeoutSeconds: 1
+    name: liveness
+```
+
+### Example states
+
   * Pod is `Running`, 1 container, container exits success
     * Log completion event
     * If RestartPolicy is:
@@ -0,0 +1,169 @@
+---
+assignees:
+- erictune
+
+---
+
+* TOC
+{:toc}
+
+In addition to having one or more main containers (or **app containers**), a
+pod can also have one or more **init containers** which run before the app
+containers.   Init containers allow you to reduce and reorganize setup scripts
+and "glue code".
+
+## Overview
+
+An init container is exactly like a regular container, except that it always
+runs to completion and each init container must complete successfully before
+the next one is started. If the init container fails, Kubernetes will restart
+the pod until the init container succeeds. If a pod is marked as `RestartNever`,
+the pod will fail if the init container fails.
+
+You specify a container as an init container by adding an annotation
+The annotation key is `pod.beta.kubernetes.io/init-containers`.  The annotation
+value is a JSON array of [objects of type `v1.Container`
+](http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_container)
+
+Once the feature exits beta, the init containers will be specified on the Pod
+Spec alongside the app `containers` array.
+The status of the init containers is returned as another annotation -
+`pod.beta.kubernetes.io/init-container-statuses` -- as an array of the
+container statuses (similar to the `status.containerStatuses` field).
+
+Init containers support all of the same features as normal containers,
+including resource limits, volumes, and security settings. The resource
+requests and limits for an init container are [handled slightly differently](
+#resources).  Init containers do not support readiness probes since they will
+run to completion before the pod can be ready.
+An init container has all of the fields of an app container.
+
+If you specify multiple init containers for a pod, those containers run one at
+a time in sequential order. Each must succeed before the next can run. Once all
+init containers have run to completion, Kubernetes initializes the pod and runs
+the application containers as usual.
+
+## What are Init Containers Good For?
+
+Because init containers have separate images from application containers, they
+have some advantages for start-up related code. These include:
+
+* they can contain utilities that are not desirable to include in the app container
+  image for security reasons,
+* they can contain utilities or custom code for setup that is not present in an app
+  image.  (No need to make an image `FROM` another image just to use a tool like
+  `sed`, `awk`, `python`, `dig`, etc during setup).
+* the application image builder and the deployer roles can work independently without
+  the need to jointly build a single app image.
+
+Because init containers have different filesystem view (Linux namespaces) from
+app containers, they can be given access to Secrets that the app containers are
+not able to access.
+
+Since init containers run to completion before any app containers start, and
+since app containers run in parallel, they provide an easier way to block or
+delay the startup of application containers until some precondition is met. 
+
+Because init containers run in sequence and there can be multiple init containers,
+they can be composed easily.
+
+Here are some ideas for how to use init containers:
+- Wait for a service to be created with a shell command like:
+  `for i in {1..100}; do sleep 1; if dig myservice; then exit 0; fi; exit 1`
+- Register this pod with a remote server with a command like:
+  `curl -X POST http://$MANAGEMENT_SERVICE_HOST:$MANAGEMENT_SERVICE_PORT/register -d 'instance=$(POD_NAME)&ip=$(POD_IP)'`
+  using `POD_NAME` and `POD_IP` from the downward API.
+- Wait for some time before starting the app container with a command like `sleep 60`.
+- Clone a git repository into a volume
+- Place values like a POD_IP into a configuration file, and run a template tool (e.g. jinja)
+  to generate a configuration file to be consumed by the main app contianer.
+```
+
+Complete usage examples can be found in the [PetSets
+guide](docs/user-guide/petset/bootstrapping/index.md) and the [Production Pods
+guide](/docs/user-guide/production-pods.md#handling-initialization).
+
+
+## Detailed Behavior
+
+Each pod may have 0..N init containers defined along with the existing
+1..M app containers.
+
+On startup of the pod, after the network and volumes are initialized, the init
+containers are started in order. Each container must exit successfully before
+the next is invoked. If a container fails to start (due to the runtime) or
+exits with failure, it is retried according to the pod RestartPolicy, except
+when the pod restart policy is RestartPolicyAlways, in which case just the init
+containers use RestartPolicyOnFailure.
+
+A pod cannot be ready until all init containers have succeeded. The ports on an
+init container are not aggregated under a service. A pod that is being
+initialized is in the `Pending` phase but should has a condition `Initializing`
+set to `true`.
+
+If the pod is [restarted](#pod-restart-reasons) all init containers must
+execute again.
+
+Changes to the init container spec are limited to the container image field.
+Altering a init container image field is equivalent to restarting the pod.
+
+Because init containers can be restarted, retried, or reexecuted, init container
+code should be idempotent.  In particular, code that writes to files on EmptyDirs
+should be prepared for the possibility that an output file already exists.
+
+An init container has all of the fields of an app container. The following
+fields are prohibited from being used on init containers by validation:
+
+* `readinessProbe` - init containers must exit for pod startup to continue,
+  are not included in rotation, and so cannot define readiness distinct from
+  completion.
+
+Init container authors may use `activeDeadlineSeconds` on the pod and
+`livenessProbe` on the container to prevent init containers from failing
+forever. The active deadline includes init containers.
+
+The name of each app and init container in a pod must be unique - it is a
+validation error for any container to share a name.
+
+### Resources
+
+Given the ordering and execution for init containers, the following rules
+for resource usage apply:
+
+* The highest of any particular resource request or limit defined on all init
+  containers is the **effective init request/limit**
+* The pod's **effective request/limit** for a resource is the higher of:
+  * sum of all app containers request/limit for a resource
+  * effective init request/limit for a resource
+* Scheduling is done based on effective requests/limits, which means
+  init containers can reserve resources for initialization that are not used
+  during the life of the pod.
+* QoS tier of the pod's **effective QoS tier** is the QoS tier for init containers
+  and app containers alike.
+
+Quota and limits are applied based on the effective pod request and
+limit.
+
+Pod level cGroups are based on the effective pod request and limit, the
+same as the scheduler.
+
+
+## Pod Restart Reasons
+
+A Pod may "restart", causing reexecution of init containers, for the following
+reasons:
+
+* An init container image is changed by a user updating the Pod Spec.
+  * App container image changes only restart the app container.
+* The pod infrastructure container is restarted
+  * This is uncommon and would have to be done by someone with root access to nodes.
+* All containers in a pod are terminated, requiring a restart (RestartPolicyAlways) AND the record of init container completion has been lost due to garbage collection.
+
+## Support and compatibilty
+
+A cluster with Kubelet and Apiserver version 1.4.0 or greater supports init
+containers with the beta annotations.  Support varies for other combinations of
+Kubelet and Apiserver version; see the [release notes
+](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md) for details.
+
+
@@ -204,6 +204,8 @@ The status of the init containers is returned as another annotation - `pod.beta.

 Init containers support all of the same features as normal containers, including resource limits, volumes, and security settings. The resource requests and limits for an init container are handled slightly different than normal containers since init containers are run one at a time instead of all at once - any limits or quotas will be applied based on the largest init container resource quantity, rather than as the sum of quantities. Init containers do not support readiness probes since they will run to completion before the pod can be ready.

+[Complete Init Container Documentation](/docs/user-guide/pods/init-containers.md)
+

 ## Lifecycle hooks and termination notice

@@ -94,7 +94,7 @@ of the replicated pods.
 kubectl create -f hpa-rs.yaml
 ```

-Alternatively, you can just use the `kubectl autoscale` command to acommplish the same
+Alternatively, you can just use the `kubectl autoscale` command to acomplish the same
 (and it's easier!)

 ```shell
@@ -345,7 +345,7 @@ can do a DNS SRV query for `"_http._tcp.my-service.my-ns"` to discover the port
 number for `"http"`.

 The Kubernetes DNS server is the only way to access services of type
-`ExternalName`.
+`ExternalName`.  More information is available in the [DNS Admin Guide](http://kubernetes.io/docs/admin/dns/).

 ## Headless services

@@ -46,7 +46,7 @@ The system adds fields in several ways:

  - Some fields are added synchronously with creation of the resource and some are set asynchronously.
    - For example: `metadata.uid` is set synchronously.  (Read more about [metadata](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#metadata)).
-    - For example, `status.hostIP` is set only after the pod has been scheduled.  This often happens fast, but you may notice pods which do not have this set yet.  This is called Late Initialization.  (Read mode about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization) ).
+    - For example, `status.hostIP` is set only after the pod has been scheduled.  This often happens fast, but you may notice pods which do not have this set yet.  This is called Late Initialization.  (Read more about [status](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) and [late initialization](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#late-initialization)).
  - Some fields are set to default values.  Some defaults vary by cluster and some are fixed for the API at a certain version.  (Read more about [defaulting](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#defaulting)).
    - For example, `spec.containers[0].imagePullPolicy` always defaults to `IfNotPresent` in api v1.
    - For example, `spec.containers[0].resources.limits.cpu` may be defaulted to  `100m` on some clusters, to some other value on others, and not defaulted at all on others.