Add clarifying language about supported version skews

kubernetes · May 5, 2016 · e618e33 · e618e33
1 parent f29d597
commit e618e33
Showing 1 changed file with 17 additions and 10 deletions.
diff --git a/docs/design/versioning.md b/docs/design/versioning.md
@@ -95,27 +95,34 @@ X.Y.Z-beta.W, with an additional +bbbb build suffix added. Furthermore, builds
 that are built off of a dirty build tree, (during development, with things in
 the tree that are not checked it,) it will be appended with -dirty.
 
-### Supported releases
+### Supported releases and component skew
 
 We expect users to stay reasonably up-to-date with the versions of Kubernetes
-they use in production, but understand that it may take time to upgrade.
+they use in production, but understand that it may take time to upgrade,
+especially for production-critical components.
 
 We expect users to be running approximately the latest patch release of a given
 minor release; we often include critical bug fixes in
 [patch releases](#patch-release), and so encourage users to upgrade as soon as
-possible. Furthermore, we expect to "support" three minor releases at a time.
-"Support" means we expect users to be running that version in production, though
-we may not port fixes back before the latest minor version. For example, when
-v1.3 comes out, v1.0 will no longer be supported: basically, that means that the
+possible.
+
+Different components are expected to be compatible across different amounts of
+skew, all relative to the master version.  Nodes may lag masters components by
+up to two minor versions but should be at a version no newer than the master; a
+client should be skewed no more than one minor version from the master, but may
+lead the master by up to one minor version.  For example, a v1.3 master should
+work with v1.1, v1.2, and v1.3 nodes, and should work with v1.2, v1.3, and v1.4
+clients.
+
+Furthermore, we expect to "support" three minor releases at a time.  "Support"
+means we expect users to be running that version in production, though we may
+not port fixes back before the latest minor version. For example, when v1.3
+comes out, v1.0 will no longer be supported: basically, that means that the
 reasonable response to the question "my v1.0 cluster isn't working," is, "you
 should probably upgrade it, (and probably should have some time ago)". With
 minor releases happening approximately every three months, that means a minor
 release is supported for approximately nine months.
 
-This does *not* mean that we expect to introduce breaking changes between v1.0
-and v1.3, but it does mean that we probably won't have reasonable confidence in
-clusters where some components are running at v1.0 and others running at v1.3.
-
 This policy is in line with
 [GKE's supported upgrades policy](https://cloud.google.com/container-engine/docs/clusters/upgrade).