Merge remote-tracking branch 'upstream/master' into release-1.8

2017-08-01 13:17:13 -07:00
parent 9979f1d821 47fb29d668
commit dfbc33b8fb
206 changed files with 2904 additions and 2513 deletions
@@ -232,7 +232,8 @@ See the [InitialResouces proposal](https://git.k8s.io/community/contributors/des
 ### NamespaceLifecycle

 This plug-in enforces that a `Namespace` that is undergoing termination cannot have new objects created in it,
-and ensures that requests in a non-existent `Namespace` are rejected.
+and ensures that requests in a non-existent `Namespace` are rejected. This plug-in also prevents deletion of
+three system reserved namespaces `default`, `kube-system`, `kube-public`.

 A `Namespace` deletion kicks off a sequence of operations that remove all objects (pods, services, etc.) in that
 namespace.  In order to enforce integrity of that process, we strongly recommend running this plug-in.
@@ -447,8 +447,8 @@ The request body will be of the following format:
 }
 ```

-The remote service is expected to fill the `TokenAccessReviewStatus` field of
-the request to indicate the success of the login. The response body's "spec"
+The remote service is expected to fill the `status` field of
+the request to indicate the success of the login. The response body's `spec`
 field is ignored and may be omitted. A successful validation of the bearer
 token would return:

@@ -86,9 +86,9 @@ An example request body:
 }
 ```

-The remote service is expected to fill the SubjectAccessReviewStatus field of
+The remote service is expected to fill the `status` field of
 the request and respond to either allow or disallow access. The response body's
-"spec" field is ignored and may be omitted. A permissive response would return:
+`spec` field is ignored and may be omitted. A permissive response would return:

 ```json
 {
@@ -3,7 +3,7 @@ assignees:
 - smarterclayton
 - lavalamp
 - whitlockjc
- caesrxuchao
+- caesarxuchao
 title: Dynamic Admission Control
 ---

@@ -41,7 +41,7 @@ This page describes how to use Initializers and External Admission Webhooks.

 Once the controller has performed its assigned task, it removes its name from
 the list. For example, it may send a PATCH that inserts a container in a pod and
-also removes its name from `metadata.initializers`. Initializers may make
+also removes its name from `metadata.initializers.pending`. Initializers may make
 mutations to objects.

 Objects which have a non-empty initializer list are considered uninitialized,
@@ -64,7 +64,7 @@ external admission webhooks, as they have better performance.
 When an object is POSTed, it is checked against all existing
 `initializerConfiguration` objects (explained below). For all that it matches,
 all `spec.initializers[].name`s are appended to the new object's
-`metadata.initializers` field.
+`metadata.initializers.pending` field.

 An initializer controller should list and watch for uninitialized objects, by
 using the query parameter `?includeUninitialized=true`. If using client-go, just
@@ -73,7 +73,7 @@ set
 to true.

 For the observed uninitialized objects, an initializer controller should first
-check if its name matches `metadata.initializers[0]`. If so, it should then
+check if its name matches `metadata.initializers.pending[0]`. If so, it should then
 perform its assigned task and remove its name from the list.

 ### Enable initializers alpha feature
@@ -81,7 +81,7 @@ perform its assigned task and remove its name from the list.
 *Initializers* is an alpha feature, so it is disabled by default. To turn it on,
 you need to:

-* Include "Initializer" in the `--admission-control` flag when starting
+* Include "Initializers" in the `--admission-control` flag when starting
  `kube-apiserver`. If you have multiple `kube-apiserver` replicas, all should
  have the same flag setting.

@@ -99,13 +99,13 @@ API](/docs/api-reference/{{page.version}}/#deployment-v1beta1-apps).
 ### Configure initializers on the fly

 You can configure what initializers are enabled and what resources are subject
-to the initializers by creating `initializerconfigurations`.
+to the initializers by creating `initializerConfiguration` resources.

 You should first deploy the initializer controller and make sure that it is
-working properly before creating the `initializerconfigurations`. Otherwise, any
+working properly before creating the `initializerConfiguration`. Otherwise, any
 newly created resources will be stuck in an uninitialized state.

-The following is an example `initiallizerConfiguration`.
+The following is an example `initializerConfiguration`:

 ```yaml
 apiVersion: admissionregistration.k8s.io/v1alpha1
@@ -126,12 +126,16 @@ initializers:
          - pods
 ```

+After you create the `initializerConfiguration`, the system will take a few
+seconds to honor the new configuration. Then, `"podimage.example.com"` will be
+appended to the `metadata.initializers.pending` field of newly created pods. You
+should already have a ready "podimage" initializer controller that handles pods
+whose `metadata.initializers.pending[0].name="podimage.example.com"`. Otherwise
+the pods will stuck uninitialized.
+
 Make sure that all expansions of the `<apiGroup, apiVersions, resources>` tuple
 in a `rule` are valid. If they are not, separate them in different `rules`.

-After you create the `initializerConfiguration`, the system will take a few
-seconds to honor the new configuration.
-
 ## External Admission Webhooks

 ### What are external admission webhooks?
@@ -232,7 +236,7 @@ it is working properly before creating the externaladmissionhookconfigurations.
 Otherwise, depending whether the webhook is configured as fail open or fail
 closed, operations will be unconditionally accepted or rejected. 

-The following is an example externaladmissionhookconfiguration.
+The following is an example `externaladmissionhookconfiguration`:

 ```yaml
 apiVersion: admissionregistration.k8s.io/v1alpha1
