From 0f5b2ee670accfddc6a85b20c1156b2f8e6e5678 Mon Sep 17 00:00:00 2001 From: bestpala Date: Thu, 8 May 2025 19:00:18 +0800 Subject: [PATCH] Upgrade KubeSphere from v3.4.x to v4.1.3 news Signed-off-by: bestpala --- ...pgrade KubeSphere from v3.4.x to v4.1.3.md | 183 ++++++++++++++++++ ...pgrading from KubeSphere v3.4.x to v4.x.md | 181 +++++++++++++++++ 2 files changed, 364 insertions(+) create mode 100644 content/en/news/How to Upgrade KubeSphere from v3.4.x to v4.1.3.md create mode 100644 content/zh/news/The Complete Guide to Smoothly Upgrading from KubeSphere v3.4.x to v4.x.md diff --git a/content/en/news/How to Upgrade KubeSphere from v3.4.x to v4.1.3.md b/content/en/news/How to Upgrade KubeSphere from v3.4.x to v4.1.3.md new file mode 100644 index 000000000..318086323 --- /dev/null +++ b/content/en/news/How to Upgrade KubeSphere from v3.4.x to v4.1.3.md @@ -0,0 +1,183 @@ +--- +title: 'Upgrading KubeSphere from v3.4.x to v4.1.3: Everything You Need to Know' +tag: 'Product News' +keyword: 'open source, Kubernetes, KubeSphere' +description: 'This guide provides comprehensive steps for upgrading from KubeSphere v3.4.x to v4.x, helping you complete the upgrade process smoothly.' +createTime: '2025-4-19' +author: 'KubeSphere' +image: 'https://pek3b.qingstor.com/kubesphere-community/images/upgrade%20kubesphere%20from%203.4.x-4.1.3.png' +--- + +This guide provides comprehensive steps for upgrading from KubeSphere v3.4.x to v4.x, helping you complete the upgrade process smoothly. Note: If your KubeSphere version is earlier than v3.4.x, you must first upgrade to v3.4.x before proceeding. + +The upgrade process consists of the following three major steps. Please execute them in order: + +1. Upgrade the host cluster and migrate extension component data. +2. Upgrade the member clusters and migrate extension component data. +3. Upgrade the gateway. + +## Download the Upgrade Script + +Download the upgrade script in both the host and member cluster environments: + +```bash +curl -LO https://github.com/kubesphere/ks-installer/archive/refs/tags/v4.1.3.tar.gz +tar -xzvf v4.1.3.tar.gz +``` + +## Modify the Upgrade Configuration File + + +Adjust the upgrade configuration file in both the host and all member clusters. The config file path is `scripts/ks-core-values.yaml.` The `upgrade`section contains upgrade-related settings. Before upgrading, you must confirm which components and configurations are to be upgraded. Use` upgrade.jobs.config..enabled `to control whether to upgrade a specific component. + +Example configuration: + +``` +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 + priority: 100 + extensionRef: + name: "network" + version: "1.1.0" + dynamicOptions: { + "rerun": "false" + } + gateway: + enabled: true + priority: 90 + extensionRef: + name: "gateway" + version: "1.0.5" +``` + + + +For more configuration details, refer to the [Extension Component Upgrade Configuration Guide](https://github.com/kubesphere/ks-upgrade/tree/release-4.1/docs). + +## Cluster Status Check + +Before upgrading the clusters, run the following script to check cluster status and ensure upgrade readiness: + +```bash +bash pre-check.sh +``` + +## Upgrade the Host Cluster + +Run the following command to upgrade the host cluster, install extension components, and migrate data: + +``` +bash upgrade.sh host | tee host-upgrade.log +``` +You can open a new terminal window and run the following command to monitor Pod status in the `kubesphere-system` namespace in real-time: + + +```bash +watch kubectl get pod -n kubesphere-system +``` + +## Upgrade the Member Cluster + +Run the following command to upgrade the member cluster, install the extension component agent, and migrate data: + + +``` +# Optional: Specify image registry +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +# Optional: Specify extension component image registry +# export EXTENSION_IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh member | tee member-upgrade.log +``` + +Monitor the Pod status similarly in the `kubesphere-system` namespace: + +```bash +watch kubectl get pod -n kubesphere-system +``` + +After the successful upgrade of the member cluster, execute the following command on the host cluster to remove the taint from the member cluster. This allows the extension component agent to be scheduled onto the member cluster. + +```bash +kubectl get clusters.cluster.kubesphere.io -o json | jq 'del(.status.conditions[] | select(.type=="Schedulable"))' | kubectl apply -f - +``` + + +## Upgrade the Gateway + +Upgrading the gateway will cause the Nginx Ingress Controller to restart, which may lead to service interruptions dependent on the gateway. It is recommended to perform the upgrade during off-peak business hours. + +Before starting the upgrade, check the deployed gateway instances and their status in the cluster using the following command: + +```bash +helm -n kubesphere-controls-system list -a +``` + +To upgrade the gateway individually, use the following command: + +``` +# Optional: Specify image registry +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh gateway kubesphere-router- | tee gateway-upgrade.log +``` + +Alternatively, to upgrade all gateways at once, use the following command: + +``` +# Optional: Specify image registry +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh gateway all | tee gateway-upgrade.log +``` + + +After the gateway upgrade is complete, check the deployment status of the gateway using the following command: + +```bash +helm -n kubesphere-controls-system list -a +``` + +## Completing the Upgrade + +Once the upgrade is complete, ensure that all services are running normally and check the system’s health. You can verify this using the following command: + +```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 that all Pod statuses are `Running`. If any issues arise, check the relevant container logs for troubleshooting. + +By following the smooth upgrade steps provided in this guide, you should be able to successfully upgrade the platform from v3.4.x to v4.x. If you encounter any difficulties or have further needs during the upgrade process, the KubeSphere community welcomes your participation and feedback. Through continuous optimization and updates, we are committed to providing a more stable and efficient cloud-native platform for all users. + +Thank you for choosing KubeSphere. We look forward to seeing you have a better experience and achieve greater success with the new version of the platform! + + +## Special Note: Product Lifecycle Management Policy + +During the upgrade, it is recommended to review the [KubeSphere Product Lifecycle Management Policy](https://kubesphere.io/zh/news/kubesphere-product-lifecycle-policy/).This policy provides the product version lifecycle termination plan, ensuring that the version you are using always meets the latest market demands and technical standards. Understanding the support and update strategy for each version will help you plan system updates and version migration in a timely manner, avoiding potential risks associated with using versions that are no longer supported. \ No newline at end of file diff --git a/content/zh/news/The Complete Guide to Smoothly Upgrading from KubeSphere v3.4.x to v4.x.md b/content/zh/news/The Complete Guide to Smoothly Upgrading from KubeSphere v3.4.x to v4.x.md new file mode 100644 index 000000000..4cfe6b2d9 --- /dev/null +++ b/content/zh/news/The Complete Guide to Smoothly Upgrading from KubeSphere v3.4.x to v4.x.md @@ -0,0 +1,181 @@ +--- +title: '过渡无压力！KubeSphere v3.4.x 到 v4.x 平滑升级全攻略' +tag: '产品动态' +keyword: '社区, 开源, 升级, KubeSphere' +description: '本文将为您提供从 KubeSphere v3.4.x 升级到 v4.x 的完整操作步骤，帮助您顺利完成升级过程。' +createTime: '2025-4-19' +author: 'KubeSphere' +image: 'https://pek3b.qingstor.com/kubesphere-community/images/KubeSphere%20v3.4.x%20to%20v4.xzh.png' +--- + +本文将为您提供从 KubeSphere v3.4.x 升级到 v4.x 的完整操作步骤，帮助您顺利完成升级过程。特别注意，如果您的 KubeSphere 版本早于 v3.4.x，您需要先将其升级至 v3.4.x，然后再进行进一步的升级。 + +升级过程分为以下三个主要步骤，请按照顺序执行： + +1. 升级 host 集群并迁移扩展组件数据。 +2. 升级 member 集群并迁移扩展组件数据。 +3. 升级网关。 + +## 下载升级脚本 + +在 host 集群和 member 集群环境中下载升级脚本： + +```bash +curl -LO https://github.com/kubesphere/ks-installer/archive/refs/tags/v4.1.3.tar.gz +tar -xzvf v4.1.3.tar.gz +``` + +## 修改升级配置文件 + +在 host 和所有的 member 集群中调整升级配置文件，配置文件路径 `scripts/ks-core-values.yaml`，其中 `upgrade` 部分为升级相关的配置项目，在升级之前，您需要确认要升级的组件和配置信息，通过 `upgrade.jobs.config..enabled` 控制是否需要升级该组件，以下为配置示例： + + +```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 # 是启用并升级该扩展组件 + priority: 100 + extensionRef: # 扩展组件的版本配置，需要与 extensions-museum 中的信息一致 + name: "network" + version: "1.1.0" + dynamicOptions: { + "rerun": "false" + } + gateway: + enabled: true + priority: 90 + extensionRef: + name: "gateway" + version: "1.0.5" +``` + +更多配置说明请参考 [扩展组件升级配置说明](https://github.com/kubesphere/ks-upgrade/tree/release-4.1/docs) + +## 集群状态检查 + +在升级集群之前，执行以下 `scripts/pre-check.sh` 脚本文件，检查集群状态及是否满足升级条件。 + +```bash +bash pre-check.sh +``` + +## 升级 host 集群 + +执行以下命令，升级 host 集群、安装扩展组件并迁移数据。 + +```bash +# 指定镜像仓库地址 +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +# 指定扩展组件镜像仓库地址 +# export EXTENSION_IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh host | tee host-upgrade.log +``` + +执行升级命令后，可以在新的终端窗口中运行以下命令，实时观察 `kubesphere-system` 命名空间下 Pod 的状态变化： + +```bash +watch kubectl get pod -n kubesphere-system +``` + +## 升级 member 集群 + +执行以下命令，升级 member 集群、安装扩展组件 agent 并迁移数据。 + +```bash +# 指定镜像仓库地址 +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +# 指定扩展组件镜像仓库地址 +# export EXTENSION_IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh member | tee member-upgrade.log +``` + +执行升级命令后，可以在新的终端窗口中运行以下命令，实时观察 `kubesphere-system` 命名空间下 Pod 的状态变化： + +```bash +watch kubectl get pod -n kubesphere-system +``` + +在 member 集群升级成功之后，需要在 host 集群上执行以下命令，移除 member 集群的污点，使扩展组件 agent 能够调度到 member 集群上。 + +```bash +kubectl get clusters.cluster.kubesphere.io -o json | jq 'del(.status.conditions[] | select(.type=="Schedulable"))' | kubectl apply -f - +``` + + +## 升级网关 + +网关的升级会导致 Nginx Ingress Controller 重启，依赖网关提供的服务会产生中断，请在业务低峰期进行升级。 + +在开始升级前，请通过以下命令检查集群中部署的网关实例及状态： + +```bash +helm -n kubesphere-controls-system list -a +``` + +通过以下命令逐一升级网关： + +```bash +# 指定镜像仓库地址 +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh gateway kubesphere-router- | tee gateway-upgrade.log +``` + +或者通过以下命令升级所有网关： + +```bash +# 指定镜像仓库地址 +# export IMAGE_REGISTRY=swr.cn-southwest-2.myhuaweicloud.com/ks +bash upgrade.sh gateway all | tee gateway-upgrade.log +``` + +在网关升级完成后，通过以下命令检查网关的部署状态： + +```bash +helm -n kubesphere-controls-system list -a +``` + +## 完成升级 + +升级完成后，请确保所有服务正常运行，并检查系统的健康状态。可以通过以下命令验证： + +```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 +``` + +确保所有 Pod 状态为 `Running`。如有问题，请查看相关容器日志以进行故障排除。 + +通过本文提供的平滑升级步骤，您应该能够顺利将平台从 v3.4.x 升级到 v4.x，如果您在升级过程中遇到任何困难或有进一步的需求，KubeSphere 社区随时欢迎您的参与和反馈。通过不断的优化和更新，我们致力于为每一位用户提供更加稳定、高效的云原生平台。 + +感谢您选择 KubeSphere，我们期待您在新版平台上获得更好的体验和成效！ + + +## 特别提醒：产品生命周期管理政策 + +在进行升级时，建议您关注 [KubeSphere 产品生命周期管理政策](https://kubesphere.io/zh/news/kubesphere-product-lifecycle-policy/)，该政策为您提供了产品版本的生命周期终止方案，确保您使用的版本始终满足最新的市场需求和技术标准。了解每个版本的支持和更新策略，有助于您及时做好系统更新与版本迁移的规划，避免由于使用不再维护的版本而带来的潜在风险。 \ No newline at end of file