From 9c81b2bf0ac17a1a613a4db2b196cbaec7cc0571 Mon Sep 17 00:00:00 2001 From: zhuxiujuan28 <562873187@qq.com> Date: Mon, 21 Apr 2025 15:11:41 +0800 Subject: [PATCH] update upgrade docs Signed-off-by: zhuxiujuan28 <562873187@qq.com> --- .../02-upgrade-kubesphere-from-v4.1.x.adoc | 167 +++++++++++++++ .../03-upgrade-kubesphere-from-v3.4.x.adoc | 190 ++++++++++++++++++ .../03-upgrade-kubesphere/_index.adoc | 9 + .../02-upgrade-kubesphere-from-v4.1.x.adoc | 10 +- .../03-upgrade-kubesphere-from-v3.4.x.adoc | 24 +-- .../03-upgrade-kubesphere/_index.adoc | 2 - 6 files changed, 382 insertions(+), 20 deletions(-) create mode 100644 content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc create mode 100644 content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc create mode 100644 content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc diff --git a/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc b/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc new file mode 100644 index 000000000..c7166165f --- /dev/null +++ b/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc @@ -0,0 +1,167 @@ +--- +title: "Upgrade from v4.1.x to v4.1.3" +keywords: "Kubernetes, {ks_product-en}, Installation, Upgrade KubeSphere" +description: "Guide for upgrading KubeSphere from v4.1.x to v4.1.3." +weight: 01 +--- + +This section explains how to upgrade {ks_product-en} from v4.1.x to v4.1.3 while maintaining your current Kubernetes version. + +== Prerequisites + +* Ensure your current {ks_product-en} version is v4.1.x. + +* Ensure your current Kubernetes version is v1.21.x ~ v1.30.x. + +* If extensions have custom configurations, back them up by downloading configuration files from the "Extension Config" dialog. + +* Back up all critical data to prevent data loss. + +== Upgrade {ks_product-en} + +{ks_product-en} v4.1+ uses Helm for upgrading ks-core. + +=== Upgrade Host Cluster + +. Verify the target cluster: ++ +-- +[source,bash] +---- +kubectl get node -o wide +---- +-- + +. Export current ks-core configuration: ++ +-- +[source,bash] +---- +helm get values -n kubesphere-system ks-core -o yaml > host-cluster-custom-values.yaml +---- +-- + +. Modify configuration file: ++ +-- +[source,yaml] +---- +# Pay special attention to these fields while preserving others +global: + imageRegistry: docker.io +extension: + imageRegistry: docker.io + +# Note: Cluster role parameter changed from 'role' to 'multicluster.role' +multicluster: + role: host +---- +-- + +. Run upgrade command: ++ +-- +[source,bash] +---- +helm -n kubesphere-system upgrade ks-core https://charts.kubesphere.io/main/ks-core-1.1.4.tgz -f host-cluster-custom-values.yaml --wait --debug +---- +-- + +. Verify successful upgrade: ++ +-- +[source,bash] +---- +helm -n kubesphere-system get metadata ks-core +NAME: ks-core +CHART: ks-core +VERSION: 1.1.4 +APP_VERSION: v4.1.3 +NAMESPACE: kubesphere-system +REVISION: 26 +STATUS: deployed +DEPLOYED_AT: 2025-03-27T11:10:00+08:00 +---- +-- + +=== Upgrade Member Cluster + +The process is similar to host cluster upgrade but requires attention to member-specific parameters. + +. Verify target member cluster: ++ +-- +[source,bash] +---- +kubectl get node -o wide +---- +-- + +. Export ks-core configuration: ++ +-- +[source,bash] +---- +helm get values -n kubesphere-system ks-core -o yaml > member-cluster-custom-values.yaml +---- +-- + +. Modify configuration file: ++ +-- +[source,yaml] +---- +# Pay special attention to these fields +global: + imageRegistry: docker.io +authentication: + issuer: + jwtSecret: + +# Cluster role parameter changed from role to multicluster.role +multicluster: + role: member +---- +-- + +. Run upgrade command: ++ +-- +[source,bash] +---- +helm -n kubesphere-system upgrade ks-core https://charts.kubesphere.io/main/ks-core-1.1.4.tgz -f member-cluster-custom-values.yaml --wait --debug +---- +-- + +. Verify successful upgrade: ++ +-- +[source,bash] +---- +helm -n kubesphere-system get metadata ks-core +NAME: ks-core +CHART: ks-core +VERSION: 1.1.4 +APP_VERSION: v4.1.3 +NAMESPACE: kubesphere-system +REVISION: 13 +STATUS: deployed +DEPLOYED_AT: 2025-03-27T11:10:00+08:00 +---- +-- + +=== Upgrade Extensions + +Upgrade required extensions in Extensions Center. + +. Navigate to extension details page in Extensions Center. + +. Click image:/images/ks-qkcp/zh/icons/more.svg[more,18,18] below the extension icon and select **Extension Config**. + +. In the dialog, click **Restore Recommended Configuration**, then manually modify with custom settings before confirming. + +. Click image:/images/ks-qkcp/zh/icons/more.svg[more,18,18] again and select **Update**. + +. In the update dialog, click **Start Update** and wait for completion. + +{ks_product-en} upgrade is now complete. \ No newline at end of file diff --git a/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc b/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc new file mode 100644 index 000000000..632d72837 --- /dev/null +++ b/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc @@ -0,0 +1,190 @@ +--- +title: "Upgrade from v3.4.x to v4.1.3" +keywords: "Kubernetes, KubeSphere, Installation, Upgrade" +description: "Guide for upgrading KubeSphere from v3.4.x to v4.1.3." +weight: 02 +--- + +The following procedures outline the steps required to upgrade KubeSphere from v3.4.x to v4.1.3. + +// Note +include::../../../../_ks_components-en/admonitions/note.adoc[] + +Prerequisite: Your KubeSphere must be v3.4.x before proceeding with this upgrade to v4.1.3. + +include::../../../../_ks_components-en/admonitions/admonEnd.adoc[] + +The upgrade process consists of three critical phases that must be executed in strict sequence: + +. Upgrade the host cluster and migrate extension data +. Upgrade all member clusters and migrate extension data +. Upgrade the gateway components + +== Download Upgrade Scripts + +Execute the following commands in both host and member clusters to get the necessary upgrade scripts: + +[source,bash] +---- +curl -LO https://github.com/kubesphere/ks-installer/archive/refs/tags/v4.1.3.tar.gz +tar -xzvf v4.1.3.tar.gz +cd ks-installer-4.1.3/scripts +---- + +== Configure Upgrade Parameters + +Modify the upgrade configuration file `ks-core-values.yaml` in all clusters, specifically the `upgrade` section. Use the `upgrade.config.jobs..enabled` flag to selectively upgrade extensions, as shown in this example: + +[source,yaml] +---- +upgrade: + enabled: true + image: + registry: "" + repository: kubesphere/ks-upgrade + tag: "v4.1.3" + pullPolicy: IfNotPresent + persistenceVolume: + name: ks-upgrade + storageClassName: "" + accessMode: ReadWriteOnce + size: 5Gi + config: + storage: + local: + path: /tmp/ks-upgrade + validator: + ksVersion: + enabled: true + extensionsMuseum: + enabled: true + namespace: kubesphere-system + name: extensions-museum + syncInterval: 0 + watchTimeout: 30m + jobs: + network: + enabled: true # Enable extension upgrade (true/false) + priority: 100 + extensionRef: # The version configuration of the extension must match the information in extensions-museum. + name: "network" + version: "1.1.0" + dynamicOptions: { + "rerun": "false" + } + gateway: + enabled: true + priority: 90 + extensionRef: + name: "gateway" + version: "1.0.5" +---- + +More reference: link:https://github.com/kubesphere/ks-upgrade/tree/release-4.1/docs[Configuration Documentation for Extension Upgrade] + +== Pre-Upgrade Verification + +Before upgrading the cluster, execute the following `pre-check.sh` script to verify whether the cluster status meets the upgrade requirements. + +[source,bash] +---- +bash pre-check.sh +---- + +Here's the strictly literal translation following the established terminology: + +== Upgrade host cluster + +Execute the following command to upgrade the host cluster, install extensions, and migrate data. + +[source,bash] +---- +# Specify image registry +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +# Specify extension image registry +# export EXTENSION_IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh host | tee host-upgrade.log +---- + +After executing the upgrade command, you can run the following command in a new terminal window to monitor real-time status changes of Pods in the `kubesphere-system` namespace: + +[source,bash] +---- +watch kubectl get pod -n kubesphere-system +---- + +== Upgrade member cluster + +Execute the following command to upgrade the member cluster, install extension agents, and migrate data. + +[source,bash] +---- +# Specify image registry +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +# Specify extension image registry +# export EXTENSION_IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh member | tee member-upgrade.log +---- + +After executing the upgrade command, you can run the following command in a new terminal window to monitor real-time status changes of Pods in the `kubesphere-system` namespace: + +[source,bash] +---- +watch kubectl get pod -n kubesphere-system +---- + +After successful upgrade of the member cluster, execute the following command on the host cluster to remove taints from the member cluster, enabling extension agents to be scheduled onto the member cluster. + +[source,bash] +---- +kubectl get clusters.cluster.kubesphere.io -o json | jq 'del(.status.conditions[] | select(.type=="Schedulable"))' | kubectl apply -f - +---- + +== Upgrade gateway + +Gateway upgrade will cause Nginx Ingress Controller to restart, resulting in service interruption for gateway-dependent services. Please perform upgrades during off-peak business hours. + +Before starting the upgrade, check the gateway instances and their status in the cluster using: + +[source,bash] +---- +helm -n kubesphere-controls-system list -a +---- + +Upgrade gateways individually using: + +[source,bash] +---- +# Specify image registry +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh gateway kubesphere-router- | tee gateway-upgrade.log +---- + +Or upgrade all gateways simultaneously using: + +[source,bash] +---- +# Specify image registry +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh gateway all | tee gateway-upgrade.log +---- + +After gateway upgrade completes, verify deployment status with: + +[source,bash] +---- +helm -n kubesphere-controls-system list -a +---- + +== Verify upgrade + +After upgrade completes, ensure all services are running normally and check system health status. Verify using: + +[source,bash] +---- +for ns in $(kubectl get namespaces -l kubesphere.io/workspace=system-workspace -o jsonpath='{.items[*].metadata.name}'); do + kubectl get pods -n $ns --no-headers --ignore-not-found | grep -vE 'Running|Completed' +done +---- + +Ensure all Pod statuses show `Running`. If issues occur, check relevant container logs for troubleshooting. \ No newline at end of file diff --git a/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc b/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc new file mode 100644 index 000000000..77751d649 --- /dev/null +++ b/content/en/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc @@ -0,0 +1,9 @@ +--- +title: "Upgrade KubeSphere" +linkTitle: "Upgrade KubeSphere" +keywords: "Kubernetes, KubeSphere, Upgrade" +description: "Instructions for upgrading KubeSphere." +layout: "second" +weight: 03 +--- + diff --git a/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc b/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc index 5dd49df8e..dd29356d5 100644 --- a/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc +++ b/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/02-upgrade-kubesphere-from-v4.1.x.adoc @@ -2,7 +2,7 @@ title: "从 v4.1.x 升级到 v4.1.3" keywords: "Kubernetes, {ks_product}, 安装, 升级{ks_product_left}" description: "介绍如何升级{ks_product_left}。" -weight: 02 +weight: 01 --- 本节介绍如何在保持当前的 Kubernetes 版本不变的情况下从{ks_product_left} v4.1.x 升级到{ks_product_left} v4.1.3。 @@ -43,7 +43,7 @@ helm get values -n kubesphere-system ks-core -o yaml > host-cluster-custom-value ---- -- -. 修改配置文件 +. 修改配置文件。 + -- [source,yaml] @@ -69,7 +69,7 @@ helm -n kubesphere-system upgrade ks-core https://charts.kubesphere.io/main/ks-c ---- -- -. 检查 host 集群是否升级成功 +. 检查 host 集群是否升级成功。 + -- [source,bash] @@ -108,7 +108,7 @@ helm get values -n kubesphere-system ks-core -o yaml > member-cluster-custom-val ---- -- -. 修改修改配置文件 +. 修改配置文件。 + -- [source,bash] @@ -135,7 +135,7 @@ helm -n kubesphere-system upgrade ks-core https://charts.kubesphere.io/main/ks-c ---- -- -. 检查 member 集群是否升级成功 +. 检查 member 集群是否升级成功。 + -- [source,bash] diff --git a/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc b/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc index 643ca7e99..9d8ec8641 100644 --- a/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc +++ b/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/03-upgrade-kubesphere-from-v3.4.x.adoc @@ -7,23 +7,21 @@ weight: 02 以下操作步骤适用于将 KubeSphere 从 v3.4.x 升级到 v4.1.3 版本。 --- // Note include::../../../../_ks_components/admonitions/note.adoc[] 在开始升级之前，您需要确保当前 KubeSphere 版本已升级到 v3.4.x，否则无法继续升级到 v4.1.3。 include::../../../../_ks_components/admonitions/admonEnd.adoc[] --- + 升级过程分为以下三个主要步骤，请严格按照顺序执行： -[arabic] . 升级 host 集群并迁移扩展组件数据。 . 升级 member 集群并迁移扩展组件数据。 . 升级网关。 -=== 下载升级脚本 +== 下载升级脚本 在 host 集群和 member 集群环境中下载升级脚本： @@ -34,7 +32,7 @@ tar -xzvf v4.1.3.tar.gz cd ks-installer-4.1.3/scripts ---- -=== 修改升级配置文件 +== 修改升级配置文件 在 host 和所有的 member 集群中调整升级配置文件 `ks-core-values.yaml`，其中 `upgrade` 部分为升级相关的配置项目，你需要在升级之前确认需要升级的组件和配置信息，通过 `upgrade.config.jobs..enabled` 控制是否需要升级该组件，以下为配置示例： @@ -67,7 +65,7 @@ upgrade: watchTimeout: 30m jobs: network: - enabled: true # 是启用并升级该扩展组件 + enabled: true # 是否启用并升级该扩展组件 priority: 100 extensionRef: # 扩展组件的版本配置，需要与 extensions-museum 中的信息一致 name: "network" @@ -83,18 +81,18 @@ upgrade: version: "1.0.5" ---- -更多配置说明请参考link:https://github.com/kubesphere/ks-upgrade/tree/release-4.1/docs[扩展组件升级配置说明] +更多配置说明请参考link:https://github.com/kubesphere/ks-upgrade/tree/release-4.1/docs[扩展组件升级配置说明]。 -=== 集群状态检查 +== 集群状态检查 -在升级集群之前，执行以下 `scripts/pre-check.sh` 脚本文件，检查集群状态及是否满足升级条件。 +在升级集群之前，执行以下 `pre-check.sh` 脚本文件，检查集群状态及是否满足升级条件。 [source,bash] ---- bash pre-check.sh ---- -=== 升级 host 集群 +== 升级 host 集群 执行以下命令，升级 host 集群、安装扩展组件并迁移数据。 @@ -114,7 +112,7 @@ bash upgrade.sh host | tee host-upgrade.log watch kubectl get pod -n kubesphere-system ---- -=== 升级 member 集群 +== 升级 member 集群 执行以下命令，升级 member 集群、安装扩展组件 agent 并迁移数据。 @@ -141,7 +139,7 @@ watch kubectl get pod -n kubesphere-system kubectl get clusters.cluster.kubesphere.io -o json | jq 'del(.status.conditions[] | select(.type=="Schedulable"))' | kubectl apply -f - ---- -=== 升级网关 +== 升级网关 网关的升级会导致 Nginx Ingress Controller 重启，依赖网关提供的服务会产生中断，请在业务低峰期进行升级。 @@ -177,7 +175,7 @@ bash upgrade.sh gateway all | tee gateway-upgrade.log helm -n kubesphere-controls-system list -a ---- -=== 完成升级 +== 完成升级 升级完成后，请确保所有服务正常运行，并检查系统的健康状态。可以通过以下命令验证： diff --git a/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc b/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc index b8897e396..a94fa3a49 100644 --- a/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc +++ b/content/zh/docs/v4.1/03-installation-and-upgrade/03-upgrade-kubesphere/_index.adoc @@ -7,5 +7,3 @@ layout: "second" weight: 03 --- - -本节仅介绍如何从{ks_product_left} v4.1.x 升级至 v4.1.3，暂不支持从 v3.x 直接升级。