@@ -17,11 +17,19 @@ and progress on the feature is being tracked as [feature #43](https://github.com

 ## kube-apiserver configuration

-You must provide a token file which specifies at least one "bootstrap token" assigned to a kubelet bootstrap-specific group.
+The API server should be configured with an [authenticator](/docs/admin/authentication/) that can authenticate tokens as a user in the `system:bootstrappers` group.
+
 This group will later be used in the controller-manager configuration to scope approvals in the default approval
 controller. As this feature matures, you should ensure tokens are bound to a Role-Based Access Control (RBAC) policy which limits requests
 (using the bootstrap token) strictly to client requests related to certificate provisioning. With RBAC in place, scoping the tokens to a group allows for great flexibility (e.g. you could disable a particular bootstrap group's access when you are done provisioning the nodes).

+While any authentication strategy can be used for the kubelet's initial bootstrap credentials, the following two authenticators are recommended for ease of provisioning.
+
+1. [Bootstrap Tokens](/docs/admin/bootstrap-tokens/) - __alpha__
+2. [Token authentication file](###token-authentication-file)
+
+Using bootstrap tokens is currently __alpha__ and will simplify the management of bootstrap token management especially in a HA scenario. 
+
 ### Token authentication file
 Tokens are arbitrary but should represent at least 128 bits of entropy derived from a secure random number
 generator (such as /dev/urandom on most modern systems). There are multiple ways you can generate a token. For example:
@@ -34,7 +42,7 @@ The token file should look like the following example, where the first three val
 name should be as depicted:

 ```
-02b50b05283e98dd0fd71db496ef01e8,kubelet-bootstrap,10001,"system:kubelet-bootstrap"
+02b50b05283e98dd0fd71db496ef01e8,kubelet-bootstrap,10001,"system:bootstrappers"
 ```

 Add the `--token-auth-file=FILENAME` flag to the kube-apiserver command (in your systemd unit file perhaps) to enable the token file.
@@ -127,20 +135,20 @@ provided by the removed auto-approval flag, of approving all CSRs by a single gr

 ```
 # REMOVED: This flag no longer works as of 1.7.
--insecure-experimental-approve-all-kubelet-csrs-for-group="kubelet-bootstrap-token"
+--insecure-experimental-approve-all-kubelet-csrs-for-group="system:bootstrappers"
 ```

 An admin would create a `ClusterRoleBinding` targeting that group.

 ```yml
-# Approve all CSRs for the group "kubelet-bootstrap-token"
+# Approve all CSRs for the group "system:bootstrappers"
 kind: ClusterRoleBinding
 apiVersion: rbac.authorization.k8s.io/v1beta1
 metadata:
  name: auto-approve-csrs-for-group
 subjects:
 - kind: Group
-  name: kubelet-bootstrap-token
+  name: system:bootstrappers
  apiGroup: rbac.authorization.k8s.io
 roleRef:
  kind: ClusterRole
@@ -179,10 +187,11 @@ kubectl config set-credentials kubelet-bootstrap --token=${BOOTSTRAP_TOKEN} --ku

 When starting the kubelet, if the file specified by `--kubeconfig` does not exist, the bootstrap kubeconfig is used to request a client certificate from the API server. On approval of the certificate request and receipt back by the kubelet, a kubeconfig file referencing the generated key and obtained certificate is written to the path specified by `--kubeconfig`. The certificate and key file will be placed in the directory specified by `--cert-dir`.

-The flag to enable this bootstrapping when starting the kubelet is:
+**Note:** The following flags are required to enable this bootstrapping when starting the kubelet:

 ```
--experimental-bootstrap-kubeconfig="/path/to/bootstrap/kubeconfig"
+--require-kubeconfig
+--bootstrap-kubeconfig="/path/to/bootstrap/kubeconfig"
 ```

 Additionally, in 1.7 the kubelet implements __alpha__ features for enabling rotation of both its client and/or serving certs.
@@ -63,7 +63,7 @@ persistent storage of objects.
 The main Kubernetes API server handles built-in resources like *pods* and *services*,
 and can also handle custom resources in a generic way through [CustomResourceDefinitions](#customresourcedefinitions).

-The [aggregation layer](/docs/concepts/api-extension/) allows you to provide specialized
+The [aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) allows you to provide specialized
 implementations for your custom resources by writing and deploying your own standalone API server.
 The main API server delegates requests to you for the custom resources that you handle,
 making them available to all of its clients.
@@ -4,11 +4,6 @@ assignees:
 - roberthbailey
 - liggitt
 title: Master-Node communication
-redirect_from:
- "/docs/admin/master-node-communication/"
- "/docs/admin/master-node-communication.html"
- "/docs/concepts/cluster-administration/master-node-communication/"
- "/docs/concepts/cluster-administration/master-node-communication.html"
 ---

 * TOC
@@ -30,18 +25,18 @@ services). In a typical deployment, the apiserver is configured to listen for
 remote connections on a secure HTTPS port (443) with one or more forms of
 client [authentication](/docs/admin/authentication/) enabled. One or more forms
 of [authorization](/docs/admin/authorization/) should be enabled, especially
-if [anonymous requests](/docs/admin/authentication/#anonymous-requests) or 
-[service account tokens](/docs/admin/authentication/#service-account-tokens) 
+if [anonymous requests](/docs/admin/authentication/#anonymous-requests) or
+[service account tokens](/docs/admin/authentication/#service-account-tokens)
 are allowed.

 Nodes should be provisioned with the public root certificate for the cluster
 such that they can connect securely to the apiserver along with valid client
 credentials. For example, on a default GCE deployment, the client credentials
-provided to the kubelet are in the form of a client certificate. See 
-[kubelet TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/) for 
-automated provisioning of kubelet client certificates. 
+provided to the kubelet are in the form of a client certificate. See
+[kubelet TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/) for
+automated provisioning of kubelet client certificates.

-Pods that wish to connect to the apiserver can do so securely by leveraging a 
+Pods that wish to connect to the apiserver can do so securely by leveraging a
 service account so that Kubernetes will automatically inject the public root
 certificate and a valid bearer token into the pod when it is instantiated.
 The `kubernetes` service (in all namespaces) is configured with a virtual IP
@@ -71,23 +66,23 @@ or service through the apiserver's proxy functionality.

 The connections from the apiserver to the kubelet are used for fetching logs
 for pods, attaching (through kubectl) to running pods, and using the kubelet's
-port-forwarding functionality. These connections terminate at the kubelet's 
+port-forwarding functionality. These connections terminate at the kubelet's
 HTTPS endpoint.

 By default, the apiserver does not verify the kubelet's serving certificate,
-which makes the connection subject to man-in-the-middle attacks, and 
+which makes the connection subject to man-in-the-middle attacks, and
 **unsafe** to run over untrusted and/or public networks.

-To verify this connection, use the `--kubelet-certificate-authority` flag to 
-provide the apiserver with a root certificates bundle to use to verify the 
+To verify this connection, use the `--kubelet-certificate-authority` flag to
+provide the apiserver with a root certificates bundle to use to verify the
 kubelet's serving certificate.

 If that is not possible, use [SSH tunneling](/docs/admin/master-node-communication/#ssh-tunnels)
-between the apiserver and kubelet if required to avoid connecting over an 
+between the apiserver and kubelet if required to avoid connecting over an
 untrusted or public network.

 Finally, [Kubelet authentication and/or authorization](/docs/admin/kubelet-authentication-authorization/)
-should be enabled to secure the kubelet API. 
+should be enabled to secure the kubelet API.

 ### apiserver -> nodes, pods, and services

@@ -3,11 +3,6 @@ assignees:
 - caesarxuchao
 - dchen1107
 title: Nodes
-redirect_from:
- "/docs/admin/node/"
- "/docs/admin/node.html"
- "/docs/concepts/nodes/node/"
- "/docs/concepts/nodes/node.html"
 ---

 * TOC
@@ -54,8 +49,8 @@ The `conditions` field describes the status of all `Running` nodes.
 |----------------|-------------|
 | `OutOfDisk`    | `True` if there is insufficient free space on the node for adding new pods, otherwise `False` |
 | `Ready`        | `True` if the node is healthy and ready to accept pods, `False` if the node is not healthy and is not accepting pods, and `Unknown` if the node controller has not heard from the node in the last 40 seconds |
-| `MemoryPressure`    | `True` if node has no memory pressure, otherwise `False` |
-| `DiskPressure`    | `True` if node has no disk pressure, otherwise `False` |
+| `MemoryPressure`    | `True` if pressure exists on the node memory -- that is, if the node memory is low; otherwise `False` |
+| `DiskPressure`    | `True` if pressure exists on the disk size -- that is, if the disk capacity is low; otherwise `False` |

 The node condition is represented as a JSON object. For example, the following response describes a healthy node.

@@ -68,7 +63,7 @@ The node condition is represented as a JSON object. For example, the following r
 ]
 ```

-If the Status of the Ready condition is "Unknown" or "False" for longer than the `pod-eviction-timeout`, an argument passed to the [kube-controller-manager](/docs/admin/kube-controller-manager/), all of the Pods on the node are scheduled for deletion by the Node Controller. The default eviction timeout duration is **five minutes**. In some cases when the node is unreachable, the apiserver is unable to communicate with the kubelet on it. The decision to delete the pods cannot be communicated to the kubelet until it re-establishes communication with the apiserver. In the meantime, the pods which are scheduled for deletion may continue to run on the partitioned node. 
+If the Status of the Ready condition is "Unknown" or "False" for longer than the `pod-eviction-timeout`, an argument passed to the [kube-controller-manager](/docs/admin/kube-controller-manager/), all of the Pods on the node are scheduled for deletion by the Node Controller. The default eviction timeout duration is **five minutes**. In some cases when the node is unreachable, the apiserver is unable to communicate with the kubelet on it. The decision to delete the pods cannot be communicated to the kubelet until it re-establishes communication with the apiserver. In the meantime, the pods which are scheduled for deletion may continue to run on the partitioned node.

 In versions of Kubernetes prior to 1.5, the node controller would [force delete](/docs/concepts/workloads/pods/pod/#force-deletion-of-pods) these unreachable pods from the apiserver. However, in 1.5 and higher, the node controller does not force delete pods until it is confirmed that they have stopped running in the cluster. One can see these pods which may be running on an unreachable node as being in the "Terminating" or "Unknown" states. In cases where Kubernetes cannot deduce from the underlying infrastructure if a node has permanently left a cluster, the cluster administrator may need to delete the node object by hand.  Deleting the node object from Kubernetes causes all the Pod objects running on it to be deleted from the apiserver, freeing up their names.

@@ -1,8 +1,5 @@
 ---
 title: Installing Addons
-redirect_from:
- "/docs/admin/addons/"
- "/docs/admin/addons.html"
 ---

 ## Overview
@@ -3,11 +3,6 @@ assignees:
 - davidopp
 - lavalamp
 title: Cluster Administration Overview
-redirect_from:
- "/docs/admin/"
- "/docs/admin/index.html"
- "/docs/tasks/administer-cluster/overview/"
- "/docs/tasks/administer-cluster/overview.html"
 ---

 {% capture overview %}
@@ -1,12 +1,5 @@
 ---
 title: Federation
-redirect_from:
- "/docs/user-guide/federation/"
- "/docs/user-guide/federation/index.html"
- "/docs/concepts/cluster-administration/multiple-clusters/"
- "/docs/concepts/cluster-administration/multiple-clusters.html"
- "/docs/admin/multi-cluster/"
- "/docs/admin/multi-cluster.html"
 ---

 {% capture overview %}
@@ -48,7 +41,7 @@ why you might want multiple clusters are:
 * [Hybrid cloud](###hybrid-cloud-capabilities): You can have multiple clusters on different cloud providers or
  on-premises data centers.

-### Caveats 
+### Caveats

 While there are a lot of attractive use cases for federation, there are also
 some caveats:
@@ -2,9 +2,6 @@
 assignees:
 - mikedanese
 title: Configuring kubelet Garbage Collection
-redirect_from:
- "/docs/admin/garbage-collection/"
- "/docs/admin/garbage-collection.html"
 ---

 * TOC
@@ -3,12 +3,6 @@ assignees:
 - crassirostris
 - piosz
 title: Logging Architecture
-redirect_from:
- "/docs/concepts/clusters/logging/"
- "/docs/concepts/clusters/logging.html"
-redirect_from:
- "/docs/user-guide/logging/overview/"
- "/docs/user-guide/logging/overview.html"
 ---

 Application and systems logs can help you understand what is happening inside your cluster. The logs are particularly useful for debugging problems and monitoring cluster activity. Most modern applications have some kind of logging mechanism; as such, most container engines are likewise designed to support some kind of logging. The easiest and most embraced logging method for containerized applications is to write to the standard output and standard error streams.
@@ -4,9 +4,6 @@ assignees:
 - janetkuo
 - mikedanese
 title: Managing Resources
-redirect_from:
- "/docs/user-guide/managing-deployments/"
- "/docs/user-guide/managing-deployments.html"
 ---

 You've deployed your application and exposed it via a service. Now what? Kubernetes provides a number of tools to help you manage your application deployment, including scaling and updating. Among the features we'll discuss in more depth are [configuration files](/docs/user-guide/configuring-containers/#configuration-in-kubernetes) and [labels](/docs/user-guide/deploying-applications/#labels).
@@ -4,9 +4,6 @@ assignees:
 - freehan
 - thockin
 title: Network Plugins
-redirect_from:
- "/docs/admin/network-plugins/"
- "/docs/admin/network-plugins.html"
 ---

 * TOC
@@ -2,9 +2,6 @@
 assignees:
 - thockin
 title: Cluster Networking
-redirect_from:
- "/docs/admin/networking/"
- "/docs/admin/networking.html"
 ---

 Kubernetes approaches networking somewhat differently than Docker does by
@@ -85,7 +82,7 @@ talk to other VMs in your project.  This is the same basic model.
 Until now this document has talked about containers.  In reality, Kubernetes
 applies IP addresses at the `Pod` scope - containers within a `Pod` share their
 network namespaces - including their IP address.  This means that containers
-within a `Pod` can all reach each other's ports on `localhost`. This does imply 
+within a `Pod` can all reach each other's ports on `localhost`. This does imply
 that containers within a `Pod` must coordinate port usage, but this is no
 different than processes in a VM.  We call this the "IP-per-pod" model.  This
 is implemented in Docker as a "pod container" which holds the network namespace
@@ -217,9 +214,9 @@ Calico can also be run in policy enforcement mode in conjunction with other netw

 ### Weave Net from Weaveworks

-[Weave Net](https://www.weave.works/products/weave-net/) is a 
-resilient and simple to use network for Kubernetes and its hosted applications.  
-Weave Net runs as a [CNI plug-in](https://www.weave.works/docs/net/latest/cni-plugin/)  
+[Weave Net](https://www.weave.works/products/weave-net/) is a
+resilient and simple to use network for Kubernetes and its hosted applications.
+Weave Net runs as a [CNI plug-in](https://www.weave.works/docs/net/latest/cni-plugin/)
 or stand-alone.  In either version, it doesn't require any configuration or extra code
 to run, and in both cases, the network provides one IP address per pod - as is standard for Kubernetes.

@@ -1,8 +1,5 @@
 ---
 title: Proxies in Kubernetes
-redirect_from:
- "/docs/user-guide/accessing-the-cluster/"
- "/docs/user-guide/accessing-the-cluster.html"
 ---

 {% capture overview %}
@@ -2,9 +2,6 @@
 assignees:
 - sttts
 title: Using Sysctls in a Kubernetes Cluster
-redirect_from:
- "/docs/admin/sysctls/"
- "/docs/admin/sysctls.html"
 ---

 * TOC
@@ -4,9 +4,6 @@ assignees:
 - kevin-wangzefeng
 - bsalamat
 title: Assigning Pods to Nodes
-redirect_from:
- "/docs/user-guide/node-selection/"
- "/docs/user-guide/node-selection/index.html"
 ---

 You can constrain a [pod](/docs/concepts/workloads/pods/pod/) to only be able to run on particular [nodes](/docs/concepts/nodes/node/) or to prefer to
@@ -142,6 +139,8 @@ If you specify multiple `nodeSelectorTerms` associated with `nodeAffinity` types

 If you specify multiple `matchExpressions` associated with `nodeSelectorTerms`, then the pod can be scheduled onto a node **only if all** `matchExpressions` can be satisfied.

+If you remove or change the label of the node where the pod is scheduled, the pod won't be removed. In other words, the affinity selection works only at the time of scheduling the pod.
+
 For more information on node affinity, see the design doc
 [here](https://git.k8s.io/community/contributors/design-proposals/nodeaffinity.md).

@@ -205,7 +204,7 @@ If omitted, it defaults to the namespace of the pod where the affinity/anti-affi
 If defined but empty, it means "all namespaces."

 All `matchExpressions` associated with `requiredDuringSchedulingIgnoredDuringExecution` affinity and anti-affinity
-must be satisfied for the pod to schedule onto a node. 
+must be satisfied for the pod to schedule onto a node.

 For more information on inter-pod affinity/anti-affinity, see the design doc
 [here](https://git.k8s.io/community/contributors/design-proposals/podaffinity.md).
@@ -236,7 +235,7 @@ taint created by the `kubectl taint` line above, and thus a pod with either tole
 to schedule onto `node1`:

 ```yaml
-tolerations: 
+tolerations:
 - key: "key"
  operator: "Equal"
  value: "value"
@@ -244,7 +243,7 @@ tolerations:
 ```

 ```yaml
-tolerations: 
+tolerations:
 - key: "key"
  operator: "Exists"
  effect: "NoSchedule"
@@ -304,7 +303,7 @@ kubectl taint nodes node1 key2=value2:NoSchedule
 And a pod has two tolerations:

 ```yaml
-tolerations: 
+tolerations:
 - key: "key1"
  operator: "Equal"
  value: "value1"
@@ -327,7 +326,7 @@ an optional `tolerationSeconds` field that dictates how long the pod will stay b
 to the node after the taint is added. For example,

 ```yaml
-tolerations: 
+tolerations:
 - key: "key1"
  operator: "Equal"
  value: "value1"
@@ -345,7 +344,7 @@ Taints and tolerations are a flexible way to steer pods away from nodes or evict
 pods that shouldn't be running. A few of the use cases are

 * **dedicated nodes**: If you want to dedicate a set of nodes for exclusive use by
-a particular set of users, you can add a taint to those nodes (say, 
+a particular set of users, you can add a taint to those nodes (say,
 `kubectl taint nodes nodename dedicated=groupName:NoSchedule`) and then add a corresponding
 toleration to their pods (this would be done most easily by writing a custom
 [admission controller](/docs/admin/admission-controllers/)).
@@ -410,7 +409,7 @@ that the partition will recover and thus the pod eviction can be avoided.
 The toleration the pod would use in that case would look like

 ```yaml
-tolerations: 
+tolerations:
 - key: "node.alpha.kubernetes.io/unreachable"
  operator: "Exists"
  effect: "NoExecute"
@@ -1,8 +1,5 @@
 ---
 title: Managing Compute Resources for Containers
-redirect_from:
- "/docs/user-guide/compute-resources/"
- "/docs/user-guide/compute-resources.html"
 ---

 {% capture overview %}
@@ -197,7 +194,7 @@ is pending with a message of this type, there are several things to try:
 - Add more nodes to the cluster.
 - Terminate unneeded Pods to make room for pending Pods.
 - Check that the Pod is not larger than all the nodes. For example, if all the
-  nodes have a capacity of `cpu: 1`, then a Pod with a limit of `cpu: 1.1` will
+  nodes have a capacity of `cpu: 1`, then a Pod with a request of `cpu: 1.1` will
  never be scheduled.

 You can check node capacities and amounts allocated with the
@@ -241,7 +238,7 @@ the node.

 The amount of resources available to Pods is less than the node capacity, because
 system daemons use a portion of the available resources. The `allocatable` field
-[NodeStatus](/docs/resources-reference/v1.6/#nodestatus-v1-core)
+[NodeStatus](/docs/resources-reference/{{page.version}}/#nodestatus-v1-core)
 gives the amount of resources that are available to Pods. For more information, see
 [Node Allocatable Resources](https://git.k8s.io/community/contributors/design-proposals/node-allocatable.md).

@@ -430,9 +427,9 @@ consistency across providers and platforms.
 * Get hands-on experience
 [assigning CPU and RAM resources to a container](/docs/tasks/configure-pod-container/assign-cpu-ram-container/).

-* [Container](/docs/api-reference/v1.6/#container-v1-core)
+* [Container](/docs/api-reference/{{page.version}}/#container-v1-core)

-* [ResourceRequirements](/docs/resources-reference/v1.6/#resourcerequirements-v1-core)
+* [ResourceRequirements](/docs/resources-reference/{{page.version}}/#resourcerequirements-v1-core)

 {% endcapture %}

@@ -2,9 +2,6 @@
 assignees:
 - mikedanese
 title: Configuration Best Practices
-redirect_from:
- "/docs/user-guide/config-best-practices/"
- "/docs/user-guide/config-best-practices.html"
 ---

 {% capture overview %}
@@ -2,9 +2,6 @@
 assignees:
 - mikedanese
 title: Secrets
-redirect_from:
- "/docs/user-guide/secrets/index/"
- "/docs/user-guide/secrets/index.html"
 ---

 Objects of type `secret` are intended to hold sensitive information, such as
@@ -769,6 +766,40 @@ it to read a file.

 <!-- TODO: explain how to do this while still using automation. -->

+## Best practices
+
+### Clients that use the secrets API
+
+When deploying applications that interact with the secrets API, access should be
+limited using [authorization policies](
+https://kubernetes.io/docs/admin/authorization/) such as [RBAC](
+https://kubernetes.io/docs/admin/authorization/rbac/).
+
+Secrets often hold values that span a spectrum of importance, many of which can
+cause escalations within Kubernetes (e.g. service account tokens) and to
+external systems. Even if an individual app can reason about the power of the
+secrets it expects to interact with, other apps within the same namespace can
+render those assumptions invalid.
+
+For these reasons `watch` and `list` requests for secrets within a namespace are
+extremely powerful capabilities and should be avoided, since listing secrets allows
+the clients to inspect the values if all secrets are in that namespace. The ability to
+`watch` and `list` all secrets in a cluster should be reserved for only the most
+privileged, system-level components.
+
+Applications that need to access the secrets API should perform `get` requests on
+the secrets they need. This lets administrators restrict access to all secrets
+while [white-listing access to individual instances](
+https://kubernetes.io/docs/admin/authorization/rbac/#referring-to-resources) that
+the app needs.
+
+For improved performance over a looping `get`, clients can design resources that
+reference a secret then `watch` the resource, re-requesting the secret when the
+reference changes. Additionally, a ["bulk watch" API](
+https://github.com/kubernetes/community/blob/master/contributors/design-proposals/bulk_watch.md)
+to let clients `watch` individual resources has also been proposed, and will likely
+be available in future releases of Kubernetes. 
+
 ## Security Properties

 ### Protections
@@ -3,15 +3,12 @@ assignees:
 - mikedanese
 - thockin
 title: Container Lifecycle Hooks
-redirect_from:
- "/docs/user-guide/container-environment/"
- "/docs/user-guide/container-environment.html"
 ---

 {% capture overview %}

 This page describes how kubelet managed Containers can use the Container lifecycle hook framework
-to run code triggered by events during their management lifecycle. 
+to run code triggered by events during their management lifecycle.

 {% endcapture %}

@@ -34,14 +31,14 @@ There are two hooks that are exposed to Containers:

 This hook executes immediately after a container is created.
 However, there is no guarantee that the hook will execute before the container ENTRYPOINT.
-No parameters are passed to the handler. 
+No parameters are passed to the handler.

 `PreStop`

 This hook is called immediately before a container is terminated.
 It is blocking, meaning it is synchronous,
-so it must complete before the call to delete the container can be sent. 
-No parameters are passed to the handler. 
+so it must complete before the call to delete the container can be sent.
+No parameters are passed to the handler.

 A more detailed description of the termination behavior can be found in
 [Termination of Pods](/docs/concepts/workloads/pods/pod/#termination-of-pods).
@@ -58,13 +55,13 @@ Resources consumed by the command are counted against the Container.
 ### Hook handler execution

 When a Container lifecycle management hook is called,
-the Kubernetes management system executes the handler in the Container registered for that hook.  
+the Kubernetes management system executes the handler in the Container registered for that hook. 

 Hook handler calls are synchronous within the context of the Pod containing the Container.
 This means that for a `PostStart` hook,
 the Container ENTRYPOINT and hook fire asynchronously.
 However, if the hook takes too long to run or hangs,
-the Container cannot reach a `running` state. 
+the Container cannot reach a `running` state.

 The behavior is similar for a `PreStop` hook.
 If the hook hangs during execution,
@@ -87,16 +84,16 @@ Generally, only single deliveries are made.
 If, for example, an HTTP hook receiver is down and is unable to take traffic,
 there is no attempt to resend.
 In some rare cases, however, double delivery may occur.
-For instance, if a kubelet restarts in the middle of sending a hook, 
+For instance, if a kubelet restarts in the middle of sending a hook,
 the hook might be resent after the kubelet comes back up.

 ### Debugging Hook handlers

 The logs for a Hook handler are not exposed in Pod events.
 If a handler fails for some reason, it broadcasts an event.
-For `PostStart`, this is the `FailedPostStartHook` event, 
-and for `PreStop`, this is the `FailedPreStopHook` event. 
-You can see these events by running `kubectl describe pod <pod_name>`. 
+For `PostStart`, this is the `FailedPostStartHook` event,
+and for `PreStop`, this is the `FailedPreStopHook` event.
+You can see these events by running `kubectl describe pod <pod_name>`.
 Here is some example output of events from running this command:

 ```
@@ -111,7 +108,7 @@ Events:
  38s        38s        1    {kubelet gke-test-cluster-default-pool-a07e5d30-siqd}    spec.containers{main}    Normal        Killing        Killing container with docker id 5c6a256a2567: PostStart handler: Error executing in Docker Container: 1
  37s        37s        1    {kubelet gke-test-cluster-default-pool-a07e5d30-siqd}    spec.containers{main}    Normal        Killing        Killing container with docker id 8df9fdfd7054: PostStart handler: Error executing in Docker Container: 1
  38s        37s        2    {kubelet gke-test-cluster-default-pool-a07e5d30-siqd}                Warning        FailedSync    Error syncing pod, skipping: failed to "StartContainer" for "main" with RunContainerError: "PostStart handler: Error executing in Docker Container: 1"
-  1m         22s         2     {kubelet gke-test-cluster-default-pool-a07e5d30-siqd}    spec.containers{main}    Warning        FailedPostStartHook    
+  1m         22s         2     {kubelet gke-test-cluster-default-pool-a07e5d30-siqd}    spec.containers{main}    Warning        FailedPostStartHook
 ```

 {% endcapture %}
@@ -3,9 +3,6 @@ assignees:
 - erictune
 - thockin
 title: Images
-redirect_from:
- "/docs/user-guide/images/"
- "/docs/user-guide/images.html"
 ---

 {% capture overview %}
@@ -83,7 +80,7 @@ images in the ECR registry.

 The kubelet will fetch and periodically refresh ECR credentials.  It needs the following permissions to do this:

- `ecr:GetAuthorizationToken` 
+- `ecr:GetAuthorizationToken`
 - `ecr:BatchCheckLayerAvailability`
 - `ecr:GetDownloadUrlForLayer`
 - `ecr:GetRepositoryPolicy`
@@ -36,7 +36,7 @@ In addition, Kubernetes contains a number of higher-level abstractions called Co

 ## Kubernetes Control Plane

-The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will respond to changes in the cluster and work to make the actual state of all the objects in the system to the desired state that you provided.
+The various parts of the Kubernetes Control Plane, such as the Kubernetes Master and kubelet processes, govern how Kubernetes communicates with your cluster. The Control Plane maintains a record of all of the Kubernetes Objects in the system, and runs continuous control loops to manage those objects' state. At any given time, the Control Plane's control loops will respond to changes in the cluster and work to make the actual state of all the objects in the system match the desired state that you provided.

 For example, when you use the Kubernetes API to create a Deployment object, you provide a new desired state for the system. The Kubernetes Control Plane records that object creation, and carries out your instructions by starting the required applications and scheduling them to cluster nodes--thus making the cluster's actual state match the desired state.

@@ -2,10 +2,8 @@
 assignees:
 - lavalamp
 title: Kubernetes Components
-redirect_from:
- "/docs/admin/cluster-components/"
- "/docs/admin/cluster-components.html"
 ---
+
 {% capture overview %}
 This document outlines the various binary components needed to
 deliver a functioning Kubernetes cluster.
@@ -15,7 +13,7 @@ deliver a functioning Kubernetes cluster.
 ## Master Components

 Master components provide the cluster's control plane. Master components make global decisions about the
-cluster (for example, scheduling), and detecting and responding to cluster events (starting up a new pod when a replication controller's 'replicas' field is unsatisfied). 
+cluster (for example, scheduling), and detecting and responding to cluster events (starting up a new pod when a replication controller's 'replicas' field is unsatisfied).

 Master components can be run on any node in the cluster. However,
 for simplicity, set up scripts typically start all master components on
@@ -28,7 +26,7 @@ Kubernetes control plane. It is designed to scale horizontally -- that is, it sc

 ### etcd

-[etcd](/docs/admin/etcd) is used as Kubernetes' backing store. All cluster data is stored here. Always have a backup plan for etcd's data for your Kubernetes cluster. 
+[etcd](/docs/admin/etcd) is used as Kubernetes' backing store. All cluster data is stored here. Always have a backup plan for etcd's data for your Kubernetes cluster.

 ### kube-controller-manager

@@ -41,12 +39,12 @@ These controllers include:
  controller object in the system.
  * Endpoints Controller: Populates the Endpoints object (that is, joins Services & Pods).
  * Service Account & Token Controllers: Create default accounts and API access tokens for new namespaces.
-  
+
 ### cloud-controller-manager

-cloud-controller-manager runs controllers that interact with the underlying cloud providers. The cloud-controller-manager binary is an alpha feature introduced in Kubernetes release 1.6. 
+cloud-controller-manager runs controllers that interact with the underlying cloud providers. The cloud-controller-manager binary is an alpha feature introduced in Kubernetes release 1.6.

-cloud-controller-manager runs cloud-provider-specific controller loops only. You must disable these controller loops in the kube-controller-manager. You can disable the controller loops by setting the `--cloud-provider` flag to `external` when starting the kube-controller-manager. 
+cloud-controller-manager runs cloud-provider-specific controller loops only. You must disable these controller loops in the kube-controller-manager. You can disable the controller loops by setting the `--cloud-provider` flag to `external` when starting the kube-controller-manager.

 cloud-controller-manager allows cloud vendors code and the Kubernetes core to evolve independent of each other. In prior releases, the core Kubernetes code was dependent upon cloud-provider-specific code for functionality. In future releases, code specific to cloud vendors should be maintained by the cloud vendor themselves, and linked to cloud-controller-manager while running Kubernetes.

@@ -55,7 +53,7 @@ The following controllers have cloud provider dependencies:
  * Node Controller: For checking the cloud provider to determine if a node has been deleted in the cloud after it stops responding
  * Route Controller: For setting up routes in the underlying cloud infrastructure
  * Service Controller: For creating, updating and deleting cloud provider load balancers
-  * Volume Controller: For creating, attaching, and mounting volumes, and interacting with the cloud provider to orchestrate volumes  
+  * Volume Controller: For creating, attaching, and mounting volumes, and interacting with the cloud provider to orchestrate volumes

 ### kube-scheduler

@@ -2,9 +2,6 @@
 assignees:
 - chenopis
 title: The Kubernetes API
-redirect_from:
- "/docs/api/"
- "/docs/api.html"
 ---

 Overall API conventions are described in the [API conventions doc](https://git.k8s.io/community/contributors/devel/api-conventions.md).
@@ -3,10 +3,8 @@ assignees:
 - bgrant0607
 - mikedanese
 title: What is Kubernetes?
-redirect_from:
- "/docs/whatisk8s/"
- "/docs/whatisk8s.html"
 ---
+
 {% capture overview %}
 This page is an overview of Kubernetes.
 {% endcapture %}
@@ -19,7 +17,7 @@ With Kubernetes, you are able to quickly and efficiently respond to customer dem
 - Deploy your applications quickly and predictably.
 - Scale your applications on the fly.
 - Roll out new features seamlessly.
- - Limit hardware usage to required resources only. 
+ - Limit hardware usage to required resources only.

 Our goal is to foster an ecosystem of components and tools that relieve the burden of running applications in public and private clouds.

@@ -1,8 +1,5 @@
 ---
 title: Annotations
-redirect_from:
- "/docs/user-guide/annotations/"
- "/docs/user-guide/annotations.html"
 ---

 {% capture overview %}
@@ -1,9 +1,5 @@
 ---
 title: Understanding Kubernetes Objects
-
-redirect_from:
- "/docs/concepts/abstractions/overview/"
- "/docs/concepts/abstractions/overview.html"
 ---

 {% capture overview %}
@@ -2,9 +2,6 @@
 assignees:
 - mikedanese
 title: Labels and Selectors
-redirect_from:
- "/docs/user-guide/labels/"
- "/docs/user-guide/labels.html"
 ---

 _Labels_ are key/value pairs that are attached to objects, such as pods.
@@ -60,7 +57,7 @@ An empty label selector (that is, one with zero requirements) selects every obje

 A null label selector (which is only possible for optional selector fields) selects no objects.

-**Note**: the label selectors of two controllers must not overlap within a namespace, otherwise they will fight with each other. 
+**Note**: the label selectors of two controllers must not overlap within a namespace, otherwise they will fight with each other.

 ### _Equality-based_ requirement

@@ -79,7 +76,7 @@ One could filter for resources in `production` excluding `frontend` using the co

 ### _Set-based_ requirement

-_Set-based_ label requirements allow filtering keys according to a set of values. Three kinds of operators are supported: `in`,`notin` and exists (only the key identifier). For example:
+_Set-based_ label requirements allow filtering keys according to a set of values. Three kinds of operators are supported: `in`,`notin` and `exists` (only the key identifier). For example:

 ```
 environment in (production, qa)
@@ -3,9 +3,6 @@ assignees:
 - mikedanese
 - thockin
 title: Names
-redirect_from:
- "/docs/user-guide/identifiers/"
- "/docs/user-guide/identifiers.html"
 ---

 All objects in the Kubernetes REST API are unambiguously identified by a Name and a UID.
@@ -4,9 +4,6 @@ assignees:
 - mikedanese
 - thockin
 title: Namespaces
-redirect_from:
- "/docs/user-guide/namespaces/"
- "/docs/user-guide/namespaces.html"
 ---

 Kubernetes supports multiple virtual clusters backed by the same physical cluster.
@@ -2,13 +2,10 @@
 assignees:
 - pweil-
 title: Pod Security Policies
-redirect_from:
- "/docs/user-guide/pod-security-policy/"
- "/docs/user-guide/pod-security-policy/index.html"
 ---

 Objects of type `PodSecurityPolicy` govern the ability
-to make requests on a pod that affect the `SecurityContext` that will be 
+to make requests on a pod that affect the `SecurityContext` that will be
 applied to a pod and container.

 See [PodSecurityPolicy proposal](https://git.k8s.io/community/contributors/design-proposals/security-context-constraints.md) for more information.
@@ -18,10 +15,10 @@ See [PodSecurityPolicy proposal](https://git.k8s.io/community/contributors/desig

 ## What is a Pod Security Policy?

-A _Pod Security Policy_ is a cluster-level resource that controls the 
+A _Pod Security Policy_ is a cluster-level resource that controls the
 actions that a pod can perform and what it has the ability to access. The
-`PodSecurityPolicy` objects define a set of conditions that a pod must 
-run with in order to be accepted into the system. They allow an 
+`PodSecurityPolicy` objects define a set of conditions that a pod must
+run with in order to be accepted into the system. They allow an
 administrator to control the following:

 | Control Aspect                                                | Field Name                        |
@@ -35,23 +32,22 @@ administrator to control the following:
 | The use of host ports                                         | `hostPorts`                       |
 | The use of host's PID namespace                               | `hostPID`                         |
 | The use of host's IPC namespace                               | `hostIPC`                         |
-| The use of host paths                                         | [`allowedHostPaths`](#allowed-host-paths)    |
 | The SELinux context of the container                          | [`seLinux`](#selinux)             |
 | The user ID                                                   | [`runAsUser`](#runasuser)         |
 | Configuring allowable supplemental groups                     | [`supplementalGroups`](#supplementalgroups) |
 | Allocating an FSGroup that owns the pod's volumes             | [`fsGroup`](#fsgroup)             |
 | Requiring the use of a read only root file system             | `readOnlyRootFilesystem`          |

-_Pod Security Policies_ are comprised of settings and strategies that 
-control the security features a pod has access to. These settings fall 
+_Pod Security Policies_ are comprised of settings and strategies that
+control the security features a pod has access to. These settings fall
 into three categories:

- *Controlled by a boolean*: Fields of this type default to the most 
-restrictive value. 
- *Controlled by an allowable set*: Fields of this type are checked 
+- *Controlled by a boolean*: Fields of this type default to the most
+restrictive value.
+- *Controlled by an allowable set*: Fields of this type are checked
 against the set to ensure their value is allowed.
 - *Controlled by a strategy*: Items that have a strategy to provide
-a mechanism to generate the value and a mechanism to ensure that a 
+a mechanism to generate the value and a mechanism to ensure that a
 specified value falls into the set of allowable values.


@@ -76,22 +72,22 @@ specified.

 ### SupplementalGroups

- *MustRunAs* - Requires at least one range to be specified. Uses the 
+- *MustRunAs* - Requires at least one range to be specified. Uses the
 minimum value of the first range as the default. Validates against all ranges.
 - *RunAsAny* - No default provided. Allows any `supplementalGroups` to be
 specified.

 ### FSGroup

- *MustRunAs* - Requires at least one range to be specified. Uses the 
-minimum value of the first range as the default. Validates against the 
+- *MustRunAs* - Requires at least one range to be specified. Uses the
+minimum value of the first range as the default. Validates against the
 first ID in the first range.
 - *RunAsAny* - No default provided. Allows any `fsGroup` ID to be specified.

 ### Controlling Volumes

-The usage of specific volume types can be controlled by setting the 
-volumes field of the PSP. The allowable values of this field correspond 
+The usage of specific volume types can be controlled by setting the
+volumes field of the PSP. The allowable values of this field correspond
 to the volume sources that are defined when creating a volume:

 1. azureFile
@@ -123,15 +119,12 @@ to the volume sources that are defined when creating a volume:
 1. storageos
 1. \* (allow all volumes)

-The recommended minimum set of allowed volumes for new PSPs are 
+The recommended minimum set of allowed volumes for new PSPs are
 configMap, downwardAPI, emptyDir, persistentVolumeClaim, secret, and projected.

 ### Host Network
 - *HostPorts*, default `empty`. List of `HostPortRange`, defined by `min`(inclusive) and `max`(inclusive), which define the allowed host ports.
-
-### Allowed Host Paths
- - *AllowedHostPaths* is a white list of allowed host path prefixes. Empty indicates that all host paths may be used.
-
+ 
 ## Admission

 _Admission control_ with `PodSecurityPolicy` allows for control over the
@@ -197,7 +190,7 @@ podsecuritypolicy "permissive" deleted

 ## Enabling Pod Security Policies

-In order to use Pod Security Policies in your cluster you must ensure the 
+In order to use Pod Security Policies in your cluster you must ensure the
 following

 1.  You have enabled the api type `extensions/v1beta1/podsecuritypolicy` (only for versions prior 1.6)
@@ -206,6 +199,29 @@ following

 ## Working With RBAC

-In Kubernetes 1.5 and newer, you can use PodSecurityPolicy to control access to privileged containers based on user role and groups. Access to different PodSecurityPolicy objects can be controlled via authorization. To limit access to PodSecurityPolicy objects for pods created via a Deployment, ReplicaSet, etc, the [Controller Manager](/docs/admin/kube-controller-manager/) must be run against the secured API port, and must not have superuser permissions.
+In Kubernetes 1.5 and newer, you can use PodSecurityPolicy to control access to
+privileged containers based on user role and groups. Access to different
+PodSecurityPolicy objects can be controlled via authorization.

-PodSecurityPolicy authorization uses the union of all policies available to the user creating the pod and the service account specified on the pod. When pods are created via a Deployment, ReplicaSet, etc, it is Controller Manager that creates the pod, so if it is running against the unsecured API port, all PodSecurityPolicy objects would be allowed, and you could not effectively subdivide access. Access to given PSP policies for a user will be effective only when deploying Pods directly. For more details, see the [PodSecurityPolicy RBAC example](https://git.k8s.io/kubernetes/examples/podsecuritypolicy/rbac/README.md) of applying PodSecurityPolicy to control access to privileged containers based on role and groups when deploying Pods directly.
+Note that [Controller Manager](/docs/admin/kube-controller-manager/) must be run
+against [the secured API port](/docs/admin/accessing-the-api/), and must not
+have superuser permissions. Otherwise requests would bypass authentication and
+authorization modules, all PodSecurityPolicy objects would be allowed,
+and user will be able to create privileged containers.
+
+PodSecurityPolicy authorization uses the union of all policies available to the
+user creating the pod and
+[the service account specified on the pod](/docs/tasks/configure-pod-container/configure-service-account/).
+
+Access to given PSP policies for a user will be effective only when creating
+Pods directly.
+
+For pods created on behalf of a user, in most cases by Controller Manager,
+access should be given to the service account specified on the pod spec
+template. Examples of resources that create pods on behalf of a user are
+Deployments, ReplicaSets, etc.
+
+For more details, see the
+[PodSecurityPolicy RBAC example](https://git.k8s.io/examples/staging/podsecuritypolicy/rbac/README.md)
+of applying PodSecurityPolicy to control access to privileged containers based
+on role and groups when deploying Pods directly.
@@ -2,9 +2,6 @@
 assignees:
 - derekwaynecarr
 title: Resource Quotas
-redirect_from:
- "/docs/admin/resourcequota/"
- "/docs/admin/resourcequota/index.html"
 ---

 When several users or teams share a cluster with a fixed number of nodes,
@@ -56,7 +53,7 @@ Resource Quota is enforced in a particular namespace when there is a
 ## Compute Resource Quota

 You can limit the total sum of [compute resources](/docs/user-guide/compute-resources) that can be requested in a given namespace.
- 
+
 The following resource types are supported:

 | Resource Name | Description |
@@ -70,7 +67,7 @@ The following resource types are supported:

 ## Storage Resource Quota

-You can limit the total sum of [storage resources](/docs/user-guide/persistent-volumes) that can be requested in a given namespace. 
+You can limit the total sum of [storage resources](/docs/user-guide/persistent-volumes) that can be requested in a given namespace.

 In addition, you can limit consumption of storage resources based on associated storage-class.

@@ -3,9 +3,6 @@ assignees:
 - rickypai
 - thockin
 title: Adding entries to Pod /etc/hosts with HostAliases
-redirect_from:
- "/docs/user-guide/add-entries-to-pod-etc-hosts-with-host-aliases/"
- "/docs/user-guide/add-entries-to-pod-etc-hosts-with-host-aliases.md"
 ---

 * TOC
@@ -4,9 +4,6 @@ assignees:
 - lavalamp
 - thockin
 title: Connecting Applications with Services
-redirect_from:
- "/docs/user-guide/connecting-applications/"
- "/docs/user-guide/connecting-applications.html"
 ---

 * TOC
@@ -67,7 +64,7 @@ This is equivalent to `kubectl create -f` the following yaml:

 {% include code.html language="yaml" file="nginx-svc.yaml" ghlink="/docs/concepts/services-networking/nginx-svc.yaml" %}

-This specification will create a Service which targets TCP port 80 on any Pod with the `run: my-nginx` label, and expose it on an abstracted Service port (`targetPort`: is the port the container accepts traffic on, `port`: is the abstracted Service port, which can be any port other pods use to access the Service). View [service API object](/docs/api-reference/v1.6/#service-v1-core) to see the list of supported fields in service definition.
+This specification will create a Service which targets TCP port 80 on any Pod with the `run: my-nginx` label, and expose it on an abstracted Service port (`targetPort`: is the port the container accepts traffic on, `port`: is the abstracted Service port, which can be any port other pods use to access the Service). View [service API object](/docs/api-reference/{{page.version}}/#service-v1-core) to see the list of supported fields in service definition.
 Check your Service:

 ```shell
@@ -181,7 +178,7 @@ secret "nginxsecret" created
 $ kubectl get secrets
 NAME                  TYPE                                  DATA      AGE
 default-token-il9rc   kubernetes.io/service-account-token   1         1d
-nginxsecret           Opaque                                2         1m     
+nginxsecret           Opaque                                2         1m
 ```

 Now modify your nginx replicas to start an https server using the certificate in the secret, and the Service, to expose both ports (80 and 443):
@@ -3,9 +3,6 @@ assignees:
 - davidopp
 - thockin
 title: DNS Pods and Services
-redirect_from:
- "/docs/admin/dns/"
- "/docs/admin/dns.html"
 ---

 ## Introduction
@@ -105,7 +102,7 @@ spec:
  clusterIP: None
  ports:
    - name: foo # Actually, no port is needed.
-      port: 1234 
+      port: 1234
      targetPort: 1234
 ---
 apiVersion: v1
@@ -142,7 +139,7 @@ spec:
 ```

 If there exists a headless service in the same namespace as the pod and with the same name as the subdomain, the cluster's KubeDNS Server also returns an A record for the Pod's fully qualified hostname.
-Given a Pod with the hostname set to "busybox-1" and the subdomain set to "default-subdomain", and a headless Service named "default-subdomain" in the same namespace, the pod will see it's own FQDN as "busybox-1.default-subdomain.my-namespace.svc.cluster.local". DNS serves an A record at that name, pointing to the Pod's IP. Both pods "busybox1" and "busybox2" can have their distinct A records. 
+Given a Pod with the hostname set to "busybox-1" and the subdomain set to "default-subdomain", and a headless Service named "default-subdomain" in the same namespace, the pod will see it's own FQDN as "busybox-1.default-subdomain.my-namespace.svc.cluster.local". DNS serves an A record at that name, pointing to the Pod's IP. Both pods "busybox1" and "busybox2" can have their distinct A records.

 As of Kubernetes v1.2, the Endpoints object also has the annotation `endpoints.beta.kubernetes.io/hostnames-map`. Its value is the json representation of map[string(IP)][endpoints.HostRecord], for example: '{"10.245.1.6":{HostName: "my-webserver"}}'.
 If the Endpoints are for a headless service, an A record is created with the format <hostname>.<service name>.<pod namespace>.svc.<cluster domain>
@@ -237,6 +234,29 @@ nameserver 10.0.0.10
 options ndots:5
 ```

+### DNS Policy
+
+By default, DNS policy for a pod is 'ClusterFirst'. So pods running with hostNetwork cannot resolve DNS names. To have DNS options set along with hostNetwork, you should specify DNS policy explicitly to 'ClusterFirstWithHostNet'. Update the busybox.yaml as following:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: busybox
+  namespace: default
+spec:
+  containers:
+  - image: busybox
+    command:
+      - sleep
+      - "3600"
+    imagePullPolicy: IfNotPresent
+    name: busybox
+  restartPolicy: Always
+  hostNetwork: true
+  dnsPolicy: ClusterFirstWithHostNet
+```
+
 #### Quick diagnosis

 Errors such as the following indicate a problem with the kube-dns add-on or associated Services:
@@ -285,7 +305,7 @@ Use `kubectl logs` command to see logs for the DNS daemons.
 ```
 kubectl logs --namespace=kube-system $(kubectl get pods --namespace=kube-system -l k8s-app=kube-dns -o name) -c kubedns
 kubectl logs --namespace=kube-system $(kubectl get pods --namespace=kube-system -l k8s-app=kube-dns -o name) -c dnsmasq
-kubectl logs --namespace=kube-system $(kubectl get pods --namespace=kube-system -l k8s-app=kube-dns -o name) -c healthz
+kubectl logs --namespace=kube-system $(kubectl get pods --namespace=kube-system -l k8s-app=kube-dns -o name) -c sidecar
 ```

 See if there is any suspicious log. W, E, F letter at the beginning represent Warning, Error and Failure. Please search for entries that have these as the logging level and use [kubernetes issues](https://github.com/kubernetes/kubernetes/issues) to report unexpected errors.
@@ -2,9 +2,6 @@
 assignees:
 - bprashanth
 title: Ingress Resources
-redirect_from:
- "/docs/user-guide/ingress/"
- "/docs/user-guide/ingress.html"
 ---

 * TOC
@@ -4,9 +4,6 @@ assignees:
 - caseydavenport
 - danwinship
 title: Network Policies
-redirect_from:
- "/docs/user-guide/networkpolicies/"
- "/docs/user-guide/networkpolicies.html"
 ---

 * TOC
@@ -28,7 +25,7 @@ Pods become isolated by having a NetworkPolicy that selects them. Once there is

 ## The `NetworkPolicy` Resource

-See the [api-reference](/docs/api-reference/v1.7/#networkpolicy-v1-networking) for a full definition of the resource.
+See the [api-reference](/docs/api-reference/{{page.version}}/#networkpolicy-v1-networking) for a full definition of the resource.

 An example `NetworkPolicy` might look like this:

@@ -2,9 +2,6 @@
 assignees:
 - bprashanth
 title: Services
-redirect_from:
- "/docs/user-guide/services/"
- "/docs/user-guide/services/index.html"
 ---

 Kubernetes [`Pods`](/docs/user-guide/pods) are mortal. They are born and when they die, they
@@ -319,9 +316,9 @@ Sometimes you don't need or want load-balancing and a single service IP.  In
 this case, you can create "headless" services by specifying `"None"` for the
 cluster IP (`spec.clusterIP`).

-This option allows developers to reduce coupling to the Kubernetes system by 
-allowing them freedom to do discovery their own way.  Applications can still use 
-a self-registration pattern and adapters for other discovery systems could easily 
+This option allows developers to reduce coupling to the Kubernetes system by
+allowing them freedom to do discovery their own way.  Applications can still use
+a self-registration pattern and adapters for other discovery systems could easily
 be built upon this API.

 For such `Services`, a cluster IP is not allocated, kube-proxy does not handle
@@ -356,15 +353,15 @@ The default is `ClusterIP`.

 `Type` values and their behaviors are:

-   * `ClusterIP`: Exposes the service on a cluster-internal IP. Choosing this value 
-     makes the service only reachable from within the cluster. This is the 
+   * `ClusterIP`: Exposes the service on a cluster-internal IP. Choosing this value
+     makes the service only reachable from within the cluster. This is the
     default `ServiceType`.
-   * `NodePort`: Exposes the service on each Node's IP at a static port (the `NodePort`). 
-     A `ClusterIP` service, to which the NodePort service will route, is automatically 
-     created.  You'll be able to contact the `NodePort` service, from outside the cluster, 
+   * `NodePort`: Exposes the service on each Node's IP at a static port (the `NodePort`).
+     A `ClusterIP` service, to which the NodePort service will route, is automatically
+     created.  You'll be able to contact the `NodePort` service, from outside the cluster,
     by requesting `<NodeIP>:<NodePort>`.
-   * `LoadBalancer`: Exposes the service externally using a cloud provider's load balancer. 
-     `NodePort` and `ClusterIP` services, to which the external load balancer will route, 
+   * `LoadBalancer`: Exposes the service externally using a cloud provider's load balancer.
+     `NodePort` and `ClusterIP` services, to which the external load balancer will route,
     are automatically created.
   * `ExternalName`: Maps the service to the contents of the `externalName` field
     (e.g. `foo.bar.example.com`), by returning a `CNAME` record with its value.
@@ -441,9 +438,9 @@ This can be achieved by adding the following annotations to the service based on
 For AWS:
 ```yaml
 [...]
-metadata: 
+metadata:
    name: my-service
-    annotations: 
+    annotations:
        service.beta.kubernetes.io/aws-load-balancer-internal: 0.0.0.0/0
 [...]
 ```
@@ -516,7 +513,7 @@ spec:
      protocol: TCP
      port: 80
      targetPort: 9376
-  externalIPs: 
+  externalIPs:
    - 80.11.12.10
 ```

@@ -5,9 +5,6 @@ assignees:
 - saad-ali
 - thockin
 title: Persistent Volumes
-redirect_from:
- "/docs/user-guide/persistent-volumes/"
- "/docs/user-guide/persistent-volumes/index.html"
 ---

 This document describes the current state of `PersistentVolumes` in Kubernetes.  Familiarity with [volumes](/docs/concepts/storage/volumes/) is suggested.
@@ -265,7 +262,7 @@ spec:
    pdName: "gce-disk-1"
 ```

-A mount option is a string which will be cumulatively joined and used while mounting volume to the disk. 
+A mount option is a string which will be cumulatively joined and used while mounting volume to the disk.

 Note that not all Persistent volume types support mount options. In Kubernetes version 1.6, the following
 volume types support mount options.
@@ -734,7 +731,7 @@ parameters:
 If storage account is not provided, all storage accounts associated with the resource group are searched to find one that matches `skuName` and `location`. If storage account is provided, it must reside in the same resource group as the cluster, and `skuName` and `location` are ignored.

 During provision, a secret will be created for mounting credentials. If the cluster has enabled both [RBAC](/docs/admin/authorization/rbac/) and [Controller Roles](/docs/admin/authorization/rbac/#controller-roles), you will first need to add `create` permission of resource `secret` for clusterrole `system:controller:persistent-volume-binder`.
- 
+
 #### Portworx Volume

 ```yaml
@@ -786,7 +783,7 @@ parameters:
 * `readOnly`: specifies the access mode to the mounted volume
 * `fsType`: the file system to use for the volume

-The ScaleIO Kubernetes volume plugin requires a configured Secret object. 
+The ScaleIO Kubernetes volume plugin requires a configured Secret object.
 The secret must be created with type `kubernetes.io/scaleio` and use the same namespace value as that of the PVC where it is referenced
 as shown in the following command:

@@ -5,9 +5,6 @@ assignees:
 - saad-ali
 - thockin
 title: Volumes
-redirect_from:
- "/docs/user-guide/volumes/"
- "/docs/user-guide/volumes.html"
 ---

 {% capture overview %}
@@ -42,7 +39,7 @@ A Kubernetes volume, on the other hand, has an explicit lifetime - the same as
 the pod that encloses it.  Consequently, a volume outlives any containers that run
 within the Pod, and data is preserved across Container restarts. Of course, when a
 Pod ceases to exist, the volume will cease to exist, too.  Perhaps more
-importantly than this, Kubernetes supports many type of volumes, and a Pod can
+importantly than this, Kubernetes supports many types of volumes, and a Pod can
 use any number of them simultaneously.

 At its core, a volume is just a directory, possibly with some data in it, which
@@ -788,7 +785,7 @@ spec:
 Note that local PersistentVolume cleanup and deletion requires manual
 intervention without the external provisioner.

-For details on the `local` volume type, see the [Local Persistent Storage 
+For details on the `local` volume type, see the [Local Persistent Storage
 user guide](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume)

 ## Using subPath
@@ -4,11 +4,6 @@ assignees:
 - soltysh
 - janetkuo
 title: Cron Jobs
-redirect_from:
- "/docs/concepts/jobs/cron-jobs/"
- "/docs/concepts/jobs/cron-jobs.html"
- "/docs/user-guide/cron-jobs/"
- "/docs/user-guide/cron-jobs.html"
 ---

 * TOC
@@ -2,9 +2,6 @@
 assignees:
 - erictune
 title: Daemon Sets
-redirect_from:
- "/docs/admin/daemons/"
- "/docs/admin/daemons.html"
 ---

 * TOC
@@ -41,9 +38,7 @@ A DaemonSet also needs a [`.spec`](https://git.k8s.io/community/contributors/dev

 The `.spec.template` is the only required field of the `.spec`.

-The `.spec.template` is a [pod template](/docs/user-guide/replication-controller/#pod-template).
-It has exactly the same schema as a [pod](/docs/user-guide/pods), except
-it is nested and does not have an `apiVersion` or `kind`.
+The `.spec.template` is a [pod template](/docs/concepts/workloads/pods/pod-overview/#pod-templates). It has exactly the same schema as a [pod](docs/concepts/workloads/pods/pod/), except it is nested and does not have an `apiVersion` or `kind`.

 In addition to required fields for a pod, a pod template in a DaemonSet has to specify appropriate
 labels (see [pod selector](#pod-selector)).
@@ -77,7 +72,7 @@ a node for testing.

 If you specify a `.spec.template.spec.nodeSelector`, then the DaemonSet controller will
 create pods on nodes which match that [node
-selector](/docs/concepts/configuration/assign-pod-node/). Likewise if you specify a `.spec.template.spec.affinity` 
+selector](/docs/concepts/configuration/assign-pod-node/). Likewise if you specify a `.spec.template.spec.affinity`
 then DaemonSet controller will create pods on nodes which match that [node affinity](/docs/concepts/configuration/assign-pod-node/).
 If you do not specify either, then the DaemonSet controller will create pods on all nodes.

@@ -91,7 +86,7 @@ when the pod is created, so it is ignored by the scheduler).  Therefore:
   by the DaemonSet controller.
 - DaemonSet controller can make pods even when the scheduler has not been started, which can help cluster
   bootstrap.
-   
+
 Daemon pods do respect [taints and tolerations](/docs/concepts/configuration/assign-pod-node/#taints-and-tolerations-beta-feature), but they are
 created with `NoExecute` tolerations for the `node.alpha.kubernetes.io/notReady` and `node.alpha.kubernetes.io/unreachable`
 taints with no `tolerationSeconds`. This ensures that when the `TaintBasedEvictions` alpha feature is enabled,
@@ -3,30 +3,31 @@ assignees:
 - bgrant0607
 - janetkuo
 title: Deployments
-redirect_from:
- "/docs/user-guide/deployments/"
- "/docs/user-guide/deployments.html"
 ---

-{:toc}
-
-## What is a Deployment?
+{% capture overview %}

 A _Deployment_ provides declarative updates for [Pods](/docs/concepts/workloads/pods/pod/) and
 [ReplicaSets](/docs/concepts/workloads/controllers/replicaset/) (the next-generation ReplicationController).
-You only need to describe the desired state in a Deployment object, and the Deployment controller will
-change the actual state to the desired state at a controlled rate for you. You can define Deployments to
-create new ReplicaSets, or remove existing Deployments and adopt all of their resources with new Deployments.
+You describe the desired state in a Deployment object, and the Deployment controller changes the actual state to the desired state at a controlled rate. You can define Deployments to
+create new ReplicaSets, or remove existing Deployments and adopt all their resources with new Deployments.

-**Note:** You should not manage ReplicaSets owned by a Deployment, otherwise you are racing with the Deployment
-controller! All of the use cases should be covered just by manipulating the Deployment object. Consider opening
-an issue in the main Kubernetes repository, if your use case is not covered below.
+**Note:** You should not manage ReplicaSets owned by a Deployment. If you do so, you are racing with the Deployment
+controller! All the use cases should be covered by manipulating the Deployment object. Consider opening
+an issue in the main Kubernetes repository if your use case is not covered below.
+
+{% endcapture %}
+
+
+{% capture body %}
+
+## Use Case

 A typical use case is:

 * [Create a Deployment to rollout a ReplicaSet](#creating-a-deployment). The ReplicaSet creates Pods in the background. Check the status of the rollout to see if it succeeds or not.
-* Later, [declare the new state of the Pods](#updating-a-deployment) you want to run by updating the PodTemplateSpec of the Deployment. A new ReplicaSet is created and the Deployment manages moving the Pods from the old to the new ReplicaSet in a controlled rate. Each new ReplicaSet that is created, updates the revision of the Deployment.
-* [Rollback to an earlier Deployment revision](#rolling-back-a-deployment) if the current state of the Deployment will not be stable. Each rollback updates the revision of the Deployment.
+* [Declare the new state of the Pods](#updating-a-deployment) by updating the PodTemplateSpec of the Deployment. A new ReplicaSet is created and the Deployment manages moving the Pods from the old ReplicaSet to the new one at a controlled rate. Each new ReplicaSet updates the revision of the Deployment.
+* [Rollback to an earlier Deployment revision](#rolling-back-a-deployment) if the current state of the Deployment is not stable. Each rollback updates the revision of the Deployment.
 * [Scale up the Deployment to facilitate more load.](#scaling-a-deployment)
 * [Pause the Deployment](#pausing-and-resuming-a-deployment) to apply multiple fixes to its PodTemplateSpec and then resume it to start a new rollout.
 * [Use the status of the Deployment](#deployment-status) as an indicator that a rollout has stuck
@@ -35,7 +36,7 @@ A typical use case is:

 ## Creating a Deployment

-Here is an example Deployment. It creates a ReplicaSet to bring up 3 nginx Pods.
+Here is an example Deployment. It creates a ReplicaSet to bring up three nginx Pods.

 {% include code.html language="yaml" file="nginx-deployment.yaml" ghlink="/docs/concepts/workloads/controllers/nginx-deployment.yaml" %}

@@ -47,7 +48,7 @@ deployment "nginx-deployment" created
 ```

 Setting the kubectl flag `--record` to `true` allows you to record current command in the annotations of
-the resources being created or updated. It will be useful for future introspection; for example, to see the
+the resources being created or updated. It is useful for future introspection: for example, to see the
 commands executed in each Deployment revision.

 Then running `get` immediately will give:
@@ -62,7 +63,7 @@ This indicates that the Deployment's number of desired replicas is 3 (according
 the number of current replicas (`.status.replicas`) is 0, the number of up-to-date replicas (`.status.updatedReplicas`)
 is 0, and the number of available replicas (`.status.availableReplicas`) is also 0.

-To see the Deployment rollout status, simply run:
+To see the Deployment rollout status, run:

 ```shell
 $ kubectl rollout status deployment/nginx-deployment
@@ -70,7 +71,7 @@ Waiting for rollout to finish: 2 out of 3 new replicas have been updated...
 deployment "nginx-deployment" successfully rolled out
 ```

-Running the `get` again a few seconds later, should give:
+Running the `get` again a few seconds later should give:

 ```shell
 $ kubectl get deployments
@@ -98,31 +99,30 @@ nginx-deployment-2035384211-kzszj   1/1       Running   0          18s       app
 nginx-deployment-2035384211-qqcnn   1/1       Running   0          18s       app=nginx,pod-template-hash=2035384211
 ```

-The created ReplicaSet will ensure that there are three nginx Pods at all times.
+The created ReplicaSet ensures that there are three nginx Pods at all times.

 **Note:** You must specify an appropriate selector and pod template labels in a Deployment (in this case,
-`app = nginx`), i.e. don't overlap with other controllers (including other Deployments, ReplicaSets,
-StatefulSets, etc.). Kubernetes won't stop you from doing that, and if you end up with multiple
-controllers that have overlapping selectors, those controllers may fight with each other and won't behave
+`app = nginx`). That is, don't overlap with other controllers (including other Deployments, ReplicaSets,
+StatefulSets, etc.). Kubernetes doesn't stop you from overlapping, and if multiple
+controllers have overlapping selectors, those controllers may fight with each other and won't behave
 correctly.

 ### Pod-template-hash label

-**Note:** This label is not meant to be mutated by users!
+**Note:** This label is not meant to be changed by users!

-Note the pod-template-hash label in the example output in the pod labels above. pod-template-hash is added by the
-Deployment controller in every ReplicaSet that a Deployment creates or adopts. Its purpose is so that children
-ReplicaSets of a Deployment will not overlap among them. It is computed by hashing the PodTemplate of the ReplicaSet
+Note the pod-template-hash label in the example output in the pod labels above. This label is added by the
+Deployment controller to every ReplicaSet that a Deployment creates or adopts. Its purpose is to make sure that child
+ReplicaSets of a Deployment do not overlap. It is computed by hashing the PodTemplate of the ReplicaSet
 and using the resulting hash as the label value that will be added in the ReplicaSet selector, pod template labels,
 and in any existing Pods that the ReplicaSet may have.

 ## Updating a Deployment

-**Note:** a Deployment's rollout is triggered if and only if the Deployment's pod template (i.e. `.spec.template`)
-is changed, e.g. updating labels or container images of the template. Other updates, such as scaling the Deployment,
-will not trigger a rollout.
+**Note:** A Deployment's rollout is triggered if and only if the Deployment's pod template (that is, `.spec.template`)
+is changed, for example if the labels or container images of the template are updated. Other updates, such as scaling the Deployment, do not trigger a rollout.

-Suppose that we now want to update the nginx Pods to start using the `nginx:1.9.1` image
+Suppose that we now want to update the nginx Pods to use the `nginx:1.9.1` image
 instead of the `nginx:1.7.9` image.

 ```shell
@@ -137,7 +137,7 @@ $ kubectl edit deployment/nginx-deployment
 deployment "nginx-deployment" edited
 ```

-To see its rollout status, simply run:
+To see the rollout status, run:

 ```shell
 $ kubectl rollout status deployment/nginx-deployment
@@ -247,14 +247,14 @@ It is generally discouraged to make label selector updates and it is suggested t
 In any case, if you need to perform a label selector update, exercise great caution and make sure you have grasped
 all of the implications.

-* Selector additions require the pod template labels in the Deployment spec to be updated with the new label, too,
+* Selector additions require the pod template labels in the Deployment spec to be updated with the new label too,
 otherwise a validation error is returned. This change is a non-overlapping one, meaning that the new selector does
 not select ReplicaSets and Pods created with the old selector, resulting in orphaning all old ReplicaSets and
 creating a new ReplicaSet.
-* Selector updates, i.e., changing the existing value in a selector key, result in the same behavior as additions.
-* Selector removals, i.e., removing an existing key from the Deployment selector, do not require any changes in the
-pod template labels, no existing ReplicaSet is orphaned, and a new ReplicaSet will not be created, but note that the
-removed label will still exist in any existing Pods and ReplicaSets.
+* Selector updates -- that is, changing the existing value in a selector key -- result in the same behavior as additions.
+* Selector removals -- that is, removing an existing key from the Deployment selector -- do not require any changes in the
+pod template labels. No existing ReplicaSet is orphaned, and a new ReplicaSet is not created, but note that the
+removed label still exists in any existing Pods and ReplicaSets.

 ## Rolling Back a Deployment

@@ -263,11 +263,11 @@ By default, all of the Deployment's rollout history is kept in the system so tha
 (you can change that by modifyingrevision history limit]).

 **Note:** a Deployment's revision is created when a Deployment's rollout is triggered. This means that the
-new revision is created if and only if the Deployment's pod template (i.e. `.spec.template`) is changed,
-e.g. updating labels or container images of the template. Other updates, such as scaling the Deployment,
-will not create a Deployment revision -- so that we can facilitate simultaneous manual- or auto-scaling.
-This implies that when you rollback to an earlier revision, only the Deployment's pod template part will
-be rolled back.
+new revision is created if and only if the Deployment's pod template (`.spec.template`) is changed,
+for example if you update the labels or container images of the template. Other updates, such as scaling the Deployment,
+do not create a Deployment revision, so that we can facilitate simultaneous manual- or auto-scaling.
+This means that when you roll back to an earlier revision, only the Deployment's pod template part is
+rolled back.

 Suppose that we made a typo while updating the Deployment, by putting the image name as `nginx:1.91` instead of `nginx:1.9.1`:

@@ -503,7 +503,7 @@ nginx-deployment-1989198191   7         7         0         7m
 nginx-deployment-618515232    11        11        11        7m
 ```

-## Pausing and Resuming a Deployment 
+## Pausing and Resuming a Deployment

 You can pause a Deployment before triggering one or more updates and then resume it. This will allow you to
 apply multiple fixes in between pausing and resuming without triggering unnecesarry rollouts.
@@ -549,7 +549,7 @@ deployment "nginx" resource requirements updated
 ```

 The initial state of the Deployment prior to pausing it will continue its function, but new updates to
-the Deployment will not have any effect as long as the Deployment is paused. 
+the Deployment will not have any effect as long as the Deployment is paused.

 Eventually, resume the Deployment and observe a new ReplicaSet coming up with all the new updates:
 ```shell
@@ -630,7 +630,7 @@ due to some of the following factors:

 One way you can detect this condition is to specify a deadline parameter in your Deployment spec:
 ([`spec.progressDeadlineSeconds`](#progress-deadline-seconds)). `spec.progressDeadlineSeconds` denotes the
-number of seconds the Deployment controller waits before indicating (via the Deployment status) that the
+number of seconds the Deployment controller waits before indicating (in the Deployment status) that the
 Deployment progress has stalled.

 The following `kubectl` command sets the spec with `progressDeadlineSeconds` to make the controller report
@@ -754,13 +754,13 @@ to a previous revision, or even pause it if you need to apply multiple tweaks in

 You can set `.spec.revisionHistoryLimit` field in a Deployment to specify how many old ReplicaSets for
 this Deployment you want to retain. The rest will be garbage-collected in the background. By default,
-all revision history will be kept. In a future version, it will default to switch to 2. 
+all revision history will be kept. In a future version, it will default to switch to 2.

 **Note:** Explicitly setting this field to 0, will result in cleaning up all the history of your Deployment
 thus that Deployment will not be able to roll back.


-## Use Cases 
+## Use Cases

 ### Canary Deployment

@@ -780,12 +780,11 @@ A Deployment also needs a [`.spec` section](https://git.k8s.io/community/contrib

 The `.spec.template` is the only required field of the `.spec`.

-The `.spec.template` is a [pod template](/docs/user-guide/replication-controller/#pod-template).  It has exactly
-the same schema as a [Pod](/docs/user-guide/pods), except it is nested and does not have an
+The `.spec.template` is a [pod template](/docs/concepts/workloads/pods/pod-overview/#pod-templates). It has exactly the same schema as a [Pod](docs/concepts/workloads/pods/pod/), except it is nested and does not have an
 `apiVersion` or `kind`.

 In addition to required fields for a Pod, a pod template in a Deployment must specify appropriate
-labels (i.e. don't overlap with other controllers, see [selector](#selector)) and an appropriate restart policy.
+labels and an appropriate restart policy. For labels, make sure not to overlap with other controllers. See [selector](#selector)).

 Only a [`.spec.template.spec.restartPolicy`](/docs/concepts/workloads/pods/pod-lifecycle/) equal to `Always` is
 allowed, which is the default if not specified.
@@ -800,19 +799,19 @@ allowed, which is the default if not specified.
 for the Pods targeted by this deployment.

 If specified, `.spec.selector` must match `.spec.template.metadata.labels`, or it will be rejected by
-the API.  If `.spec.selector` is unspecified, `.spec.selector.matchLabels` will be defaulted to
+the API.  If `.spec.selector` is unspecified, `.spec.selector.matchLabels` defaults to
 `.spec.template.metadata.labels`.

-Deployment may kill Pods whose labels match the selector, in the case that their template is different
-than `.spec.template` or if the total number of such Pods exceeds `.spec.replicas`. It will bring up new
-Pods with `.spec.template` if number of Pods are less than the desired number.
+A Deployment may terminate Pods whose labels match the selector if their template is different
+tfrom `.spec.template` or if the total number of such Pods exceeds `.spec.replicas`. It brings up new
+Pods with `.spec.template` if the number of Pods is less than the desired number.

-**Note:** You should not create other pods whose labels match this selector, either directly, via
-another Deployment or via another controller such as ReplicaSets or ReplicationControllers. Otherwise,
-the Deployment will think that those pods were created by it. Kubernetes will not stop you from doing this.
+**Note:** You should not create other pods whose labels match this selector, either directly, by creating
+another Deployment, or by creating another controller such as a ReplicaSet or a ReplicationController. If you
+do so, the first Deployment thinks that it created these other pods. Kubernetes does not stop you from doing this.

 If you have multiple controllers that have overlapping selectors, the controllers will fight with each
-other's and won't behave correctly.
+other and won't behave correctly.

 ### Strategy

@@ -833,10 +832,9 @@ the rolling update process.
 ##### Max Unavailable

 `.spec.strategy.rollingUpdate.maxUnavailable` is an optional field that specifies the maximum number
-of Pods that can be unavailable during the update process. The value can be an absolute number (e.g. 5)
-or a percentage of desired Pods (e.g. 10%). The absolute number is calculated from percentage by
-rounding down. This can not be 0 if `.spec.strategy.rollingUpdate.maxSurge` is 0. By default, a
-value of 25% is used.
+of Pods that can be unavailable during the update process. The value can be an absolute number (for example, 5)
+or a percentage of desired Pods (for example, 10%). The absolute number is calculated from percentage by
+rounding down. The value cannot be 0 if `.spec.strategy.rollingUpdate.maxSurge` is 0. The default value is 25%.

 For example, when this value is set to 30%, the old ReplicaSet can be scaled down to 70% of desired
 Pods immediately when the rolling update starts. Once new Pods are ready, old ReplicaSet can be scaled
@@ -846,12 +844,12 @@ at all times during the update is at least 70% of the desired Pods.
 ##### Max Surge

 `.spec.strategy.rollingUpdate.maxSurge` is an optional field that specifies the maximum number of Pods
-that can be created above the desired number of Pods. Value can be an absolute number (e.g. 5) or a
-percentage of desired Pods (e.g. 10%). This can not be 0 if `MaxUnavailable` is 0. The absolute number
-is calculated from percentage by rounding up. By default, a value of 25% is used.
+that can be created over the desired number of Pods. The value can be an absolute number (for example, 5) or a
+percentage of desired Pods (for example, 10%). The value cannot be 0 if `MaxUnavailable` is 0. The absolute number
+is calculated from the percentage by rounding up. The default value is 25%.

 For example, when this value is set to 30%, the new ReplicaSet can be scaled up immediately when the
-rolling update starts, such that the total number of old and new Pods do not exceed 130% of desired
+rolling update starts, such that the total number of old and new Pods does not exceed 130% of desired
 Pods. Once old Pods have been killed, the new ReplicaSet can be scaled up further, ensuring that the
 total number of Pods running at any time during the update is at most 130% of desired Pods.

@@ -900,7 +898,7 @@ ReplicaSets will be kept by default, consuming resources in `etcd` and crowding
 if this field is not set. The configuration of each Deployment revision is stored in its ReplicaSets;
 therefore, once an old ReplicaSet is deleted, you lose the ability to rollback to that revision of Deployment.

-More specifically, setting this field to zero means that all old ReplicaSets with 0 replica will be cleaned up. 
+More specifically, setting this field to zero means that all old ReplicaSets with 0 replica will be cleaned up.
 In this case, a new Deployment rollout cannot be undone, since its revision history is cleaned up.

 ### Paused
@@ -917,3 +915,7 @@ it is created.
 [Kubectl rolling update](/docs/user-guide/kubectl/{{page.version}}/#rolling-update) updates Pods and ReplicationControllers
 in a similar fashion. But Deployments are recommended, since they are declarative, server side, and have
 additional features, such as rolling back to any previous revision even after the rolling update is done.
+
+{% endcapture %}
+
+{% include templates/concept.md %}
@@ -1,11 +1,5 @@
 ---
 title: Garbage Collection
-redirect_from:
- "/docs/concepts/abstractions/controllers/garbage-collection/"
- "/docs/concepts/abstractions/controllers/garbage-collection.html"
- "/docs/user-guide/garbage-collection/"
- "/docs/user-guide/garbage-collection.html"
-
 ---

 {% capture overview %}
@@ -70,15 +64,15 @@ metadata:

 When you delete an object, you can specify whether the object's dependents are
 also deleted automatically. Deleting dependents automatically is called *cascading
-deletion*.  There are two modes of *cascading deletion*: *background* and *foreground*. 
+deletion*.  There are two modes of *cascading deletion*: *background* and *foreground*.

 If you delete an object without deleting its dependents
-automatically, the dependents are said to be *orphaned*. 
+automatically, the dependents are said to be *orphaned*.

 ### Background cascading deletion

-In *background cascading deletion*, Kubernetes deletes the owner object 
-immediately and the garbage collector then deletes the dependents in 
+In *background cascading deletion*, Kubernetes deletes the owner object
+immediately and the garbage collector then deletes the dependents in
 the background.

 ### Foreground cascading deletion
@@ -90,7 +84,7 @@ the following things are true:
 * The object is still visible via the REST API
 * The object's `deletionTimestamp` is set
 * The object's `metadata.finalizers` contains the value "foregroundDeletion".
- 
+
 Once the "deletion in progress" state is set, the garbage
 collector deletes the object's dependents. Once the garbage collector has deleted all
 "blocking" dependents (objects with `ownerReference.blockOwnerDeletion=true`), it delete
@@ -100,7 +94,7 @@ Note that in the "foregroundDeletion", only dependents with
 `ownerReference.blockOwnerDeletion` block the deletion of the owner object.
 Kubernetes version 1.7 will add an admission controller that controls user access to set
 `blockOwnerDeletion` to true based on delete permissions on the owner object, so that
-unauthorized dependents cannot delay deletion of an owner object. 
+unauthorized dependents cannot delay deletion of an owner object.

 If an object's `ownerReferences` field is set by a controller (such as Deployment or ReplicaSet),
 blockOwnerDeletion is set automatically and you do not need to manually modify this field.
@@ -3,11 +3,6 @@ assignees:
 - erictune
 - soltysh
 title: Jobs - Run to Completion
-redirect_from:
- "/docs/concepts/jobs/run-to-completion-finite-workloads/"
- "/docs/concepts/jobs/run-to-completion-finite-workloads.html"
- "/docs/user-guide/jobs/"
- "/docs/user-guide/jobs.html"
 ---

 * TOC
@@ -92,9 +87,7 @@ A Job also needs a [`.spec` section](https://git.k8s.io/community/contributors/d

 The `.spec.template` is the only required field of the `.spec`.

-The `.spec.template` is a [pod template](/docs/user-guide/replication-controller/#pod-template).  It has exactly
-the same schema as a [pod](/docs/user-guide/pods), except it is nested and does not have an `apiVersion` or
-`kind`.
+The `.spec.template` is a [pod template](/docs/concepts/workloads/pods/pod-overview/#pod-templates). It has exactly the same schema as a [pod](/docs/user-guide/pods), except it is nested and does not have an `apiVersion` or `kind`.

 In addition to required fields for a Pod, a pod template in a job must specify appropriate
 labels (see [pod selector](#pod-selector)) and an appropriate restart policy.
@@ -115,12 +108,12 @@ There are three main types of jobs:
  - normally only one pod is started, unless the pod fails.
  - job is complete as soon as Pod terminates successfully.
 1. Parallel Jobs with a *fixed completion count*:
-  - specify a non-zero positive value for `.spec.completions`
+  - specify a non-zero positive value for `.spec.completions`.
  - the job is complete when there is one successful pod for each value in the range 1 to `.spec.completions`.
  - **not implemented yet:** each pod passed a different index in the range 1 to `.spec.completions`.
 1. Parallel Jobs with a *work queue*:
-  - do not specify `.spec.completions`, default to `.spec.Parallelism`
-  - the pods must coordinate with themselves or an external service to determine what each should work on
+  - do not specify `.spec.completions`, default to `.spec.Parallelism`.
+  - the pods must coordinate with themselves or an external service to determine what each should work on.
  - each pod is independently capable of determining whether or not all its peers are done, thus the entire Job is done.
  - when _any_ pod terminates with success, no new pods are created.
  - once at least one pod has terminated with success and all pods are terminated, then the job is completed with success.
@@ -8,13 +8,6 @@ assignees:
 - kow3ns
 - smarterclayton
 title: PetSets
-redirect_from:
- "/docs/concepts/abstractions/controllers/petsets/"
- "/docs/concepts/abstractions/controllers/petsets.html"
- "/docs/user-guide/petset/bootstrapping/"
- "/docs/user-guide/petset/bootstrapping/index.html"
- "/docs/user-guide/petset/"
- "/docs/user-guide/petset.html"
 ---

 __Warning:__ Starting in Kubernetes version 1.5, PetSet has been renamed to [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets). To use (or continue to use) PetSet in Kubernetes 1.5, you _must_ [migrate](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/) your existing PetSets to StatefulSets. For information on working with StatefulSet, see the tutorial on [how to run replicated stateful applications](/docs/tutorials/stateful-application/run-replicated-stateful-application).
@@ -4,15 +4,9 @@ assignees:
 - bprashanth
 - madhusudancs
 title: Replica Sets
-redirect_from:
- "/docs/user-guide/replicasets/"
- "/docs/user-guide/replicasets.html"
 ---

-* TOC
-{:toc}
-
-## What is a ReplicaSet?
+{% capture overview %}

 ReplicaSet is the next-generation Replication Controller. The only difference
 between a _ReplicaSet_ and a
@@ -21,6 +15,13 @@ the selector support. ReplicaSet supports the new set-based selector requirement
 as described in the [labels user guide](/docs/user-guide/labels/#label-selectors)
 whereas a Replication Controller only supports equality-based selector requirements.

+{% endcapture %}
+
+
+{% capture body %}
+
+## How to use a ReplicaSet
+
 Most [`kubectl`](/docs/user-guide/kubectl/) commands that support
 Replication Controllers also support ReplicaSets. One exception is the
 [`rolling-update`](/docs/user-guide/kubectl/{{page.version}}/#rolling-update) command. If
@@ -36,16 +37,16 @@ creation, deletion and updates. When you use Deployments you don't have to worry
 about managing the ReplicaSets that they create. Deployments own and manage
 their ReplicaSets.

-## When to use a ReplicaSet?
+## When to use a ReplicaSet

-A ReplicaSet ensures that a specified number of pod “replicas” are running at any given
+A ReplicaSet ensures that a specified number of pod replicas are running at any given
 time. However, a Deployment is a higher-level concept that manages ReplicaSets and
 provides declarative updates to pods along with a lot of other useful features.
 Therefore, we recommend using Deployments instead of directly using ReplicaSets, unless
 you require custom update orchestration or don't require updates at all.

 This actually means that you may never need to manipulate ReplicaSet objects:
-use directly a Deployment and define your application in the spec section.
+use a Deployment instead, and define your application in the spec section.

 ## Example

@@ -82,8 +83,8 @@ frontend-qhloh   1/1       Running   0          1m
 ## ReplicaSet as an Horizontal Pod Autoscaler target

 A ReplicaSet can also be a target for
-[Horizontal Pod Autoscalers (HPA)](/docs/tasks/run-application/horizontal-pod-autoscale/),
-i.e. a ReplicaSet can be auto-scaled by an HPA. Here is an example HPA targeting
+[Horizontal Pod Autoscalers (HPA)](/docs/tasks/run-application/horizontal-pod-autoscale/). That is,
+a ReplicaSet can be auto-scaled by an HPA. Here is an example HPA targeting
 the ReplicaSet we created in the previous example.

 {% include code.html language="yaml" file="hpa-rs.yaml" ghlink="/docs/concepts/workloads/controllers/hpa-rs.yaml" %}
@@ -97,9 +98,13 @@ of the replicated pods.
 kubectl create -f hpa-rs.yaml
 ```

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

 ```shell
 kubectl autoscale rs frontend
 ```
+
+{% endcapture %}
+
+{% include templates/concept.md %}
@@ -3,38 +3,42 @@ assignees:
 - bprashanth
 - janetkuo
 title: Replication Controller
-redirect_from:
- "/docs/user-guide/replication-controller/"
- "/docs/user-guide/replication-controller/index.html"
 ---

-* TOC
-{:toc}
+{% capture overview %}

-## What is a ReplicationController?
+NOTE: A [`Deployment`](/docs/concepts/workloads/controllers/deployment/) that configures a [`ReplicaSet`](/docs/concepts/workloads/controllers/replicaset/) is now the recommended way to set up replication.

-A _ReplicationController_ ensures that a specified number of pod "replicas" are running at any one
-time. In other words, a ReplicationController makes sure that a pod or homogeneous set of pods are
+A _ReplicationController_ ensures that a specified number of pod replicas are running at any one
+time. In other words, a ReplicationController makes sure that a pod or a homogeneous set of pods is
 always up and available.
-If there are too many pods, it will kill some. If there are too few, the
-ReplicationController will start more. Unlike manually created pods, the pods maintained by a
-ReplicationController are automatically replaced if they fail, get deleted, or are terminated.
-For example, your pods get re-created on a node after disruptive maintenance such as a kernel upgrade.
-For this reason, we recommend that you use a ReplicationController even if your application requires
-only a single pod. You can think of a ReplicationController as something similar to a process supervisor,
-but rather than individual processes on a single node, the ReplicationController supervises multiple pods
+
+{% endcapture %}
+
+
+{% capture body %}
+
+## How a ReplicationController Works
+
+If there are too many pods, the ReplicationController terminates the extra pods. If there are too few, the
+ReplicationController starts more pods. Unlike manually created pods, the pods maintained by a
+ReplicationController are automatically replaced if they fail, are deleted, or are terminated.
+For example, your pods are re-created on a node after disruptive maintenance such as a kernel upgrade.
+For this reason, you should use a ReplicationController even if your application requires
+only a single pod. A ReplicationController is similar to a process supervisor,
+but instead of supervising individual processes on a single node, the ReplicationController supervises multiple pods
 across multiple nodes.

 ReplicationController is often abbreviated to "rc" or "rcs" in discussion, and as a shortcut in
 kubectl commands.

-A simple case is to create 1 ReplicationController object in order to reliably run one instance of
+A simple case is to create one ReplicationController object to reliably run one instance of
 a Pod indefinitely.  A more complex use case is to run several identical replicas of a replicated
 service, such as web servers.

 ## Running an example ReplicationController

-Here is an example ReplicationController config.  It runs 3 copies of the nginx web server.
+This example ReplicationController config runs three copies of the nginx web server.

 {% include code.html language="yaml" file="replication.yaml" ghlink="/docs/concepts/workloads/controllers/replication.yaml" %}

@@ -64,14 +68,14 @@ Events:
  20s             20s          1        {replication-controller }                    Normal    SuccessfulCreate    Created pod: nginx-4ok8v
 ```

-Here, 3 pods have been made, but none are running yet, perhaps because the image is being pulled.
+Here, three pods are created, but none is running yet, perhaps because the image is being pulled.
 A little later, the same command may show:

 ```shell
 Pods Status:    3 Running / 0 Waiting / 0 Succeeded / 0 Failed
 ```

-To list all the pods that belong to the rc in a machine readable form, you can use a command like this:
+To list all the pods that belong to the ReplicationController in a machine readable form, you can use a command like this:

 ```shell
 $ pods=$(kubectl get pods --selector=app=nginx --output=jsonpath={.items..metadata.name})
@@ -96,12 +100,10 @@ A ReplicationController also needs a [`.spec` section](https://git.k8s.io/commun

 The `.spec.template` is the only required field of the `.spec`.

-The `.spec.template` is a pod template.  It has exactly
-the same schema as a [pod](/docs/concepts/workloads/pods/pod/), except it is nested and does not have an `apiVersion` or
-`kind`.
+The `.spec.template` is a [pod template](/docs/concepts/workloads/pods/pod-overview/#pod-templates). It has exactly the same schema as a [pod](/docs/concepts/workloads/pods/pod/), except it is nested and does not have an `apiVersion` or `kind`.

 In addition to required fields for a Pod, a pod template in a ReplicationController must specify appropriate
-labels (i.e. don't overlap with other controllers, see [pod selector](#pod-selector)) and an appropriate restart policy.
+labels and an appropriate restart policy. For labels, make sure not to overlap with other controllers. See [pod selector](#pod-selector).

 Only a [`.spec.template.spec.restartPolicy`](/docs/concepts/workloads/pods/pod-lifecycle/) equal to `Always` is allowed, which is the default
 if not specified.
@@ -113,27 +115,27 @@ for example the [Kubelet](/docs/admin/kubelet/) or Docker.

 The ReplicationController can itself have labels (`.metadata.labels`).  Typically, you
 would set these the same as the `.spec.template.metadata.labels`; if `.metadata.labels` is not specified
-then it is defaulted to  `.spec.template.metadata.labels`.  However, they are allowed to be
+then it defaults to  `.spec.template.metadata.labels`.  However, they are allowed to be
 different, and the `.metadata.labels` do not affect the behavior of the ReplicationController.

 ### Pod Selector

-The `.spec.selector` field is a [label selector](/docs/user-guide/labels/#label-selectors).  A replication
-controller manages all the pods with labels which match the selector.  It does not distinguish
-between pods which it created or deleted versus pods which some other person or process created or
-deleted.  This allows the ReplicationController to be replaced without affecting the running pods.
+The `.spec.selector` field is a [label selector](/docs/user-guide/labels/#label-selectors). A ReplicationController
+manages all the pods with labels that match the selector. It does not distinguish
+between pods that it created or deleted and pods that another person or process created or
+deleted. This allows the ReplicationController to be replaced without affecting the running pods.

 If specified, the `.spec.template.metadata.labels` must be equal to the `.spec.selector`, or it will
 be rejected by the API.  If `.spec.selector` is unspecified, it will be defaulted to
 `.spec.template.metadata.labels`.

-Also you should not normally create any pods whose labels match this selector, either directly, via
-another ReplicationController or via another controller such as Job.  Otherwise, the
-ReplicationController will think that those pods were created by it.  Kubernetes will not stop you
+Also you should not normally create any pods whose labels match this selector, either directly, with 
+another ReplicationController, or with another controller such as Job. If you do so, the
+ReplicationController thinks that it created the other pods.  Kubernetes does not stop you
 from doing this.

 If you do end up with multiple controllers that have overlapping selectors, you
-will have to manage the deletion yourself (see [below](#updating-a-replication-controller)).
+will have to manage the deletion yourself (see [below](#working-with-replicationcontrollers)).

 ### Multiple Replicas

@@ -177,7 +179,7 @@ Pods may be removed from a ReplicationController's target set by changing their

 ### Rescheduling

-As mentioned above, whether you have 1 pod you want to keep running, or 1000, a ReplicationController will ensure that the specified number of pods exists, even in the event of node failure or pod termination (e.g., due to an action by another control agent).
+As mentioned above, whether you have 1 pod you want to keep running, or 1000, a ReplicationController will ensure that the specified number of pods exists, even in the event of node failure or pod termination (for example, due to an action by another control agent).

 ### Scaling

@@ -194,7 +196,7 @@ Ideally, the rolling update controller would take application readiness into acc
 The two ReplicationControllers would need to create pods with at least one differentiating label, such as the image tag of the primary container of the pod, since it is typically image updates that motivate rolling updates.

 Rolling update is implemented in the client tool
-[`kubectl rolling-update`](/docs/user-guide/kubectl/{{page.version}}/#rolling-update). Visit [`kubectl rolling-update` task](/docs/tasks/run-application/rolling-update-replication-controller/) for more concrete examples. 
+[`kubectl rolling-update`](/docs/user-guide/kubectl/{{page.version}}/#rolling-update). Visit [`kubectl rolling-update` task](/docs/tasks/run-application/rolling-update-replication-controller/) for more concrete examples.

 ### Multiple release tracks

@@ -211,13 +213,13 @@ A ReplicationController will never terminate on its own, but it isn't expected t

 ## Writing programs for Replication

-Pods created by a ReplicationController are intended to be fungible and semantically identical, though their configurations may become heterogeneous over time. This is an obvious fit for replicated stateless servers, but ReplicationControllers can also be used to maintain availability of master-elected, sharded, and worker-pool applications. Such applications should use dynamic work assignment mechanisms, such as the [etcd lock module](https://coreos.com/docs/distributed-configuration/etcd-modules/) or [RabbitMQ work queues](https://www.rabbitmq.com/tutorials/tutorial-two-python.html), as opposed to static/one-time customization of the configuration of each pod, which is considered an anti-pattern. Any pod customization performed, such as vertical auto-sizing of resources (e.g., cpu or memory), should be performed by another online controller process, not unlike the ReplicationController itself.
+Pods created by a ReplicationController are intended to be fungible and semantically identical, though their configurations may become heterogeneous over time. This is an obvious fit for replicated stateless servers, but ReplicationControllers can also be used to maintain availability of master-elected, sharded, and worker-pool applications. Such applications should use dynamic work assignment mechanisms, such as the [etcd lock module](https://coreos.com/docs/distributed-configuration/etcd-modules/) or [RabbitMQ work queues](https://www.rabbitmq.com/tutorials/tutorial-two-python.html), as opposed to static/one-time customization of the configuration of each pod, which is considered an anti-pattern. Any pod customization performed, such as vertical auto-sizing of resources (for example, cpu or memory), should be performed by another online controller process, not unlike the ReplicationController itself.

 ## Responsibilities of the ReplicationController

 The ReplicationController simply ensures that the desired number of pods matches its label selector and are operational. Currently, only terminated pods are excluded from its count. In the future, [readiness](http://issue.k8s.io/620) and other information available from the system may be taken into account, we may add more controls over the replacement policy, and we plan to emit events that could be used by external clients to implement arbitrarily sophisticated replacement and/or scale-down policies.

-The ReplicationController is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in [#492](http://issue.k8s.io/492)), which would change its `replicas` field. We will not add scheduling policies (e.g., [spreading](http://issue.k8s.io/367#issuecomment-48428019)) to the ReplicationController. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation ([#170](http://issue.k8s.io/170)).
+The ReplicationController is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in [#492](http://issue.k8s.io/492)), which would change its `replicas` field. We will not add scheduling policies (for example, [spreading](http://issue.k8s.io/367#issuecomment-48428019)) to the ReplicationController. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation ([#170](http://issue.k8s.io/170)).

 The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, stop, scale, rolling-update) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](http://techblog.netflix.com/2012/06/asgard-web-based-cloud-management-and.html) managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.

@@ -240,17 +242,17 @@ Note that we recommend using Deployments instead of directly using Replica Sets,
 ### Deployment (Recommended)

 [`Deployment`](/docs/concepts/workloads/controllers/deployment/) is a higher-level API object that updates its underlying Replica Sets and their Pods
-in a similar fashion as `kubectl rolling-update`. Deployments are recommended if you want this rolling update functionality, 
+in a similar fashion as `kubectl rolling-update`. Deployments are recommended if you want this rolling update functionality,
 because unlike `kubectl rolling-update`, they are declarative, server-side, and have additional features.

 ### Bare Pods

-Unlike in the case where a user directly created pods, a ReplicationController replaces pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a ReplicationController even if your application requires only a single pod. Think of it similarly to a process supervisor, only it supervises multiple pods across multiple nodes instead of individual processes on a single node.  A ReplicationController delegates local container restarts to some agent on the node (e.g., Kubelet or Docker).
+Unlike in the case where a user directly created pods, a ReplicationController replaces pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a ReplicationController even if your application requires only a single pod. Think of it similarly to a process supervisor, only it supervises multiple pods across multiple nodes instead of individual processes on a single node.  A ReplicationController delegates local container restarts to some agent on the node (for example, Kubelet or Docker).

 ### Job

 Use a [`Job`](/docs/concepts/jobs/run-to-completion-finite-workloads/) instead of a ReplicationController for pods that are expected to terminate on their own
-(i.e. batch jobs).
+(that is, batch jobs).

 ### DaemonSet

@@ -262,3 +264,7 @@ safe to terminate when the machine is otherwise ready to be rebooted/shutdown.
 ## For more information

 Read [Run Stateless AP Replication Controller](/docs/tutorials/stateless-application/run-stateless-ap-replication-controller/).
+
+{% endcapture %}
+
+{% include templates/concept.md %}
@@ -7,14 +7,11 @@ assignees:
 - kow3ns
 - smarterclayton
 title: StatefulSets
-redirect_from:
- "/docs/concepts/abstractions/controllers/statefulsets/"
- "/docs/concepts/abstractions/controllers/statefulsets.html"
 ---

 {% capture overview %}
-**StatefulSets are a beta feature in 1.7. This feature replaces the 
-PetSets feature from 1.4. Users of PetSets are referred to the 1.5 
+**StatefulSets are a beta feature in 1.7. This feature replaces the
+PetSets feature from 1.4. Users of PetSets are referred to the 1.5
 [Upgrade Guide](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/)
 for further information on how to upgrade existing PetSets to StatefulSets.**

@@ -26,7 +23,7 @@ guarantees about the ordering of deployment and scaling.

 ## Using StatefulSets

-StatefulSets are valuable for applications that require one or more of the 
+StatefulSets are valuable for applications that require one or more of the
 following.

 * Stable, unique network identifiers.
@@ -36,10 +33,10 @@ following.
 * Ordered, automated rolling updates.

 In the above, stable is synonymous with persistence across Pod (re)scheduling.
-If an application doesn't require any stable identifiers or ordered deployment, 
-deletion, or scaling, you should deploy your application with a controller that 
-provides a set of stateless replicas. Controllers such as 
-[Deployment](/docs/concepts/workloads/controllers/deployment/) or 
+If an application doesn't require any stable identifiers or ordered deployment,
+deletion, or scaling, you should deploy your application with a controller that
+provides a set of stateless replicas. Controllers such as
+[Deployment](/docs/concepts/workloads/controllers/deployment/) or
 [ReplicaSet](/docs/concepts/workloads/controllers/replicaset/) may be better suited to your stateless needs.

 ## Limitations
@@ -50,11 +47,11 @@ provides a set of stateless replicas. Controllers such as
 * StatefulSets currently require a [Headless Service](/docs/concepts/services-networking/service/#headless-services) to be responsible for the network identity of the Pods. You are responsible for creating this Service.

 ## Components
-The example below demonstrates the components of a StatefulSet. 
+The example below demonstrates the components of a StatefulSet.

-* A Headless Service, named nginx, is used to control the network domain. 
+* A Headless Service, named nginx, is used to control the network domain.
 * The StatefulSet, named web, has a Spec that indicates that 3 replicas of the nginx container will be launched in unique Pods.
-* The volumeClaimTemplates will provide stable storage using [PersistentVolumes](/docs/concepts/storage/volumes/) provisioned by a 
+* The volumeClaimTemplates will provide stable storage using [PersistentVolumes](/docs/concepts/storage/volumes/) provisioned by a
 PersistentVolume Provisioner.

 ```yaml
@@ -107,30 +104,30 @@ spec:
 ```

 ## Pod Identity
-StatefulSet Pods have a unique identity that is comprised of an ordinal, a 
-stable network identity, and stable storage. The identity sticks to the Pod, 
+StatefulSet Pods have a unique identity that is comprised of an ordinal, a
+stable network identity, and stable storage. The identity sticks to the Pod,
 regardless of which node it's (re)scheduled on.

 ### Ordinal Index

-For a StatefulSet with N replicas, each Pod in the StatefulSet will be 
-assigned an integer ordinal, in the range [0,N), that is unique over the Set. 
+For a StatefulSet with N replicas, each Pod in the StatefulSet will be
+assigned an integer ordinal, in the range [0,N), that is unique over the Set.

 ### Stable Network ID

-Each Pod in a StatefulSet derives its hostname from the name of the StatefulSet 
-and the ordinal of the Pod. The pattern for the constructed hostname 
-is `$(statefulset name)-$(ordinal)`. The example above will create three Pods 
+Each Pod in a StatefulSet derives its hostname from the name of the StatefulSet
+and the ordinal of the Pod. The pattern for the constructed hostname
+is `$(statefulset name)-$(ordinal)`. The example above will create three Pods
 named `web-0,web-1,web-2`.
 A StatefulSet can use a [Headless Service](/docs/concepts/services-networking/service/#headless-services)
-to control the domain of its Pods. The domain managed by this Service takes the form: 
-`$(service name).$(namespace).svc.cluster.local`, where "cluster.local" 
-is the [cluster domain](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/dns/README.md). 
-As each Pod is created, it gets a matching DNS subdomain, taking the form: 
-`$(podname).$(governing service domain)`, where the governing service is defined 
+to control the domain of its Pods. The domain managed by this Service takes the form:
+`$(service name).$(namespace).svc.cluster.local`, where "cluster.local"
+is the [cluster domain](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/dns/README.md).
+As each Pod is created, it gets a matching DNS subdomain, taking the form:
+`$(podname).$(governing service domain)`, where the governing service is defined
 by the `serviceName` field on the StatefulSet.

-Here are some examples of choices for Cluster Domain, Service name, 
+Here are some examples of choices for Cluster Domain, Service name,
 StatefulSet name, and how that affects the DNS names for the StatefulSet's Pods.

 Cluster Domain | Service (ns/name) | StatefulSet (ns/name)  | StatefulSet Domain  | Pod DNS | Pod Hostname |
@@ -139,96 +136,96 @@ Cluster Domain | Service (ns/name) | StatefulSet (ns/name)  | StatefulSet Domain
 cluster.local | foo/nginx         | foo/web           | nginx.foo.svc.cluster.local     | web-{0..N-1}.nginx.foo.svc.cluster.local     | web-{0..N-1} |
 kube.local    | foo/nginx         | foo/web           | nginx.foo.svc.kube.local        | web-{0..N-1}.nginx.foo.svc.kube.local        | web-{0..N-1} |

-Note that Cluster Domain will be set to `cluster.local` unless 
+Note that Cluster Domain will be set to `cluster.local` unless
 [otherwise configured](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/dns/README.md).

 ### Stable Storage

-Kubernetes creates one [PersistentVolume](/docs/concepts/storage/volumes/) for each 
-VolumeClaimTemplate. In the nginx example above, each Pod will receive a single PersistentVolume 
-with a storage class of `anything` and 1 Gib of provisioned storage. When a Pod is (re)scheduled 
-onto a node, its `volumeMounts` mount the PersistentVolumes associated with its 
-PersistentVolume Claims. Note that, the PersistentVolumes associated with the 
-Pods' PersistentVolume Claims are not deleted when the Pods, or StatefulSet are deleted. 
+Kubernetes creates one [PersistentVolume](/docs/concepts/storage/volumes/) for each
+VolumeClaimTemplate. In the nginx example above, each Pod will receive a single PersistentVolume
+with a storage class of `anything` and 1 Gib of provisioned storage. When a Pod is (re)scheduled
+onto a node, its `volumeMounts` mount the PersistentVolumes associated with its
+PersistentVolume Claims. Note that, the PersistentVolumes associated with the
+Pods' PersistentVolume Claims are not deleted when the Pods, or StatefulSet are deleted.
 This must be done manually.

 ## Deployment and Scaling Guarantees

-* For a StatefulSet with N replicas, when Pods are being deployed, they are created sequentially, in order from {0..N-1}. 
+* For a StatefulSet with N replicas, when Pods are being deployed, they are created sequentially, in order from {0..N-1}.
 * When Pods are being deleted, they are terminated in reverse order, from {N-1..0}.
-* Before a scaling operation is applied to a Pod, all of its predecessors must be Running and Ready. 
+* Before a scaling operation is applied to a Pod, all of its predecessors must be Running and Ready.
 * Before a Pod is terminated, all of its successors must be completely shutdown.

 The StatefulSet should not specify a `pod.Spec.TerminationGracePeriodSeconds` of 0. This practice is unsafe and strongly discouraged. For further explanation, please refer to [force deleting StatefulSet Pods](/docs/tasks/run-application/force-delete-stateful-set-pod/).

-When the nginx example above is created, three Pods will be deployed in the order 
-web-0, web-1, web-2. web-1 will not be deployed before web-0 is 
-[Running and Ready](/docs/user-guide/pod-states), and web-2 will not be deployed until 
-web-1 is Running and Ready. If web-0 should fail, after web-1 is Running and Ready, but before 
-web-2 is launched, web-2 will not be launched until web-0 is successfully relaunched and 
-becomes Running and Ready. 
+When the nginx example above is created, three Pods will be deployed in the order
+web-0, web-1, web-2. web-1 will not be deployed before web-0 is
+[Running and Ready](/docs/user-guide/pod-states), and web-2 will not be deployed until
+web-1 is Running and Ready. If web-0 should fail, after web-1 is Running and Ready, but before
+web-2 is launched, web-2 will not be launched until web-0 is successfully relaunched and
+becomes Running and Ready.

 If a user were to scale the deployed example by patching the StatefulSet such that
-`replicas=1`, web-2 would be terminated first. web-1 would not be terminated until web-2 
-is fully shutdown and deleted. If web-0 were to fail after web-2 has been terminated and 
-is completely shutdown, but prior to web-1's termination, web-1 would not be terminated 
+`replicas=1`, web-2 would be terminated first. web-1 would not be terminated until web-2
+is fully shutdown and deleted. If web-0 were to fail after web-2 has been terminated and
+is completely shutdown, but prior to web-1's termination, web-1 would not be terminated
 until web-0 is Running and Ready.

 ### Pod Management Policies
-In Kubernetes 1.7 and later, StatefulSet allows you to relax its ordering guarantees while 
+In Kubernetes 1.7 and later, StatefulSet allows you to relax its ordering guarantees while
 preserving its uniqueness and identity guarantees via its `.spec.podManagementPolicy` field.

 #### OrderedReady Pod Management

-`OrderedReady` pod management is the default for StatefulSets. It implements the behavior 
+`OrderedReady` pod management is the default for StatefulSets. It implements the behavior
 described [above](#deployment-and-scaling-guarantees).

 #### Parallel Pod Management

-`Parallel` pod management tells the StatefulSet controller to launch or 
-terminate all Pods in parallel, and to not wait for Pods to become Running 
-and Ready or completely terminated prior to launching or terminating another 
+`Parallel` pod management tells the StatefulSet controller to launch or
+terminate all Pods in parallel, and to not wait for Pods to become Running
+and Ready or completely terminated prior to launching or terminating another
 Pod.

 ## Update Strategies

-In Kuberentes 1.7 and later, StatefulSet's `.spec.updateStrategy` field allows you to configure 
-and disable automated rolling updates for containers, labels, resource request/limits, and 
+In Kubernetes 1.7 and later, StatefulSet's `.spec.updateStrategy` field allows you to configure
+and disable automated rolling updates for containers, labels, resource request/limits, and
 annotations for the Pods in a StatefulSet.

 ### On Delete

-The `OnDelete` update strategy implements the legacy (1.6 and prior) behavior. It is the default 
-strategy when `spec.updateStrategy` is left unspecified. When a StatefulSet's 
-`.spec.updateStrategy.type` is set to `OnDelete`, the StatefulSet controller will not automatically 
-update the Pods in a StatefulSet. Users must manually delete Pods to cause the controller to 
+The `OnDelete` update strategy implements the legacy (1.6 and prior) behavior. It is the default
+strategy when `spec.updateStrategy` is left unspecified. When a StatefulSet's
+`.spec.updateStrategy.type` is set to `OnDelete`, the StatefulSet controller will not automatically
+update the Pods in a StatefulSet. Users must manually delete Pods to cause the controller to
 create new Pods that reflect modifications made to a StatefulSet's `.spec.template`.

 ### Rolling Updates

-The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a 
-StatefulSet. When a StatefulSet's `.spec.updateStrategy.type` is set to `RollingUpdate`, the 
-StatefulSet controller will delete and recreate each Pod in the StatefulSet. It will proceed 
-in the same order as Pod termination (from the largest ordinal to the smallest), updating 
-each Pod one at a time. It will wait until an updated Pod is Running and Ready prior to 
+The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a
+StatefulSet. When a StatefulSet's `.spec.updateStrategy.type` is set to `RollingUpdate`, the
+StatefulSet controller will delete and recreate each Pod in the StatefulSet. It will proceed
+in the same order as Pod termination (from the largest ordinal to the smallest), updating
+each Pod one at a time. It will wait until an updated Pod is Running and Ready prior to
 updating its predecessor.

 #### Partitions

-The `RollingUpdate` update strategy can be partitioned, by specifying a 
-`.spec.updateStrategy.rollingUpdate.partition`. If a partition is specified, all Pods with an 
-ordinal that is greater than or equal to the partition will be updated when the StatefulSet's 
-`.spec.template` is updated. All Pods with an ordinal that is less than the partition will not 
-be updated, and, even if they are deleted, they will be recreated at the previous version. If a 
-StatefulSet's `.spec.updateStrategy.rollingUpdate.partition` is greater than its `.spec.replicas`, 
+The `RollingUpdate` update strategy can be partitioned, by specifying a
+`.spec.updateStrategy.rollingUpdate.partition`. If a partition is specified, all Pods with an
+ordinal that is greater than or equal to the partition will be updated when the StatefulSet's
+`.spec.template` is updated. All Pods with an ordinal that is less than the partition will not
+be updated, and, even if they are deleted, they will be recreated at the previous version. If a
+StatefulSet's `.spec.updateStrategy.rollingUpdate.partition` is greater than its `.spec.replicas`,
 updates to its `.spec.template` will not be propagated to its Pods.
-In most cases you will not need to use a partition, but they are useful if you want to stage an 
+In most cases you will not need to use a partition, but they are useful if you want to stage an
 update, roll out a canary, or perform a phased roll out.

 {% endcapture %}
 {% capture whatsnext %}

-* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set). 
+* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set).

 {% endcapture %}
 {% include templates/concept.md %}
@@ -4,11 +4,6 @@ assignees:
 - foxish
 - davidopp
 title: Disruptions
-redirect_from:
- "/docs/admin/disruptions/"
- "/docs/admin/disruptions.html"
- "/docs/tasks/configure-pod-container/configure-pod-disruption-budget/"
- "/docs/tasks/administer-cluster/configure-pod-disruption-budget/"
 ---

 {% capture overview %}
@@ -41,7 +36,7 @@ an application.  Examples are:
 - eviction of a pod due to the node being [out-of-resources](/docs/tasks/administer-cluster/out-of-resource.md).

 Except for the out-of-resources condition, all these conditions
-should be familiar to most users; they are are not specific
+should be familiar to most users; they are not specific
 to Kubernetes.

 We call other cases *voluntary disruptions*.  These include both
@@ -102,7 +97,7 @@ voluntary disruptions.  For example, a quorum-based application would
 like to ensure that the number of replicas running is never brought below the
 number needed for a quorum. A web front end might want to
 ensure that the number of replicas serving load never falls below a certain
-percentage of the total.  
+percentage of the total.

 Cluster managers and hosting providers should use tools which
 respect Pod Disruption Budgets by calling the [Eviction API](/docs/tasks/administer-cluster/safely-drain-node/#the-eviction-api)
@@ -136,7 +131,7 @@ during application updates is configured in the controller spec.
 (Learn about [updating a deployment](/docs/concepts/cluster-administration/manage-deployment/#updating-your-application-without-a-service-outage).)

 When a pod is evicted using the eviction API, it is gracefully terminated (see
-`terminationGracePeriodSeconds` in [PodSpec](/docs/resources-reference/v1.6/#podspec-v1-core).)
+`terminationGracePeriodSeconds` in [PodSpec](/docs/resources-reference/{{page.version}}/#podspec-v1-core).)

 ## PDB Example

@@ -188,9 +183,7 @@ At some point, the pods terminate, and the cluster look like this:

 At this point, if an impatient cluster administrator tries to drain `node-2` or
 `node-3`, the drain command will block, because there are only 2 available
-pods for the deployment, and its PDB requires at least 2.  After some time
-
-asses, `pod-d` becomes available.
+pods for the deployment, and its PDB requires at least 2.  After some time passes, `pod-d` becomes available.

 The cluster state now looks like this:

@@ -200,14 +193,14 @@ The cluster state now looks like this:
 |                      | pod-d *available*   | pod-y              |

 Now, the cluster admin tries to drain `node-2`.
-The drain command will try to evict the two pods in some order, say 
+The drain command will try to evict the two pods in some order, say
 `pod-b` first and then `pod-d`.  It will succeed at evicting `pod-b`.
 But, when it tries to evict `pod-d`, it will be refused because that would leave only
 one pod available for the deployment.

 The deployment creates a replacement for `pod-b` called `pod-e`.
 However, not there are not enough resources in the cluster to schedule
-`pod-e`.  So, the drain  then the drain will block.  The cluster may end up in this
+`pod-e`.  So, the drain will again block.  The cluster may end up in this
 state:

 |    node-1 *drained*  |       node-2        |       node-3       | *no node*          |
@@ -234,7 +227,7 @@ and Application Owner as separate roles with limited knowledge
 of each other.   This separation of responsibilities
 may make sense in these scenarios:

- when there are many application teams sharing a Kubernetes cluster, and 
+- when there are many application teams sharing a Kubernetes cluster, and
  there is natural specialization of roles
 - when third-party tools or services are used to automate cluster management

@@ -249,7 +242,7 @@ you may not need to use Pod Disruption Budgets.
 If you are a Cluster Administrator, and you need to perform a disruptive action on all
 the nodes in your cluster, such as a node or system software upgrade, here are some options:

- Accept downtime during the upgrade. 
+- Accept downtime during the upgrade.
 - Fail over to another complete replica cluster.
   -  No downtime, but may be costly both for the duplicated nodes,
     and for human effort to orchestrate the switchover.
@@ -270,7 +263,7 @@ the nodes in your cluster, such as a node or system software upgrade, here are s

 * Learn more about [draining nodes](/docs/tasks/administer-cluster//safely-drain-node.md)

-{% endcapture %} 
+{% endcapture %}


 {% include templates/concept.md %}
@@ -2,11 +2,6 @@
 assignees:
 - erictune
 title: Init Containers
-redirect_from:
- "/docs/concepts/abstractions/init-containers/"
- "/docs/concepts/abstractions/init-containers.html"
- "/docs/user-guide/pods/init-container/"
- "/docs/user-guide/pods/init-container.html"
 ---

 {% capture overview %}
@@ -36,7 +31,7 @@ Init Containers are exactly like regular Containers, except:
 If an Init Container fails for a Pod, Kubernetes restarts the Pod repeatedly until the Init
 Container succeeds. However, if the Pod has a `restartPolicy` of Never, it is not restarted.

-To specify a Container as an Init Container, add the `initContainers` field on the PodSpec as a JSON array of objects of type [v1.Container](/docs/api-reference/v1.6/#container-v1-core) alongside the app `containers` array.
+To specify a Container as an Init Container, add the `initContainers` field on the PodSpec as a JSON array of objects of type [v1.Container](/docs/api-reference/{{page.version}}/#container-v1-core) alongside the app `containers` array.
 The status of the init containers is returned in `status.initContainerStatuses`
 field as an array of the container statuses (similar to the `status.containerStatuses`
 field).
@@ -185,7 +180,7 @@ pod "myapp-pod" created
 $ kubectl get -f myapp.yaml
 NAME        READY     STATUS     RESTARTS   AGE
 myapp-pod   0/1       Init:0/2   0          6m
-$ kubectl describe -f myapp.yaml 
+$ kubectl describe -f myapp.yaml
 Name:          myapp-pod
 Namespace:     default
 [...]
@@ -1,8 +1,5 @@
 ---
 title: Pod Lifecycle
-redirect_from:
- "/docs/user-guide/pod-states/"
- "/docs/user-guide/pod-states.html"
 ---

 {% capture overview %}
@@ -20,7 +17,7 @@ This page describes the lifecycle of a Pod.
 ## Pod phase

 A Pod's `status` field is a
-[PodStatus](/docs/resources-reference/v1.6/#podstatus-v1-core)
+[PodStatus](/docs/resources-reference/{{page.version}}/#podstatus-v1-core)
 object, which has a `phase` field.

 The phase of a Pod is a simple, high-level summary of where the Pod is in its
@@ -55,7 +52,7 @@ Here are the possible values for `phase`:
 ## Pod conditions

 A Pod has a PodStatus, which has an array of
-[PodConditions](/docs/resources-reference/v1.6/#podcondition-v1-core). Each element
+[PodConditions](/docs/resources-reference/{{page.version}}/#podcondition-v1-core). Each element
 of the PodCondition array has a `type` field and a `status` field. The `type`
 field is a string, with possible values PodScheduled, Ready, Initialized, and
 Unschedulable. The `status` field is a string, with possible values True, False,
@@ -63,22 +60,22 @@ and Unknown.

 ## Container probes

-A [Probe](/docs/resources-reference/v1.6/#probe-v1-core) is a diagnostic
+A [Probe](/docs/resources-reference/{{page.version}}/#probe-v1-core) is a diagnostic
 performed periodically by the [kubelet](/docs/admin/kubelet/)
 on a Container. To perform a diagnostic,
 the kubelet calls a
 [Handler](https://godoc.org/k8s.io/kubernetes/pkg/api/v1#Handler) implemented by
 the Container. There are three types of handlers:

-* [ExecAction](/docs/resources-reference/v1.6/#execaction-v1-core):
+* [ExecAction](/docs/resources-reference/{{page.version}}/#execaction-v1-core):
  Executes a specified command inside the Container. The diagnostic
  is considered successful if the command exits with a status code of 0.

-* [TCPSocketAction](/docs/resources-reference/v1.6/#tcpsocketaction-v1-core):
+* [TCPSocketAction](/docs/resources-reference/{{page.version}}/#tcpsocketaction-v1-core):
  Performs a TCP check against the Container's IP address on
  a specified port. The diagnostic is considered successful if the port is open.

-* [HTTPGetAction](/docs/resources-reference/v1.6/#httpgetaction-v1-core):
+* [HTTPGetAction](/docs/resources-reference/{{page.version}}/#httpgetaction-v1-core):
  Performs an HTTP Get request against the Container's IP
  address on a specified port and path. The diagnostic is considered successful
  if the response has a status code greater than or equal to 200 and less than 400.
@@ -132,11 +129,11 @@ to stop.
 ## Pod and Container status

 For detailed information about Pod Container status, see
-[PodStatus](/docs/resources-reference/v1.6/#podstatus-v1-core)
+[PodStatus](/docs/resources-reference/{{page.version}}/#podstatus-v1-core)
 and
-[ContainerStatus](/docs/resources-reference/v1.6/#containerstatus-v1-core).
+[ContainerStatus](/docs/resources-reference/{{page.version}}/#containerstatus-v1-core).
 Note that the information reported as Pod status depends on the current
-[ContainerState](/docs/resources-reference/v1.6/#containerstatus-v1-core).
+[ContainerState](/docs/resources-reference/{{page.version}}/#containerstatus-v1-core).

 ## Restart policy

@@ -2,11 +2,6 @@
 assignees:
 - erictune
 title: Pod Overview
-redirect_from:
- "/docs/concepts/abstractions/pod/"
- "/docs/concepts/abstractions/pod.html"
- "/docs/user-guide/pod-templates/"
- "/docs/user-guide/pod-templates.html"
 ---

 {% capture overview %}
@@ -64,7 +59,7 @@ Pods do not, by themselves, self-heal. If a Pod is scheduled to a Node that fail

 ### Pods and Controllers

-A Controller can create and manage multiple Pods for you, handling replication and rollout and providing self-healing capabilities at cluster scope. For example, if a Node fails, the Controller might automatically replace the Pod by scheduling an identical replacement on a different Node. 
+A Controller can create and manage multiple Pods for you, handling replication and rollout and providing self-healing capabilities at cluster scope. For example, if a Node fails, the Controller might automatically replace the Pod by scheduling an identical replacement on a different Node.

 Some examples of Controllers that contain one or more pods include:

@@ -1,9 +1,6 @@
 ---
 assignees:
 title: Pods
-redirect_from:
- "/docs/user-guide/pods/index/"
- "/docs/user-guide/pods/index.html"
 ---

 * TOC
@@ -153,7 +150,7 @@ Pod is exposed as a primitive in order to facilitate:
 * clean composition of Kubelet-level functionality with cluster-level functionality &mdash; Kubelet is effectively the "pod controller"
 * high-availability applications, which will expect pods to be replaced in advance of their termination and certainly in advance of deletion, such as in the case of planned evictions, image prefetching, or live pod migration [#3949](http://issue.k8s.io/3949)

-There is new first-class support for stateful pods with the [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets/) controller (currently in beta). The feature was alpha in 1.4 and was called [PetSet](/docs/concepts/workloads/controllers/petset/). For prior versions of Kubernetes, best practice for having stateful pods is to create a replication controller with `replicas` equal to `1` and a corresponding service, see [this MySQL deployment example](/docs/tutorials/stateful-application/run-stateful-application/). 
+There is new first-class support for stateful pods with the [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets/) controller (currently in beta). The feature was alpha in 1.4 and was called [PetSet](/docs/concepts/workloads/controllers/petset/). For prior versions of Kubernetes, best practice for having stateful pods is to create a replication controller with `replicas` equal to `1` and a corresponding service, see [this MySQL deployment example](/docs/tutorials/stateful-application/run-stateful-application/).

 ## Termination of Pods

@@ -196,4 +193,4 @@ spec.containers[0].securityContext.privileged: forbidden '<*>(0xc20b222db0)true'

 Pod is a top-level resource in the Kubernetes REST API. More details about the
 API object can be found at: [Pod API
-object](/docs/api-reference/v1.6/#pod-v1-core).
+object](/docs/api-reference/{{page.version}}/#pod-v1-core).
@@ -252,7 +252,7 @@ kubectl cluster-info

 ### Accessing the cluster programmatically 

-It's possible to use the locally stored client certificates to access the api server. For example, you may want to use any of the [Kubernetes API client libraries](https://git.k8s.io/community/contributors/devel/client-libraries.md) to program against your Kubernetes cluster in the programming language of your choice. 
+It's possible to use the locally stored client certificates to access the api server. For example, you may want to use any of the [Kubernetes API client libraries](/docs/reference/client-libraries/) to program against your Kubernetes cluster in the programming language of your choice. 

 To demonstrate how to use these locally stored certificates, we provide the following example of using ```curl``` to communicate to the master api server via https:

@@ -65,11 +65,11 @@ kube-node-02.example.com

 ## Setting up ansible access to your nodes

-If you already are running on a machine which has passwordless ssh access to the kube-master and kube-node-{01,02} nodes, and 'sudo' privileges, simply set the value of `ansible_ssh_user` in `~/contrib/ansible/group_vars/all.yml` to the username which you use to ssh to the nodes (i.e. `fedora`), and proceed to the next step...
+If you already are running on a machine which has passwordless ssh access to the kube-master and kube-node-{01,02} nodes, and 'sudo' privileges, simply set the value of `ansible_ssh_user` in `~/contrib/ansible/inventory/group_vars/all.yml` to the username which you use to ssh to the nodes (i.e. `fedora`), and proceed to the next step...

 *Otherwise* setup ssh on the machines like so (you will need to know the root password to all machines in the cluster).

-edit: ~/contrib/ansible/group_vars/all.yml
+edit: ~/contrib/ansible/inventory/group_vars/all.yml

 ```yaml
 ansible_ssh_user: root
@@ -95,10 +95,10 @@ done

 ## Setting up the cluster

-Although the default value of variables in `~/contrib/ansible/group_vars/all.yml` should be good enough, if not, change them as needed.
+Although the default value of variables in `~/contrib/ansible/inventory/group_vars/all.yml` should be good enough, if not, change them as needed.

 ```conf
-edit: ~/contrib/ansible/group_vars/all.yml
+edit: ~/contrib/ansible/inventory/group_vars/all.yml
 ```

 **Configure access to Kubernetes packages**
@@ -444,14 +444,29 @@ because of how this is used later.
 - Alternate, manual approach:

  1. Set `--configure-cbr0=false` on kubelet and restart.
-  1. Create a bridge
-     - `ip link add name cbr0 type bridge`.
+  1. Create a bridge.
+
+        ```
+        ip link add name cbr0 type bridge
+        ```
+
  1. Set appropriate MTU. NOTE: the actual value of MTU will depend on your network environment
-     - `ip link set dev cbr0 mtu 1460`
+
+        ```
+        ip link set dev cbr0 mtu 1460
+        ```
+
  1. Add the node's network to the bridge (docker will go on other side of bridge).
-     - `ip addr add $NODE_X_BRIDGE_ADDR dev cbr0`
+
+        ```
+        ip addr add $NODE_X_BRIDGE_ADDR dev cbr0
+        ```
+
  1. Turn it on
-     - `ip link set dev cbr0 up`
+
+        ```
+        ip link set dev cbr0 up
+        ```

 If you have turned off Docker's IP masquerading to allow pods to talk to each
 other, then you may need to do masquerading just for destination IPs outside
@@ -501,11 +516,13 @@ all configured and managed *by Kubernetes*:

 You will need to run one or more instances of etcd.

-  - Recommended approach: run one etcd instance, with its log written to a directory backed
+  - Highly available and easy to restore - Run 3 or 5 etcd instances with, their logs written to a directory backed
    by durable storage (RAID, GCE PD)
-  - Alternative: run 3 or 5 etcd instances.
-    - Log can be written to non-durable storage because storage is replicated.
-    - run a single apiserver which connects to one of the etcd nodes.
+  - Not highly available, but easy to restore - Run one etcd instance, with its log written to a directory backed
+    by durable storage (RAID, GCE PD)
+    **Note:** May result in operations outages in case of instance outage
+  - Highly available - Run 3 or 5 etcd instances with non durable storage.
+    **Note:** Log can be written to non-durable storage because storage is replicated.

 See [cluster-troubleshooting](/docs/admin/cluster-troubleshooting) for more discussion on factors affecting cluster
 availability.
@@ -1,12 +1,9 @@
 ---
 title: Kubernetes on Ubuntu
-redirect_from:
- "/docs/getting-started-guides/ubuntu/calico/"
- "/docs/getting-started-guides/ubuntu/calico.html"
 ---

 {% capture overview %}
-There are multiple ways to run a Kubernetes cluster with Ubuntu. These pages explain how to deploy Kubernetes on Ubuntu on multiple public and private clouds, as well as bare metal. 
+There are multiple ways to run a Kubernetes cluster with Ubuntu. These pages explain how to deploy Kubernetes on Ubuntu on multiple public and private clouds, as well as bare metal.
 {% endcapture %}

 {% capture body %}
@@ -20,7 +17,7 @@ Supports AWS, GCE, Azure, Joyent, OpenStack, VMWare, Bare Metal and localhost de

 [conjure-up](http://conjure-up.io/) provides the quickest way to deploy Kubernetes on Ubuntu for multiple clouds and bare metal. It provides a user-friendly UI that prompts you for cloud credentials and configuration options

-Available for Ubuntu 16.04 and newer: 
+Available for Ubuntu 16.04 and newer:

 ```
 sudo snap install conjure-up --classic
@@ -37,7 +34,7 @@ conjure-up kubernetes

 ### Operational Guides

-These are more in-depth guides for users choosing to run Kubernetes in production: 
+These are more in-depth guides for users choosing to run Kubernetes in production:

  - [Installation](/docs/getting-started-guides/ubuntu/installation)
  - [Validation](/docs/getting-started-guides/ubuntu/validation)
@@ -10,7 +10,7 @@ This page covers how to get started with deploying Kubernetes on vSphere and det
 * TOC
 {:toc}

-### Getting started with vSphere
+### Getting started with the vSphere Cloud Provider

 Kubernetes comes with a cloud provider for vSphere. A quick and easy way to try out the cloud provider is to deploy Kubernetes using [Kubernetes-Anywhere](https://github.com/kubernetes/kubernetes-anywhere).

@@ -20,7 +20,7 @@ This page also describes how to configure and get started with the cloud provide

 To start using Kubernetes on top of vSphere and use the vSphere Cloud Provider use Kubernetes-Anywhere. Kubernetes-Anywhere will deploy and configure a cluster from scratch.

-Detailed steps can be found at the [getting started with Kubernetes-Anywhere on vSphere page](https://git.k8s.io/kubernetes-anywhere/phase1/vsphere/README.md)
+Detailed steps can be found at the [getting started with Kubernetes-Anywhere on vSphere](https://git.k8s.io/kubernetes-anywhere/phase1/vsphere/README.md) page

 ### vSphere Cloud Provider

@@ -31,219 +31,178 @@ vSphere Cloud Provider allows using vSphere managed storage within Kubernetes. I
 3. Storage Classes and provisioning of volumes.
 4. vSphere Storage Policy Based Management for Containers orchestrated by Kubernetes.

-Documentation for how to use vSphere managed storage can be found in the
-[persistent volumes user
-guide](/docs/concepts/storage/persistent-volumes/#vsphere) and the
-[volumes user
-guide](/docs/concepts/storage/volumes/#vspherevolume)
+Documentation for how to use vSphere managed storage can be found in the [persistent volumes user guide](/docs/concepts/storage/persistent-volumes/#vsphere) and the [volumes user guide](/docs/concepts/storage/volumes/#vspherevolume)

-Examples can be found
-[here](https://git.k8s.io/kubernetes/examples/volumes/vsphere)
+Examples can be found [here](https://git.k8s.io/kubernetes/examples/volumes/vsphere)

-#### Configuring vSphere Cloud Provider
+#### Enable vSphere Cloud Provider

-If a Kubernetes cluster has not been deployed using Kubernetes-Anywhere, follow the instructions below to use the vSphere Cloud Provider. These steps are not needed when using Kubernetes-Anywhere, they will be done as part of the deployment.
+If a Kubernetes cluster has not been deployed using Kubernetes-Anywhere, follow the instructions below to enable the vSphere Cloud Provider. These steps are not needed when using Kubernetes-Anywhere, they will be done as part of the deployment.

-* Enable UUID for a VM
+**Step-1** [Create a VM folder](https://docs.vmware.com/en/VMware-vSphere/6.0/com.vmware.vsphere.vcenterhost.doc/GUID-031BDB12-D3B2-4E2D-80E6-604F304B4D0C.html) and move Kubernetes Node VMs to this folder.

-This can be done via [govc tool](https://github.com/vmware/govmomi/tree/master/govc)
+**Step-2** Make sure Node VM names must comply with the regex `[a-z](([-0-9a-z]+)?[0-9a-z])?(\.[a-z0-9](([-0-9a-z]+)?[0-9a-z])?)*` If Node VMs does not comply with this regex, rename them and make it compliant to this regex.

-```
-export GOVC_URL=<IP/URL>
-export GOVC_USERNAME=<vCenter User>
-export GOVC_PASSWORD=<vCenter Password>
-export GOVC_INSECURE=1
-govc vm.change -e="disk.enableUUID=1" -vm=<VMNAME>
-```
+  Node VM names constraints:

-* Create Role and User with Required Privileges for vSphere Cloud Provider
+  * VM names can not begin with numbers.
+  * VM names can not have capital letters, any special charaters except `.` and `-`.
+  * VM names can not be shorter than 3 chars and longer than 63

-vSphere Cloud Provider requires the following minimal set of privileges to interact with vCenter:
+**Step-3** Enable disk UUID on Node virtual machines

-Please refer [vSphere Documentation Center](http://pubs.vmware.com/vsphere-65/index.jsp?topic=%2Fcom.vmware.vsphere.security.doc%2FGUID-18071E9A-EED1-4968-8D51-E0B4F526FDA3.html&resultof=%22%43%72%65%61%74%65%22%20%22%63%72%65%61%74%22%20%22%43%75%73%74%6f%6d%22%20%22%63%75%73%74%6f%6d%22%20%22%52%6f%6c%65%22%20%22%72%6f%6c%65%22%20) to know about steps for creating a Custom Role, User and Role Assignment.
+The disk.EnableUUID parameter must be set to "TRUE" for each Node VM. This step is necessary so that the VMDK always presents a consistent UUID to the VM, thus allowing the disk to be mounted properly. 

-Note: Assign Permissions at the vCenter Level and make sure to check Propagate.
+For each of the virtual machine nodes that will be participating in the cluster, follow the steps below using [GOVC tool](https://github.com/vmware/govmomi/tree/master/govc)

-```
-Datastore > Allocate space
-Datastore > Low level file Operations
-Virtual Machine > Configuration > Add existing disk
-Virtual Machine > Configuration > Add or remove device
-Virtual Machine > Configuration > Remove disk
-```
+* Set up GOVC environment

-For the VSAN policy based volume provisioning feature, the following additional privileges are required.
+        export GOVC_URL='vCenter IP OR FQDN'
+        export GOVC_USERNAME='vCenter User'
+        export GOVC_PASSWORD='vCenter Password'
+        export GOVC_INSECURE=1

-```
-Network > Assign network
-Virtual machine > Configuration > Add new disk
-Virtual Machine > Inventory > Create new
-Virtual machine > Configuration > Add new disk
-Resource > Assign virtual machine to resource pool
-```
+* Find Node VM Paths

-* Provide the cloud config file to each instance of kubelet, apiserver and controller manager via ```--cloud-config=<path to file>``` flag. Cloud config [template can be found at Kubernetes-Anywhere](https://git.k8s.io/kubernetes-anywhere/phase1/vsphere/vsphere.conf)
+        govc ls /datacenter/vm/<vm-folder-name>

-Sample Config:
+* Set disk.EnableUUID to true for all VMs
+
+        govc vm.change -e="disk.enableUUID=1" -vm='VM Path'
+
+Note: If Kubernetes Node VMs are created from template VM then `disk.EnableUUID=1` can be set on the template VM. VMs cloned from this template, will automatically inherit this property.
+
+**Step-4** Create and assign Roles to the vSphere Cloud Provider user and vSphere entities.
+
+Note: if you want to use Administrator account then this step can be skipped.
+
+vSphere Cloud Provider requires the following minimal set of privileges to interact with vCenter. Please refer [vSphere Documentation Center](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.security.doc/GUID-18071E9A-EED1-4968-8D51-E0B4F526FDA3.html) to know about steps for creating a Custom Role, User and Role Assignment.
+
+<table>
+<thead>
+<tr>
+  <th>Roles</th>
+  <th>Privileges</th>
+  <th>Entities</th>
+  <th>Propagate to Children</th>
+</tr>
+</thead>
+<tbody><tr>
+  <td>manage-k8s-node-vms</td>
+  <td>Resource.AssignVMToPool<br> System.Anonymous<br> System.Read<br> System.View<br> VirtualMachine.Config.AddExistingDisk<br> VirtualMachine.Config.AddNewDisk<br> VirtualMachine.Config.AddRemoveDevice<br> VirtualMachine.Config.RemoveDisk<br> VirtualMachine.Inventory.Create<br> VirtualMachine.Inventory.Delete</td>
+  <td>Cluster,<br> Hosts,<br> VM Folder</td>
+  <td>Yes</td>
+</tr>
+<tr>
+  <td>manage-k8s-volumes</td>
+  <td>Datastore.AllocateSpace<br> Datastore.FileManagement<br> System.Anonymous<br> System.Read<br> System.View</td>
+  <td>Datastore</td>
+  <td>No</td>
+</tr>
+<tr>
+  <td>k8s-system-read-and-spbm-profile-view</td>
+  <td>StorageProfile.View<br> System.Anonymous<br> System.Read<br> System.View</td>
+  <td>vCenter</td>
+  <td>No</td>
+</tr>
+<tr>
+  <td>ReadOnly</td>
+  <td>System.Anonymous<br>System.Read<br>System.View</td>
+  <td>Datacenter,<br> Datastore Cluster,<br> Datastore Storage Folder</td>
+  <td>No</td>
+</tr>
+</tbody>
+</table>
+
+**Step-5** Create the vSphere cloud config file (`vsphere.conf`). Cloud config template can be found [here](https://github.com/kubernetes/kubernetes-anywhere/blob/master/phase1/vsphere/vsphere.conf)
+
+This config file needs to be placed in the shared directory which should be accessible from kubelet container, controller-manager pod, and API server pod.
+
+**```vsphere.conf``` for Master Node:**

 ```
 [Global]
-        user = <User name for vCenter>
-        password = <Password for vCenter>
-        server = <IP/URL for vCenter>
-        port = <Default 443 for vCenter>
-        insecure-flag = <set to 1 if the host above uses a self-signed cert>
-        datacenter = <Datacenter to be used>
-        datastore = <Datastore to use for provisioning volumes using storage classes/dynamic provisioning>
-        working-dir = <Folder in which VMs are provisioned, can be null>
-        vm-uuid = <VM Instance UUID of virtual machine which can be retrieved from instanceUuid property in VmConfigInfo, or also set as vc.uuid in VMX file. If empty, will be retrieved from sysfs (requires root)>
+        user = "vCenter username for cloud provider"
+        password = "password"
+        server = "IP/FQDN for vCenter"
+        port = "443" #Optional
+        insecure-flag = "1" #set to 1 if the vCenter uses a self-signed cert
+        datacenter = "Datacenter name" 
+        datastore = "Datastore name" #Datastore to use for provisioning volumes using storage classes/dynamic provisioning
+        working-dir = "vCenter VM folder path in which node VMs are located"
+        vm-name = "VM name of the Master Node" #Optional
+        vm-uuid = "UUID of the Node VM" # Optional        
 [Disk]
    scsicontrollertype = pvscsi
 ```

-* Set the cloud provider via ```--cloud-provider=vsphere``` flag for each instance of kubelet, apiserver and controller manager.
+Note: **```vm-name``` parameter is introduced in 1.6.4 release.** Both ```vm-uuid``` and ```vm-name``` are optional parameters. if ```vm-name``` is specified then ```vm-uuid``` is not used. if both are not specified then kubelet will get vm-uuid from `/sys/class/dmi/id/product_serial` and query vCenter to find the Node VM's name. 

-* When upgrading to 1.6 install the default storage class addons, [click here for more details](https://github.com/kubernetes/kubernetes/issues/40070)
+**```vsphere.conf``` for Worker Nodes:** (Only Applicable to 1.6.4 release and above. For older releases this file should have all the parameters specified in Master node's ```vSphere.conf``` file)
+ 
+``` 
+[Global]
+        vm-name = "VM name of the Worker Node"
+```
+
+Below is summary of supported parameters in the `vsphere.conf` file
+
+* ```user``` is the vCenter username for vSphere Cloud Provider.
+* ```password``` is the password for vCenter user specified with `user`.
+* ```server``` is the vCenter Server IP or FQDN
+* ```port``` is the vCenter Server Port. Default is 443 if not specified.
+* ```insecure-flag``` is set to 1 if vCenter used a self-signed certificate.
+* ```datacenter``` is the name of the datacenter on which Node VMs are deployed.
+* ```datastore``` is the default datastore to use for provisioning volumes using storage classes/dynamic provisioning.
+* ```vm-name``` is recently added configuration parameter. This is optional parameter. When this parameter is present, ```vsphere.conf``` file on the worker node does not need vCenter credentials.
+
+  **Note:** ```vm-name``` is added in the release 1.6.4. Prior releases does not support this parameter. 
+
+* ```working-dir``` can be set to empty ( working-dir = ""), if Node VMs are located in the root VM folder.
+* ```vm-uuid``` is the VM Instance UUID of virtual machine. ```vm-uuid``` can be set to empty (```vm-uuid = ""```). if set to empty, this will be retrieved from /sys/class/dmi/id/product_serial file on virtual machine (requires root access).
+
+  * ```vm-uuid``` needs to be set in this format - ```423D7ADC-F7A9-F629-8454-CE9615C810F1```
+
+  * ```vm-uuid``` can be retrieved from Node Virtual machines using following command. This will be different on each node VM.
+
+        cat /sys/class/dmi/id/product_serial | sed -e 's/^VMware-//' -e 's/-/ /' | awk '{ print toupper($1$2$3$4 "-" $5$6 "-" $7$8 "-" $9$10 "-" $11$12$13$14$15$16) }'
+
+* `datastore` is the default datastore used for provisioning volumes using storage classes. If datastore is located in storage folder or datastore is member of datastore cluster, make sure to specify full datastore path. Make sure vSphere Cloud Provider user has Read Privilege set on the datastore cluster or storage folder to be able to find datastore.
+  * For datastore located in the datastore cluster, specify datastore as mentioned below
+
+        datastore = "DatastoreCluster/datastore1"
+
+  * For datastore located in the storage folder, specify datastore as mentioned below
+
+        datastore = "DatastoreStorageFolder/datastore1"
+
+**Step-6** Add flags to controller-manager, API server and Kubelet to enable vSphere Cloud Provider.
+* Add following flags to kubelet running on every node and to the controller-manager and API server pods manifest files. 
+
+```
+--cloud-provider=vsphere
+--cloud-config=<Path of the vsphere.conf file>
+```
+
+Manifest files for API server and controller-manager are generally located at `/etc/kubernetes`
+
+**Step-7** Restart Kubelet on all nodes.
+* Reload kubelet systemd unit file using ```systemctl daemon-reload```
+* Restart kubelet service using ```systemctl restart kubelet.service```
+
+Note: After enabling the vSphere Cloud Provider, Node names will be set to the VM names from the vCenter Inventory.

 #### Known issues
-
-### Kube-up (Deprecated)
-
-Kube-up.sh is no longer supported and is deprecated. The steps for kube-up are included but going forward [kube-anywhere](https://github.com/kubernetes/kubernetes-anywhere) is preferred.
-
-The recommended version for kube-up is [v1.4.7](https://github.com/kubernetes/kubernetes/releases/tag/v1.4.7)
-
-The example below creates a Kubernetes cluster with 4 worker node Virtual.
-Machines and a master Virtual Machine (i.e. 5 VMs in your cluster). This cluster is set up and controlled from your workstation (or wherever you find convenient).
-
-#### Prerequisites
-
-* You need administrator credentials to an ESXi machine or vCenter instance with write mode api access enabled (not available on the free ESXi license).
-* You must have Go (see [here](https://git.k8s.io/community/contributors/devel/development.md#go-versions) for supported versions) installed: [www.golang.org](http://www.golang.org).
-* You must have your `GOPATH` set up and include `$GOPATH/bin` in your `PATH`.
-
-```shell
-export GOPATH=$HOME/src/go
-mkdir -p $GOPATH
-export PATH=$PATH:$GOPATH/bin
-```
-
-* Install the govc tool to interact with ESXi/vCenter. Head to [govc Releases](https://github.com/vmware/govmomi/releases) to download the latest.
-
-```shell
-# Sample commands for v0.8.0 for 64 bit Linux.
-curl -OL https://github.com/vmware/govmomi/releases/download/v0.8.0/govc_linux_amd64.gz
-gzip -d govc_linux_amd64.gz
-chmod +x govc_linux_amd64
-mv govc_linux_amd64 /usr/local/bin/govc
-```
-
-* Get or build a [binary release](/docs/getting-started-guides/binary_release)
-
-#### Setup
-
-Download a prebuilt Debian 8.2 VMDK that we'll use as a base image:
-
-```shell
-curl --remote-name-all https://storage.googleapis.com/govmomi/vmdk/2016-01-08/kube.vmdk.gz{,.md5}
-md5sum -c kube.vmdk.gz.md5
-gzip -d kube.vmdk.gz
-```
-
-Configure the environment for govc
-
-```shell
-export GOVC_URL='hostname' # hostname of the vc
-export GOVC_USERNAME='username' # username for logging into the vsphere.
-export GOVC_PASSWORD='password' # password for the above username
-export GOVC_NETWORK='Network Name' # Name of the network the vms should join. Many times it could be "VM Network"
-export GOVC_INSECURE=1 # If the host above uses a self-signed cert
-export GOVC_DATASTORE='target datastore'
-# To get resource pool via govc: govc ls -l 'host/*' | grep ResourcePool | awk '{print $1}' | xargs -n1 -t govc pool.info
-export GOVC_RESOURCE_POOL='resource pool or cluster with access to datastore'
-export GOVC_GUEST_LOGIN='kube:kube' # Used for logging into kube.vmdk during deployment.
-export GOVC_PORT=443 # The port to be used by vSphere cloud provider plugin
-# To get datacente via govc: govc datacenter.info
-export GOVC_DATACENTER='ha-datacenter' # The datacenter to be used by vSphere cloud provider plugin
-```
-
-Sample environment
-
-```shell
-export GOVC_URL='10.161.236.217'
-export GOVC_USERNAME='administrator'
-export GOVC_PASSWORD='MyPassword1'
-export GOVC_NETWORK='VM Network'
-export GOVC_INSECURE=1
-export GOVC_DATASTORE='datastore1'
-export GOVC_RESOURCE_POOL='/Datacenter/host/10.20.104.24/Resources'
-export GOVC_GUEST_LOGIN='kube:kube'
-export GOVC_PORT='443'
-export GOVC_DATACENTER='Datacenter'
-```
-
-Import this VMDK into your vSphere datastore:
-
-```shell
-govc import.vmdk kube.vmdk ./kube/
-```
-
-Verify that the VMDK was correctly uploaded and expanded to ~3GiB:
-
-```shell
-govc datastore.ls ./kube/
-```
-
-If you need to debug any part of the deployment, the guest login for
-the image that you imported is `kube:kube`. It is normally specified
-in the GOVC_GUEST_LOGIN parameter above.
-
-Also take a look at the file `cluster/vsphere/config-default.sh` and
-make any needed changes. You can configure the number of nodes
-as well as the IP subnets you have made available to Kubernetes, pods,
-and services.
-
-#### Starting a cluster
-
-Now, let's continue with deploying Kubernetes.
-This process takes about ~20-30 minutes depending on your network.
-
-##### From extracted binary release
-
-```shell
-cd kubernetes
-KUBERNETES_PROVIDER=vsphere cluster/kube-up.sh
-```
-
-##### Build from source
-
-```shell
-cd kubernetes
-make release
-KUBERNETES_PROVIDER=vsphere cluster/kube-up.sh
-```
-
-Refer to the top level README and the getting started guide for Google Compute
-Engine. Once you have successfully reached this point, your vSphere Kubernetes
-deployment works just as any other one!
-
-**Enjoy!**
-
-#### Extra: debugging deployment failure
-
-The output of `kube-up.sh` displays the IP addresses of the VMs it deploys. You
-can log into any VM as the `kube` user to poke around and figure out what is
-going on (find yourself authorized with your SSH key, or use the password
-`kube` otherwise).
+[vmware#220](https://github.com/vmware/kubernetes/issues/220) :
+vSphere Cloud Provider can not be used on the Kubernetes Cluster when vCenter port is configured other than the default port 443. Fix for this issue is already out (Kubernetes PR# [49689](https://github.com/kubernetes/kubernetes/pull/49689)). We will make sure that, PR 49689 is cherry picked to 1.7, 1.6 and 1.5 branches. 

 ## Support Level


-IaaS Provider        | Config. Mgmt | OS     | Networking  | Docs                                              | Conforms | Support Level
-------------------- | ------------ | ------ | ----------  | ---------------------------------------------     | ---------| ----------------------------
-Vmware vSphere       | Kube-anywhere    | Photon OS | Flannel         | [docs](/docs/getting-started-guides/vsphere)                                |          | Community  ([@abrarshivani](https://github.com/abrarshivani)), ([@kerneltime](https://github.com/kerneltime)), ([@BaluDontu](https://github.com/BaluDontu)), ([@luomiao](https://github.com/luomiao)), ([@divyenpatel](https://github.com/divyenpatel))
+IaaS Provider        | Config. Mgmt | OS     | Networking | Docs                                          | Conforms  | Support Level
+-------------------- | ------------ | ------ | ---------- | --------------------------------------------- | --------- | ----------------------------
+Vmware vSphere       | Kube-anywhere    | Photon OS | Flannel         | [docs](/docs/getting-started-guides/vsphere)                                |                | Community  ([@abrarshivani](https://github.com/abrarshivani)), ([@kerneltime](https://github.com/kerneltime)), ([@BaluDontu](https://github.com/BaluDontu)), ([@luomiao](https://github.com/luomiao)), ([@divyenpatel](https://github.com/divyenpatel))

 If you identify any issues/problems using the vSphere cloud provider, you can create an issue in our repo - [VMware Kubernetes](https://github.com/vmware/kubernetes).

 For support level information on all solutions, see the [Table of solutions](/docs/getting-started-guides/#table-of-solutions) chart.
-
@@ -1,7 +1,4 @@
 ---
-redirect_from:
- "/docs/templatedemos/"
- "/docs/templatedemos.html"
 title: Using Page Templates
 ---

@@ -137,6 +137,111 @@ A list of Kubernetes-specific terms and words to be used consistently across the
  <tr><td>TBD</td><td>TBD</td></tr>
 </table>{% endcomment %}

+## Callout Formatting
+Callouts help create different rhetorical appeal levels. Our documentation supports three different callouts: **Note:** {: .note}, **Caution:** {: .caution}, and **Warning:** {: .warning}. 
+
+1. Start each callout with the appropriate prefix.
+
+2. Use the following syntax to apply a style:
+
+```console
+**Note:** The prefix you use is the same text you use in the tag. 
+{: .note} <!-- This tag must appear on a new line. -->
+```
+
+The output is:
+
+**Note:** The prefix you choose is the same text for the tag.
+{: .note}
+
+### Note
+
+Use {: .note} to highlight a tip or a piece of information that may be helpful to know. 
+
+For example:
+
+```console
+**Note:** You can _still_ use Markdown inside these callouts. 
+{: .note}
+```
+
+The output is:
+
+**Note:** You can _still_ use Markdown inside these callouts.
+{: .note}
+
+### Caution
+
+Use {: .caution} to call attention to an important piece of information to avoid pitfalls.  
+
+For example:
+
+```console
+**Caution:** The callout style only applies to the line directly above the tag. 
+{: .caution}
+```
+
+The output is:
+
+**Caution:** The callout style only applies to the line directly above the tag. 
+{: .caution}
+
+### Warning
+
+Use {: .warning} to indicate danger or a piece of information that is crucial to follow.
+
+For example:
+
+```console
+**Warning:** Beware. 
+{: .warning}
+```
+
+The output is:
+
+**Warning:** Beware. 
+{: .warning}
+
+## Common Callout Issues
+
+### Style Does Not Apply
+
+Callout tags must be on a new line to apply the style. Github's Preview Changes feature further obfuscates this fact by rendering the tag on the same line, but your code must match the following syntax:
+
+```console
+**Note:** Your text goes here.
+{: .note} <!-- This tag must appear on a new line. -->
+```
+
+### Multiple Lines
+
+Callouts should generally be single sentences and automatically span multiple lines. However, you can use `<br/>` tags if you need to create multiple lines.
+
+For example:
+
+```console
+**Note:"** This is my note. Use `<br/>` to create multiple lines. <br/> <br/> You can still use _Markdown_ to **format** text!
+{: .note}
+```
+
+The output is:
+
+**Note:** This is my note. Use `<br/>` to create multiple lines. <br/> <br/> You can still use _Markdown_ to **format** text!
+{: .note}
+
+Typing multiple lines does **not** work. The callout style only applies to the line directly above the tag. 
+
+```console
+**Note:** This is my note. 
+
+I didn't read the stlye guide.
+{: .note}
+```
+
+**Note:** This is my note. 
+
+I didn't read the stlye guide.
+{: .note}

 ## Content best practices

@@ -3,11 +3,6 @@ assignees:
 - bgrant0607
 - thockin
 title: Kubernetes Documentation
-redirect_from:
- "/docs/"
- "/docs/index.html"
- "/docs/user-guide/"
- "/docs/user-guide/index.html"
 ---

 Kubernetes documentation can help you set up Kubernetes, learn about the system, or get your applications and workloads running on Kubernetes. To learn the basics of what Kubernetes is and how it works, read "[What is Kubernetes](/docs/concepts/overview/what-is-kubernetes/)".
@@ -36,21 +36,22 @@ Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery
 The following Kubernetes API client libraries are provided and maintained by
 their authors, not the Kubernetes team.

-| Language | Client Library |
-|----------|----------------|
-| Clojure  | [github.com/yanatan16/clj-kubernetes-api](https://github.com/yanatan16/clj-kubernetes-api) |
-| Go       | [github.com/ericchiang/k8s](https://github.com/ericchiang/k8s) |
-| Java (OSGi) | [bitbucket.org/amdatulabs/amdatu-kubernetes](https://bitbucket.org/amdatulabs/amdatu-kubernetes) |
+| Language             | Client Library                           |
+| -------------------- | ---------------------------------------- |
+| Clojure              | [github.com/yanatan16/clj-kubernetes-api](https://github.com/yanatan16/clj-kubernetes-api) |
+| Go                   | [github.com/ericchiang/k8s](https://github.com/ericchiang/k8s) |
+| Java (OSGi)          | [bitbucket.org/amdatulabs/amdatu-kubernetes](https://bitbucket.org/amdatulabs/amdatu-kubernetes) |
 | Java (Fabric8, OSGi) | [github.com/fabric8io/kubernetes-client](https://github.com/fabric8io/kubernetes-client) |
-| Node.js  | [github.com/tenxcloud/node-kubernetes-client](https://github.com/tenxcloud/node-kubernetes-client) |
-| Node.js  | [github.com/godaddy/kubernetes-client](https://github.com/godaddy/kubernetes-client) |
-| Perl     | [metacpan.org/pod/Net::Kubernetes](https://metacpan.org/pod/Net::Kubernetes) |
-| PHP      | [github.com/devstub/kubernetes-api-php-client](https://github.com/devstub/kubernetes-api-php-client) |
-| PHP      | [github.com/maclof/kubernetes-client](https://github.com/maclof/kubernetes-client) |
-| Python   | [github.com/eldarion-gondor/pykube](https://github.com/eldarion-gondor/pykube) |
-| Ruby     | [github.com/Ch00k/kuber](https://github.com/Ch00k/kuber) |
-| Ruby     | [github.com/abonas/kubeclient](https://github.com/abonas/kubeclient) |
-| Scala    | [github.com/doriordan/skuber](https://github.com/doriordan/skuber) |
+| Node.js (TypeScript) | [github.com/Goyoo/node-k8s-client](https://github.com/Goyoo/node-k8s-client) |
+| Node.js              | [github.com/tenxcloud/node-kubernetes-client](https://github.com/tenxcloud/node-kubernetes-client) |
+| Node.js              | [github.com/godaddy/kubernetes-client](https://github.com/godaddy/kubernetes-client) |
+| Perl                 | [metacpan.org/pod/Net::Kubernetes](https://metacpan.org/pod/Net::Kubernetes) |
+| PHP                  | [github.com/devstub/kubernetes-api-php-client](https://github.com/devstub/kubernetes-api-php-client) |
+| PHP                  | [github.com/maclof/kubernetes-client](https://github.com/maclof/kubernetes-client) |
+| Python               | [github.com/eldarion-gondor/pykube](https://github.com/eldarion-gondor/pykube) |
+| Ruby                 | [github.com/Ch00k/kuber](https://github.com/Ch00k/kuber) |
+| Ruby                 | [github.com/abonas/kubeclient](https://github.com/abonas/kubeclient) |
+| Scala                | [github.com/doriordan/skuber](https://github.com/doriordan/skuber) |
 {% endcapture %}

 {% include templates/concept.md %}
@@ -1,8 +1,5 @@
 ---
 title: Federation API Reference
-redirect_from:
- "/docs/federation/api-reference/"
- "/docs/federation/api-reference/index.md"
 ---
 # API Reference

@@ -5,9 +5,6 @@ assignees:
 - errordeveloper
 - jbeda
 title: Using kubeadm to Create a Cluster
-redirect_from:
- "/docs/getting-started-guides/kubeadm/"
- "/docs/getting-started-guides/kubeadm.html"
 ---

 {% capture overview %}
@@ -105,17 +102,16 @@ kubeadm on, and run:
 kubeadm init
 ```

-**Note:** this will autodetect the network interface to advertise the master on
+**Note:**
+ - You need to choose a Pod Network Plugin in the next step. Depending on what
+third-party provider you choose, you might have to set the `--pod-network-cidr` to
+something provider-specific. The tabs below will contain a notice about what flags
+on `kubeadm init` are required.
+ - This will autodetect the network interface to advertise the master on
 as the interface with the default gateway. If you want to use a different
 interface, specify `--apiserver-advertise-address=<ip-address>` argument to `kubeadm
 init`.

-There are pod network implementations where the master also plays a role in
-allocating a set of network address space for each node.  When using
-[flannel](https://github.com/coreos/flannel) as the [pod network](#pod-network)
-(described in step 3), specify `--pod-network-cidr=10.244.0.0/16`. _This is not
-required for any other networks besides flannel._
-
 Please refer to the [kubeadm reference doc](/docs/admin/kubeadm/) if you want to
 read more about the flags `kubeadm init` provides.

@@ -182,31 +178,9 @@ token can add authenticated nodes to your cluster.  These tokens can be listed,
 created and deleted with the `kubeadm token` command.  See the [reference
 guide](/docs/admin/kubeadm/#manage-tokens).

-#### Master Isolation
-
-By default, your cluster will not schedule pods on the master for security
-reasons. If you want to be able to schedule pods on the master, e.g. for a
-single-machine Kubernetes cluster for development, run:
-
-``` bash
-kubectl taint nodes --all node-role.kubernetes.io/master-
-```
-
-With output looking something like:
-
-```
-node "test-01" tainted
-taint key="dedicated" and effect="" not found.
-taint key="dedicated" and effect="" not found.
-```
-
-This will remove the `node-role.kubernetes.io/master` taint from any nodes that
-have it, including the master node, meaning that the scheduler will then be able
-to schedule pods everywhere.
-
 ### (3/4) Installing a pod network {#pod-network}

-You must install a pod network add-on so that your pods can communicate with
+You **must** install a pod network add-on so that your pods can communicate with
 each other.

 **The network must be deployed before any applications.  Also, kube-dns, a
@@ -228,13 +202,79 @@ You can install a pod network add-on with the following command:
 kubectl apply -f <add-on.yaml>
 ```

-Please refer to the specific add-on installation guide for exact details. 
-
 **NOTE:** You can install **only one** pod network per cluster.

-If you are on another architecture than amd64, you should use the
-flannel or Weave Net overlay networks as described in [the
-multi-platform section](#multi-platform)
+
+{% capture choose %}
+Please select one of the tabs to see installation instructions for the respective third-party Pod Network Provider.
+{% endcapture %}
+
+{% capture calico %}
+
+The official Calico guide is [here](http://docs.projectcalico.org/v2.3/getting-started/kubernetes/installation/hosted/kubeadm/)
+
+**Note:**
+ - In order for Network Policy to work correctly, you need to pass `--pod-network-cidr=192.168.0.0/16` to `kubeadm init`
+ - Calico works on `amd64` only.
+
+```shell
+kubectl apply -f http://docs.projectcalico.org/v2.3/getting-started/kubernetes/installation/hosted/kubeadm/1.6/calico.yaml
+```
+{% endcapture %}
+
+{% capture canal %}
+
+The official Canal set-up guide is [here](https://github.com/projectcalico/canal/tree/master/k8s-install)
+
+**Note:**
+ - For Canal to work correctly, `--pod-network-cidr=10.244.0.0/16` has to be passed to `kubeadm init`.
+ - Canal works on `amd64` only.
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/projectcalico/canal/master/k8s-install/1.6/rbac.yaml
+kubectl apply -f https://raw.githubusercontent.com/projectcalico/canal/master/k8s-install/1.6/canal.yaml
+```
+{% endcapture %}
+
+{% capture flannel %}
+
+**Note:**
+ - For flannel to work correctly, `--pod-network-cidr=10.244.0.0/16` has to be passed to `kubeadm init`.
+ - flannel works on `amd64`, `arm`, `arm64` and `ppc64le`, but for it to work on an other platform than
+`amd64` you have to manually download the manifest and replace `amd64` occurances with your chosen platform.
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
+kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel-rbac.yml
+```
+{% endcapture %}
+
+{% capture romana %}
+
+The official Romana set-up guide is [here](https://github.com/romana/romana/tree/master/containerize#using-kubeadm)
+
+**Note:** Romana works on `amd64` only.
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/romana/romana/master/containerize/specs/romana-kubeadm.yml
+```
+{% endcapture %}
+
+{% capture weave_net %}
+
+The official Weave Net set-up guide is [here](https://www.weave.works/docs/net/latest/kube-addon/)
+
+**Note:** Weave Net works on `amd64`, `arm` and `arm64` without any extra action required.
+
+```shell
+kubectl apply -f https://git.io/weave-kube-1.6
+```
+{% endcapture %}
+
+{% assign tab_names = "Choose one...,Calico,Canal,Flannel,Romana,Weave Net" | split: ',' | compact %}
+{% assign tab_contents = site.emptyArray | push: choose | push: calico | push: canal | push: flannel | push: romana | push: weave_net %}
+
+{% include tabs.md %}

 Once a pod network has been installed, you can confirm that it is working by
 checking that the kube-dns pod is Running in the output of `kubectl get pods --all-namespaces`.
@@ -243,6 +283,28 @@ And once the kube-dns pod is up and running, you can continue by joining your no
 If your network is not working or kube-dns is not in the Running state, check
 out the [troubleshooting section](#troubleshooting) below.

+#### Master Isolation
+
+By default, your cluster will not schedule pods on the master for security
+reasons. If you want to be able to schedule pods on the master, e.g. for a
+single-machine Kubernetes cluster for development, run:
+
+``` bash
+kubectl taint nodes --all node-role.kubernetes.io/master-
+```
+
+With output looking something like:
+
+```
+node "test-01" tainted
+taint key="dedicated" and effect="" not found.
+taint key="dedicated" and effect="" not found.
+```
+
+This will remove the `node-role.kubernetes.io/master` taint from any nodes that
+have it, including the master node, meaning that the scheduler will then be able
+to schedule pods everywhere.
+
 ### (4/4) Joining your nodes

 The nodes are where your workloads (containers and pods, etc) run. To add new nodes to your cluster do the following for each machine:
@@ -294,7 +356,7 @@ kubectl --kubeconfig ./admin.conf get nodes

 **Note:** If you are using GCE, instances disable ssh access for root by default.
 If that's the case you can log in to the machine, copy the file someplace that
-can be accessed and then use 
+can be accessed and then use
 [`gcloud compute copy-files`](https://cloud.google.com/sdk/gcloud/reference/compute/copy-files)

 ### (Optional) Proxying API Server to localhost
@@ -419,7 +481,9 @@ kubeadm deb/rpm packages and binaries are built for amd64, arm (32-bit), arm64,
 following the [multi-platform
 proposal](https://github.com/kubernetes/kubernetes/blob/master/docs/proposals/multi-platform.md).

-Currently, only the pod networks [flannel](https://github.com/coreos/flannel) and [Weave Net](https://www.weave.works/docs/net/latest/kube-addon/) work on multiple architectures.
+Only some of the network providers offer solutions for all platforms. Please consult the list of
+network providers above or the documentation from each provider to figure out whether the provider
+supports your chosen platform.

 ## Limitations

@@ -4,9 +4,6 @@ assignees:
 - erictune
 - mikedanese
 title: Picking the Right Solution
-redirect_from:
- "/docs/getting-started-guides/index/"
- "/docs/getting-started-guides/index.html"
 ---

 Kubernetes can run on various platforms: from your laptop, to VMs on a cloud provider, to rack of
@@ -1,10 +1,5 @@
 ---
 title: Accessing Clusters
-redirect_from:
- "/docs/user-guide/accessing-the-cluster/"
- "/docs/user-guide/accessing-the-cluster.html"
- "/docs/concepts/cluster-administration/access-cluster/"
- "/docs/concepts/cluster-administration/access-cluster.html"
 ---

 * TOC
@@ -124,7 +119,8 @@ with future high-availability support.

 ### Programmatic access to the API

-Kubernetes supports [Go](#go-client) and [Python](#python-client) client libraries.
+Kubernetes officially supports [Go](#go-client) and [Python](#python-client)
+client libraries.

 #### Go client

@@ -145,7 +141,8 @@ as the kubectl CLI does to locate and authenticate to the apiserver. See this [e

 #### Other languages

-There are [client libraries](https://git.k8s.io/community/contributors/devel/client-libraries.md) for accessing the API from other languages. See documentation for other libraries for how they authenticate.
+There are [client libraries](/docs/reference/client-libraries/) for accessing the API from other languages.
+See documentation for other libraries for how they authenticate.

 ### Accessing the API from a Pod

@@ -3,11 +3,6 @@ assignees:
 - mikedanese
 - thockin
 title: Authenticate Across Clusters with kubeconfig
-redirect_from:
- "/docs/user-guide/kubeconfig-file/"
- "/docs/user-guide/kubeconfig-file.html"
- "/docs/concepts/cluster-administration/authenticate-across-clusters-kubeconfig/"
- "/docs/concepts/cluster-administration/authenticate-across-clusters-kubeconfig.html"
 ---

 Authentication in Kubernetes can differ for different individuals.
@@ -1,10 +1,5 @@
 ---
 title: Communicate Between Containers in the Same Pod Using a Shared Volume
-redirect_from:
- "/docs/user-guide/pods/multi-container/"
- "/docs/user-guide/pods/multi-container.html"
- "docs/tasks/configure-pod-container/communicate-containers-same-pod/"
- "docs/tasks/configure-pod-container/communicate-containers-same-pod.html"
 ---

 {% capture overview %}
@@ -144,9 +139,9 @@ the shared Volume is lost.
 * See
 [Configuring a Pod to Use a Volume for Storage](/docs/tasks/configure-pod-container/configure-volume-storage/).

-* See [Volume](/docs/api-reference/v1.6/#volume-v1-core).
+* See [Volume](/docs/api-reference/{{page.version}}/#volume-v1-core).

-* See [Pod](/docs/api-reference/v1.6/#pod-v1-core).
+* See [Pod](/docs/api-reference/{{page.version}}/#pod-v1-core).

 {% endcapture %}

@@ -3,9 +3,6 @@ assignees:
 - bprashanth
 - davidopp
 title: Configure Your Cloud Provider's Firewalls
-redirect_from:
- "/docs/user-guide/services-firewalls/"
- "/docs/user-guide/services-firewalls.html"
 ---

 Many cloud providers (e.g. Google Compute Engine) define firewalls that help prevent inadvertent
@@ -1,10 +1,5 @@
 ---
 title: Connect a Front End to a Back End Using a Service
-redirect_from:
- "/docs/user-guide/services/operations/"
- "/docs/user-guide/services/operations.html"
- "/docs/tutorials/connecting-apps/connecting-frontend-backend/"
- "/docs/tutorials/connecting-apps/connecting-frontend-backend.html"
 ---

 {% capture overview %}
@@ -1,8 +1,5 @@
 ---
 title: Create an External Load Balancer
-redirect_from:
- "/docs/user-guide/load-balancer/"
- "/docs/user-guide/load-balancer.html"
 ---


@@ -1,8 +1,5 @@
 ---
 title: List All Container Images Running in a Cluster
-redirect_from:
- "/docs/tasks/kubectl/list-all-running-container-images/"
- "/docs/tasks/kubectl/list-all-running-container-images.html"
 ---

 {% capture overview %}
@@ -1,8 +1,5 @@
 ---
 title: Use Port Forwarding to Access Applications in a Cluster
-redirect_from:
- "/docs/user-guide/connecting-to-applications-port-forward/"
- "/docs/user-guide/connecting-to-applications-port-forward.html"
 ---

 {% capture overview %}
@@ -1,10 +1,5 @@
 ---
 title: Use a Service to Access an Application in a Cluster
-redirect_from:
- "/docs/user-guide/quick-start/"
- "/docs/user-guide/quick-start.html"
- "/docs/tutorials/stateless-application/expose-external-ip-address-service/"
- "/docs/tutorials/stateless-application/expose-external-ip-address-service.html"
 ---

 {% capture overview %}
@@ -99,11 +94,14 @@ provides load balancing for an application that has two running instances.
   see the node address by running `kubectl cluster-info`. If you are
   using Google Compute Engine instances, you can use the
   `gcloud compute instances list` command to see the public addresses of your
-   nodes.
+   nodes. For more information about this command, see the [GCE documentation](https://cloud.google.com/sdk/gcloud/reference/compute/instances/list). 

 1. On your chosen node, create a firewall rule that allows TCP traffic
   on your node port. For example, if your Service has a NodePort value of
-   31568, create a firewall rule that allows TCP traffic on port 31568.
+   31568, create a firewall rule that allows TCP traffic on port 31568. Different 
+   cloud providers offer different ways of configuring firewall rules. See [the 
+   GCE documentation on firewall rules](https://cloud.google.com/compute/docs/vpc/firewalls), 
+   for example.

 1. Use the node address and node port to access the Hello World application:

@@ -4,11 +4,6 @@ assignees:
 - mikedanese
 - rf232
 title: Web UI (Dashboard)
-redirect_from:
- "/docs/user-guide/ui/"
- "/docs/user-guide/ui.html"
- "/docs/tasks/web-ui-dashboard/"
- "/docs/tasks/web-ui-dashboard.html"
 ---

 Dashboard is a web-based Kubernetes user interface. You can use Dashboard to deploy containerized applications to a Kubernetes cluster, troubleshoot your containerized application, and manage the cluster itself along with its attendant resources. You can use Dashboard to get an overview of applications running on your cluster, as well as for creating or modifying individual Kubernetes resources (such as Deployments, Jobs, DaemonSets, etc). For example, you can scale a Deployment, initiate a rolling update, restart a pod or deploy new applications using a deploy wizard.
@@ -3,11 +3,6 @@ assignees:
 - enisoc
 - IanLewis
 title: Extend the Kubernetes API with ThirdPartyResources
-redirect_from:
- "/docs/user-guide/thirdpartyresources/"
- "/docs/user-guide/thirdpartyresources.html"
- "/docs/concepts/ecosystem/thirdpartyresource/"
- "/docs/concepts/ecosystem/thirdpartyresource.html"
 ---

 {% assign for_k8s_version="1.7" %}{% include feature-state-deprecated.md %}
@@ -1,8 +1,5 @@
 ---
 title: Use an HTTP Proxy to Access the Kubernetes API
-redirect_from:
- "/docs/user-guide/connecting-to-applications-proxy/"
- "/docs/user-guide/connecting-to-applications-proxy.html"
 ---

 {% capture overview %}
@@ -1,9 +1,5 @@
 ---
 title: Access Clusters Using the Kubernetes API
-redirect_from:
- "/docs/user-guide/accessing-the-cluster/"
- "/docs/user-guide/accessing-the-cluster.html"
- "/docs/concepts/cluster-administration/access-cluster/"
 ---

 {% capture overview %}
@@ -43,10 +39,10 @@ kubectl.  Complete documentation is found in the [kubectl manual](/docs/user-gui
 Kubectl handles locating and authenticating to the apiserver. If you want to directly access the REST API with an http client like
 `curl` or `wget`, or a browser, there are multiple ways you can locate and authenticate against the apiserver:

- 1. Run kubectl in proxy mode (recommended).  This method is recommended, since it uses the stored apiserver location abd verifies the identity of the apiserver using a self-signed cert.  No Man-in-the-middle (MITM) attack is possible using this method . 
+ 1. Run kubectl in proxy mode (recommended).  This method is recommended, since it uses the stored apiserver location abd verifies the identity of the apiserver using a self-signed cert.  No Man-in-the-middle (MITM) attack is possible using this method .
 1. Alternatively, you can provide the location and credentials directly to the http client. This works with for client code that is confused by proxies.  To protect against man in the middle attacks, you'll need to import a root cert into your browser.
- 
- Using the Go or Python client libraries provides accessing kubectl in proxy mode. 
+
+ Using the Go or Python client libraries provides accessing kubectl in proxy mode.

 #### Using kubectl proxy

@@ -116,7 +112,8 @@ with future high-availability support.

 ### Programmatic access to the API

-Kubernetes supports [Go](#go-client) and [Python](#python-client) client libraries.
+Kubernetes officially supports client libraries for [Go](#go-client) and
+[Python](#python-client).

 #### Go client

@@ -167,7 +164,7 @@ for i in ret.items:

 #### Other languages

-There are [client libraries](https://git.k8s.io/community/contributors/devel/client-libraries.md) for accessing the API from other languages. See documentation for other libraries for how they authenticate.
+There are [client libraries](/docs/reference/client-libraries/) for accessing the API from other languages. See documentation for other libraries for how they authenticate.

 ### Accessing the API from a Pod

@@ -1,12 +1,9 @@
 ---
 title: Access Services Running on Clusters
-redirect_from:
- "/docs/user-guide/accessing-the-cluster/"
- "/docs/user-guide/accessing-the-cluster.html"
 ---

 {% capture overview %}
-This page shows how to connect to services running on the Kubernetes cluster. 
+This page shows how to connect to services running on the Kubernetes cluster.
 {% endcapture %}

 {% capture prerequisites %}
@@ -3,11 +3,6 @@ assignees:
 - derekwaynecarr
 - janetkuo
 title: Apply Resource Quotas and Limits
-redirect_from:
- "/docs/admin/resourcequota/walkthrough/"
- "/docs/admin/resourcequota/walkthrough.html"
- "/docs/tasks/configure-pod-container/apply-resource-quota-limit/"
- "/docs/tasks/configure-pod-container/apply-resource-quota-limit.html"
 ---

 {% capture overview %}
@@ -359,7 +354,7 @@ the 2 pods we created in the `not-best-effort-nginx` quota.

 Scopes provide a mechanism to subdivide the set of resources that are tracked by
 any quota document to allow greater flexibility in how operators deploy and track resource
-consumption.  
+consumption.

 In addition to `BestEffort` and `NotBestEffort` scopes, there are scopes to restrict
 long-running versus time-bound pods.  The `Terminating` scope will match any pod
@@ -2,11 +2,6 @@
 assignees:
 - caseydavenport
 title: Use Calico for NetworkPolicy
-redirect_from:
- "/docs/getting-started-guides/network-policy/calico/"
- "/docs/getting-started-guides/network-policy/calico.html"
- "/docs/tasks/configure-pod-container/calico-network-policy/"
- "/docs/tasks/configure-pod-container/calico-network-policy.html"
 ---

 {% capture overview %}
@@ -14,7 +9,7 @@ This page shows how to use Calico for NetworkPolicy.
 {% endcapture %}

 {% capture prerequisites %}
-* Install Calico for Kubernetes. 
+* Install Calico for Kubernetes.
 {% endcapture %}

 {% capture steps %}
@@ -34,7 +29,7 @@ See the [Calico documentation](http://docs.projectcalico.org/) for more options
 {% capture discussion %}
 ##  Understanding Calico components

-Deploying a cluster with Calico adds Pods that support Kubernetes NetworkPolicy.  These Pods run in the `kube-system` Namespace. 
+Deploying a cluster with Calico adds Pods that support Kubernetes NetworkPolicy.  These Pods run in the `kube-system` Namespace.

 To see this list of Pods run:

@@ -18,7 +18,7 @@ PersistentVolume.
 ## Why change reclaim policy of a PersistentVolume

 `PersistentVolumes` can have various reclaim policies, including "Retain",
-"Recycle", and "Delete". For dynamically provisioned `PersistentVolumes`, 
+"Recycle", and "Delete". For dynamically provisioned `PersistentVolumes`,
 the default reclaim policy is "Delete". This means that a dynamically provisioned
 volume is automatically deleted when a user deletes the corresponding
 `PeristentVolumeClaim`. This automatic behavior might be inappropriate if the volume
@@ -72,9 +72,9 @@ the corresponding `PersistentVolume` is not be deleted. Instead, it is moved to

 ### Reference

-* [PersistentVolume](/docs/api-reference/v1.6/#persistentvolume-v1-core)
-* [PersistentVolumeClaim](/docs/api-reference/v1.6/#persistentvolumeclaim-v1-core)
-* See the `persistentVolumeReclaimPolicy` field of [PersistentVolumeSpec](/docs/api-reference/v1.6/#persistentvolumeclaim-v1-core).
+* [PersistentVolume](/docs/api-reference/{{page.version}}/#persistentvolume-v1-core)
+* [PersistentVolumeClaim](/docs/api-reference/{{page.version}}/#persistentvolumeclaim-v1-core)
+* See the `persistentVolumeReclaimPolicy` field of [PersistentVolumeSpec](/docs/api-reference/{{page.version}}/#persistentvolumeclaim-v1-core).
 {% endcapture %}

 {% include templates/task.md %}
@@ -3,11 +3,6 @@ assignees:
 - lavalamp
 - thockin
 title: Cluster Management
-redirect_from:
- "/docs/admin/cluster-management/"
- "/docs/admin/cluster-management.html"
- "/docs/concepts/cluster-administration/cluster-management/"
- "/docs/concepts/cluster-administration/cluster-management.html"
 ---

 * TOC
@@ -3,11 +3,6 @@ assignees:
 - davidopp
 - madhusudancs
 title: Configure Multiple Schedulers
-redirect_from:
- "/docs/admin/multiple-schedulers/"
- "/docs/admin/multiple-schedulers.html"
- "/docs/tutorials/clusters/multiple-schedulers/"
- "/docs/tutorials/clusters/multiple-schedulers.html"
 ---

 Kubernetes ships with a default scheduler that is described [here](/docs/admin/kube-scheduler/).
@@ -3,17 +3,6 @@ assignees:
 - mml
 - wojtek-t
 title: Operating etcd clusters for Kubernetes
-redirect_from:
- "/docs/concepts/storage/etcd-store-api-object/"
- "/docs/concepts/storage/etcd-store-api-object.html"
- "/docs/admin/etcd/"
- "/docs/admin/etcd.html"
- "/docs/admin/etcd_upgrade/"
- "/docs/admin/etcd_upgrade.html"
- "/docs/concepts/cluster-administration/configure-etcd/"
- "/docs/concepts/cluster-administration/configure-etcd.html"
- "/docs/concepts/cluster-administration/etcd-upgrade/"
- "/docs/concepts/cluster-administration/etcd-upgrade.html"
 ---

 etcd is a strong, consistent, and highly-available key value store which Kubernetes uses for persistent storage of all of its API objects. This documentation provides specific instruction on operating, upgrading, and rolling back etcd clusters for Kubernetes. For in-depth information on etcd, see [etcd documentation](https://github.com/coreos/etcd/blob/master/Documentation/docs.md).
@@ -3,11 +3,6 @@ assignees:
 - derekwaynecarr
 - janetkuo
 title: Set Pod CPU and Memory Limits
-redirect_from:
- "/docs/admin/limitrange/"
- "/docs/admin/limitrange/index.html"
- "/docs/tasks/configure-pod-container/limit-range/"
- "/docs/tasks/configure-pod-container/limit-range.html"
 ---

 {% capture overview %}
@@ -39,7 +34,7 @@ $ kubectl create namespace limit-example
 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: 
+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
@@ -103,7 +98,7 @@ 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/v1.6/#run) for more details. 
+If you want to obtain the old behavior, use `--generator=run/v1` to create replication controllers. See [`kubectl run`](/docs/user-guide/kubectl/{{page.version}}/#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
@@ -112,7 +107,7 @@ NAME                     READY     STATUS    RESTARTS   AGE
 nginx-2040093540-s8vzu   1/1       Running   0          11s
 ```

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

 ```shell
 $ kubectl get pods nginx-2040093540-s8vzu --namespace=limit-example -o yaml | grep resources -C 8
@@ -151,7 +146,7 @@ $ kubectl create -f https://k8s.io/docs/tasks/configure-pod-container/valid-pod.
 pod "valid-pod" created
 ```

-Now look at the Pod's resources field: 
+Now look at the Pod's resources field:

 ```shell
 $ kubectl get pods valid-pod --namespace=limit-example -o yaml | grep -C 6 resources
@@ -215,8 +210,8 @@ to 512MB of memory.  The cluster operator creates a separate namespace for each
 each namespace.
 3. Users may create a pod which consumes resources just below the capacity of a machine.  The left over space
 may be too small to be useful, but big enough for the waste to be costly over the entire cluster.  As a result,
-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 limit waste.
+the cluster operator may want to set limits that a pod must consume no more than 20% of the memory and CPU of
+their average node size in order to provide for more uniform scheduling and limit waste.

 ## Summary

@@ -3,14 +3,9 @@ assignees:
 - caseydavenport
 - danwinship
 title: Declare Network Policy
-redirect_from:
- "/docs/getting-started-guides/network-policy/walkthrough/"
- "/docs/getting-started-guides/network-policy/walkthrough.html"
- "/docs/tasks/configure-pod-container/declare-network-policy/"
- "/docs/tasks/configure-pod-container/declare-network-policy.html"
 ---
 {% capture overview %}
-This document helps you get started using using the Kubernetes [NetworkPolicy API](/docs/user-guide/network-policies) to declare network policies that govern how pods communicate with each other. 
+This document helps you get started using using the Kubernetes [NetworkPolicy API](/docs/concepts/services-networking/network-policies/) to declare network policies that govern how pods communicate with each other.
 {% endcapture %}

 {% capture prerequisites %}
@@ -28,16 +23,16 @@ You'll need to have a Kubernetes cluster in place, with network policy support.

 ## Create an `nginx` deployment and expose it via a service

-To see how Kubernetes network policy works, start off by creating an `nginx` deployment and exposing it via a service. 
+To see how Kubernetes network policy works, start off by creating an `nginx` deployment and exposing it via a service.

 ```console
 $ kubectl run nginx --image=nginx --replicas=2
 deployment "nginx" created
-$ kubectl expose deployment nginx --port=80 
+$ kubectl expose deployment nginx --port=80
 service "nginx" exposed
 ```

-This runs two `nginx` pods in the default namespace, and exposes them through a service called `nginx`. 
+This runs two `nginx` pods in the default namespace, and exposes them through a service called `nginx`.

 ```console
 $ kubectl get svc,pod
@@ -104,7 +99,7 @@ Waiting for pod default/busybox-472357175-y0m47 to be running, status is Pending

 Hit enter for command prompt

-/ # wget --spider --timeout=1 nginx 
+/ # wget --spider --timeout=1 nginx
 Connecting to nginx (10.100.0.16:80)
 wget: download timed out
 / #
@@ -148,7 +148,7 @@ program to retrieve the contents of your secret.
 Since secrets are encrypted on write, performing an update on a secret will encrypt that content.

 ```
-kubectl get secrets -o json | kubectl update -f -
+kubectl get secrets -o json | kubectl replace -f -
 ```

 The command above reads all secrets and then updates them to apply server side encryption.
@@ -165,7 +165,7 @@ the presence of a highly available deployment where multiple `kube-apiserver` pr
 2. Restart all `kube-apiserver` processes to ensure each server can decrypt using the new key
 3. Make the new key the first entry in the `keys` array so that it is used for encryption in the config
 4. Restart all `kube-apiserver` processes to ensure each server now encrypts using the new key
-5. Run `kubectl get secrets -o json | kubectl update -f -` to update all secrets
+5. Run `kubectl get secrets -o json | kubectl replace -f -` to encrypt all existing secrets with the new key
 6. Remove the old decryption key from the config after you back up etcd with the new key in use and update all secrets

 With a single `kube-apiserver`, step 2 may be skipped
@@ -189,7 +189,7 @@ resources:
          secret: <BASE 64 ENCODED SECRET>
 ```

-and restart all `kube-apiserver` processes. Then run the command `kubectl get secrets -o json | kubectl update -f -`
+and restart all `kube-apiserver` processes. Then run the command `kubectl get secrets -o json | kubectl replace -f -`
 to force all secrets to be decrypted.

 {% endcapture %}
@@ -4,11 +4,6 @@ assignees:
 - filipg
 - piosz
 title: Guaranteed Scheduling For Critical Add-On Pods
-redirect_from:
- "/docs/admin/rescheduler/"
- "/docs/admin/rescheduler.html"
- "/docs/concepts/cluster-administration/guaranteed-scheduling-critical-addon-pods/"
- "/docs/concepts/cluster-administration/guaranteed-scheduling-critical-addon-pods.html"
 ---

 * TOC
@@ -2,9 +2,6 @@
 assignees:
 - jszczepkowski
 title: Set up High-Availability Kubernetes Masters
-redirect_from:
- "/docs/admin/ha-master-gce/"
- "/docs/admin/ha-master-gce.html"
 ---

 * TOC
@@ -65,7 +62,7 @@ You can remove a master replica from an HA cluster by using a `kube-down` script
 * `KUBE_DELETE_NODES=false` - to restrain deletion of kubelets.

 * `KUBE_GCE_ZONE=zone` - the zone from where master replica will be removed.
- 
+
 * `KUBE_REPLICA_NAME=replica_name` - (optional) the name of master replica to remove.
 If empty: any replica from the given zone will be removed.

@@ -105,7 +102,7 @@ A two-replica cluster is thus inferior, in terms of HA, to a single replica clus

 * When you add a master replica, cluster state (etcd) is copied to a new instance.
 If the cluster is large, it may take a long time to duplicate its state.
-This operation may be sped up by migrating etcd data directory, as described [here](https://coreos.com/etcd/docs/latest/admin_guide.html#member-migration) 
+This operation may be sped up by migrating etcd data directory, as described [here](https://coreos.com/etcd/docs/latest/admin_guide.html#member-migration)
 (we are considering adding support for etcd data dir migration in future).

 ## Implementation notes
@@ -60,7 +60,7 @@ By default, in GCE/GKE starting with Kubernetes version 1.7.0, the ip-masq-agent
 To create an ip-masq-agent, run the following kubectl command:

 `
-kubectl create -f https://github.com/kubernetes-incubator/ip-masq-agent/blob/master/ip-masq-agent.yaml
+kubectl create -f https://raw.githubusercontent.com/kubernetes-incubator/ip-masq-agent/master/ip-masq-agent.yaml
 `

 More information can be found in the ip-masq-agent documentation [here](https://github.com/kubernetes-incubator/ip-masq-agent)
@@ -2,9 +2,6 @@
 assignees:
 - pipejakob
 title: Upgrading kubeadm clusters from 1.6 to 1.7
-redirect_from:
- "/docs/admin/kubeadm-upgrade-1-7/"
- "/docs/admin/kubeadm-upgrade-1-7.html"
 ---

 {% capture overview %}
@@ -95,4 +92,4 @@ You need to have a Kubernetes cluster running version 1.6.x.

 {% endcapture %}

-{% include templates/task.md %}
+{% include templates/task.md %}
@@ -1,16 +1,13 @@
 ---
 title: Limit Storage Consumption
-redirect_from:
- "/docs/admin/resourcequota/limitstorageconsumption/"
- "/docs/admin/resourcequota/limitstorageconsumption.html"
 ---

 {% capture overview %}

 This example demonstrates an easy way to limit the amount of storage consumed in a namespace.

-The following resources are used in the demonstration: [ResourceQuota](/docs/concepts/policy/resource-quotas/), 
-[LimitRange](/docs/tasks/configure-pod-container/limit-range/), 
+The following resources are used in the demonstration: [ResourceQuota](/docs/concepts/policy/resource-quotas/),
+[LimitRange](/docs/tasks/configure-pod-container/limit-range/),
 and [PersistentVolumeClaim](/docs/concepts/storage/persistent-volumes/).

 {% endcapture %}
@@ -56,17 +53,17 @@ spec:
      storage: 1Gi
 ```

-Minimum storage requests are used when the underlying storage provider requires certain minimums. For example, 
-AWS EBS volumes have a 1Gi minimum requirement. 
+Minimum storage requests are used when the underlying storage provider requires certain minimums. For example,
+AWS EBS volumes have a 1Gi minimum requirement.

 ## StorageQuota to limit PVC count and cumulative storage capacity

 Admins can limit the number of PVCs in a namespace as well as the cumulative capacity of those PVCs. New PVCs that exceed
 either maximum value will be rejected.

-In this example, a 6th PVC in the namespace would be rejected because it exceeds the maximum count of 5. Alternatively, 
+In this example, a 6th PVC in the namespace would be rejected because it exceeds the maximum count of 5. Alternatively,
 a 5Gi maximum quota when combined with the 2Gi max limit above, cannot have 3 PVCs where each has 2Gi. That would be 6Gi requested
- for a namespace capped at 5Gi. 
+ for a namespace capped at 5Gi.

 ```
 apiVersion: v1
@@ -83,10 +80,10 @@ spec:

 {% capture discussion %}

-## Summary 
+## Summary

 A limit range can put a ceiling on how much storage is requested while a resource quota can effectively cap the storage
-consumed by a namespace through claim counts and cumulative storage capacity. The allows a cluster-admin to plan their 
+consumed by a namespace through claim counts and cumulative storage capacity. The allows a cluster-admin to plan their
 cluster's storage budget without risk of any one project going over their allotment.

 {% endcapture %}
@@ -3,9 +3,6 @@ assignees:
 - derekwaynecarr
 - janetkuo
 title: Namespaces Walkthrough
-redirect_from:
- "/docs/admin/namespaces/walkthrough/"
- "/docs/admin/namespaces/walkthrough.html"
 ---

 Kubernetes _namespaces_ help different projects, teams, or customers to share a Kubernetes cluster.
@@ -153,9 +150,9 @@ Let's create some contents.
 ```shell
 $ 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. 
+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/v1.6/#run) for more details. 
+If you want to obtain the old behavior, use `--generator=run/v1` to create replication controllers. See [`kubectl run`](/docs/user-guide/kubectl/v1.6/#run) for more details.

 ```shell
 $ kubectl get deployment
@@ -3,47 +3,22 @@ assignees:
 - derekwaynecarr
 - janetkuo
 title: Share a Cluster with Namespaces
-redirect_from:
- "/docs/admin/namespaces/"
- "/docs/admin/namespaces/index.html"
 ---

-A Namespace is a mechanism to partition resources created by users into
-a logically named group.
+{% capture overview %}
+This page shows how to view, work in, and delete namespaces. The page also shows how to use Kubernetes namespaces to subdivide your cluster.
+{% endcapture %}

-## Motivation
+{% capture prerequisites %}
+* Have an [existing Kubernetes cluster](/docs/getting-started-guides/).
+* Have a basic understanding of Kubernetes _[Pods](/docs/concepts/workloads/pods/pod/)_, _[Services](/docs/concepts/services-networking/service/)_, and _[Deployments](/docs/concepts/workloads/controllers/deployment/)_.
+{% endcapture %}

-A single cluster should be able to satisfy the needs of multiple users or groups of users (henceforth a 'user community').
-
-Each user community wants to be able to work in isolation from other communities.
-
-Each user community has its own:
-
-1. resources (pods, services, replication controllers, etc.)
-2. policies (who can or cannot perform actions in their community)
-3. constraints (this community is allowed this much quota, etc.)
-
-A cluster operator may create a Namespace for each unique user community.
-
-The Namespace provides a unique scope for:
-
-1. named resources (to avoid basic naming collisions)
-2. delegated management authority to trusted users
-3. ability to limit community resource consumption
-
-## Use cases
-
-1.  As a cluster operator, I want to support multiple user communities on a single cluster.
-2.  As a cluster operator, I want to delegate authority to partitions of the cluster to trusted users
-    in those communities.
-3.  As a cluster operator, I want to limit the amount of resources each community can consume in order
-    to limit the impact to other communities using the cluster.
-4.  As a cluster user, I want to interact with resources that are pertinent to my user community in
-    isolation of what other user communities are doing on the cluster.
+{% capture steps %}

 ## Viewing namespaces

-You can list the current namespaces in a cluster using:
+1. List the current namespaces in a cluster using:

 ```shell
 $ kubectl get namespaces
@@ -67,16 +42,16 @@ Or you can get detailed information with:

 ```shell
 $ kubectl describe namespaces <name>
-Name:       default
-Labels:       <none>
-Status:       Active
+Name:      default
+Labels:    <none>
+Status:    Active

 No resource quota.

 Resource Limits
- Type        Resource    Min    Max    Default
- ----                --------    ---    ---    ---
- Container            cpu            -    -    100m
+ Type       Resource    Min Max Default
+ ----               --------    --- --- ---
+ Container          cpu         -   -   100m
 ```

 Note that these details show both resource quota (if present) as well as resource limit ranges.
@@ -98,7 +73,7 @@ See the [design doc](https://git.k8s.io/community/contributors/design-proposals/

 ## Creating a new namespace

-To create a new namespace, first create a new YAML file called `my-namespace.yaml` with the contents:
+1. Create a new YAML file called `my-namespace.yaml` with the contents:

 ```yaml
 apiVersion: v1
@@ -119,15 +94,9 @@ There's an optional field `finalizers`, which allows observables to purge resour

 More information on `finalizers` can be found in the namespace [design doc](https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers).

-
-### Working in namespaces
-
-See [Setting the namespace for a request](/docs/user-guide/namespaces/#setting-the-namespace-for-a-request)
-and [Setting the namespace preference](/docs/user-guide/namespaces/#setting-the-namespace-preference).
-
 ## Deleting a namespace

-You can delete a namespace with
+1. Delete a namespace with

 ```shell
 $ kubectl delete namespaces <insert-some-namespace-name>
@@ -137,16 +106,246 @@ $ kubectl delete namespaces <insert-some-namespace-name>

 This delete is asynchronous, so for a time you will see the namespace in the `Terminating` state.

-## Namespaces and DNS
+## Subdividing your cluster using Kubernetes namespaces

-When you create a [Service](/docs/user-guide/services), it creates a corresponding [DNS entry](/docs/admin/dns).
+1. Understand the default namespace
+
+By default, a Kubernetes cluster will instantiate a default namespace when provisioning the cluster to hold the default set of Pods,
+Services, and Deployments used by the cluster.
+
+Assuming you have a fresh cluster, you can introspect the available namespace's by doing the following:
+
+```shell
+$ kubectl get namespaces
+NAME      STATUS    AGE
+default   Active    13m
+```
+
+2. Create new namespaces
+
+For this exercise, we will create two additional Kubernetes namespaces to hold our content.
+
+In a scenario where an organization is using a shared Kubernetes cluster for development and production use cases:
+
+The development team would like to maintain a space in the cluster where they can get a view on the list of Pods, Services, and Deployments
+they use to build and run their application.  In this space, Kubernetes resources come and go, and the restrictions on who can or cannot modify resources
+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.
+
+One pattern this organization could follow is to partition the Kubernetes cluster into two namespaces: development and production.
+
+Let's create two new namespaces to hold our work.
+
+Use the file [`namespace-dev.json`](/docs/admin/namespaces/namespace-dev.json) which describes a development namespace:
+
+{% include code.html language="json" file="namespace-dev.json" ghlink="/docs/admin/namespaces/namespace-dev.json" %}
+
+Create the development namespace using kubectl.
+
+```shell
+$ kubectl create -f docs/admin/namespaces/namespace-dev.json
+```
+
+And then let's create the production namespace using kubectl.
+
+```shell
+$ kubectl create -f docs/admin/namespaces/namespace-prod.json
+```
+
+To be sure things are right, list all of the namespaces in our cluster.
+
+```shell
+$ kubectl get namespaces --show-labels
+NAME          STATUS    AGE       LABELS
+default       Active    32m       <none>
+development   Active    29s       name=development
+production    Active    23s       name=production
+```
+
+3. Create pods in each namespace
+
+A Kubernetes namespace provides the scope for Pods, Services, and Deployments in the cluster.
+
+Users interacting with one namespace do not see the content in another namespace.
+
+To demonstrate this, let's spin up a simple Deployment and Pods in the development namespace.
+
+We first check what is the current context:
+
+```shell
+$ kubectl config view
+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
+    user: lithe-cocoa-92103_kubernetes
+  name: lithe-cocoa-92103_kubernetes
+current-context: lithe-cocoa-92103_kubernetes
+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
+
+$ 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.
+
+```shell
+$ kubectl config set-context dev --namespace=development --cluster=lithe-cocoa-92103_kubernetes --user=lithe-cocoa-92103_kubernetes
+$ kubectl config set-context prod --namespace=production --cluster=lithe-cocoa-92103_kubernetes --user=lithe-cocoa-92103_kubernetes
+```
+
+The above commands provided two request contexts you can alternate against depending on what namespace you
+wish to work against.
+
+Let's switch to operate in the development namespace.
+
+```shell
+$ kubectl config use-context dev
+```
+
+You can verify your current context by doing the following:
+
+```shell
+$ kubectl config current-context
+dev
+```
+
+At this point, all requests we make to the Kubernetes cluster from the command line are scoped to the development namespace.
+
+Let's create some contents.
+
+```shell
+$ 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/v1.7/#run) for more details. 
+
+```shell
+$ kubectl get deployment
+NAME        DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+snowflake   2         2         2            2           2m
+
+$ kubectl get pods -l run=snowflake
+NAME                         READY     STATUS    RESTARTS   AGE
+snowflake-3968820950-9dgr8   1/1       Running   0          2m
+snowflake-3968820950-vgc4n   1/1       Running   0          2m
+```
+
+And this is great, developers are able to do what they want, and they do not have to worry about affecting content in the production namespace.
+
+Let's switch to the production namespace and show how resources in one namespace are hidden from the other.
+
+```shell
+$ kubectl config use-context prod
+```
+
+The production namespace should be empty, and the following commands should return nothing.
+
+```shell
+$ kubectl get deployment
+$ kubectl get pods
+```
+
+Production likes to run cattle, so let's create some cattle pods.
+
+```shell
+$ kubectl run cattle --image=kubernetes/serve_hostname --replicas=5
+
+$ kubectl get deployment
+NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+cattle    5         5         5            5           10s
+
+kubectl get pods -l run=cattle
+NAME                      READY     STATUS    RESTARTS   AGE
+cattle-2263376956-41xy6   1/1       Running   0          34s
+cattle-2263376956-kw466   1/1       Running   0          34s
+cattle-2263376956-n4v97   1/1       Running   0          34s
+cattle-2263376956-p5p3i   1/1       Running   0          34s
+cattle-2263376956-sxpth   1/1       Running   0          34s
+```
+
+At this point, it should be clear that the resources users create in one namespace are hidden from the other namespace.
+
+As the policy support in Kubernetes evolves, we will extend this scenario to show how you can provide different
+authorization rules for each namespace.
+
+{% endcapture %}
+
+{% capture discussion %}
+
+## Understanding the motivation for using namespaces
+
+A single cluster should be able to satisfy the needs of multiple users or groups of users (henceforth a 'user community').
+
+Kubernetes _namespaces_ help different projects, teams, or customers to share a Kubernetes cluster.
+
+It does this by providing the following:
+
+1. A scope for [Names](/docs/concepts/overview/working-with-objects/names/).
+2. A mechanism to attach authorization and policy to a subsection of the cluster.
+
+Use of multiple namespaces is optional.
+
+Each user community wants to be able to work in isolation from other communities.
+
+Each user community has its own:
+
+1. resources (pods, services, replication controllers, etc.)
+2. policies (who can or cannot perform actions in their community)
+3. constraints (this community is allowed this much quota, etc.)
+
+A cluster operator may create a Namespace for each unique user community.
+
+The Namespace provides a unique scope for:
+
+1. named resources (to avoid basic naming collisions)
+2. delegated management authority to trusted users
+3. ability to limit community resource consumption
+
+Use cases include: 
+
+1.  As a cluster operator, I want to support multiple user communities on a single cluster.
+2.  As a cluster operator, I want to delegate authority to partitions of the cluster to trusted users
+    in those communities.
+3.  As a cluster operator, I want to limit the amount of resources each community can consume in order
+    to limit the impact to other communities using the cluster.
+4.  As a cluster user, I want to interact with resources that are pertinent to my user community in
+    isolation of what other user communities are doing on the cluster.
+
+## Understanding namespaces and DNS
+
+When you create a [Service](/docs/concepts/services-networking/service/), it creates a corresponding [DNS entry](/docs/admin/dns).
 This entry is of the form `<service-name>.<namespace-name>.svc.cluster.local`, which means
 that if a container just uses `<service-name>` it will resolve to the service which
 is local to a namespace.  This is useful for using the same configuration across
 multiple namespaces such as Development, Staging and Production.  If you want to reach
 across namespaces, you need to use the fully qualified domain name (FQDN).

-## Design
+{% endcapture %}

-Details of the design of namespaces in Kubernetes, including a [detailed example](https://git.k8s.io/community/contributors/design-proposals/namespaces.md#example-openshift-origin-managing-a-kubernetes-namespace)
-can be found in the [namespaces design doc](https://git.k8s.io/community/contributors/design-proposals/namespaces.md)
+{% capture whatsnext %}
+* Learn more about [setting the namespace preference](/docs/concepts/overview/working-with-objects/namespaces/#setting-the-namespace-preference).
+* Learn more about [setting the namespace for a request](/docs/concepts/overview/working-with-objects/namespaces/#setting-the-namespace-for-a-request)
+* See [namespaces design](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/namespaces.md).
+{% endcapture %}
+
+{% include templates/task.md %}
@@ -4,11 +4,6 @@ assignees:
 - vishh
 - timstclair
 title: Configure Out Of Resource Handling
-redirect_from:
- "/docs/admin/out-of-resource/"
- "/docs/admin/out-of-resource.html"
- "/docs/concepts/cluster-administration/out-of-resource/"
- "/docs/concepts/cluster-administration/out-of-resource.html"
 ---

 * TOC
--- a/Show More
+++ b/Show More