From 3c46506472d64013e081db55261e0aaa4434e6dc Mon Sep 17 00:00:00 2001 From: Sherlock113 <65327072+Sherlock113@users.noreply.github.com> Date: Wed, 28 Apr 2021 22:27:11 +0800 Subject: [PATCH] Update KS 3.1 upgrade guide (#1454) * Update KS 3.1 upgrade guide Signed-off-by: Sherlock113 * minor fix Signed-off-by: Sherlock113 * Update ks-installer and kk download link Signed-off-by: Sherlock113 --- content/en/docs/upgrade/overview.md | 26 ++---- .../docs/upgrade/upgrade-with-ks-installer.md | 41 +++------ .../en/docs/upgrade/upgrade-with-kubekey.md | 84 ++++++++++--------- 3 files changed, 63 insertions(+), 88 deletions(-) diff --git a/content/en/docs/upgrade/overview.md b/content/en/docs/upgrade/overview.md index 96fc9d2e6..bc26c1921 100644 --- a/content/en/docs/upgrade/overview.md +++ b/content/en/docs/upgrade/overview.md @@ -1,24 +1,18 @@ --- title: "Upgrade — Overview" -keywords: "Kubernetes, upgrade, KubeSphere, v3.0.0, upgrade" +keywords: "Kubernetes, upgrade, KubeSphere, v3.1.0, upgrade" description: "Understand what you need to pay attention to before the upgrade, such as versions and upgrade tools." linkTitle: "Overview" weight: 7100 --- -## Kubernetes +## Make Your Upgrade Plan -KubeSphere v3.0.0 is compatible with Kubernetes 1.15.x, 1.16.x, 1.17.x and 1.18.x: +KubeSphere v3.1.0 is compatible with Kubernetes 1.17.x, 1.18.x, 1.19.x and 1.20.x: -- If your KubeSphere v2.1.x is installed on Kubernetes 1.15.x+, you can choose to only upgrade KubeSphere to v3.0.0 or upgrade Kubernetes (to a higher version) and KubeSphere (to v3.0.0) at the same time. - -- If your KubeSphere v2.1.x is installed on Kubernetes 1.14.x, you have to upgrade Kubernetes (to 1.15.x+) and KubeSphere (to v3.0.0 ) at the same time. - -{{< notice warning >}} - -There are some significant API changes in Kubernetes 1.16.x compared with prior versions 1.14.x and 1.15.x. Refer to [Deprecated APIs Removed In 1.16: Here’s What You Need To Know](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/) for more details. So if you plan to upgrade from Kubernetes 1.14.x/1.15.x to 1.16.x+, you have to migrate some of your workloads after upgrading. - -{{}} +- Before you upgrade your cluster to KubeSphere v3.1.0, you need to have a KubeSphere cluster running v3.0.0. +- If your exiting KubeSphere v3.0.0 cluster is installed on Kubernetes 1.17.x+, you can choose to only upgrade KubeSphere to v3.1.0 or upgrade Kubernetes (to a higher version) and KubeSphere (to v3.1.0) at the same time. +- If your existing KubeSphere v3.0.0 cluster is installed on Kubernetes 1.16.x or earlier, you have to upgrade Kubernetes (to 1.17.x+) and KubeSphere (to v3.1.0 ) at the same time. ## Before the Upgrade @@ -26,14 +20,10 @@ There are some significant API changes in Kubernetes 1.16.x compared with prior - You are supposed to implement a simulation for the upgrade in a testing environment first. After the upgrade is successful in the testing environment and all applications are running normally, upgrade your cluster in your production environment. - During the upgrade process, there may be a short interruption of applications (especially for those single-replica Pods). Please arrange a reasonable period of time for your upgrade. -- It is recommended to back up ETCD and stateful applications before upgrading in a production environment. You can use [Velero](https://velero.io/) to implement the backup and migrate Kubernetes resources and persistent volumes. +- It is recommended to back up etcd and stateful applications before in production. You can use [Velero](https://velero.io/) to implement the backup and migrate Kubernetes resources and persistent volumes. {{}} ## Upgrade Tool -A brand-new installer [KubeKey](https://github.com/kubesphere/kubekey) is introduced in KubeSphere v3.0.0, with which you can install or upgrade Kubernetes and KubeSphere. For more information, see [Upgrade with KubeKey](../upgrade-with-kubekey/). - -## KubeKey or ks-installer - -[ks-installer](https://github.com/kubesphere/ks-installer/tree/master) was the main installation tool as of KubeSphere v2. For users whose Kubernetes clusters were NOT deployed via [KubeSphere Installer](https://v2-1.docs.kubesphere.io/docs/installation/all-in-one/#step-2-download-installer-package), they should choose ks-installer to upgrade KubeSphere. For example, if your Kubernetes is hosted by cloud vendors or self provisioned, refer to [Upgrade with ks-installer](../upgrade-with-ks-installer/). +Depending on how your existing cluster was set up, you can use KubeKey or ks-installer to upgrade your cluster. It is recommended that you [use KubeKey to upgrade your cluster](../upgrade-with-kubekey/) if it was created by KubeKey. Otherwise, [use ks-installer to upgrade your cluster](../upgrade-with-ks-installer/). \ No newline at end of file diff --git a/content/en/docs/upgrade/upgrade-with-ks-installer.md b/content/en/docs/upgrade/upgrade-with-ks-installer.md index 5c70e8347..59d6fa70d 100644 --- a/content/en/docs/upgrade/upgrade-with-ks-installer.md +++ b/content/en/docs/upgrade/upgrade-with-ks-installer.md @@ -1,47 +1,28 @@ --- title: "Upgrade with ks-installer" -keywords: "Kubernetes, upgrade, KubeSphere, v3.0.0" +keywords: "Kubernetes, upgrade, KubeSphere, v3.1.0" description: "Use ks-installer to upgrade KubeSphere." linkTitle: "Upgrade with ks-installer" weight: 7300 --- -ks-installer is recommended for users whose Kubernetes clusters were not set up through the [KubeSphere Installer](https://v2-1.docs.kubesphere.io/docs/installation/all-in-one/#step-2-download-installer-package), but hosted by cloud vendors. This tutorial is for **upgrading KubeSphere only**. Cluster operators are responsible for upgrading Kubernetes themselves beforehand. +ks-installer is recommended for users whose Kubernetes clusters were not set up by [KubeKey](../../installing-on-linux/introduction/kubekey/), but hosted by cloud vendors. This tutorial is for **upgrading KubeSphere only**. Cluster operators are responsible for upgrading Kubernetes beforehand. ## Prerequisites -- You need to have a KubeSphere cluster running version 2.1.1. If your KubeSphere version is v2.1.0 or earlier, upgrade to v2.1.1 first. +- You need to have a KubeSphere cluster running v3.0.0. If your KubeSphere version is v2.1.1 or earlier, upgrade to v3.0.0 first. +- Read [Release Notes for 3.1.0](../../release/release-v310/) carefully. +- Back up any important component beforehand. +- Supported Kubernetes versions of KubeSphere v3.1.0: v1.17.x, v1.18.x, v1.19.x or v1.20.x. -- Make sure you read [Release Notes For 3.0.0](../../release/release-v300/) carefully. +## Apply ks-installer - {{< notice warning >}} -In v3.0.0, KubeSphere refactors many of its components such as Fluent Bit Operator and IAM. Make sure you back up any important components if you heavily customized them but not from the console. - {{}} - -## Step 1: Download YAML files - -Execute the following commands to download configuration templates. +Run the following command to upgrade your cluster. ```bash -wget https://github.com/kubesphere/ks-installer/releases/download/v3.0.0/kubesphere-installer.yaml +kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.1.0/kubesphere-installer.yaml ``` -```bash -wget https://github.com/kubesphere/ks-installer/releases/download/v3.0.0/cluster-configuration.yaml -``` +## Enable Pluggable Components -## Step 2: Modify the Configuration File - -Synchronize the changes from v2.1.1 to v3.0.0 into the configuration section of `cluster-configuration.yaml`. Note that the storage class and the pluggable components need to be consistent with that of v2.1.1. - -## Step 3: Apply YAML files - -Execute the following commands to upgrade KubeSphere. - -```bash -kubectl apply -f kubesphere-installer.yaml -``` - -```bash -kubectl apply -f cluster-configuration.yaml -``` +You can [enable new pluggable components](../../pluggable-components/overview/) of KubeSphere v3.1.0 after the upgrade to explore more features of the container platform. \ No newline at end of file diff --git a/content/en/docs/upgrade/upgrade-with-kubekey.md b/content/en/docs/upgrade/upgrade-with-kubekey.md index e5fd4756c..41806ecb8 100644 --- a/content/en/docs/upgrade/upgrade-with-kubekey.md +++ b/content/en/docs/upgrade/upgrade-with-kubekey.md @@ -1,26 +1,33 @@ --- title: "Upgrade with KubeKey" -keywords: "Kubernetes, upgrade, KubeSphere, v3.0.0, KubeKey" +keywords: "Kubernetes, upgrade, KubeSphere, v3.1.0, KubeKey" description: "Use KubeKey to upgrade Kubernetes and KubeSphere." linkTitle: "Upgrade with KubeKey" weight: 7200 --- -KubeKey is recommended for users whose KubeSphere and Kubernetes were both deployed by the [KubeSphere Installer](https://v2-1.docs.kubesphere.io/docs/installation/all-in-one/#step-2-download-installer-package). If your Kubernetes cluster was provisioned by yourself or cloud providers, refer to [Upgrade with ks-installer](../upgrade-with-ks-installer/). +KubeKey is recommended for users whose KubeSphere and Kubernetes were both installed by [KubeKey](../../installing-on-linux/introduction/kubekey/). If your Kubernetes cluster was provisioned by yourself or cloud providers, refer to [Upgrade with ks-installer](../upgrade-with-ks-installer/). + +This tutorial demonstrates how to upgrade your cluster using KubeKey. ## Prerequisites -- You need to have a KubeSphere cluster running version 2.1.1. If your KubeSphere version is v2.1.0 or earlier, upgrade to v2.1.1 first. +- You need to have a KubeSphere cluster running v3.0.0. If your KubeSphere version is v2.1.1 or earlier, upgrade to v3.0.0 first. +- Read [Release Notes for 3.1.0](../../release/release-v310/) carefully. +- Back up any important component beforehand. +- Make your upgrade plan. Two scenarios are provided in this document for [all-in-one clusters](#all-in-one-cluster) and [multi-node clusters](#multi-node-cluster) respectively. -- You have downloaded KubeKey. Otherwise, follow the steps below to download it first. +## Download KubeKey - {{< tabs >}} +Follow the steps below to download KubeKey before you upgrade your cluster. + +{{< tabs >}} {{< tab "Good network connections to GitHub/Googleapis" >}} Download KubeKey from its [GitHub Release Page](https://github.com/kubesphere/kubekey/releases) or use the following command directly. ```bash -curl -sfL https://get-kk.kubesphere.io | VERSION=v1.0.1 sh - +curl -sfL https://get-kk.kubesphere.io | VERSION=v1.1.0 sh - ``` {{}} @@ -36,7 +43,7 @@ export KKZONE=cn Run the following command to download KubeKey: ```bash -curl -sfL https://get-kk.kubesphere.io | VERSION=v1.0.1 sh - +curl -sfL https://get-kk.kubesphere.io | VERSION=v1.1.0 sh - ``` {{< notice note >}} @@ -49,25 +56,17 @@ After you download KubeKey, if you transfer it to a new machine also with poor n {{}} - {{< notice note >}} +{{< notice note >}} -The commands above download the latest release (v1.0.1) of KubeKey. You can change the version number in the command to download a specific version. +The commands above download the latest release (v1.1.0) of KubeKey. You can change the version number in the command to download a specific version. {{}} - Make `kk` executable: - - ```bash - chmod +x kk - ``` +Make `kk` executable: -- Make sure you read [Release Notes For 3.0.0](../../release/release-v300/) carefully. - - {{< notice warning >}} -In v3.0.0, KubeSphere refactors many of its components such as Fluent Bit Operator and IAM. Make sure you back up any important components if you heavily customized them but not from the KubeSphere console. - {{}} - -- Make your upgrade plan. Two upgrading scenarios are documented below. +```bash +chmod +x kk +``` ## Upgrade KubeSphere and Kubernetes @@ -75,31 +74,30 @@ Upgrading steps are different for single-node clusters (all-in-one) and multi-no {{< notice info >}} -- Upgrading Kubernetes will cause Helm to be upgraded from v2 to v3. If you want to continue using helm2, back up it first: `cp /usr/local/bin/helm /usr/local/bin/helm2` -- When upgrading Kubernetes, KubeKey will upgrade from one MINOR version to the next MINOR version until the target version. For example, you may see the upgrading process going from 1.16 to 1.17 and to 1.18, instead of directly jumping to 1.18 from 1.16. +When upgrading Kubernetes, KubeKey will upgrade from one MINOR version to the next MINOR version until the target version. For example, you may see the upgrading process going from 1.16 to 1.17 and to 1.18, instead of directly jumping to 1.18 from 1.16. {{}} ### All-in-one cluster -Run the following command to use KubeKey to upgrade your single-node cluster to KubeSphere v3.0.0 and Kubernetes v1.17.9 (default): +Run the following command to use KubeKey to upgrade your single-node cluster to KubeSphere v3.1.0 and Kubernetes v1.20.4: ```bash -./kk upgrade --with-kubernetes v1.17.9 --with-kubesphere v3.0.0 +./kk upgrade --with-kubernetes v1.20.4 --with-kubesphere v3.1.0 ``` To upgrade Kubernetes to a specific version, explicitly provide the version after the flag `--with-kubernetes`. Available versions are: -- v1.15.12 -- v1.16.8, v1.16.10, v1.16.12, v1.16.13 - v1.17.0, v1.17.4, v1.17.5, v1.17.6, v1.17.7, v1.17.8, v1.17.9 -- v1.18.3, v1.18.5, v1.18.6 +- v1.18.3, v1.18.5, v1.18.6, v1.18.8 +- v1.19.0, v1.19.8, v1.19.9 +- v1.20.4 ### Multi-node cluster #### Step 1: Generate a configuration file using KubeKey -This command creates a configuration file `sample.yaml` from your cluster. +This command creates a configuration file `sample.yaml` of your cluster. ```bash ./kk create config --from-cluster @@ -111,14 +109,14 @@ It assumes your kubeconfig is allocated in `~/.kube/config`. You can change it w {{}} -#### Step 2: Modify the configuration file template +#### Step 2: Edit the configuration file template -Modify `sample.yaml` based on your cluster configuration. Make sure you replace the following fields correctly. +Edit `sample.yaml` based on your cluster configuration. Make sure you replace the following fields correctly. -- `hosts`: Input connection information among your hosts. -- `roleGroups.etcd`: Input etcd members. -- `controlPlaneEndpoint`: Input your load balancer address (Optional). -- `registry`: Input image registry information (Optional). +- `hosts`: The basic information of your hosts (hostname and IP address) and how to connect to them using SSH. +- `roleGroups.etcd`: Your etcd nodes. +- `controlPlaneEndpoint`: Your load balancer address (optional). +- `registry`: Your image registry information (optional). {{< notice note >}} @@ -127,15 +125,21 @@ For more information, see [Edit the configuration file](../../installing-on-linu {{}} #### Step 3: Upgrade your cluster -The following command upgrades your cluster to KubeSphere v3.0.0 and Kubernetes v1.17.9 (default): +The following command upgrades your cluster to KubeSphere v3.1.0 and Kubernetes v1.20.4: ```bash -./kk upgrade --with-kubernetes v1.17.9 --with-kubesphere v3.0.0 -f config-sample.yaml +./kk upgrade --with-kubernetes v1.20.4 --with-kubesphere v3.1.0 -f sample.yaml ``` To upgrade Kubernetes to a specific version, explicitly provide the version after the flag `--with-kubernetes`. Available versions are: -- v1.15.12 -- v1.16.8, v1.16.10, v1.16.12, v1.16.13 - v1.17.0, v1.17.4, v1.17.5, v1.17.6, v1.17.7, v1.17.8, v1.17.9 -- v1.18.3, v1.18.5, v1.18.6 +- v1.18.3, v1.18.5, v1.18.6, v1.18.8 +- v1.19.0, v1.19.8, v1.19.9 +- v1.20.4 + +{{< notice note >}} + +To use new features of KubeSphere v3.1.0, you may need to enable some pluggable components after the upgrade. + +{{}} \ No newline at end of file