From 90070474d463d4ab057235efd510744c49d354ec Mon Sep 17 00:00:00 2001
From: Andrew Chen <chenopis@users.noreply.github.com>
Date: Thu, 20 Apr 2017 13:04:32 -0700
Subject: [PATCH] Reference ToC refactor (#3427)

* Reference ToC refactor

* Move Federation into Reference

* Fix ToC, add deprecation notice

* Fix Reference ToC

* tweak ToC

* Move content into Reference

* touch up kubectl

* fix ToC syntax error

* remove resources-reference docs

* change kubectl section name

* adjust page titles

* create Command-Line Tools section

* Move Federation API out to top level

* remove extensions/v1beta1 definitions

* rewrite Kubernetes API in Concepts in a later PR

* Add jbeda to Kubernetes API Overview page for reviews.

* incorporate feedback

* remove /docs/federation

* move around copy

* cleanup reference landing page

* update reference landing page
---
 _data/reference.yml                           |  87 ++++---
 _includes/api-reference-content-moved.md      |   2 +
 _includes/federation-content-moved.md         |   2 +
 docs/admin/accessing-the-api.md               |   2 +-
 docs/admin/kubeadm.md                         |   2 +-
 docs/admin/kubelet.md                         |   2 +-
 .../labels-annotations-taints.md              | 110 +--------
 docs/concepts/overview/kubernetes-api.md      |   6 +-
 docs/federation/api-reference/index.md        |  15 --
 docs/reference.md                             |  28 ---
 docs/reference/api-overview.md                |  92 ++++++++
 .../{home => reference}/deprecation-policy.md |   0
 .../extensions/v1beta1/definitions.html       |   2 +
 .../extensions/v1beta1/operations.html        |   2 +
 docs/reference/federation/index.md            |  17 ++
 .../federation}/v1/definitions.html           |   2 +
 .../federation}/v1/operations.html            |   2 +
 .../federation/v1beta1/definitions.html       |   2 +
 .../federation/v1beta1/operations.html        |   2 +
 docs/reference/index.md                       |  39 ++++
 docs/reference/labels-annotations-taints.md   | 113 +++++++++
 docs/{home => reference}/security.md          |   0
 docs/user-guide/kubectl-overview.md           |   2 +-
 skip_toc_check.txt                            | 217 ++++++++----------
 24 files changed, 428 insertions(+), 320 deletions(-)
 create mode 100644 _includes/api-reference-content-moved.md
 create mode 100644 _includes/federation-content-moved.md
 delete mode 100644 docs/federation/api-reference/index.md
 delete mode 100644 docs/reference.md
 create mode 100644 docs/reference/api-overview.md
 rename docs/{home => reference}/deprecation-policy.md (100%)
 rename docs/{federation/api-reference => reference/federation}/extensions/v1beta1/definitions.html (99%)
 rename docs/{federation/api-reference => reference/federation}/extensions/v1beta1/operations.html (99%)
 create mode 100644 docs/reference/federation/index.md
 rename docs/{federation/api-reference => reference/federation}/v1/definitions.html (99%)
 rename docs/{federation/api-reference => reference/federation}/v1/operations.html (99%)
 rename docs/{federation/api-reference => reference}/federation/v1beta1/definitions.html (99%)
 rename docs/{federation/api-reference => reference}/federation/v1beta1/operations.html (99%)
 create mode 100644 docs/reference/index.md
 create mode 100644 docs/reference/labels-annotations-taints.md
 rename docs/{home => reference}/security.md (100%)

diff --git a/_data/reference.yml b/_data/reference.yml
index 00fb1ee249..b5dd77a3aa 100644
--- a/_data/reference.yml
+++ b/_data/reference.yml
@@ -1,72 +1,70 @@
 bigheader: "Reference Documentation"
 abstract: "Design docs, concept definitions, and references for APIs and CLIs."
 toc:
-- docs/reference.md
+- docs/reference/index.md
 
-- title: "Kubernetes Resource Types"
+- title: Using the API
   section:
-  - title: Version 1.6
-    path: /docs/resources-reference/v1.6/
-  - title: Version 1.5
-    path: /docs/resources-reference/v1.5/
-
-- title: "Kubernetes API"
-  section:
-  - title: Overview
-    path: /docs/concepts/overview/kubernetes-api/
-  - title: Version 1.6
-    path: /docs/api-reference/v1.6/
-  - title: Version 1.5
-    path: /docs/api-reference/v1.5/
+  - docs/reference/api-overview.md
   - title: Accessing the API
     section:
     - docs/admin/accessing-the-api.md
     - docs/admin/authentication.md
     - docs/admin/bootstrap-tokens.md
-    - title: Authorization Plugins
-      section:
-      - docs/admin/authorization/index.md
-      - docs/admin/authorization/rbac.md
     - docs/admin/admission-controllers.md
     - docs/admin/service-accounts-admin.md
-  - docs/api-reference/labels-annotations-taints.md
-  - docs/api-reference/extensions/v1beta1/definitions.html
+  - title: Authorization
+    section:
+    - docs/admin/authorization/index.md
+    - docs/admin/authorization/rbac.md
+  - docs/reference/deprecation-policy.md
+
+- title: API Reference
+  section:
+  - title: v1.6
+    path: /docs/api-reference/v1.6/
+  - title: v1.5
+    path: /docs/api-reference/v1.5/
+  - docs/reference/labels-annotations-taints.md
+  - title: OpenAPI and Swagger
+    section:
+    - title: OpenAPI Spec
+      path: https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/
+    - title: Swagger Spec
+      path: https://github.com/kubernetes/kubernetes/tree/master/api/swagger-spec/
+
+- title: Federation API
+  section:
+    - docs/reference/federation/v1/operations.html
+    - docs/reference/federation/v1/definitions.html
+    - docs/reference/federation/v1beta1/operations.html
+    - docs/reference/federation/v1beta1/definitions.html
+    - docs/reference/federation/extensions/v1beta1/operations.html
+    - docs/reference/federation/extensions/v1beta1/definitions.html
 
 - title: kubectl CLI
   section:
