github.com/apprenda/kismatic@v1.12.0/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.