From 315cfe10c60f37f19e680b9fc7e40d9ba3596f9b Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 30 Dec 2019 16:19:11 -0700 Subject: [PATCH 1/5] Add RKE command to show available K8s versions --- content/rke/latest/en/upgrades/_index.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/content/rke/latest/en/upgrades/_index.md b/content/rke/latest/en/upgrades/_index.md index c980c2e960d..5857ae5bda5 100644 --- a/content/rke/latest/en/upgrades/_index.md +++ b/content/rke/latest/en/upgrades/_index.md @@ -9,12 +9,20 @@ After RKE has deployed Kubernetes, you can upgrade the versions of the component > **Note:** RKE does not support rollback to previous versions. -To upgrade the Kubernetes version of an RKE provisioned cluster set the `kubernetes_version` string in the `cluster.yml` to the desired version from the list of supported Kubernetes versions for the specific version of RKE. You can find the list of supported Kubernetes versions for a specific version of RKE as documented at [Listing Supported Kubernetes Versions]({{< baseurl >}}/rke/latest/en/config-options/#listing-supported-kubernetes-versions.). +To upgrade the Kubernetes version of an RKE-provisioned cluster, set the `kubernetes_version` string in the `cluster.yml` to the desired version from the list of supported Kubernetes versions for the specific version of RKE: ```yaml kubernetes_version: "v1.15.5-rancher1-1" ``` +You can find the list of supported Kubernetes versions for a specific version of RKE as documented at [Listing Supported Kubernetes Versions]({{< baseurl >}}/rke/latest/en/config-options/#listing-supported-kubernetes-versions.). + +To see all of the Kubernetes versions that are available for your version of RKE, run the following command: + +``` +rke config -l -a +``` + > **Note:** In case both `kubernetes_version` and `system_images` are defined, the `system_images` configuration will take precedence over `kubernetes_version`. In addition, if neither `kubernetes_version` nor `system_images` are configured in the `cluster.yml`, RKE will apply the default Kubernetes version for the specific version of RKE used to invoke `rke up`. The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/). Having configured the `kubernetes_version`, ensure that any `system_images` configuration is absent from the `cluster.yml`, and then invoke `rke up` to upgrade Kubernetes. From 158a512d007ec03e767de2ed9bdedb58bcdbe582 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 13 Jan 2020 14:39:38 -0700 Subject: [PATCH 2/5] Remove duplicated section --- content/rke/latest/en/upgrades/_index.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/content/rke/latest/en/upgrades/_index.md b/content/rke/latest/en/upgrades/_index.md index 5857ae5bda5..b9ebd292167 100644 --- a/content/rke/latest/en/upgrades/_index.md +++ b/content/rke/latest/en/upgrades/_index.md @@ -15,13 +15,7 @@ To upgrade the Kubernetes version of an RKE-provisioned cluster, set the `kubern kubernetes_version: "v1.15.5-rancher1-1" ``` -You can find the list of supported Kubernetes versions for a specific version of RKE as documented at [Listing Supported Kubernetes Versions]({{< baseurl >}}/rke/latest/en/config-options/#listing-supported-kubernetes-versions.). - -To see all of the Kubernetes versions that are available for your version of RKE, run the following command: - -``` -rke config -l -a -``` +You can find the list of supported Kubernetes versions for a specific version of RKE as documented at [Listing Supported Kubernetes Versions]({{< baseurl >}}/rke/latest/en/config-options/#listing-supported-kubernetes-versions). > **Note:** In case both `kubernetes_version` and `system_images` are defined, the `system_images` configuration will take precedence over `kubernetes_version`. In addition, if neither `kubernetes_version` nor `system_images` are configured in the `cluster.yml`, RKE will apply the default Kubernetes version for the specific version of RKE used to invoke `rke up`. The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/). From 58f8486b6e1d4c69fda823168f1996b46af0329a Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 13 Jan 2020 17:46:58 -0700 Subject: [PATCH 3/5] Move Kubernetes versions command to upgrades section --- .../rke/latest/en/config-options/_index.md | 22 +----- content/rke/latest/en/upgrades/_index.md | 72 ++++++++++++++----- 2 files changed, 57 insertions(+), 37 deletions(-) diff --git a/content/rke/latest/en/config-options/_index.md b/content/rke/latest/en/config-options/_index.md index 64cb99d8932..387bf4d0543 100644 --- a/content/rke/latest/en/config-options/_index.md +++ b/content/rke/latest/en/config-options/_index.md @@ -75,27 +75,7 @@ In case both `kubernetes_version` and [system images]({{< baseurl >}}/rke/latest > - For RKE v0.3.0+, the service defaults are located [here](https://github.com/rancher/kontainer-driver-metadata/blob/master/rke/k8s_service_options.go). > - For RKE prior to v0.3.0, the service defaults are located [here](https://github.com/rancher/types/blob/release/v2.2/apis/management.cattle.io/v3/k8s_defaults.go). Note: The version in the path of the service defaults file corresponds to a Rancher version. Therefore, for Rancher v2.1.x, [this file](https://github.com/rancher/types/blob/release/v2.1/apis/management.cattle.io/v3/k8s_defaults.go) should be used. -#### Listing Supported Kubernetes Versions - -Please refer to the [release notes](https://github.com/rancher/rke/releases) of the RKE version that you are running, to find the list of supported Kubernetes versions as well as the default Kubernetes version. - -You can also list the supported versions and system images of specific version of RKE release with a quick command. - -``` -$ rke config --list-version --all -v1.15.3-rancher2-1 -v1.13.10-rancher1-2 -v1.14.6-rancher2-1 -v1.16.0-beta.1-rancher1-1 -``` - -#### Using an unsupported Kubernetes version - -As of v0.2.0, if a version is defined in `kubernetes_version` and is not found in the specific list of supported Kubernetes versions, then RKE will error out. - -Prior to v0.2.0, if a version is defined in `kubernetes_version` and is not found in the specific list of supported Kubernetes versions, the default version from the supported list is used. - -If you want to use a different version from the supported list, please use the [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) option. +For the command to list all of the supported Kubernetes versions, refer to [this section.]({{}}/rke/latest/en/upgrades/#listing-supported-kubernetes-versions) ### Prefix Path diff --git a/content/rke/latest/en/upgrades/_index.md b/content/rke/latest/en/upgrades/_index.md index b9ebd292167..6d878159e1e 100644 --- a/content/rke/latest/en/upgrades/_index.md +++ b/content/rke/latest/en/upgrades/_index.md @@ -5,9 +5,49 @@ weight: 100 After RKE has deployed Kubernetes, you can upgrade the versions of the components in your Kubernetes cluster, [definition of the Kubernetes services]({{< baseurl >}}/rke/latest/en/config-options/services/) or [add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/). -## Kubernetes Version Upgrades +### Prerequisites for Upgrading Kubernetes -> **Note:** RKE does not support rollback to previous versions. +- Having configured the `kubernetes_version`, ensure that any `system_images` configuration is absent from the `cluster.yml`. For details on how `system_images` configuration can affect the upgrade, refer to the section on [Kubernetes version precedence.](#kubernetes-version-precedence) +- Ensure that the correct files to manage [Kubernetes cluster state]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state) are present in the working directory. Refer to the tabs below for the required files, which differ based on the RKE version. + +{{% tabs %}} +{{% tab "RKE v0.2.0+" %}} +The `cluster.rkestate` file contains the current state of the cluster including the RKE configuration and the certificates. + +This file is created in the same directory that has the cluster configuration file `cluster.yml`. + +It is required to keep the `cluster.rkestate` file to perform any operation on the cluster through RKE, or when upgrading a cluster last managed via RKE v0.2.0 or later. +{{% /tab %}} +{{% tab "RKE prior to v0.2.0" %}} +Ensure that the `kube_config_cluster.yml` file is present in the working directory. + +RKE saves the Kubernetes cluster state as a secret. When updating the state, RKE pulls the secret, updates or changes the state, and saves a new secret. The `kube_config_cluster.yml` file is required for upgrading a cluster last managed via RKE v0.1.x. +{{% /tab %}} +{{% /tabs %}} + +### Listing Supported Kubernetes Versions + +Please refer to the [release notes](https://github.com/rancher/rke/releases) of the RKE version that you are running, to find the list of supported Kubernetes versions as well as the default Kubernetes version. + +You can also list the supported versions and system images of specific version of RKE release with a quick command. + +``` +$ rke config --list-version --all +v1.15.3-rancher2-1 +v1.13.10-rancher1-2 +v1.14.6-rancher2-1 +v1.16.0-beta.1-rancher1-1 +``` + +### Kubernetes Version Precedence + +In case both `kubernetes_version` and `system_images` are defined, the `system_images` configuration will take precedence over `kubernetes_version`. + +In addition, if neither `kubernetes_version` nor `system_images` are configured in the `cluster.yml`, RKE will apply the default Kubernetes version for the specific version of RKE used to invoke `rke up`. + +### Kubernetes Version Upgrades + +> **Note:** RKE does not support rolling back to previous versions. To upgrade the Kubernetes version of an RKE-provisioned cluster, set the `kubernetes_version` string in the `cluster.yml` to the desired version from the list of supported Kubernetes versions for the specific version of RKE: @@ -15,30 +55,30 @@ To upgrade the Kubernetes version of an RKE-provisioned cluster, set the `kubern kubernetes_version: "v1.15.5-rancher1-1" ``` -You can find the list of supported Kubernetes versions for a specific version of RKE as documented at [Listing Supported Kubernetes Versions]({{< baseurl >}}/rke/latest/en/config-options/#listing-supported-kubernetes-versions). - -> **Note:** In case both `kubernetes_version` and `system_images` are defined, the `system_images` configuration will take precedence over `kubernetes_version`. In addition, if neither `kubernetes_version` nor `system_images` are configured in the `cluster.yml`, RKE will apply the default Kubernetes version for the specific version of RKE used to invoke `rke up`. The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/). - -Having configured the `kubernetes_version`, ensure that any `system_images` configuration is absent from the `cluster.yml`, and then invoke `rke up` to upgrade Kubernetes. - -It is important to ensure that the correct files to manage [Kubernetes cluster state]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state) are present in the working directory when invoking `rke up` to upgrade the cluster. - -- In v0.1.x, RKE saved the Kubernetes cluster state as a secret. When updating the state, RKE pulls the secret, updates/changes the state and saves a new secret. When upgrading a cluster last managed via RKE v0.1.x you should ensure the `kube_config_cluster.yml` file is present in the working directory when invoking `rke up`. -- As of v0.2.0, RKE creates a `cluster.rkestate` file in the same directory that has the cluster configuration file `cluster.yml`. The `cluster.rkestate` file contains the current state of the cluster including the RKE configuration and the certificates. It is required to keep this file in order to update the cluster or perform any operation on it through RKE. When upgrading a cluster last managed via RKE v0.2.0 or later, you should ensure the `cluster.rkestate` file is present in the working directory when invoking `rke up`. - -When all the prerequisites described above are fulfilled, you can invoke `rke up`: +Then invoke `rke up`: ``` $ rke up --config cluster.yml ``` +### Default Kubernetes Version -## Service Upgrades +The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/). + +### Using an unsupported Kubernetes version + +As of v0.2.0, if a version is defined in `kubernetes_version` and is not found in the specific list of supported Kubernetes versions, then RKE will error out. + +Prior to v0.2.0, if a version is defined in `kubernetes_version` and is not found in the specific list of supported Kubernetes versions, the default version from the supported list is used. + +If you want to use a different version from the supported list, please use the [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) option. + +### Service Upgrades [Services]({{< baseurl >}}/rke/latest/en/config-options/services/) can be upgraded by changing any of the services arguments or `extra_args` and running `rke up` again with the updated configuration file. > **Note:** The following arguments, `service_cluster_ip_range` or `cluster_cidr`, cannot be changed as any changes to these arguments will result in a broken cluster. Currently, network pods are not automatically upgraded. -## Add-Ons Upgrades +### Add-Ons Upgrades As of v0.1.8, upgrades to add-ons are supported. From 286923ce5c29f98a7f18ec34903fc0fb5c12c42d Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Mon, 13 Jan 2020 18:17:26 -0700 Subject: [PATCH 4/5] Clean up RKE upgrades doc --- content/rke/latest/en/upgrades/_index.md | 48 +++++++++++++++--------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/content/rke/latest/en/upgrades/_index.md b/content/rke/latest/en/upgrades/_index.md index 6d878159e1e..9cb8720dc55 100644 --- a/content/rke/latest/en/upgrades/_index.md +++ b/content/rke/latest/en/upgrades/_index.md @@ -5,9 +5,20 @@ weight: 100 After RKE has deployed Kubernetes, you can upgrade the versions of the components in your Kubernetes cluster, [definition of the Kubernetes services]({{< baseurl >}}/rke/latest/en/config-options/services/) or [add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/). -### Prerequisites for Upgrading Kubernetes +This page covers the following topics: -- Having configured the `kubernetes_version`, ensure that any `system_images` configuration is absent from the `cluster.yml`. For details on how `system_images` configuration can affect the upgrade, refer to the section on [Kubernetes version precedence.](#kubernetes-version-precedence) +- [Prerequisites](#prerequisites) +- [Upgrading Kubernetes](#upgrading-kubernetes) +- [Listing supported Kubernetes versions](#listing-supported-kubernetes-versions) +- [Kubernetes version precedence](#kubernetes-version-precedence) +- [Default Kubernetes version](#default-kubernetes-version) +- [Using an unsupported Kubernetes version](#using-an-unsupported-kubernetes-version) +- [Service upgrades](#service-upgrades) +- [Add-ons upgrades](#add-ons-upgrades) + +### Prerequisites + +- Ensure that any `system_images` configuration is absent from the `cluster.yml`. The Kubernetes version should only be listed under the `system_images` directive if an [unsupported version](#using-an-unsupported-kubernetes-version) is being used. For details on how `system_images` configuration can affect the upgrade, refer to the section on [Kubernetes version precedence.](#kubernetes-version-precedence) - Ensure that the correct files to manage [Kubernetes cluster state]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state) are present in the working directory. Refer to the tabs below for the required files, which differ based on the RKE version. {{% tabs %}} @@ -25,6 +36,22 @@ RKE saves the Kubernetes cluster state as a secret. When updating the state, RKE {{% /tab %}} {{% /tabs %}} +### Upgrading Kubernetes + +> **Note:** RKE does not support rolling back to previous versions. + +To upgrade the Kubernetes version of an RKE-provisioned cluster, set the `kubernetes_version` string in the `cluster.yml` to the desired version from the [list of supported Kubernetes versions](#listing-supported-kubernetes-versions) for the specific version of RKE: + +```yaml +kubernetes_version: "v1.15.5-rancher1-1" +``` + +Then invoke `rke up`: + +``` +$ rke up --config cluster.yml +``` + ### Listing Supported Kubernetes Versions Please refer to the [release notes](https://github.com/rancher/rke/releases) of the RKE version that you are running, to find the list of supported Kubernetes versions as well as the default Kubernetes version. @@ -45,26 +72,11 @@ In case both `kubernetes_version` and `system_images` are defined, the `system_i In addition, if neither `kubernetes_version` nor `system_images` are configured in the `cluster.yml`, RKE will apply the default Kubernetes version for the specific version of RKE used to invoke `rke up`. -### Kubernetes Version Upgrades - -> **Note:** RKE does not support rolling back to previous versions. - -To upgrade the Kubernetes version of an RKE-provisioned cluster, set the `kubernetes_version` string in the `cluster.yml` to the desired version from the list of supported Kubernetes versions for the specific version of RKE: - -```yaml -kubernetes_version: "v1.15.5-rancher1-1" -``` - -Then invoke `rke up`: - -``` -$ rke up --config cluster.yml -``` ### Default Kubernetes Version The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/). -### Using an unsupported Kubernetes version +### Using an Unsupported Kubernetes Version As of v0.2.0, if a version is defined in `kubernetes_version` and is not found in the specific list of supported Kubernetes versions, then RKE will error out. From 54c7fdbb8a37e24f46883fbeed4935e848b3ddc7 Mon Sep 17 00:00:00 2001 From: Catherine Luse Date: Tue, 14 Jan 2020 11:16:49 -0700 Subject: [PATCH 5/5] Move Kubernetes version info from config options to upgrades --- .../rke/latest/en/config-options/_index.md | 17 ++---------- content/rke/latest/en/upgrades/_index.md | 26 ++++++++++++++----- 2 files changed, 21 insertions(+), 22 deletions(-) diff --git a/content/rke/latest/en/config-options/_index.md b/content/rke/latest/en/config-options/_index.md index 387bf4d0543..ecf29f2a412 100644 --- a/content/rke/latest/en/config-options/_index.md +++ b/content/rke/latest/en/config-options/_index.md @@ -60,22 +60,9 @@ ignore_docker_version: true ### Kubernetes Version -By default, RKE is defaulted to launch with a specific Kubernetes version. You can also select a different version of Kubernetes to install for your cluster. Each version of RKE has a specific list of supported Kubernetes versions. +For information on upgrading Kubernetes, refer to the [upgrade section.]({{}}/rke/latest/en/upgrades/) -You can set the Kubernetes version as follows: - -```yaml -kubernetes_version: "v1.11.6-rancher1-1" -``` - -In case both `kubernetes_version` and [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) are defined, the system images configuration will take precedence over `kubernetes_version`. - -> **Note:** In RKE, `kubernetes_version` is used to map the version of Kubernetes to the default services, parameters, and options: - -> - For RKE v0.3.0+, the service defaults are located [here](https://github.com/rancher/kontainer-driver-metadata/blob/master/rke/k8s_service_options.go). -> - For RKE prior to v0.3.0, the service defaults are located [here](https://github.com/rancher/types/blob/release/v2.2/apis/management.cattle.io/v3/k8s_defaults.go). Note: The version in the path of the service defaults file corresponds to a Rancher version. Therefore, for Rancher v2.1.x, [this file](https://github.com/rancher/types/blob/release/v2.1/apis/management.cattle.io/v3/k8s_defaults.go) should be used. - -For the command to list all of the supported Kubernetes versions, refer to [this section.]({{}}/rke/latest/en/upgrades/#listing-supported-kubernetes-versions) +Rolling back to previous Kubernetes versions is not supported. ### Prefix Path diff --git a/content/rke/latest/en/upgrades/_index.md b/content/rke/latest/en/upgrades/_index.md index 9cb8720dc55..5e47ee6ab09 100644 --- a/content/rke/latest/en/upgrades/_index.md +++ b/content/rke/latest/en/upgrades/_index.md @@ -3,7 +3,15 @@ title: Upgrades weight: 100 --- -After RKE has deployed Kubernetes, you can upgrade the versions of the components in your Kubernetes cluster, [definition of the Kubernetes services]({{< baseurl >}}/rke/latest/en/config-options/services/) or [add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/). +After RKE has deployed Kubernetes, you can upgrade the versions of the components in your Kubernetes cluster, the [definition of the Kubernetes services]({{< baseurl >}}/rke/latest/en/config-options/services/) or the [add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/). + +The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/). + +You can also select a newer version of Kubernetes to install for your cluster. Downgrading Kubernetes is not supported. + +Each version of RKE has a specific [list of supported Kubernetes versions.](#listing-supported-kubernetes-versions) + +In case the Kubernetes version is defined in the `kubernetes_version` directive and under the `system-images` directive are defined, the `system-images` configuration will take precedence over `kubernetes_version`. This page covers the following topics: @@ -11,14 +19,14 @@ This page covers the following topics: - [Upgrading Kubernetes](#upgrading-kubernetes) - [Listing supported Kubernetes versions](#listing-supported-kubernetes-versions) - [Kubernetes version precedence](#kubernetes-version-precedence) -- [Default Kubernetes version](#default-kubernetes-version) - [Using an unsupported Kubernetes version](#using-an-unsupported-kubernetes-version) +- [Mapping the Kubernetes version to services](#mapping-the-kubernetes-version-to-services) - [Service upgrades](#service-upgrades) - [Add-ons upgrades](#add-ons-upgrades) ### Prerequisites -- Ensure that any `system_images` configuration is absent from the `cluster.yml`. The Kubernetes version should only be listed under the `system_images` directive if an [unsupported version](#using-an-unsupported-kubernetes-version) is being used. For details on how `system_images` configuration can affect the upgrade, refer to the section on [Kubernetes version precedence.](#kubernetes-version-precedence) +- Ensure that any `system_images` configuration is absent from the `cluster.yml`. The Kubernetes version should only be listed under the `system_images` directive if an [unsupported version](#using-an-unsupported-kubernetes-version) is being used. Refer to [Kubernetes version precedence](#kubernetes-version-precedence) for more information. - Ensure that the correct files to manage [Kubernetes cluster state]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state) are present in the working directory. Refer to the tabs below for the required files, which differ based on the RKE version. {{% tabs %}} @@ -72,10 +80,6 @@ In case both `kubernetes_version` and `system_images` are defined, the `system_i In addition, if neither `kubernetes_version` nor `system_images` are configured in the `cluster.yml`, RKE will apply the default Kubernetes version for the specific version of RKE used to invoke `rke up`. -### Default Kubernetes Version - -The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/). - ### Using an Unsupported Kubernetes Version As of v0.2.0, if a version is defined in `kubernetes_version` and is not found in the specific list of supported Kubernetes versions, then RKE will error out. @@ -84,6 +88,14 @@ Prior to v0.2.0, if a version is defined in `kubernetes_version` and is not foun If you want to use a different version from the supported list, please use the [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) option. +### Mapping the Kubernetes Version to Services + +In RKE, `kubernetes_version` is used to map the version of Kubernetes to the default services, parameters, and options. + +For RKE v0.3.0+, the service defaults are located [here](https://github.com/rancher/kontainer-driver-metadata/blob/master/rke/k8s_service_options.go). + +For RKE prior to v0.3.0, the service defaults are located [here](https://github.com/rancher/types/blob/release/v2.2/apis/management.cattle.io/v3/k8s_defaults.go). Note: The version in the path of the service defaults file corresponds to a Rancher version. Therefore, for Rancher v2.1.x, [this file](https://github.com/rancher/types/blob/release/v2.1/apis/management.cattle.io/v3/k8s_defaults.go) should be used. + ### Service Upgrades [Services]({{< baseurl >}}/rke/latest/en/config-options/services/) can be upgraded by changing any of the services arguments or `extra_args` and running `rke up` again with the updated configuration file.