Merge pull request #2763 from kubernetes/etcd3

Added 1.6 Upgrade notes to outline changes for etcd 3.

_data/guides.yml

@@ -169,6 +169,7 @@ toc:
   section:
   - docs/admin/index.md
   - docs/admin/cluster-management.md
+  - docs/admin/upgrade-1-6.md
   - docs/admin/kubeadm.md
   - docs/admin/addons.md
   - docs/admin/audit.md

docs/admin/cluster-management.md

@@ -19,7 +19,9 @@ To install Kubernetes on a set of machines, consult one of the existing [Getting
 
 ## Upgrading a cluster
 
-The current state of cluster upgrades is provider dependent.
+The current state of cluster upgrades is provider dependent, and some releases may require special care when upgrading. It is recommended that administrators consult both the [release notes](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md), as well as the version specific upgrade notes prior to upgrading their clusters.  
+
+* [Upgrading to 1.6](/docs/admin/upgrade)
 
 ### Upgrading Google Compute Engine clusters
 
@@ -56,8 +58,12 @@ The node upgrade process is user-initiated and is described in the [GKE document
 
 ### Upgrading clusters on other platforms
 
-The `cluster/kube-push.sh` script will do a rudimentary update.  This process is still quite experimental, we
-recommend testing the upgrade on an experimental cluster before performing the update on a production cluster.
+Different providers, and tools, will manage upgrades differently.  It is recommended that you consult their main documentation regarding upgrades. 
+
+* [kops](https://github.com/kubernetes/kops)
+* [kargo](https://github.com/kubernetes-incubator/kargo)
+* [CoreOS Tectonic](https://coreos.com/tectonic/docs/latest/admin/upgrade.html)
+* ... 
 
 ## Resizing a cluster
 

docs/admin/upgrade-1-6.md

@@ -0,0 +1,26 @@
+---
+assignees:
+- mml
+title: Cluster Management Guide
+---
+
+* TOC
+{:toc}
+
+This document outlines the potentially disruptive changes that exist in the 1.6 release cycle.  Operators, administrators, and developers should 
+take note of the changes below in order to maintain continuity across their upgrade process. 
+
+## Cluster defaults set to etcd 3 
+
+In the 1.6 release cycle, the default backend storage layer has been upgraded to fully leverage [etcd 3 capabilities](https://coreos.com/blog/etcd3-a-new-etcd.html) by default.  
+For new clusters, there is nothing an operator will need to do, it should "just work".  However, if you are upgrading from a 1.5 cluster, care should be taken to ensure 
+continuity.  
+
+It is possible to maintain v2 compatibility mode while running etcd 3 for an interim period of time.  To do this, you will simply need to update an argument passed to your apiserver during 
+startup: 
+
+```
+$ kube-apiserver --storage-backend='etcd2' $(EXISTING_ARGS)
+``` 
+
+However, for long-term maintenance of the cluster, we recommend that the operator plan an outage window in order to perform a [v2->v3 data upgrade](https://coreos.com/etcd/docs/latest/upgrades/upgrade_3_0.html).