-  - title: Overview
-    path: /docs/user-guide/kubectl-overview/
-  - title: Commands
-    section:
-    - title: Version 1.6
-      path: /docs/user-guide/kubectl/v1.6/
-    - title: Version 1.5
-      path: /docs/user-guide/kubectl/v1.5/
+  - docs/user-guide/kubectl-overview.md
+  - title: v1.6 Commands
+    path: /docs/user-guide/kubectl/v1.6/
+  - title: v1.5 Commands
+    path: /docs/user-guide/kubectl/v1.5/
   - docs/user-guide/docker-cli-to-kubectl.md
   - docs/user-guide/kubectl-conventions.md
   - docs/user-guide/jsonpath.md
   - docs/user-guide/kubectl-cheatsheet.md
 
-- title: Kubernetes Components
+- docs/admin/kubeadm.md
+
+- title: Config Reference
   section:
+  - docs/admin/kubelet.md
   - docs/admin/kube-apiserver.md
   - docs/admin/kube-controller-manager.md
   - docs/admin/kube-proxy.md
   - docs/admin/kube-scheduler.md
-  - docs/admin/kubeadm.md
   - docs/admin/federation-apiserver.md
   - docs/admin/federation-controller-manager.md
-  - docs/federation/api-reference/index.md
-  - title: kubelet
-    section:
-    - docs/admin/kubelet.md
-    - docs/admin/kubelet-tls-bootstrapping.md
-    - docs/admin/kubelet-authentication-authorization.md
-
-- title: Glossary
-  section:
-  - docs/user-guide/cron-jobs.md
-  - docs/admin/resourcequota/index.md
 
 - title: Kubernetes Design Docs
   section:
@@ -82,11 +80,10 @@ toc:
   - title: Security in Kubernetes
     path: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/security.md
 
-- title: Issues and Security
+- title: Kubernetes Issues and Security
   section:
   - title: Kubernetes Issue Tracker on GitHub
     path: https://github.com/kubernetes/kubernetes/issues/
-  - docs/home/security.md
-  - docs/home/deprecation-policy.md
+  - docs/reference/security.md
 
 
diff --git a/_includes/api-reference-content-moved.md b/_includes/api-reference-content-moved.md
new file mode 100644
index 0000000000..a9bba0ff8d
--- /dev/null
+++ b/_includes/api-reference-content-moved.md
@@ -0,0 +1,2 @@
+The topics in the `/docs/api-reference/` section of the Kubernetes docs
+are being moved to the [Reference](/docs/reference/) section. The content in this topic has moved to:
diff --git a/_includes/federation-content-moved.md b/_includes/federation-content-moved.md
new file mode 100644
index 0000000000..87a10e7199
--- /dev/null
+++ b/_includes/federation-content-moved.md
@@ -0,0 +1,2 @@
+The topics in the [Federation API](/docs/federation/api-reference/) section of the Kubernetes docs
+are being moved to the [Reference](/docs/reference/) section. The content in this topic has moved to:
diff --git a/docs/admin/accessing-the-api.md b/docs/admin/accessing-the-api.md
index dd7aa902db..49dd84a406 100644
--- a/docs/admin/accessing-the-api.md
+++ b/docs/admin/accessing-the-api.md
@@ -3,7 +3,7 @@ assignees:
 - bgrant0607
 - erictune
 - lavalamp
-title: Controlling Accessing to the Kubernetes API
+title: Controlling Access to the Kubernetes API
 ---
 
 Users [access the API](/docs/user-guide/accessing-the-cluster) using `kubectl`,
diff --git a/docs/admin/kubeadm.md b/docs/admin/kubeadm.md
index bdf66086d3..0a512193e4 100644
--- a/docs/admin/kubeadm.md
+++ b/docs/admin/kubeadm.md
@@ -4,7 +4,7 @@ assignees:
 - luxas
 - errordeveloper
 - jbeda
-title: kubeadm reference
+title: kubeadm Setup Tool
 ---
 
 This document provides information on how to use kubeadm's advanced options.
diff --git a/docs/admin/kubelet.md b/docs/admin/kubelet.md
index 1528043343..9da312344d 100644
--- a/docs/admin/kubelet.md
+++ b/docs/admin/kubelet.md
@@ -1,5 +1,5 @@
 ---
-title: Overview
+title: kubelet
 notitle: true
 ---
 ## kubelet
diff --git a/docs/api-reference/labels-annotations-taints.md b/docs/api-reference/labels-annotations-taints.md
index e159fbf818..0a052bebe2 100644
--- a/docs/api-reference/labels-annotations-taints.md
+++ b/docs/api-reference/labels-annotations-taints.md
@@ -2,112 +2,6 @@
 title: Well-Known Labels, Annotations and Taints
 ---
 
-Kubernetes reserves all labels and annotations in the kubernetes.io namespace.  This document describes
-the well-known kubernetes.io labels and annotations.
+{% include api-reference-content-moved.md %}
 
