diff --git a/docs/design/versioning.md b/docs/design/versioning.md index 4d387af9f26..f6b8efafe28 100644 --- 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).