Merge branch 'master' into release-1.8

_data/reference.yml

@@ -88,16 +88,16 @@ toc:
 - title: Kubernetes Design Docs
   section:
   - title: Kubernetes Architecture
-    path: https://git.k8s.io/community/contributors/design-proposals/architecture.md
+    path: https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md
   - title: Kubernetes Design Overview
     path: https://github.com/kubernetes/kubernetes/tree/release-1.6/docs/design
   - title: Kubernetes Identity and Access Management
-    path: https://git.k8s.io/community/contributors/design-proposals/access.md
+    path: https://git.k8s.io/community/contributors/design-proposals/auth/access.md
   - docs/admin/ovs-networking.md
   - title: Security Contexts
-    path: https://git.k8s.io/community/contributors/design-proposals/security_context.md
+    path: https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md
   - title: Security in Kubernetes
-    path: https://git.k8s.io/community/contributors/design-proposals/security.md
+    path: https://git.k8s.io/community/contributors/design-proposals/auth/security.md
 
 - title: Kubernetes Issues and Security
   section:

cn/docs/concepts/architecture/nodes.md

@@ -18,7 +18,7 @@ redirect_from:
 ## Node 是什么？
 
 
-`Node` 是 Kubernetes 的工作节点，以前叫做 `minion`。取决于你的集群，Node 可以是一个虚拟机或者物理机器。每个 node 都有用于运行 [pods](/docs/user-guide/pods) 的必要服务，并由 master 组件管理。Node 上的服务包括 Docker、kubelet 和 kube-proxy。请查阅架构设计文档中 [The Kubernetes Node](https://git.k8s.io/community/contributors/design-proposals/architecture.md#the-kubernetes-node) 一节获取更多细节。
+`Node` 是 Kubernetes 的工作节点，以前叫做 `minion`。取决于你的集群，Node 可以是一个虚拟机或者物理机器。每个 node 都有用于运行 [pods](/docs/user-guide/pods) 的必要服务，并由 master 组件管理。Node 上的服务包括 Docker、kubelet 和 kube-proxy。请查阅架构设计文档中 [The Kubernetes Node](https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md#the-kubernetes-node) 一节获取更多细节。
 
 
 ## Node 状态

cn/docs/concepts/overview/what-is-kubernetes.md

@@ -93,7 +93,7 @@ Kubernetes 提供了很多的功能，总会有新的场景受益于新特性。
 
 此外，[Kubernetes 控制面 (Controll Plane)](/docs/admin/cluster-components) 是构建在相同的 [APIs](/docs/api/) 上面，开发人员和用户都可以用。用户可以编写自己的控制器， [调度器](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/scheduler.md)等等，如果这么做，根据新加的[自定义 API](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/extending-api.md) ，可以扩展当前的通用 [CLI 命令行工具](/docs/user-guide/kubectl-overview/)。
 
-这种 [设计](https://git.k8s.io/community/contributors/design-proposals/principles.md) 使得许多其他系统可以构建在 Kubernetes 之上。
+这种 [设计](https://git.k8s.io/community/contributors/design-proposals/architecture/principles.md) 使得许多其他系统可以构建在 Kubernetes 之上。
 
 #### Kubernetes 不是什么:
 

cn/docs/tasks/run-application/horizontal-pod-autoscale.md

@@ -44,7 +44,7 @@ or the custom metrics API (for all other metrics).
 
   Please note that if some of the pod's containers do not have the relevant resource request set,
   CPU utilization for the pod will not be defined and the autoscaler will not take any action
-  for that metric. See the [autoscaling algorithm design document](https://git.k8s.io/community/contributors/design-proposals/horizontal-pod-autoscaler.md#autoscaling-algorithm) for further
+  for that metric. See the [autoscaling algorithm design document](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md#autoscaling-algorithm) for further
   details about how the autoscaling algorithm works.
 
 * For per-pod custom metrics, the controller functions similarly to per-pod resource metrics,
@@ -64,7 +64,7 @@ See [Support for custom metrics](#support-for-custom-metrics) for more details o
 
 The autoscaler accesses corresponding replication controller, deployment or replica set by scale sub-resource.
 Scale is an interface that allows you to dynamically set the number of replicas and examine each of their current states.
-More details on scale sub-resource can be found [here](https://git.k8s.io/community/contributors/design-proposals/horizontal-pod-autoscaler.md#scale-subresource).
+More details on scale sub-resource can be found [here](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md#scale-subresource).
 
 
 ## API Object
@@ -78,7 +78,7 @@ can be found in `autoscaling/v2alpha1`. The new fields introduced in `autoscalin
 are preserved as annotations when working with `autoscaling/v1`.
 
 More details about the API object can be found at
-[HorizontalPodAutoscaler Object](https://git.k8s.io/community/contributors/design-proposals/horizontal-pod-autoscaler.md#horizontalpodautoscaler-object).
+[HorizontalPodAutoscaler Object](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md#horizontalpodautoscaler-object).
 
 ## Support for Horizontal Pod Autoscaler in kubectl
 
@@ -149,6 +149,6 @@ custom metrics API with the API aggregation layer. Both of these API servers mus
 
 ## Further reading
 
-* Design documentation: [Horizontal Pod Autoscaling](https://git.k8s.io/community/contributors/design-proposals/horizontal-pod-autoscaler.md).
+* Design documentation: [Horizontal Pod Autoscaling](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md).
 * kubectl autoscale command: [kubectl autoscale](/docs/user-guide/kubectl/v1.6/#autoscale).
 * Usage example of [Horizontal Pod Autoscaler](/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/).

cn/docs/tasks/run-application/rolling-update-replication-controller.md

@@ -12,7 +12,7 @@ title: 基于Replication Controller执行滚动升级
 **注**: 创建副本应用的首选方法是使用[Deployment](/docs/api-reference/{{page.version}}/#deployment-v1beta1-apps)，Deployment使用[ReplicaSet](/docs/api-reference/{{page.version}}/#replicaset-v1beta1-extensions)来进行副本控制。
 更多信息, 查看[使用Deployment运行一个无状态应用](/docs/tasks/run-application/run-stateless-application-deployment/)。
 
-为了在更新服务的同时不中断业务， `kubectl` 支持['滚动更新'](/docs/user-guide/kubectl/v1.6/#rolling-update)，它一次更新一个pod，而不是同时停止整个服务。 有关更多信息，请参阅 [滚动更新设计文档](https://git.k8s.io/community/contributors/design-proposals/simple-rolling-update.md) 和 [滚动更新示例](/docs/tasks/run-application/rolling-update-replication-controller/)。
+为了在更新服务的同时不中断业务， `kubectl` 支持['滚动更新'](/docs/user-guide/kubectl/v1.6/#rolling-update)，它一次更新一个pod，而不是同时停止整个服务。 有关更多信息，请参阅 [滚动更新设计文档](https://git.k8s.io/community/contributors/design-proposals/cli/simple-rolling-update.md) 和 [滚动更新示例](/docs/tasks/run-application/rolling-update-replication-controller/)。
 
 请注意， `kubectl rolling-update` 仅支持Replication Controllers。 但是，如果使用Replication Controllers部署应用，请考虑将其切换到[Deployments](/docs/concepts/workloads/controllers/deployment/). Deployment是一种被推荐使用的更高级别的控制器，它可以对应用进行声明性的自动滚动更新。 如果您仍然希望保留您的Replication Controllers并使用 `kubectl rolling-update`进行滚动更新， 请继续往下阅读：
 
@@ -123,7 +123,7 @@ spec:
         - containerPort: 80
 ```
 
-要更新到1.9.1版本，你可以使用[`kubectl rolling-update --image`](https://git.k8s.io/community/contributors/design-proposals/simple-rolling-update.md)来指定一个新的镜像：
+要更新到1.9.1版本，你可以使用[`kubectl rolling-update --image`](https://git.k8s.io/community/contributors/design-proposals/cli/simple-rolling-update.md)来指定一个新的镜像：
 
 ```shell
 $ kubectl rolling-update my-nginx --image=nginx:1.9.1

cn/docs/tasks/run-application/run-stateless-application-deployment.md

@@ -0,0 +1,143 @@
+---
+title: 使用Deployment运行一个无状态应用
+---
+
+{% capture overview %}
+
+本文介绍通过Kubernetes Deployment对象如何去运行一个应用.
+
+{% endcapture %}
+
+
+{% capture objectives %}
+
+* 创建一个nginx deployment.
+* 使用kubectl列举关于deployment信息.
+* 更新deployment.
+
+{% endcapture %}
+
+
+{% capture prerequisites %}
+
+{% include task-tutorial-prereqs.md %}
+
+{% endcapture %}
+
+
+{% capture lessoncontent %}
+
+## 创建和探究一个nginx deployment
+
+你可以通过创建一个Kubernetes Deployment对象来运行一个应用, 可以在一个YAML文件中描述Deployment. 例如, 下面这个YAML文件描述了一个运行nginx:1.7.9 Docker镜像的Deployment:
+
+{% include code.html language="yaml" file="deployment.yaml" ghlink="/cn/docs/tasks/run-application/deployment.yaml" %}
+
+
+1. 通过YAML文件创建一个Deployment:
+
+       kubectl create -f https://k8s.io/docs/tasks/run-application/deployment.yaml
+
+1. 展示Deployment相关信息:
+
+       kubectl describe deployment nginx-deployment
+
+        user@computer:~/kubernetes.github.io$ kubectl describe deployment nginx-deployment
+        Name:     nginx-deployment
+        Namespace:    default
+        CreationTimestamp:  Tue, 30 Aug 2016 18:11:37 -0700
+        Labels:     app=nginx
+        Annotations:    deployment.kubernetes.io/revision=1
+        Selector:   app=nginx
+        Replicas:   2 desired | 2 updated | 2 total | 2 available | 0 unavailable
+        StrategyType:   RollingUpdate
+        MinReadySeconds:  0
+        RollingUpdateStrategy:  1 max unavailable, 1 max surge
+        Pod Template:
+          Labels:       app=nginx
+          Containers:
+           nginx:
+            Image:              nginx:1.7.9
+            Port:               80/TCP
+            Environment:        <none>
+            Mounts:             <none>
+          Volumes:              <none>
+        Conditions:
+          Type          Status  Reason
+          ----          ------  ------
+          Available     True    MinimumReplicasAvailable
+          Progressing   True    NewReplicaSetAvailable
+        OldReplicaSets:   <none>
+        NewReplicaSet:    nginx-deployment-1771418926 (2/2 replicas created)
+        No events.
+
+1. 列出deployment创建的pods:
+
+       kubectl get pods -l app=nginx
+
+        NAME                                READY     STATUS    RESTARTS   AGE
+        nginx-deployment-1771418926-7o5ns   1/1       Running   0          16h
+        nginx-deployment-1771418926-r18az   1/1       Running   0          16h
+
+1. 展示某一个pod信息:
+
+       kubectl describe pod <pod-name>
+
+    该处 `<pod-name>` 指某一pod的名称.
+
+## 更新deployment
+
+你可以通过更新一个新的YAML文件来更新deployment. 下面的YAML文件指定该deployment镜像更新为nginx 1.8.
+
+{% include code.html language="yaml" file="deployment-update.yaml" ghlink="/cn/docs/tutorials/stateless-application/deployment-update.yaml" %}
+
+1. 应用新的YAML:
+
+       kubectl apply -f https://k8s.io/docs/tutorials/stateless-application/deployment-update.yaml
+
+1. 查看该deployment创建的pods以新的名称同时删除旧的pods:
+
+       kubectl get pods -l app=nginx
+
+## 通过增加副本数来弹缩应用
+
+你可以通过应用新的YAML文件来增加Deployment中pods的数量. 该YAML文件将`replicas`设置为4, 指定该Deployment应有4个pods:
+
+{% include code.html language="yaml" file="deployment-scale.yaml" ghlink="/cn/docs/tutorials/stateless-application/deployment-scale.yaml" %}
+
+1. 应用新的YAML文件:
+
+       kubectl apply -f https://k8s.io/docs/tutorials/stateless-application/deployment-scale.yaml
+
+1. 验证Deployment有4个pods:
+
+       kubectl get pods -l app=nginx
+
+    输出的结果类似于:
+
+        NAME                               READY     STATUS    RESTARTS   AGE
+        nginx-deployment-148880595-4zdqq   1/1       Running   0          25s
+        nginx-deployment-148880595-6zgi1   1/1       Running   0          25s
+        nginx-deployment-148880595-fxcez   1/1       Running   0          2m
+        nginx-deployment-148880595-rwovn   1/1       Running   0          2m
+
+## 删除deployment
+
+通过名称删除deployment:
+
+    kubectl delete deployment nginx-deployment
+
+## ReplicationControllers -- 旧的方式
+
+创建一个多副本应用首选方法是使用Deployment,反过来使用ReplicaSet. 在Deployment和ReplicaSet加入到Kubernetes之前, 多副本应用通过[ReplicationController](/docs/concepts/workloads/controllers/replicationcontroller/)来配置.
+
+{% endcapture %}
+
+
+{% capture whatsnext %}
+
+* 了解更多 [Deployment objects](/docs/concepts/workloads/controllers/deployment/).
+
+{% endcapture %}
+
+{% include templates/tutorial.md %}

docs/admin/authorization/index.md

@@ -135,3 +135,10 @@ As of version 1.3, clusters created by kube-up.sh are configured so that the A
 {% endcapture %}
 
 {% include templates/concept.md %}
+
+## Privilege escalation via pod creation
+
+Users who have ability to create pods in a namespace can potentially escalate their privileges within that namespace.  They can create pods that access secrets the user cannot themselves read, or that run under a service account with different/greater permissions.
+
+**Caution:** System administrators, use care when granting access to pod creation.  A user granted permission to create pods (or controllers that create pods) in the namespace can: read all secrets in the namespace; read all config maps in the namespace; and impersonate any service account in the namespace and take any action the account could take. This applies regardless of authorization mode.
+{: .caution}

docs/admin/bootstrap-tokens.md

@@ -57,7 +57,7 @@ Authorization: Bearer 07401b.f395accd246ae52d
 
 Each valid token is backed by a secret in the `kube-system` namespace.  You can
 find the full design doc
-[here](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/bootstrap-discovery.md).
+[here](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/cluster-lifecycle/bootstrap-discovery.md).
 
 Here is what the secret looks like.  Note that `base64(string)` indicates the
 value should be base64 encoded.  The undecoded version is provided here for

docs/admin/federation/index.md

@@ -385,4 +385,4 @@ if required.
 
 ## For more information
 
- * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation.md) details use cases that motivated this work.
+ * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation/federation.md) details use cases that motivated this work.

docs/admin/kubelet.md

@@ -70,7 +70,7 @@ kubelet
       --enable-custom-metrics                                   Support for gathering custom metrics.
       --enable-debugging-handlers                               Enables server endpoints for log collection and local running of containers and commands (default true)
       --enable-server                                           Enable the Kubelet's server (default true)
-      --enforce-node-allocatable stringSlice                    A comma separated list of levels of node allocatable enforcement to be enforced by kubelet. Acceptable options are 'pods', 'system-reserved' & 'kube-reserved'. If the latter two options are specified, '--system-reserved-cgroup' & '--kube-reserved-cgroup' must also be set respectively. See https://git.k8s.io/community/contributors/design-proposals/node-allocatable.md for more details. (default [pods])
+      --enforce-node-allocatable stringSlice                    A comma separated list of levels of node allocatable enforcement to be enforced by kubelet. Acceptable options are 'pods', 'system-reserved' & 'kube-reserved'. If the latter two options are specified, '--system-reserved-cgroup' & '--kube-reserved-cgroup' must also be set respectively. See https://git.k8s.io/community/contributors/design-proposals/node/node-allocatable.md for more details. (default [pods])
       --event-burst int32                                       Maximum size of a bursty event records, temporarily allows event records to burst to this number, while still not exceeding event-qps. Only used if --event-qps > 0 (default 10)
       --event-qps int32                                         If > 0, limit event creations per second to this value. If 0, unlimited. (default 5)
       --eviction-hard string                                    A set of eviction thresholds (e.g. memory.available<1Gi) that if met would trigger a pod eviction. (default "memory.available<100Mi,nodefs.available<10%,nodefs.inodesFree<5%")
@@ -80,7 +80,7 @@ kubelet
       --eviction-soft string                                    A set of eviction thresholds (e.g. memory.available<1.5Gi) that if met over a corresponding grace period would trigger a pod eviction.
       --eviction-soft-grace-period string                       A set of eviction grace periods (e.g. memory.available=1m30s) that correspond to how long a soft eviction threshold must hold before triggering a pod eviction.
       --exit-on-lock-contention                                 Whether kubelet should exit upon lock-file contention.
-      --experimental-allocatable-ignore-eviction                When set to 'true', Hard Eviction Thresholds will be ignored while calculating Node Allocatable. See https://git.k8s.io/community/contributors/design-proposals/node-allocatable.md for more details. [default=false]
+      --experimental-allocatable-ignore-eviction                When set to 'true', Hard Eviction Thresholds will be ignored while calculating Node Allocatable. See https://git.k8s.io/community/contributors/design-proposals/node/node-allocatable.md for more details. [default=false]
       --experimental-allowed-unsafe-sysctls stringSlice         Comma-separated whitelist of unsafe sysctls or unsafe sysctl patterns (ending in *). Use these at your own risk.
       --experimental-bootstrap-kubeconfig string                deprecated: use --bootstrap-kubeconfig
       --experimental-check-node-capabilities-before-mount       [Experimental] if set true, the kubelet will check the underlying node for required componenets (binaries, etc.) before performing the mount

docs/admin/multiple-zones.md

@@ -11,7 +11,7 @@ title: Running in Multiple Zones
 Kubernetes 1.2 adds support for running a single cluster in multiple failure zones
 (GCE calls them simply "zones", AWS calls them "availability zones", here we'll refer to them as "zones").
 This is a lightweight version of a broader Cluster Federation feature (previously referred to by the affectionate
-nickname ["Ubernetes"](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/federation.md)).
+nickname ["Ubernetes"](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/federation/federation.md)).
 Full Cluster Federation allows combining separate
 Kubernetes clusters running in different regions or cloud providers
 (or on-premises data centers).  However, many

docs/api-reference/v1.6/index.html

@@ -7918,7 +7918,7 @@ Appears In <a href="#pod-v1-core">Pod</a> </aside>
 </tr>
 <tr>
 <td>qosClass <br /> <em>string</em></td>
-<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://git.k8s.io/community/contributors/design-proposals/resource-qos.md">https://git.k8s.io/community/contributors/design-proposals/resource-qos.md</a></td>
+<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md">https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md</a></td>
 </tr>
 <tr>
 <td>reason <br /> <em>string</em></td>

docs/api-reference/v1.7/index.html

@@ -191,7 +191,7 @@ Appears In:
 </tr>
 <tr>
 <td>securityContext <br /> <em><a href="#securitycontext-v1-core">SecurityContext</a></em></td>
-<td>Security options the pod should run with. More info: <a href="https://kubernetes.io/docs/concepts/policy/security-context/">https://kubernetes.io/docs/concepts/policy/security-context/</a> More info: <a href="https://git.k8s.io/community/contributors/design-proposals/security_context.md">https://git.k8s.io/community/contributors/design-proposals/security_context.md</a></td>
+<td>Security options the pod should run with. More info: <a href="https://kubernetes.io/docs/concepts/policy/security-context/">https://kubernetes.io/docs/concepts/policy/security-context/</a> More info: <a href="https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md">https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md</a></td>
 </tr>
 <tr>
 <td>stdin <br /> <em>boolean</em></td>
@@ -5951,7 +5951,7 @@ Appears In:
 </tr>
 <tr>
 <td>manualSelector <br /> <em>boolean</em></td>
-<td>manualSelector controls generation of pod labels and pod selectors. Leave <code>manualSelector</code> unset unless you are certain what you are doing. When false or unset, the system pick labels unique to this job and appends those labels to the pod template.  When true, the user is responsible for picking unique labels and specifying the selector.  Failure to pick a unique label may cause this and other jobs to not function correctly.  However, You may see <code>manualSelector=true</code> in jobs that were created with the old <code>extensions/v1beta1</code> API. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/selector-generation.md">https://git.k8s.io/community/contributors/design-proposals/selector-generation.md</a></td>
+<td>manualSelector controls generation of pod labels and pod selectors. Leave <code>manualSelector</code> unset unless you are certain what you are doing. When false or unset, the system pick labels unique to this job and appends those labels to the pod template.  When true, the user is responsible for picking unique labels and specifying the selector.  Failure to pick a unique label may cause this and other jobs to not function correctly.  However, You may see <code>manualSelector=true</code> in jobs that were created with the old <code>extensions/v1beta1</code> API. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/apps/selector-generation.md">https://git.k8s.io/community/contributors/design-proposals/apps/selector-generation.md</a></td>
 </tr>
 <tr>
 <td>parallelism <br /> <em>integer</em></td>
@@ -8018,7 +8018,7 @@ Appears In:
 </tr>
 <tr>
 <td>qosClass <br /> <em>string</em></td>
-<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://github.com/kubernetes/community/blob/master/contributors/design-proposals/resource-qos.md">https://github.com/kubernetes/community/blob/master/contributors/design-proposals/resource-qos.md</a></td>
+<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/resource-qos.md">https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/resource-qos.md</a></td>
 </tr>
 <tr>
 <td>reason <br /> <em>string</em></td>
@@ -41943,7 +41943,7 @@ Appears In:
 <tbody>
 <tr>
 <td>finalizers <br /> <em>string array</em></td>
-<td>Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers">https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers</a></td>
+<td>Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers">https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers</a></td>
 </tr>
 </tbody>
 </table>
@@ -41965,7 +41965,7 @@ Appears In:
 <tbody>
 <tr>
 <td>phase <br /> <em>string</em></td>
-<td>Phase is the current lifecycle phase of the namespace. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases">https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases</a></td>
+<td>Phase is the current lifecycle phase of the namespace. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases">https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases</a></td>
 </tr>
 </tbody>
 </table>
@@ -59749,7 +59749,7 @@ Appears In:
 </tr>
 <tr>
 <td>seLinuxOptions <br /> <em><a href="#selinuxoptions-v1-core">SELinuxOptions</a></em></td>
-<td>seLinuxOptions required to run as; required for MustRunAs More info: <a href="https://git.k8s.io/community/contributors/design-proposals/security_context.md">https://git.k8s.io/community/contributors/design-proposals/security_context.md</a></td>
+<td>seLinuxOptions required to run as; required for MustRunAs More info: <a href="https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md">https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md</a></td>
 </tr>
 </tbody>
 </table>

docs/concepts/architecture/nodes.md

@@ -14,7 +14,7 @@ A `node` is a worker machine in Kubernetes, previously known as a `minion`. A no
 may be a VM or physical machine, depending on the cluster. Each node has
 the services necessary to run [pods](/docs/user-guide/pods) and is managed by the master
 components. The services on a node include Docker, kubelet and kube-proxy. See
-[The Kubernetes Node](https://git.k8s.io/community/contributors/design-proposals/architecture.md#the-kubernetes-node) section in the
+[The Kubernetes Node](https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md#the-kubernetes-node) section in the
 architecture design doc for more details.
 
 ## Node Status

docs/concepts/cluster-administration/federation.md

@@ -170,7 +170,7 @@ you may need even more clusters.  Kubernetes v1.3 supports clusters up to 1000 n
 
 {% capture whatsnext %}
 * Learn more about the [Federation
-  proposal](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/federation.md).
+  proposal](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/federation/federation.md).
 * See this [setup guide](/docs/tutorials/federation/set-up-cluster-federation-kubefed/) for cluster federation.
 * See this [Kubecon2016 talk on federation](https://www.youtube.com/watch?v=pq9lbkmxpS8)
 {% endcapture %}

docs/concepts/cluster-administration/networking.md

@@ -234,4 +234,4 @@ CNI-Genie also supports [assigning multiple IP addresses to a pod](https://githu
 
 The early design of the networking model and its rationale, and some future
 plans are described in more detail in the [networking design
-document](https://git.k8s.io/community/contributors/design-proposals/networking.md).
+document](https://git.k8s.io/community/contributors/design-proposals/network/networking.md).

docs/concepts/configuration/assign-pod-node.md

@@ -6,9 +6,9 @@ approvers:
 title: Assigning Pods to Nodes
 ---
 
-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
+You can constrain a [pod](/docs/concepts/workloads/pods/pod/) to only be able to run on particular [nodes](/docs/concepts/architecture/nodes/) or to prefer to
 run on particular nodes. There are several ways to do this, and they all use
-[label selectors](/docs/user-guide/labels/) to make the selection.
+[label selectors](/docs/concepts/overview/working-with-objects/labels/) to make the selection.
 Generally such constraints are unnecessary, as the scheduler will automatically do a reasonable placement
 (e.g. spread your pods across nodes, not place the pod on a node with insufficient free resources, etc.)
 but there are some circumstances where you may want more control on a node where a pod lands, e.g. to ensure
@@ -40,7 +40,7 @@ Run `kubectl get nodes` to get the names of your cluster's nodes. Pick out the o
 
 If this fails with an "invalid command" error, you're likely using an older version of kubectl that doesn't have the `label` command. In that case, see the [previous version](https://github.com/kubernetes/kubernetes/blob/a053dbc313572ed60d89dae9821ecab8bfd676dc/examples/node-selection/README.md) of this guide for instructions on how to manually set labels on a node.
 
-Also, note that label keys must be in the form of DNS labels (as described in the [identifiers doc](https://git.k8s.io/community/contributors/design-proposals/identifiers.md)), meaning that they are not allowed to contain any upper-case letters.
+Also, note that label keys must be in the form of DNS labels (as described in the [identifiers doc](https://git.k8s.io/community/contributors/design-proposals/architecture/identifiers.md)), meaning that they are not allowed to contain any upper-case letters.
 
 You can verify that it worked by re-running `kubectl get nodes --show-labels` and checking that the node now has a label.
 
@@ -142,7 +142,7 @@ If you specify multiple `matchExpressions` associated with `nodeSelectorTerms`,
 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).
+[here](https://git.k8s.io/community/contributors/design-proposals/scheduling/nodeaffinity.md).
 
 ### Inter-pod affinity and anti-affinity (beta feature)
 
@@ -183,7 +183,7 @@ value V that is running a pod that has a label with key "security" and value "S1
 rule says that the pod prefers to not schedule onto a node if that node is already running a pod with label
 having key "security" and value "S2". (If the `topologyKey` were `failure-domain.beta.kubernetes.io/zone` then
 it would mean that the pod cannot schedule onto a node if that node is in the same zone as a pod with
-label having key "security" and value "S2".) See the [design doc](https://git.k8s.io/community/contributors/design-proposals/podaffinity.md).
+label having key "security" and value "S2".) See the [design doc](https://git.k8s.io/community/contributors/design-proposals/scheduling/podaffinity.md).
 for many more examples of pod affinity and anti-affinity, both the `requiredDuringSchedulingIgnoredDuringExecution`
 flavor and the `preferredDuringSchedulingIgnoredDuringExecution` flavor.
 
@@ -206,15 +206,15 @@ 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.
 
-#### More Practical Use-cases 
+#### More Practical Use-cases
 
 Interpod Affinity and AnitAffinity can be even more useful when they are used with higher
 level collections such as ReplicaSets, Statefulsets, Deployments, etc.  One can easily configure that a set of workloads should
-be co-located in the same defined topology, eg., the same node. 
+be co-located in the same defined topology, eg., the same node.
 
 ##### Always co-located in the same node
 
-In a three node cluster, a web application has in-memory cache such as redis. We want the web-servers to be co-located with the cache as much as possible. 
+In a three node cluster, a web application has in-memory cache such as redis. We want the web-servers to be co-located with the cache as much as possible.
 Here is the yaml snippet of a simple redis deployment with three replicas and selector label `app=store`
 
 ```yaml
@@ -234,8 +234,8 @@ spec:
         image: redis:3.2-alpine
 ```
 
-Below yaml snippet of the webserver deployment has `podAffinity` configured, this informs the scheduler that all its replicas are to be 
+Below yaml snippet of the webserver deployment has `podAffinity` configured, this informs the scheduler that all its replicas are to be
-co-located with pods that has selector label `app=store` 
+co-located with pods that has selector label `app=store`
 
 ```yaml
 apiVersion: apps/v1beta1 # for versions before 1.6.0 use extensions/v1beta1
@@ -270,7 +270,7 @@ if we create the above two deployments, our three node cluster could look like b
 | *webserver-1*        |   *webserver-2*     |    *webserver-3*   |
 |  *cache-1*           |     *cache-2*       |     *cache-3*      |
 
-As you can see, all the 3 replicas of the `web-server` are automatically co-located with the cache as expected. 
+As you can see, all the 3 replicas of the `web-server` are automatically co-located with the cache as expected.
 
 ```
 $kubectl get pods -o wide
@@ -296,7 +296,7 @@ Highly Available database statefulset has one master and three replicas, one may
 [Here](https://kubernetes.io/docs/tutorials/stateful-application/zookeeper/#tolerating-node-failure) is an example of zookeper statefulset configured with anti-affinity for high availability.
 
 For more information on inter-pod affinity/anti-affinity, see the design doc
-[here](https://git.k8s.io/community/contributors/design-proposals/podaffinity.md).
+[here](https://git.k8s.io/community/contributors/design-proposals/scheduling/podaffinity.md).
 
 You may want to check [Taints](/docs/concepts/configuration/taint-and-toleration/)
 as well, which allow a *node* to *repel* a set of pods.

docs/concepts/configuration/manage-compute-resources-container.md

@@ -10,7 +10,7 @@ requests specified, the scheduler can make better decisions about which nodes to
 place Pods on. And when Containers have their limits specified, contention for
 resources on a node can be handled in a specified manner. For more details about
 the difference between requests and limits, see
-[Resource QoS](https://git.k8s.io/community/contributors/design-proposals/resource-qos.md).
+[Resource QoS](https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md).
 
 {% endcapture %}
 
@@ -238,7 +238,7 @@ The amount of resources available to Pods is less than the node capacity, becaus
 system daemons use a portion of the available resources. The `allocatable` field
 [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).
+[Node Allocatable Resources](https://git.k8s.io/community/contributors/design-proposals/node/node-allocatable.md).
 
 The [resource quota](/docs/concepts/policy/resource-quotas/) feature can be configured
 to limit the total amount of resources that can be consumed. If used in conjunction
@@ -541,7 +541,7 @@ all Containers in a Pod, such as
 Kubernetes version 1.5 only supports Container requests and limits for CPU and
 memory. It is planned to add new resource types, including a node disk space
 resource, and a framework for adding custom
-[resource types](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/resources.md).
+[resource types](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/scheduling/resources.md).
 
 Kubernetes supports overcommitment of resources by supporting multiple levels of
 [Quality of Service](http://issue.k8s.io/168).

docs/concepts/overview/kubernetes-api.md

@@ -28,7 +28,7 @@ Complete API details are documented using [Swagger v1.2](http://swagger.io/) and
 
 Starting with Kubernetes 1.4, OpenAPI spec is also available at [`/swagger.json`](https://git.k8s.io/kubernetes/api/openapi-spec/swagger.json). While we are transitioning from Swagger v1.2 to OpenAPI (aka Swagger v2.0), some of the tools such as kubectl and swagger-ui are still using v1.2 spec. OpenAPI spec is in Beta as of Kubernetes 1.5.
 
-Kubernetes implements an alternative Protobuf based serialization format for the API that is primarily intended for intra-cluster communication, documented in the [design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/protobuf.md) and the IDL files for each schema are located in the Go packages that define the API objects.
+Kubernetes implements an alternative Protobuf based serialization format for the API that is primarily intended for intra-cluster communication, documented in the [design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md) and the IDL files for each schema are located in the Go packages that define the API objects.
 
 ## API versioning
 
@@ -102,5 +102,5 @@ to pick up the `--runtime-config` changes.
 
 DaemonSets, Deployments, HorizontalPodAutoscalers, Ingress, Jobs and ReplicaSets are enabled by default.
 Other extensions resources can be enabled by setting `--runtime-config` on
-apiserver. `--runtime-config` accepts comma separated values. For ex: to disable deployments and ingress, set
+apiserver. `--runtime-config` accepts comma separated values. For example: to disable deployments and ingress, set
 `--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/ingress=false`

docs/concepts/overview/what-is-kubernetes.md

@@ -91,7 +91,7 @@ Even though Kubernetes provides a lot of functionality, there are always new sce
 
 [Labels](/docs/concepts/overview/working-with-objects/labels/) empower users to organize their resources however they please. [Annotations](/docs/concepts/overview/working-with-objects/annotations/) enable users to decorate resources with custom information to facilitate their workflows and provide an easy way for management tools to checkpoint state.
 
-Additionally, the [Kubernetes control plane](/docs/concepts/overview/components/) is built upon the same [APIs](/docs/reference/api-overview/) that are available to developers and users. Users can write their own controllers, such as [schedulers](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/devel/scheduler.md), with [their own APIs](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/extending-api.md) that can be targeted by a general-purpose [command-line tool](/docs/user-guide/kubectl-overview/).
+Additionally, the [Kubernetes control plane](/docs/concepts/overview/components/) is built upon the same [APIs](/docs/reference/api-overview/) that are available to developers and users. Users can write their own controllers, such as [schedulers](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/devel/scheduler.md), with [their own APIs](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/api-machinery/extending-api.md) that can be targeted by a general-purpose [command-line tool](/docs/user-guide/kubectl-overview/).
 
 This [design](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/architecture/principles.md) has enabled a number of other systems to build atop Kubernetes.
 

docs/concepts/overview/working-with-objects/names.md

@@ -11,7 +11,7 @@ For non-unique user-provided attributes, Kubernetes provides [labels](/docs/user
 
 ## Names
 
-Names are generally client-provided.  Only one object of a given kind can have a given name at a time (i.e., they are spatially unique).  But if you delete an object, you can make a new object with the same name.  Names are used to refer to an object in a resource URL, such as `/api/v1/pods/some-name`.   By convention, the names of Kubernetes resources should be up to maximum length of 253 characters and consist of lower case alphanumeric characters, `-`, and `.`, but certain resources have more specific restrictions.  See the [identifiers design doc](https://git.k8s.io/community/contributors/design-proposals/identifiers.md) for the precise syntax rules for names.
+Names are generally client-provided.  Only one object of a given kind can have a given name at a time (i.e., they are spatially unique).  But if you delete an object, you can make a new object with the same name.  Names are used to refer to an object in a resource URL, such as `/api/v1/pods/some-name`.   By convention, the names of Kubernetes resources should be up to maximum length of 253 characters and consist of lower case alphanumeric characters, `-`, and `.`, but certain resources have more specific restrictions.  See the [identifiers design doc](https://git.k8s.io/community/contributors/design-proposals/architecture/identifiers.md) for the precise syntax rules for names.
 
 ## UIDs
 

docs/concepts/policy/pod-security-policy.md

@@ -8,7 +8,7 @@ Objects of type `PodSecurityPolicy` govern the ability
 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.
+See [PodSecurityPolicy proposal](https://git.k8s.io/community/contributors/design-proposals/auth/security-context-constraints.md) for more information.
 
 * TOC
 {:toc}

docs/concepts/policy/psp.yaml

@@ -16,3 +16,5 @@ spec:
     max: 8080
   volumes:
   - '*'
+  allowedCapabilities:
+  - '*'

docs/concepts/services-networking/ingress.md

@@ -105,7 +105,7 @@ NAME                RULE          BACKEND        ADDRESS
 test-ingress        -             testsvc:80     107.178.254.228
 ```
 
-Where `107.178.254.228` is the IP allocated by the Ingress controller to satisfy this Ingress. The `RULE` column shows that all traffic send to the IP is directed to the Kubernetes Service listed under `BACKEND`.
+Where `107.178.254.228` is the IP allocated by the Ingress controller to satisfy this Ingress. The `RULE` column shows that all traffic sent to the IP is directed to the Kubernetes Service listed under `BACKEND`.
 
 ### Simple fanout
 
@@ -239,7 +239,7 @@ test      -                       178.91.123.132
 $ kubectl edit ing test
 ```
 
-This should pop up an editor with the existing yaml, modify it to include the new Host.
+This should pop up an editor with the existing yaml, modify it to include the new Host:
 
 ```yaml
 spec:
@@ -261,7 +261,7 @@ spec:
 ..
 ```
 
-saving it will update the resource in the API server, which should tell the Ingress controller to reconfigure the loadbalancer.
+Saving it will update the resource in the API server, which should tell the Ingress controller to reconfigure the loadbalancer.
 
 ```shell
 $ kubectl get ing

docs/concepts/storage/persistent-volumes.md

@@ -160,7 +160,7 @@ Each PV contains a spec and status, which is the specification and status of the
 
 ### Capacity
 
-Generally, a PV will have a specific storage capacity.  This is set using the PV's `capacity` attribute.  See the Kubernetes [Resource Model](https://git.k8s.io/community/contributors/design-proposals/resources.md) to understand the units expected by `capacity`.
+Generally, a PV will have a specific storage capacity.  This is set using the PV's `capacity` attribute.  See the Kubernetes [Resource Model](https://git.k8s.io/community/contributors/design-proposals/scheduling/resources.md) to understand the units expected by `capacity`.
 
 Currently, storage size is the only resource that can be set or requested.  Future attributes may include IOPS, throughput, etc.
 
@@ -297,7 +297,7 @@ Claims use the same conventions as volumes when requesting storage with specific
 
 ### Resources
 
-Claims, like pods, can request specific quantities of a resource.  In this case, the request is for storage.  The same [resource model](https://git.k8s.io/community/contributors/design-proposals/resources.md) applies to both volumes and claims.
+Claims, like pods, can request specific quantities of a resource.  In this case, the request is for storage.  The same [resource model](https://git.k8s.io/community/contributors/design-proposals/scheduling/resources.md) applies to both volumes and claims.
 
 ### Selector
 
@@ -433,7 +433,7 @@ for provisioning PVs. This field must be specified.
 You are not restricted to specifying the "internal" provisioners
 listed here (whose names are prefixed with "kubernetes.io" and shipped
 alongside Kubernetes). You can also run and specify external provisioners,
-which are independent programs that follow a [specification](https://git.k8s.io/community/contributors/design-proposals/volume-provisioning.md)
+which are independent programs that follow a [specification](https://git.k8s.io/community/contributors/design-proposals/storage/volume-provisioning.md)
 defined by Kubernetes. Authors of external provisioners have full discretion
 over where their code lives, how the provisioner is shipped, how it needs to be
 run, what volume plugin it uses (including Flex), etc. The repository [kubernetes-incubator/external-storage](https://github.com/kubernetes-incubator/external-storage)

docs/concepts/storage/volumes.md

@@ -466,7 +466,7 @@ Currently, the following types of volume sources can be projected:
 - [`downwardAPI`](#downardapi)
 - `configMap`
 
-All sources are required to be in the same namespace as the pod. For more details, see the [all-in-one volume design document](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md).
+All sources are required to be in the same namespace as the pod. For more details, see the [all-in-one volume design document](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/node/all-in-one-volume.md).
 
 #### Example pod with a secret, a downward API, and a configmap.
 

docs/concepts/workloads/controllers/garbage-collection.md

@@ -163,9 +163,9 @@ Tracked at [#26120](https://github.com/kubernetes/kubernetes/issues/26120)
 
 {% capture whatsnext %}
 
-[Design Doc 1](https://git.k8s.io/community/contributors/design-proposals/garbage-collection.md)
+[Design Doc 1](https://git.k8s.io/community/contributors/design-proposals/api-machinery/garbage-collection.md)
 
-[Design Doc 2](https://git.k8s.io/community/contributors/design-proposals/synchronous-garbage-collection.md)
+[Design Doc 2](https://git.k8s.io/community/contributors/design-proposals/api-machinery/synchronous-garbage-collection.md)
 
 {% endcapture %}
 

docs/getting-started-guides/fedora/fedora_ansible_config.md

@@ -69,7 +69,7 @@ If you already are running on a machine which has passwordless ssh access to the
 
 *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/inventory/group_vars/all.yml
+edit: `~/contrib/ansible/inventory/group_vars/all.yml`
 
 ```yaml
 ansible_ssh_user: root

docs/getting-started-guides/minikube.md

@@ -318,7 +318,7 @@ $ export no_proxy=$no_proxy,$(minikube ip)
 
 Minikube uses [libmachine](https://github.com/docker/machine/tree/master/libmachine) for provisioning VMs, and [localkube](https://git.k8s.io/minikube/pkg/localkube) (originally written and donated to this project by [RedSpread](https://redspread.com/)) for running the cluster.
 
-For more information about minikube, see the [proposal](https://git.k8s.io/community/contributors/design-proposals/local-cluster-ux.md).
+For more information about minikube, see the [proposal](https://git.k8s.io/community/contributors/design-proposals/cluster-lifecycle/local-cluster-ux.md).
 
 ## Additional Links:
 * **Goals and Non-Goals**: For the goals and non-goals of the minikube project, please see our [roadmap](https://git.k8s.io/minikube/docs/contributors/roadmap.md).

docs/getting-started-guides/rkt/notes.md

@@ -67,7 +67,7 @@ Exponential restart back-off for a failing container is currently not supported.
 
 ## Experimental NVIDIA GPU support
 
-The `--experimental-nvidia-gpus` flag, and related [GPU features](https://git.k8s.io/community/contributors/design-proposals/gpu-support.md) are not supported.
+The `--experimental-nvidia-gpus` flag, and related [GPU features](https://git.k8s.io/community/contributors/design-proposals/resource-management/gpu-support.md) are not supported.
 
 ## QoS Classes
 

docs/getting-started-guides/vsphere.md

@@ -56,18 +56,18 @@ For each of the virtual machine nodes that will be participating in the cluster,
 
 * Set up GOVC environment
 
-        export GOVC_URL='vCenter IP OR FQDN'
+      export GOVC_URL='vCenter IP OR FQDN'
-        export GOVC_USERNAME='vCenter User'
+      export GOVC_USERNAME='vCenter User'
-        export GOVC_PASSWORD='vCenter Password'
+      export GOVC_PASSWORD='vCenter Password'
-        export GOVC_INSECURE=1
+      export GOVC_INSECURE=1
 
 * Find Node VM Paths
 
-        govc ls /datacenter/vm/<vm-folder-name>
+      govc ls /datacenter/vm/<vm-folder-name>
 
 * Set disk.EnableUUID to true for all VMs
 
-        govc vm.change -e="disk.enableUUID=1" -vm='VM Path'
+      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.
 
@@ -197,7 +197,7 @@ Please visit [known issues](https://vmware.github.io/vsphere-storage-for-kuberne
 
 ## Support Level
 
-For quick support please join VMware Code Slack ([#kubernetes](https://vmwarecode.slack.com/messages/kubernetes/)) and post your question.
+For quick support please join VMware Code Slack ([kubernetes](https://vmwarecode.slack.com/messages/kubernetes/)) and post your question.
 
 IaaS Provider        | Config. Mgmt | OS     | Networking | Docs                                          | Conforms  | Support Level
 -------------------- | ------------ | ------ | ---------- | --------------------------------------------- | --------- | ----------------------------

docs/reference/api-overview.md

@@ -33,7 +33,7 @@ multiple API versions, each at a different API path, such as `/api/v1` or
 The version is set at the API level rather than at the resource or field level to ensure that the API presents a clear, consistent view of system resources and behavior, and to enable controlling access to end-of-life and/or experimental APIs. The JSON and Protobuf serialization schemas follow the same guidelines for schema changes; all descriptions below cover both formats.
 
 Note that API versioning and software versioning are only indirectly related.  The [API and release
-versioning proposal](https://git.k8s.io/community/contributors/design-proposals/versioning.md) describes the relationship between API versioning and software versioning.
+versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) describes the relationship between API versioning and software versioning.
 
 Different API versions imply different levels of stability and support.  The criteria for each level are described
 in more detail in the [API Changes documentation](https://git.k8s.io/community/contributors/devel/api_changes.md#alpha-beta-and-stable-versions).  
@@ -60,7 +60,7 @@ The criteria are summarized here:
 
 ## API groups
 
-[*API groups*](https://git.k8s.io/community/contributors/design-proposals/api-group.md) make it easier to extend the Kubernetes API. The API group is specified in a REST path and in the `apiVersion` field of a serialized object.
+[*API groups*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md) make it easier to extend the Kubernetes API. The API group is specified in a REST path and in the `apiVersion` field of a serialized object.
 
 Currently, there are several API groups in use:
 
@@ -73,7 +73,7 @@ There are two supported paths to extending the API with [custom resources](/docs
 1. [CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
    is for users with very basic CRUD needs.
 1. Coming soon: users needing the full set of Kubernetes API semantics can implement their own apiserver
-   and use the [aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/aggregated-api-servers.md)
+   and use the [aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md)
    to make it seamless for clients.
  
 

docs/reference/federation/extensions/v1beta1/definitions.html

@@ -5778,7 +5778,7 @@ Both these may change in the future. Incoming requests are matched against the h
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">securityContext</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Security options the pod should run with. More info: <a href="https://kubernetes.io/docs/concepts/policy/security-context/">https://kubernetes.io/docs/concepts/policy/security-context/</a> More info: <a href="https://git.k8s.io/community/contributors/design-proposals/security_context.md">https://git.k8s.io/community/contributors/design-proposals/security_context.md</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Security options the pod should run with. More info: <a href="https://kubernetes.io/docs/concepts/policy/security-context/">https://kubernetes.io/docs/concepts/policy/security-context/</a> More info: <a href="https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md">https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md</a></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_v1_securitycontext">v1.SecurityContext</a></p></td>
 <td class="tableblock halign-left valign-top"></td>

docs/reference/federation/v1/definitions.html

@@ -1096,7 +1096,7 @@ span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }
 <tbody>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">phase</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Phase is the current lifecycle phase of the namespace. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases">https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Phase is the current lifecycle phase of the namespace. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases">https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases</a></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td>
 <td class="tableblock halign-left valign-top"></td>
@@ -1185,7 +1185,7 @@ span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }
 <tbody>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">finalizers</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers">https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers">https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers</a></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_v1_finalizername">v1.FinalizerName</a> array</p></td>
 <td class="tableblock halign-left valign-top"></td>

docs/resources-reference/v1.6/index.html

@@ -1217,7 +1217,7 @@ Appears In <a href="#pod-v1-core">Pod</a> </aside>
 </tr>
 <tr>
 <td>qosClass <br /> <em>string</em></td>
-<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://git.k8s.io/community/contributors/design-proposals/resource-qos.md">https://git.k8s.io/community/contributors/design-proposals/resource-qos.md</a></td>
+<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md">https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md</a></td>
 </tr>
 <tr>
 <td>reason <br /> <em>string</em></td>

docs/resources-reference/v1.7/index.html

@@ -124,7 +124,7 @@ Appears In:
 </tr>
 <tr>
 <td>securityContext <br /> <em><a href="#securitycontext-v1-core">SecurityContext</a></em></td>
-<td>Security options the pod should run with. More info: <a href="https://kubernetes.io/docs/concepts/policy/security-context/">https://kubernetes.io/docs/concepts/policy/security-context/</a> More info: <a href="https://git.k8s.io/community/contributors/design-proposals/security_context.md">https://git.k8s.io/community/contributors/design-proposals/security_context.md</a></td>
+<td>Security options the pod should run with. More info: <a href="https://kubernetes.io/docs/concepts/policy/security-context/">https://kubernetes.io/docs/concepts/policy/security-context/</a> More info: <a href="https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md">https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md</a></td>
 </tr>
 <tr>
 <td>stdin <br /> <em>boolean</em></td>
@@ -997,7 +997,7 @@ Appears In:
 </tr>
 <tr>
 <td>manualSelector <br /> <em>boolean</em></td>
-<td>manualSelector controls generation of pod labels and pod selectors. Leave <code>manualSelector</code> unset unless you are certain what you are doing. When false or unset, the system pick labels unique to this job and appends those labels to the pod template.  When true, the user is responsible for picking unique labels and specifying the selector.  Failure to pick a unique label may cause this and other jobs to not function correctly.  However, You may see <code>manualSelector=true</code> in jobs that were created with the old <code>extensions/v1beta1</code> API. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/selector-generation.md">https://git.k8s.io/community/contributors/design-proposals/selector-generation.md</a></td>
+<td>manualSelector controls generation of pod labels and pod selectors. Leave <code>manualSelector</code> unset unless you are certain what you are doing. When false or unset, the system pick labels unique to this job and appends those labels to the pod template.  When true, the user is responsible for picking unique labels and specifying the selector.  Failure to pick a unique label may cause this and other jobs to not function correctly.  However, You may see <code>manualSelector=true</code> in jobs that were created with the old <code>extensions/v1beta1</code> API. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/apps/selector-generation.md">https://git.k8s.io/community/contributors/design-proposals/apps/selector-generation.md</a></td>
 </tr>
 <tr>
 <td>parallelism <br /> <em>integer</em></td>
@@ -1315,7 +1315,7 @@ Appears In:
 </tr>
 <tr>
 <td>qosClass <br /> <em>string</em></td>
-<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://github.com/kubernetes/community/blob/master/contributors/design-proposals/resource-qos.md">https://github.com/kubernetes/community/blob/master/contributors/design-proposals/resource-qos.md</a></td>
+<td>The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: <a href="https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/resource-qos.md">https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/resource-qos.md</a></td>
 </tr>
 <tr>
 <td>reason <br /> <em>string</em></td>
@@ -4873,7 +4873,7 @@ Appears In:
 <tbody>
 <tr>
 <td>finalizers <br /> <em>string array</em></td>
-<td>Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers">https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers</a></td>
+<td>Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers">https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers</a></td>
 </tr>
 </tbody>
 </table>
@@ -4895,7 +4895,7 @@ Appears In:
 <tbody>
 <tr>
 <td>phase <br /> <em>string</em></td>
-<td>Phase is the current lifecycle phase of the namespace. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases">https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases</a></td>
+<td>Phase is the current lifecycle phase of the namespace. More info: <a href="https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases">https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases</a></td>
 </tr>
 </tbody>
 </table>
@@ -12868,7 +12868,7 @@ Appears In:
 </tr>
 <tr>
 <td>seLinuxOptions <br /> <em><a href="#selinuxoptions-v1-core">SELinuxOptions</a></em></td>
-<td>seLinuxOptions required to run as; required for MustRunAs More info: <a href="https://git.k8s.io/community/contributors/design-proposals/security_context.md">https://git.k8s.io/community/contributors/design-proposals/security_context.md</a></td>
+<td>seLinuxOptions required to run as; required for MustRunAs More info: <a href="https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md">https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md</a></td>
 </tr>
 </tbody>
 </table>

docs/setup/independent/create-cluster-kubeadm.md

@@ -103,6 +103,7 @@ kubeadm init
 ```
 
 **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
@@ -214,7 +215,8 @@ Please select one of the tabs to see installation instructions for the respectiv
 The official Calico guide is [here](http://docs.projectcalico.org/latest/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`
+
+ - 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
@@ -227,6 +229,7 @@ kubectl apply -f http://docs.projectcalico.org/v2.4/getting-started/kubernetes/i
 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.
 
@@ -239,6 +242,7 @@ kubectl apply -f https://raw.githubusercontent.com/projectcalico/canal/master/k8
 {% 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` occurences with your chosen platform.

docs/tasks/access-kubernetes-api/migrate-third-party-resource.md

@@ -10,7 +10,7 @@ This page shows how to migrate data stored in a ThirdPartyResource (TPR) to a Cu
 
 Kubernetes does not automatically migrate existing TPRs.
 This is due to API changes introduced as part of
-[graduating to beta](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/thirdpartyresources.md)
+[graduating to beta](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/thirdpartyresources.md)
 under a new name and API group.
 Instead, both TPR and CRD are available and operate independently in Kubernetes 1.7.
 Users must migrate each TPR one by one to preserve their data before upgrading to Kubernetes 1.8.

docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods.md

@@ -29,7 +29,7 @@ the rescheduler tries to free up space for the add-on by evicting some pods; the
 
 To avoid situation when another pod is scheduled into the space prepared for the critical add-on,
 the chosen node gets a temporary taint "CriticalAddonsOnly" before the eviction(s)
-(see [more details](https://git.k8s.io/community/contributors/design-proposals/taint-toleration-dedicated.md)).
+(see [more details](https://git.k8s.io/community/contributors/design-proposals/scheduling/taint-toleration-dedicated.md)).
 Each critical add-on has to tolerate it,
 while the other pods shouldn't tolerate the taint. The taint is removed once the add-on is successfully scheduled.
 

docs/tasks/administer-cluster/namespaces.md

@@ -70,7 +70,7 @@ A namespace can be in one of two phases:
    * `Active` the namespace is in use
    * `Terminating` the namespace is being deleted, and can not be used for new objects
 
-See the [design doc](https://git.k8s.io/community/contributors/design-proposals/namespaces.md#phases) for more details.
+See the [design doc](https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#phases) for more details.
 
 ## Creating a new namespace
 
@@ -93,7 +93,7 @@ Note that the name of your namespace must be a DNS compatible label.
 
 There's an optional field `finalizers`, which allows observables to purge resources whenever the namespace is deleted. Keep in mind that if you specify a nonexistent finalizer, the namespace will be created but will get stuck in the `Terminating` state if the user tries to delete it.
 
-More information on `finalizers` can be found in the namespace [design doc](https://git.k8s.io/community/contributors/design-proposals/namespaces.md#finalizers).
+More information on `finalizers` can be found in the namespace [design doc](https://git.k8s.io/community/contributors/design-proposals/architecture/namespaces.md#finalizers).
 
 ## Deleting a namespace
 
@@ -346,7 +346,7 @@ across namespaces, you need to use the fully qualified domain name (FQDN).
 {% 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).
+* See [namespaces design](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/architecture/namespaces.md).
 {% endcapture %}
 
 {% include templates/task.md %}

docs/tasks/administer-cluster/reserve-compute-resources.md

@@ -99,7 +99,7 @@ It is recommended that the kubernetes system daemons are placed under a top
 level control group (`runtime.slice` on systemd machines for example). Each
 system daemon should ideally run within its own child control group. Refer to
 [this
-doc](https://git.k8s.io/community/contributors/design-proposals/node-allocatable.md#recommended-cgroups-setup)
+doc](https://git.k8s.io/community/contributors/design-proposals/node/node-allocatable.md#recommended-cgroups-setup)
 for more details on recommended control group hierarchy.
 
 Note that Kubelet **does not** create `--kube-reserved-cgroup` if it doesn't

docs/tasks/administer-federation/ingress.md

@@ -300,6 +300,6 @@ Check that:
 {% capture whatsnext %}
 *  If you need assistance, use one of the [support channels](/docs/tasks/debug-application-cluster/troubleshooting/) to seek assistance.
  *  For details about use cases that motivated this work, see
- [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation.md).
+ [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation/federation.md).
 {% endcapture %}
 {% include templates/task.md %}

docs/tasks/configure-pod-container/configure-projected-volume-storage.md

@@ -57,7 +57,7 @@ the Pod:
 
 {% capture whatsnext %}
 * Learn more about [`projected`](/docs/concepts/storage/volumes/#projected) volumes.
-* Read the the [all-in-one volume](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md) design document.
+* Read the the [all-in-one volume](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/node/all-in-one-volume.md) design document.
 {% endcapture %}
 
 {% include templates/task.md %}

docs/tasks/configure-pod-container/security-context.md

@@ -325,7 +325,7 @@ applied to Volumes as follows:
 
 * `fsGroup`: Volumes that support ownership management are modified to be owned
 and writable by the GID specified in `fsGroup`. See the
-[Ownership Management design document](https://git.k8s.io/community/contributors/design-proposals/volume-ownership-management.md)
+[Ownership Management design document](https://git.k8s.io/community/contributors/design-proposals/storage/volume-ownership-management.md)
 for more details.
 
 * `seLinuxOptions`: Volumes that support SELinux labeling are relabeled to be accessible
@@ -344,8 +344,8 @@ label given to all Containers in the Pod as well as the Volumes.
 * [PodSecurityContext](/docs/api-reference/{{page.version}}/#podsecuritycontext-v1-core)
 * [SecurityContext](/docs/api-reference/{{page.version}}/#securitycontext-v1-core)
 * [Tuning Docker with the newest security enhancements](https://opensource.com/business/15/3/docker-security-tuning)
-* [Security Contexts design document](https://git.k8s.io/community/contributors/design-proposals/security_context.md)
+* [Security Contexts design document](https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md)
-* [Ownership Management design document](https://git.k8s.io/community/contributors/design-proposals/volume-ownership-management.md)
+* [Ownership Management design document](https://git.k8s.io/community/contributors/design-proposals/storage/volume-ownership-management.md)
 * [Pod Security Policies](/docs/concepts/policy/pod-security-policy/)
 * [AllowPrivilegeEscalation design
   document](https://git.k8s.io/community/contributors/design-proposals/auth/no-new-privs.md)

docs/tasks/federation/federation-service-discovery.md

@@ -379,4 +379,4 @@ Check that:
 
 ## For more information
 
- * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation.md) details use cases that motivated this work.
+ * [Federation proposal](https://git.k8s.io/community/contributors/design-proposals/federation/federation.md) details use cases that motivated this work.

docs/tasks/inject-data-application/podpreset.md

@@ -8,7 +8,7 @@ You can use a `podpreset` object to inject certain information into pods at crea
 time. This information can include secrets, volumes, volume mounts, and environment
 variables.
 
-See [PodPreset proposal](https://git.k8s.io/community/contributors/design-proposals/pod-preset.md) for more information.
+See [PodPreset proposal](https://git.k8s.io/community/contributors/design-proposals/service-catalog/pod-preset.md) for more information.
 
 * TOC
 {:toc}

docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md

@@ -49,7 +49,7 @@ controlled by the php-apache deployment we created in the first step of these in
 Roughly speaking, HPA will increase and decrease the number of replicas
 (via the deployment) to maintain an average CPU utilization across all Pods of 50%
 (since each pod requests 200 milli-cores by [kubectl run](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/user-guide/kubectl/kubectl_run.md), this means average CPU usage of 100 milli-cores).
-See [here](https://git.k8s.io/community/contributors/design-proposals/horizontal-pod-autoscaler.md#autoscaling-algorithm) for more details on the algorithm.
+See [here](https://git.k8s.io/community/contributors/design-proposals/autoscaling/horizontal-pod-autoscaler.md#autoscaling-algorithm) for more details on the algorithm.
 
 ```shell
 $ kubectl autoscale deployment php-apache --cpu-percent=50 --min=1 --max=10

docs/tasks/run-application/rolling-update-replication-controller.md

@@ -16,7 +16,7 @@ which in turn uses a
 For more information, see
 [Running a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/).
 
-To update a service without an outage, `kubectl` supports what is called ['rolling update'](/docs/user-guide/kubectl/v1.6/#rolling-update), which updates one pod at a time, rather than taking down the entire service at the same time. See the [rolling update design document](https://git.k8s.io/community/contributors/design-proposals/simple-rolling-update.md) and the [example of rolling update](/docs/tasks/run-application/rolling-update-replication-controller/) for more information.
+To update a service without an outage, `kubectl` supports what is called ['rolling update'](/docs/user-guide/kubectl/v1.6/#rolling-update), which updates one pod at a time, rather than taking down the entire service at the same time. See the [rolling update design document](https://git.k8s.io/community/contributors/design-proposals/cli/simple-rolling-update.md) and the [example of rolling update](/docs/tasks/run-application/rolling-update-replication-controller/) for more information.
 
 Note that `kubectl rolling-update` only supports Replication Controllers. However, if you deploy applications with Replication Controllers,
 consider switching them to [Deployments](/docs/concepts/workloads/controllers/deployment/). A Deployment is a higher-level controller that automates rolling updates
@@ -156,7 +156,7 @@ spec:
         - containerPort: 80
 ```
 
-To update to version 1.9.1, you can use [`kubectl rolling-update --image`](https://git.k8s.io/community/contributors/design-proposals/simple-rolling-update.md) to specify the new image:
+To update to version 1.9.1, you can use [`kubectl rolling-update --image`](https://git.k8s.io/community/contributors/design-proposals/cli/simple-rolling-update.md) to specify the new image:
 
 ```shell
 $ kubectl rolling-update my-nginx --image=nginx:1.9.1

docs/user-guide/update-demo/index.md.orig

@@ -4,7 +4,7 @@ assignees:
 title: Rolling Update Demo
 ---
 
-This example demonstrates the usage of Kubernetes to perform a [rolling update](/docs/user-guide/kubectl/kubectl_rolling-update/) on a running group of [pods](/docs/user-guide/pods/). See [here](/docs/concepts/cluster-administration/manage-deployment/#updating-your-application-without-a-service-outage) to understand why you need a rolling update. Also check [rolling update design document](https://git.k8s.io/community/contributors/design-proposals/simple-rolling-update.md) for more information.
+This example demonstrates the usage of Kubernetes to perform a [rolling update](/docs/user-guide/kubectl/kubectl_rolling-update/) on a running group of [pods](/docs/user-guide/pods/). See [here](/docs/concepts/cluster-administration/manage-deployment/#updating-your-application-without-a-service-outage) to understand why you need a rolling update. Also check [rolling update design document](https://git.k8s.io/community/contributors/design-proposals/cli/simple-rolling-update.md) for more information.
 
 The files for this example are viewable in [our docs repo
 here](https://github.com/kubernetes/kubernetes.github.io/tree/{{page.docsbranch}}/docs/user-guide/update-demo).