-This document serves both as a reference to the values, and as a coordination point for assigning values.
-
-**Table of contents:**
-<!-- BEGIN MUNGE: GENERATED_TOC -->
-
-- [Well-Known Labels, Annotations and Taints](#well-known-labels-annotations-and-taints)
-  - [beta.kubernetes.io/arch](#betakubernetesioarch)
-  - [beta.kubernetes.io/os](#betakubernetesioos)
-  - [kubernetes.io/hostname](#kubernetesiohostname)
-  - [beta.kubernetes.io/instance-type](#betakubernetesioinstance-type)
-  - [failure-domain.beta.kubernetes.io/region](#failure-domainbetakubernetesioregion)
-  - [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
-
-<!-- END MUNGE: GENERATED_TOC -->
-
-
-## beta.kubernetes.io/arch
-
-Example: `beta.kubernetes.io/arch=amd64`
-
-Used on: Node
-
-Kubelet populates this with `runtime.GOARCH` as defined by Go.  This can be handy if you are mixing arm and x86 nodes,
-for example.
-
-## beta.kubernetes.io/os
-
-Example: `beta.kubernetes.io/os=linux`
-
-Used on: Node
-
-Kubelet populates this with `runtime.GOOS` as defined by Go.  This can be handy if you are mixing operating systems
-in your cluster (although currently Linux is the only OS supported by Kubernetes).
-
-## kubernetes.io/hostname
-
-Example: `kubernetes.io/hostname=ip-172-20-114-199.ec2.internal`
-
-Used on: Node
-
-Kubelet populates this with the hostname.  Note that the hostname can be changed from the "actual" hostname
-by passing the `--hostname-override` flag to kubelet.
-
-## beta.kubernetes.io/instance-type
-
-Example: `beta.kubernetes.io/instance-type=m3.medium`
-
-Used on: Node
-
-Kubelet populates this with the instance type as defined by the `cloudprovider`.  It will not be set if
-not using a cloudprovider.  This can be handy if you want to target certain workloads to certain instance
-types, but typically you want to rely on the Kubernetes scheduler to perform resource-based scheduling,
-and you should aim to schedule based on properties rather than on instance types (e.g. require a GPU, instead
-of requiring a `g2.2xlarge`)
-
-
-## failure-domain.beta.kubernetes.io/region
-
-See [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
-
-## failure-domain.beta.kubernetes.io/zone
-
-Example:
-
-`failure-domain.beta.kubernetes.io/region=us-east-1`
-
-`failure-domain.beta.kubernetes.io/zone=us-east-1c`
-
-Used on: Node, PersistentVolume
-
-On the Node: Kubelet populates this with the zone information as defined by the `cloudprovider`.  It will not be set if
-not using a `cloudprovider`, but you should consider setting it on the nodes if it makes sense in your topology.
-
-On the PersistentVolume: The `PersistentVolumeLabel` admission controller will automatically add zone labels to PersistentVolumes,
-on GCE and AWS.
-
-Kubernetes will automatically spread the pods in a replication controller or service across nodes in a single-zone
-cluster (to reduce the impact of failures.) With multiple-zone clusters, this spreading behaviour is extended
-across zones (to reduce the impact of zone failures.) This is achieved via SelectorSpreadPriority.
-
-This is a best-effort placement, and so if the zones in your cluster are heterogeneous (e.g. different numbers of nodes,
-different types of nodes, or different pod resource requirements), this might prevent equal spreading of
-your pods across zones. If desired, you can use homogenous zones (same number and types of nodes) to reduce
-the probability of unequal spreading.
-
-The scheduler (via the VolumeZonePredicate predicate) will also ensure that pods that claim a given volume
-are only placed into the same zone as that volume, as volumes cannot be attached across zones.
-
-
-The actual values of zone and region don't matter, and nor is the meaning of the hierarchy rigidly defined.  The expectation
-is that failures of nodes in different zones should be uncorrelated unless the entire region has failed.  For example,
-zones should typically avoid sharing a single network switch.  The exact mapping depends on your particular
-infrastructure - a three-rack installation will choose a very different setup to a multi-datacenter configuration.
-
-If `PersistentVolumeLabel` does not support automatic labeling of your PersistentVolumes, you should consider
-adding the labels manually (or adding support to `PersistentVolumeLabel`), if you want the scheduler to prevent
-pods from mounting volumes in a different zone.  If your infrastructure doesn't have this constraint, you don't
-need to add the zone labels to the volumes at all.
-
-
-
-
-
-<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
-[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/api-reference/labels-annotations-taints.md?pixel)]()
-<!-- END MUNGE: GENERATED_ANALYTICS -->
+* [Well-Known Labels, Annotations and Taints](/docs/reference/labels-annotations-taints/)
\ No newline at end of file
diff --git a/docs/concepts/overview/kubernetes-api.md b/docs/concepts/overview/kubernetes-api.md
index fc7cbff56e..a9672d7df8 100644
--- a/docs/concepts/overview/kubernetes-api.md
+++ b/docs/concepts/overview/kubernetes-api.md
@@ -1,13 +1,9 @@
 ---
 assignees:
-- bgrant0607
-- erictune
-- lavalamp
+- chenopis
 title: The Kubernetes API
 ---
 
-Primary system and API concepts are documented in the [User guide](/docs/user-guide/).
-
 Overall API conventions are described in the [API conventions doc](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md).
 
 API endpoints, resource types and samples are described in [API Reference](/docs/reference).
diff --git a/docs/federation/api-reference/index.md b/docs/federation/api-reference/index.md
deleted file mode 100644
index 30dbfe3070..0000000000
--- a/docs/federation/api-reference/index.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-title: Federation API Reference
----
-# API Reference
-
-Federation API server supports the following group versions:
-
-* federation/v1beta1: [operations](/docs/federation/api-reference/federation/v1beta1/operations.html), [model definitions](/docs/federation/api-reference/federation/v1beta1/definitions.html)
-* v1: [operations](/docs/federation/api-reference/v1/operations.html), [model definitions](/docs/federation/api-reference/v1/definitions.html)
-* extensions/v1beta1: [operations](/docs/federation/api-reference/extensions/v1beta1/operations.html), [model definitions](/docs/federation/api-reference/extensions/v1beta1/definitions.html)
-
-
-<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
-[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/federation/api-reference/README.md?pixel)]()
-<!-- END MUNGE: GENERATED_ANALYTICS -->
diff --git a/docs/reference.md b/docs/reference.md
deleted file mode 100644
index 674a83d8ec..0000000000
--- a/docs/reference.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: Reference Documentation
----
-
-In the reference section, you can find reference documentation for Kubernetes APIs, CLIs, and tools, as well as our glossary and design docs. 
-
-## API References
-
-* [Kubernetes API Overview](/docs/concepts/overview/kubernetes-api/) - Conceptual overview of the API for Kubernetes.
-* Versions
-  * [1.6](/docs/api-reference/v1.6/)
-  * [1.5](/docs/api-reference/v1.5/)
-
-## CLI References
-
-* [kubectl](/docs/user-guide/kubectl-overview/) - Runs commands against Kubernetes clusters.
-    * [JSONPath](/docs/user-guide/jsonpath/) - Syntax     guide for using [JSONPath expressions](http://goessner.net/articles/JsonPath/) with kubectl.
-* [kube-apiserver](/docs/admin/kube-apiserver/) - REST API that validates and configures data for API objects such as  pods, services, replication controllers.
-* [kube-proxy](/docs/admin/kube-proxy/) - Can do simple TCP/UDP stream forwarding or round-robin TCP/UDP forwarding across a set of backends.
-* [kubelet](/docs/admin/kubelet/) - The primary "node agent" that runs on each node. The kubelet takes a set of PodSpecs and ensures that the described containers are running and healthy.
-
-## Glossary
-
-Explore the glossary of essential Kubernetes concepts. Some good starting points are the entries for [Pods](/docs/concepts/workloads/pods/pod/), [Nodes](/docs/concepts/nodes/node/), [Services](/docs/concepts/services-networking/service/), and [ReplicaSets](/docs/concepts/workloads/controllers/replicaset/).
-
-## Design Docs
-
-An archive of the design docs for Kubernetes functionality. Good starting points are [Kubernetes Architecture](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture.md) and [Kubernetes Design Overview](https://github.com/kubernetes/kubernetes/tree/{{page.fullversion}}/docs/design).
diff --git a/docs/reference/api-overview.md b/docs/reference/api-overview.md
new file mode 100644
index 0000000000..076c7b89db
--- /dev/null
+++ b/docs/reference/api-overview.md
@@ -0,0 +1,92 @@
+---
+title: Kubernetes API Overview
+assignees:
+- bgrant0607
+- erictune
+- lavalamp
+- jbeda
+---
+
+The REST API is the fundamental fabric of Kubernetes. All operations and
+communications between components are REST API calls handled by the API Server,
+including external user commands. Consequently, everything in the Kubernetes
+platform is treated as an API object and has a corresponding entry in the
+[API](/docs/api-reference/{{page.version}}/).
+
+Most operations can be performed through the
+[kubectl](/docs/user-guide/kubectl-overview/) command-line interface or other
+command-line tools, such as [kubeadm](/docs/admin/kubeadm/), which in turn use
+the API. However, the API can also be accessed directly using REST calls.
+
+## API versioning
+
+To make it easier to eliminate fields or restructure resource representations, Kubernetes supports
+multiple API versions, each at a different API path, such as `/api/v1` or
+`/apis/extensions/v1beta1`.
+
+We chose to version 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-lifed 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://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/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://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api_changes.md#alpha-beta-and-stable-versions).  They are summarized here:
+
+- Alpha level:
+  - The version names contain `alpha` (e.g. `v1alpha1`).
+  - May be buggy.  Enabling the feature may expose bugs.  Disabled by default.
+  - Support for feature may be dropped at any time without notice.
+  - The API may change in incompatible ways in a later software release without notice.
+  - Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
+- Beta level:
+  - The version names contain `beta` (e.g. `v2beta3`).
+  - Code is well tested.  Enabling the feature is considered safe.  Enabled by default.
+  - Support for the overall feature will not be dropped, though details may change.
+  - The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release.  When this happens,
+    we will provide instructions for migrating to the next version.  This may require deleting, editing, and re-creating
+    API objects.  The editing process may require some thought.   This may require downtime for applications that rely on the feature.
+  - Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases.  If you have
+    multiple clusters which can be upgraded independently, you may be able to relax this restriction.
+  - **Please do try our beta features and give feedback on them!  Once they exit beta, it may not be practical for us to make more changes.**
+- Stable level:
+  - The version name is `vX` where `X` is an integer.
+  - Stable versions of features will appear in released software for many subsequent versions.
+
+## API groups
+
+To make it easier to extend the Kubernetes API, we implemented [*API groups*](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-group.md).
+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:
+
+1. the "core" (oftentimes called "legacy", due to not having explicit group name) group, which is at
+   REST path `/api/v1` and is not specified as part of the `apiVersion` field, e.g. `apiVersion: v1`.
+1. the named groups are at REST path `/apis/$GROUP_NAME/$VERSION`, and use `apiVersion: $GROUP_NAME/$VERSION`
+   (e.g. `apiVersion: batch/v1`).  Full list of supported API groups can be seen in [Kubernetes API reference](/docs/reference/).
+
+
+There are two supported paths to extending the API.
+1. [Third Party Resources](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/extending-api.md)
+   are 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)
+   to make it seamless for clients.
+
+
+## Enabling API groups
+
+Certain resources and API groups are enabled by default.  They can be enabled or disabled by setting `--runtime-config`
+on apiserver. `--runtime-config` accepts comma separated values. For ex: to disable batch/v1, set
+`--runtime-config=batch/v1=false`, to enable batch/v2alpha1, set `--runtime-config=batch/v2alpha1`.
+The flag accepts comma separated set of key=value pairs describing runtime configuration of the apiserver.
+
+IMPORTANT: Enabling or disabling groups or resources requires restarting apiserver and controller-manager
+to pick up the `--runtime-config` changes.
+
+## Enabling resources in the groups
+
+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 jobs, set
+`--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/jobs=false`
\ No newline at end of file
diff --git a/docs/home/deprecation-policy.md b/docs/reference/deprecation-policy.md
similarity index 100%
rename from docs/home/deprecation-policy.md
rename to docs/reference/deprecation-policy.md
diff --git a/docs/federation/api-reference/extensions/v1beta1/definitions.html b/docs/reference/federation/extensions/v1beta1/definitions.html
similarity index 99%
rename from docs/federation/api-reference/extensions/v1beta1/definitions.html
rename to docs/reference/federation/extensions/v1beta1/definitions.html
index 47ae1c3cab..2ef6848531 100755
--- a/docs/federation/api-reference/extensions/v1beta1/definitions.html
+++ b/docs/reference/federation/extensions/v1beta1/definitions.html
@@ -1,4 +1,6 @@
 ---
+title: extensions/v1beta1 Model Definitions
+notitle: true
 ---
 <!DOCTYPE html>
 <html lang="en">
diff --git a/docs/federation/api-reference/extensions/v1beta1/operations.html b/docs/reference/federation/extensions/v1beta1/operations.html
similarity index 99%
rename from docs/federation/api-reference/extensions/v1beta1/operations.html
rename to docs/reference/federation/extensions/v1beta1/operations.html
index f0a596846c..d651fabb6f 100755
--- a/docs/federation/api-reference/extensions/v1beta1/operations.html
+++ b/docs/reference/federation/extensions/v1beta1/operations.html
@@ -1,4 +1,6 @@
 ---
+title: extensions/v1beta1 Operations
+notitle: true
 ---
 <!DOCTYPE html>
 <html lang="en">
diff --git a/docs/reference/federation/index.md b/docs/reference/federation/index.md
new file mode 100644
index 0000000000..7aa794f470
--- /dev/null
+++ b/docs/reference/federation/index.md
@@ -0,0 +1,17 @@
+---
+title: Federation API Reference
+redirect_from:
+- "/docs/federation/api-reference/"
+- "/docs/federation/api-reference/index.md"
+---
+
+Federation API server supports the following group versions:
+
+* federation/v1beta1: [operations](/docs/reference/federation/v1beta1/operations.html), [model definitions](/docs/reference/federation/v1beta1/definitions.html)
+* v1: [operations](/docs/reference/federation/v1/operations.html), [model definitions](/docs/reference/federation/v1/definitions.html)
+* extensions/v1beta1: [operations](/docs/reference/federation/extensions/v1beta1/operations.html), [model definitions](/docs/reference/federation/extensions/v1beta1/definitions.html)
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/federation/api-reference/README.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->
diff --git a/docs/federation/api-reference/v1/definitions.html b/docs/reference/federation/v1/definitions.html
similarity index 99%
rename from docs/federation/api-reference/v1/definitions.html
rename to docs/reference/federation/v1/definitions.html
index ef661cdadb..30a662d14b 100755
--- a/docs/federation/api-reference/v1/definitions.html
+++ b/docs/reference/federation/v1/definitions.html
@@ -1,4 +1,6 @@
 ---
+title: v1 Model Definitions
+notitle: true
 ---
 <!DOCTYPE html>
 <html lang="en">
diff --git a/docs/federation/api-reference/v1/operations.html b/docs/reference/federation/v1/operations.html
similarity index 99%
rename from docs/federation/api-reference/v1/operations.html
rename to docs/reference/federation/v1/operations.html
index c6bcb4e6fc..23b37f45bf 100755
--- a/docs/federation/api-reference/v1/operations.html
+++ b/docs/reference/federation/v1/operations.html
@@ -1,4 +1,6 @@
 ---
+title: v1 Operations
+notitle: true
 ---
 <!DOCTYPE html>
 <html lang="en">
diff --git a/docs/federation/api-reference/federation/v1beta1/definitions.html b/docs/reference/federation/v1beta1/definitions.html
similarity index 99%
rename from docs/federation/api-reference/federation/v1beta1/definitions.html
rename to docs/reference/federation/v1beta1/definitions.html
index 6e84c578be..53d1936775 100755
--- a/docs/federation/api-reference/federation/v1beta1/definitions.html
+++ b/docs/reference/federation/v1beta1/definitions.html
@@ -1,4 +1,6 @@
 ---
+title: federation/v1beta1 Model Definitions
+notitle: true
 ---
 <!DOCTYPE html>
 <html lang="en">
diff --git a/docs/federation/api-reference/federation/v1beta1/operations.html b/docs/reference/federation/v1beta1/operations.html
similarity index 99%
rename from docs/federation/api-reference/federation/v1beta1/operations.html
rename to docs/reference/federation/v1beta1/operations.html
index 67adf4e83f..28cc47802c 100755
--- a/docs/federation/api-reference/federation/v1beta1/operations.html
+++ b/docs/reference/federation/v1beta1/operations.html
@@ -1,4 +1,6 @@
 ---
+title: federation/v1beta1 Operations
+notitle: true
 ---
 <!DOCTYPE html>
 <html lang="en">
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 0000000000..d863ae2bec
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,39 @@
+---
+title: Reference Documentation
+assignees:
+- chenopis
+---
+
+## API Reference
+
+* [Kubernetes API Overview](/docs/reference/api-overview/) - Overview of the API for Kubernetes.
+* Kubernetes API Versions
+  * [1.6](/docs/api-reference/v1.6/)
+  * [1.5](/docs/api-reference/v1.5/)
+* Federation API
+  * [v1 Operations](docs/reference/federation/v1/operations.html)
+  * [v1 Model Definitions](docs/reference/federation/v1/definitions.html)
+  * [federation/v1beta1 Operations](docs/reference/federation/v1beta1/operations.html)
+  * [federation/v1beta1 Model Definitions](docs/reference/federation/v1beta1/definitions.html)
+  * [extensions/v1beta1 Operations](docs/reference/federation/extensions/v1beta1/operations.html)
+  * [extensions/v1beta1 Model Definitions](docs/reference/federation/extensions/v1beta1/definitions.html)
+
+## CLI Reference
+
+* [kubectl](/docs/user-guide/kubectl-overview) - Main CLI tool for running commands and managing Kubernetes clusters.
+    * [JSONPath](/docs/user-guide/jsonpath/) - Syntax guide for using [JSONPath expressions](http://goessner.net/articles/JsonPath/) with kubectl.
+* [kubeadm](/docs/admin/kubeadm/) - CLI tool to 
+
+## Config Reference
+
+* [kubelet](/docs/admin/kubelet/) - The primary *node agent* that runs on each node. The kubelet takes a set of PodSpecs and ensures that the described containers are running and healthy.
+* [kube-apiserver](/docs/admin/kube-apiserver/) - REST API that validates and configures data for API objects such as  pods, services, replication controllers.
+* [kube-controller-manager](docs/admin/kube-controller-manager/) - Daemon that embeds the core control loops shipped with Kubernetes.
+* [kube-proxy](/docs/admin/kube-proxy/) - Can do simple TCP/UDP stream forwarding or round-robin TCP/UDP forwarding across a set of back-ends.
+* [kube-scheduler](/docs/admin/kube-scheduler/) - Scheduler that manages availability, performance, and capacity.
+* [federation-apiserver](/docs/admin/federation-apiserver/) - API server for federated clusters.
+* [federation-controller-manager](/docs/admin/federation-controller-manager/) - Daemon that embeds the core control loops shipped with Kubernetes federation.
+
+## Design Docs
+
+An archive of the design docs for Kubernetes functionality. Good starting points are [Kubernetes Architecture](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture.md) and [Kubernetes Design Overview](https://github.com/kubernetes/kubernetes/tree/{{page.fullversion}}/docs/design).
diff --git a/docs/reference/labels-annotations-taints.md b/docs/reference/labels-annotations-taints.md
new file mode 100644
index 0000000000..e159fbf818
--- /dev/null
+++ b/docs/reference/labels-annotations-taints.md
@@ -0,0 +1,113 @@
+---
+title: Well-Known Labels, Annotations and Taints
+---
+
+Kubernetes reserves all labels and annotations in the kubernetes.io namespace.  This document describes
+the well-known kubernetes.io labels and annotations.
+
+This document serves both as a reference to the values, and as a coordination point for assigning values.
+
+**Table of contents:**
+<!-- BEGIN MUNGE: GENERATED_TOC -->
+
+- [Well-Known Labels, Annotations and Taints](#well-known-labels-annotations-and-taints)
+  - [beta.kubernetes.io/arch](#betakubernetesioarch)
+  - [beta.kubernetes.io/os](#betakubernetesioos)
+  - [kubernetes.io/hostname](#kubernetesiohostname)
+  - [beta.kubernetes.io/instance-type](#betakubernetesioinstance-type)
+  - [failure-domain.beta.kubernetes.io/region](#failure-domainbetakubernetesioregion)
+  - [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
+
+<!-- END MUNGE: GENERATED_TOC -->
+
+
+## beta.kubernetes.io/arch
+
+Example: `beta.kubernetes.io/arch=amd64`
+
+Used on: Node
+
+Kubelet populates this with `runtime.GOARCH` as defined by Go.  This can be handy if you are mixing arm and x86 nodes,
+for example.
+
+## beta.kubernetes.io/os
+
+Example: `beta.kubernetes.io/os=linux`
+
+Used on: Node
+
+Kubelet populates this with `runtime.GOOS` as defined by Go.  This can be handy if you are mixing operating systems
+in your cluster (although currently Linux is the only OS supported by Kubernetes).
+
+## kubernetes.io/hostname
+
+Example: `kubernetes.io/hostname=ip-172-20-114-199.ec2.internal`
+
+Used on: Node
+
+Kubelet populates this with the hostname.  Note that the hostname can be changed from the "actual" hostname
+by passing the `--hostname-override` flag to kubelet.
+
+## beta.kubernetes.io/instance-type
+
+Example: `beta.kubernetes.io/instance-type=m3.medium`
+
+Used on: Node
+
+Kubelet populates this with the instance type as defined by the `cloudprovider`.  It will not be set if
+not using a cloudprovider.  This can be handy if you want to target certain workloads to certain instance
+types, but typically you want to rely on the Kubernetes scheduler to perform resource-based scheduling,
+and you should aim to schedule based on properties rather than on instance types (e.g. require a GPU, instead
+of requiring a `g2.2xlarge`)
+
+
+## failure-domain.beta.kubernetes.io/region
+
+See [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
+
+## failure-domain.beta.kubernetes.io/zone
+
+Example:
+
+`failure-domain.beta.kubernetes.io/region=us-east-1`
+
+`failure-domain.beta.kubernetes.io/zone=us-east-1c`
+
+Used on: Node, PersistentVolume
+
+On the Node: Kubelet populates this with the zone information as defined by the `cloudprovider`.  It will not be set if
+not using a `cloudprovider`, but you should consider setting it on the nodes if it makes sense in your topology.
+
+On the PersistentVolume: The `PersistentVolumeLabel` admission controller will automatically add zone labels to PersistentVolumes,
+on GCE and AWS.
+
+Kubernetes will automatically spread the pods in a replication controller or service across nodes in a single-zone
+cluster (to reduce the impact of failures.) With multiple-zone clusters, this spreading behaviour is extended
+across zones (to reduce the impact of zone failures.) This is achieved via SelectorSpreadPriority.
+
+This is a best-effort placement, and so if the zones in your cluster are heterogeneous (e.g. different numbers of nodes,
+different types of nodes, or different pod resource requirements), this might prevent equal spreading of
+your pods across zones. If desired, you can use homogenous zones (same number and types of nodes) to reduce
+the probability of unequal spreading.
+
+The scheduler (via the VolumeZonePredicate predicate) will also ensure that pods that claim a given volume
+are only placed into the same zone as that volume, as volumes cannot be attached across zones.
+
+
+The actual values of zone and region don't matter, and nor is the meaning of the hierarchy rigidly defined.  The expectation
+is that failures of nodes in different zones should be uncorrelated unless the entire region has failed.  For example,
+zones should typically avoid sharing a single network switch.  The exact mapping depends on your particular
+infrastructure - a three-rack installation will choose a very different setup to a multi-datacenter configuration.
+
+If `PersistentVolumeLabel` does not support automatic labeling of your PersistentVolumes, you should consider
+adding the labels manually (or adding support to `PersistentVolumeLabel`), if you want the scheduler to prevent
+pods from mounting volumes in a different zone.  If your infrastructure doesn't have this constraint, you don't
+need to add the zone labels to the volumes at all.
+
+
+
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/api-reference/labels-annotations-taints.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->
diff --git a/docs/home/security.md b/docs/reference/security.md
similarity index 100%
rename from docs/home/security.md
rename to docs/reference/security.md
diff --git a/docs/user-guide/kubectl-overview.md b/docs/user-guide/kubectl-overview.md
index 516007f30c..d03fd63614 100644
--- a/docs/user-guide/kubectl-overview.md
+++ b/docs/user-guide/kubectl-overview.md
@@ -2,7 +2,7 @@
 assignees:
 - bgrant0607
 - hw-qiaolei
-title: kubectl Overview
+title: Overview of kubectl
 ---
 
 `kubectl` is a command line interface for running commands against Kubernetes clusters. This overview covers `kubectl` syntax, describes the command operations, and provides common examples. For details about each command, including all the supported flags and subcommands, see the [kubectl](/docs/user-guide/kubectl) reference documentation. For installation instructions see [installing kubectl](/docs/tasks/kubectl/install/).
diff --git a/skip_toc_check.txt b/skip_toc_check.txt
index 4c5ebe2499..59639ead56 100644
--- a/skip_toc_check.txt
+++ b/skip_toc_check.txt
@@ -1,138 +1,125 @@
 # Put files you want to skip table of contents entry check here:
+docs/admin/apparmor/index.md
+docs/admin/audit.md
+docs/admin/cluster-components.md
+docs/admin/cluster-management.md
+docs/admin/cluster-troubleshooting.md
+docs/admin/daemons.md
+docs/admin/disruptions.md
+docs/admin/dns.md
+docs/admin/federation/kubefed.md
+docs/admin/index.md
+docs/admin/kubelet-authentication-authorization.md
+docs/admin/kubelet-tls-bootstrapping.md
+docs/admin/limitrange/index.md
+docs/admin/master-node-communication.md
+docs/admin/multi-cluster.md
+docs/admin/multiple-schedulers.md
+docs/admin/network-plugins.md
+docs/admin/networking.md
+docs/admin/node-problem.md
+docs/admin/node.md
+docs/admin/out-of-resource.md
+docs/admin/rescheduler.md
+docs/admin/resourcequota/index.md
+docs/admin/resourcequota/limitstorageconsumption.md
+docs/admin/resourcequota/walkthrough.md
+docs/admin/static-pods.md
+docs/admin/sysctls.md
+docs/api-reference/labels-annotations-taints.md
+docs/concepts/abstractions/pod-termination.md
+docs/contribute/README.md
+docs/contribute/create-pull-request.md
+docs/contribute/page-templates.md
+docs/contribute/review-issues.md
+docs/contribute/stage-documentation-changes.md
+docs/contribute/style-guide.md
+docs/contribute/write-new-topic.md
+docs/deprecation-policy.md
+docs/federation/api-reference/index.md
+docs/getting-started-guides/kubectl.md
+docs/home/deprecation-policy.md
+docs/home/security.md
 docs/search.md
 docs/sitemap.md
-docs/user-guide/pods/_viewing-a-pod.md
-docs/user-guide/simple-yaml.md
-docs/user-guide/walkthrough/index.md
-docs/user-guide/walkthrough/k8s201.md
-docs/user-guide/logging-demo/README.md
-docs/user-guide/downward-api/README.md
+docs/user-guide/accessing-the-cluster.md
+docs/user-guide/annotations.md
+docs/user-guide/application-troubleshooting.md
+docs/user-guide/compute-resources.md
+docs/user-guide/config-best-practices.md
 docs/user-guide/configmap/README.md
-docs/concepts/abstractions/pod-termination.md
-
-docs/user-guide/pods/init-container.md
-docs/user-guide/pod-states.md
+docs/user-guide/connecting-applications.md
+docs/user-guide/connecting-to-applications-port-forward.md
+docs/user-guide/connecting-to-applications-proxy.md
+docs/user-guide/container-environment.md
+docs/user-guide/debugging-pods-and-replication-controllers.md
+docs/user-guide/debugging-services.md
+docs/user-guide/deployments.md
+docs/user-guide/downward-api/README.md
 docs/user-guide/downward-api/index.md
 docs/user-guide/downward-api/volume/index.md
-docs/user-guide/getting-into-containers.md
-
-docs/user-guide/accessing-the-cluster.md
-docs/user-guide/working-with-resources.md
-docs/user-guide/garbage-collection.md
-docs/user-guide/services/operations.md
-docs/user-guide/load-balancer.md
-docs/user-guide/services-firewalls.md
-docs/user-guide/federation/federated-services.md
-docs/user-guide/pods/multi-container.md
 docs/user-guide/environment-guide/index.md
-docs/user-guide/compute-resources.md
-
-docs/user-guide/petset/bootstrapping/index.md
-docs/user-guide/monitoring.md
-docs/user-guide/logging/overview.md
-docs/user-guide/logging/stackdriver.md
-docs/user-guide/logging/elasticsearch.md
-docs/user-guide/connecting-to-applications-proxy.md
-docs/user-guide/connecting-to-applications-port-forward.md
-docs/admin/audit.md
-docs/admin/disruptions.md
-docs/admin/resourcequota/index.md
-docs/admin/resourcequota/walkthrough.md
-docs/admin/resourcequota/limitstorageconsumption.md
-docs/admin/rescheduler.md
-docs/admin/sysctls.md
-docs/admin/cluster-components.md
-
-docs/admin/multi-cluster.md
-docs/admin/networking.md
-docs/admin/dns.md
-docs/admin/network-plugins.md
-docs/admin/static-pods.md
-docs/admin/out-of-resource.md
-docs/admin/node-problem.md
-docs/admin/apparmor/index.md
 docs/user-guide/federation/configmap.md
 docs/user-guide/federation/daemonsets.md
 docs/user-guide/federation/deployment.md
 docs/user-guide/federation/events.md
 docs/user-guide/federation/federated-ingress.md
+docs/user-guide/federation/federated-services.md
+docs/user-guide/federation/index.md
 docs/user-guide/federation/namespaces.md
 docs/user-guide/federation/replicasets.md
 docs/user-guide/federation/secrets.md
-
-docs/home/security.md
-docs/deprecation-policy.md
-docs/home/deprecation-policy.md
-
-docs/whatisk8s.md
-
-docs/contribute/README.md
-
-docs/getting-started-guides/kubectl.md
-docs/user-guide/sharing-clusters.md
-docs/user-guide/kubeconfig-file.md
-docs/user-guide/prereqs.md
-
-docs/user-guide/managing-deployments.md
-docs/user-guide/replication-controller/operations.md
-docs/user-guide/resizing-a-replication-controller.md
-docs/user-guide/rolling-updates.md
-docs/user-guide/update-demo/index.md
-
+docs/user-guide/garbage-collection.md
+docs/user-guide/getting-into-containers.md
+docs/user-guide/horizontal-pod-autoscaling/index.md
+docs/user-guide/identifiers.md
+docs/user-guide/images.md
+docs/user-guide/ingress.md
+docs/user-guide/introspection-and-debugging.md
 docs/user-guide/jobs.md
 docs/user-guide/jobs/work-queue-1/index.md
 docs/user-guide/jobs/work-queue-2/index.md
-
-docs/user-guide/container-environment.md
-docs/user-guide/images.md
-docs/user-guide/volumes.md
-docs/user-guide/node-selection/index.md
-
-docs/user-guide/config-best-practices.md
-docs/user-guide/connecting-applications.md
-docs/user-guide/pod-templates.md
-docs/user-guide/persistent-volumes/index.md
-
-docs/admin/index.md
-docs/admin/cluster-management.md
-docs/admin/limitrange/index.md
-docs/admin/multiple-schedulers.md
-docs/admin/master-node-communication.md
-
-docs/admin/federation/kubefed.md
-docs/user-guide/federation/index.md
-
-docs/user-guide/debugging-pods-and-replication-controllers.md
-docs/user-guide/introspection-and-debugging.md
-docs/user-guide/application-troubleshooting.md
-docs/admin/cluster-troubleshooting.md
-docs/user-guide/debugging-services.md
-docs/contribute/create-pull-request.md
-docs/contribute/write-new-topic.md
-docs/contribute/stage-documentation-changes.md
-docs/contribute/page-templates.md
-docs/contribute/review-issues.md
-docs/contribute/style-guide.md
-
-docs/admin/daemons.md
-docs/user-guide/deployments.md
-docs/user-guide/replicasets.md
-docs/user-guide/replication-controller/index.md
-docs/user-guide/ingress.md
+docs/user-guide/kubeconfig-file.md
+docs/user-guide/load-balancer.md
+docs/user-guide/logging-demo/README.md
+docs/user-guide/logging/elasticsearch.md
+docs/user-guide/logging/overview.md
+docs/user-guide/logging/stackdriver.md
+docs/user-guide/managing-deployments.md
+docs/user-guide/monitoring.md
 docs/user-guide/namespaces.md
-docs/user-guide/identifiers.md
 docs/user-guide/networkpolicies.md
-docs/admin/node.md
+docs/user-guide/node-selection/index.md
+docs/user-guide/persistent-volumes/index.md
 docs/user-guide/petset.md
-docs/user-guide/pods/index.md
-
-docs/user-guide/replication-controller/index.md
-docs/user-guide/secrets/index.md
-docs/user-guide/security-context.md
-docs/user-guide/services/index.md
-docs/user-guide/service-accounts.md
-docs/user-guide/thirdpartyresources.md
+docs/user-guide/petset/bootstrapping/index.md
 docs/user-guide/pod-preset/index.md
 docs/user-guide/pod-security-policy/index.md
-docs/user-guide/horizontal-pod-autoscaling/index.md
-docs/user-guide/annotations.md
+docs/user-guide/pod-states.md
+docs/user-guide/pod-templates.md
+docs/user-guide/pods/_viewing-a-pod.md
+docs/user-guide/pods/index.md
+docs/user-guide/pods/init-container.md
+docs/user-guide/pods/multi-container.md
+docs/user-guide/prereqs.md
+docs/user-guide/replicasets.md
+docs/user-guide/replication-controller/index.md
+docs/user-guide/replication-controller/index.md
+docs/user-guide/replication-controller/operations.md
+docs/user-guide/resizing-a-replication-controller.md
+docs/user-guide/rolling-updates.md
+docs/user-guide/secrets/index.md
+docs/user-guide/security-context.md
+docs/user-guide/service-accounts.md
+docs/user-guide/services-firewalls.md
+docs/user-guide/services/index.md
+docs/user-guide/services/operations.md
+docs/user-guide/sharing-clusters.md
+docs/user-guide/simple-yaml.md
+docs/user-guide/thirdpartyresources.md
+docs/user-guide/update-demo/index.md
+docs/user-guide/volumes.md
+docs/user-guide/walkthrough/index.md
+docs/user-guide/walkthrough/k8s201.md
+docs/user-guide/working-with-resources.md
+docs/whatisk8s.md