github.com/jlmeeker/kismatic@v1.10.1-0.20180612190640-57f9005a1f1a/docs/design-decisions/decouple-versions.md (about) 1 # Decouple Components Versions from KET Version 2 3 ## Motivation 4 5 KET is used to install Kubernetes and many other components in the cluster. Historically the version of Kubernetes and all other components versions were tied to a version of KET. 6 7 For example KET `v1.7.0` can only install a cluster with Kubernetes `v1.9.0` and when the next version of Kubernetes is released KET would need to update its own version. 8 9 This has been working fine while KET was in active development, however as it became more stable and the release cycle slows down many KET releases will only contain the Kubernetes version change. 10 11 To alleviate the pressure on the KET team to release with every Kubernetes `Patch` version and to also allow users to stay with the latest bug fixes, the version of Kubernetes should be decoupled from the version of KET. 12 Decoupling of Kubernetes will be done first and the decoupling of all other components that are installed can be discussed at a later time. 13 14 ## Kubernetes Versions 15 16 Kubernetes follows the semantic versioning schema `X.Y.Z` - `Major.Minor.Patch` 17 18 The latest version as of this writing is `v1.9.0` 19 20 The Kubernetes release cadence has become quite stable, with a new `Minor` version about every 3 months and a `Patch` release about every 2 weeks. 21 22 --- 23 24 `Minor` releases will contain API changes and may contain docker and etcd changes, in addition to other components changes, ie `dashboard`, `kube-dns`, `heapster` etc. 25 26 --- 27 28 `Patch` releases are intended for critical bug fixes to the latest minor version, such as addressing security vulnerabilities, fixes to problems affecting a large number of users, severe problems with no workaround, and blockers for products based on Kubernetes. 29 30 They should not contain miscellaneous feature additions or improvements, and especially no incompatibilities should be introduced between patch versions of the same minor version. 31 32 ## KET Versions 33 34 KET follows the semantic versioning schema `X.Y.Z` - `Major.Minor.Patch` 35 36 The latest version as of this writing is `v1.7.0` 37 38 KET had a release cycle of about every 8 weeks for a `Minor` version and 2-3 weeks for a `Patch` version. 39 40 --- 41 42 `Minor` releases contained larger changes, but more importantly a Kubernetes `Minor` change could only be upgraded on a KET `Minor` release. 43 44 --- 45 `Patch` releases are smaller bug fixes and improvements. 46 47 --- 48 49 KET has always been up to date with the latest Kubernetes `Minor` version within 2 weeks of the release, however the Kubernetes `Patch` version tracking has been a "best effort" approach and not guaranteed to be at the latest. KET has also never retroactively released a `Patch` version of previous `Minor`. 50 51 ## Implementation 52 53 A particular `Minor` release of KET will support **any** `Patch` version of Kubernetes. (Note multiple consecutive `Minor` versions of KET can support the same `Minor` version of Kubernetes, until KET is updated to support a new version of Kubernetes). 54 55 As discussed above, Kubernetes `Minor` changes will contain component and API changes and testing is required before KET can support and certify a new Kubernetes `Minor` release. 56 57 By contrast, Kubernetes `Patch` versions will only contain bug fixes and smaller patches and it should be safe to use any `Patch` version, and is actually recommended by the Kubernetes team to always use the latest patch version. 58 59 The tested and default Kubernetes `Patch` versions will still be upgraded whenever there are other KET bug fixes, however a new `Patch` version will NOT be released for the sole purpose of upgrading a Kubernetes `Patch` version. 60 61 ### Example Versions 62 63 | KET Version | 1.8.0 | 1.8.1 | 1.8.2 | 1.9.0 | 1.10.0 | 64 |------------------------------|---------------|---------------|-------------|-------------|---------------| 65 | Tested Kubernetes Version | 1.9.1 | 1.9.2 | 1.9.2 | 1.9.4 | 1.10.0 | 66 | Supported Kubernetes Version | 1.9.x | 1.9.x | 1.9.x | 1.9.x | 1.10.x | 67 68 ### Plan File Changes 69 70 ``` yaml 71 # Set component versions to install. 72 cluster: 73 version: "v1.9.0" 74 ... 75 ``` 76 77 A new optional field will be added that will contain the Kubernetes `version` under the existing `cluster` tag. 78 79 ### Install Changes 80 81 When running `kismatic install plan` the version will be set to the version the the KET binary was built and tested with. 82 83 The `kubernetes` version string will also be validated to be the supported `Minor` version and less than or equal to the latest stable version of that `Minor` from: 84 ``` bash 85 https://storage.googleapis.com/kubernetes-release/release/stable-1.9.txt 86 ``` 87 If the latest version cannot be fetched KET will only validate that the provided version the supported `Minor` version, it will be up to the user to select an existing valid version. This is required to support disconnected installs and any when errors retrieving latest stable version. 88 89 The `kubernetes` version will be propagated to Ansible: 90 ``` yaml 91 kube_proxy: 92 name: gcr.io/google-containers/kube-proxy-amd64 93 version: "v1.9.0" 94 kube_controller_manager: 95 name: gcr.io/google-containers/kube-controller-manager-amd64 96 version: "v1.9.0" 97 kube_scheduler: 98 name: gcr.io/google-containers/kube-scheduler-amd64 99 version: "v1.9.0" 100 kube_apiserver: 101 name: gcr.io/google-containers/kube-apiserver-amd64 102 version: "v1.9.0" 103 ``` 104 105 **NOTE:** The `kubectl` version in the released tar will always be the default version. 106 107 ### Upgrade Changes 108 109 With current version of KET prior tp upgrade the installer reads `/etc/kismatic-version` on all of the nodes to determine if the upgrade should proceed on the node. This will no longer be enough as the user may want to upgrade to a newer Kubernetes `Patch` version using the same KET version. 110 111 A new file will be placed in `/etc/installed-components.yaml`: 112 113 ``` yaml 114 versions: 115 kubernetes: "v1.9.0" 116 ``` 117 118 This new file will then also be read to determine if the node needs to be upgraded. 119 120 ## Considerations 121 122 If there is a concern with installing a cluster with an untested Kubernetes version, the user can always leave the version field empty (or set it the version specified in the release notes). This would guarantee that the Kubernetes version used in the installation has been tested during the KET release process. 123 124 For the initial implementation of components decoupling only the Kubernetes version will be supported and this feature will be expanded to other components in the cluster at a later time.