This is an automated email from the ASF dual-hosted git repository. wusheng pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/skywalking.git
The following commit(s) were added to refs/heads/master by this push: new 421ba88 Provide the new version upgrade documentation/FAQ. (#4311) 421ba88 is described below commit 421ba88dbfba48cdc5845547381aa4763775b4b1 Author: 吴晟 Wu Sheng <wu.sh...@foxmail.com> AuthorDate: Tue Feb 4 17:40:12 2020 +0800 Provide the new version upgrade documentation/FAQ. (#4311) * Provide the new version upgrade documentation/FAQ. * Make the sentence more clear. --- docs/en/FAQ/README.md | 3 ++- docs/en/FAQ/{Upgrade.md => v3-version-upgrade.md} | 3 +-- docs/en/FAQ/v6-version-upgrade.md | 30 +++++++++++++++++++++++ docs/en/setup/README.md | 3 +++ 4 files changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/en/FAQ/README.md b/docs/en/FAQ/README.md index 3e0e79f..2f1e110 100644 --- a/docs/en/FAQ/README.md +++ b/docs/en/FAQ/README.md @@ -9,10 +9,11 @@ These are known and common FAQs. We welcome you to contribute yours. * [Required items could not be found, when import project into Eclipse](Import-Project-Eclipse-RequireItems-Exception.md) ## Runtime +* [6.x version upgrade](v6-version-upgrade.md) * [Why only traces in UI?](Why-have-traces-no-others.md) * [Too many GRPC logs in the console](Too-many-gRPC-logs.md) * [The trace doesn't continue in kafka consumer side](kafka-plugin.md) -* [Agent or collector version upgrade](Upgrade.md) +* [Agent or collector version upgrade, 3.x -> 5.0.0-alpha](v3-version-upgrade.md) * [EnhanceRequireObjectCache class cast exception](EnhanceRequireObjectCache-Cast-Exception.md) * [ElasticSearch server performance FAQ, including ERROR CODE:429](ES-Server-FAQ.md) * [IllegalStateException when install Java agent on WebSphere 7](install_agent_on_websphere.md) diff --git a/docs/en/FAQ/Upgrade.md b/docs/en/FAQ/v3-version-upgrade.md similarity index 90% rename from docs/en/FAQ/Upgrade.md rename to docs/en/FAQ/v3-version-upgrade.md index a6ce1ed..ab4dcb1 100644 --- a/docs/en/FAQ/Upgrade.md +++ b/docs/en/FAQ/v3-version-upgrade.md @@ -1,5 +1,4 @@ -# Upgrade FAQs -## Version 3.x -> 5.0.0-alpha +## Version 3.x -> 5.0.0-alpha Upgrade FAQs ### Collector ### Problem There is no information showing in the UI. diff --git a/docs/en/FAQ/v6-version-upgrade.md b/docs/en/FAQ/v6-version-upgrade.md new file mode 100644 index 0000000..1ee6989 --- /dev/null +++ b/docs/en/FAQ/v6-version-upgrade.md @@ -0,0 +1,30 @@ +# V6 upgrade +SkyWalking v6 is widely used in many production environments. Users may wants to upgrade to an old release to new. +This is a guidance to tell users how to do that. + +**NOTICE**, the following ways are not the only ways to do upgrade. + +## Use Canary Release +Like all applications, SkyWalking could use `canary release` method to upgrade by following these steps +1. Deploy a new cluster by using the latest(or new) version of SkyWalking OAP cluster with new database cluster. +1. Once the target(being monitored) service has chance to upgrade the agent.jar(or just simply reboot), change the `collector.backend_service` +pointing to the new OAP backend, and use/add a new namespace(`agent.namespace` in [Table of Agent Configuration Properties](../setup/service-agent/java-agent/README.md#table-of-agent-configuration-properties)). +The namespace will avoid the conflict between different versions. +1. When all target services have been rebooted, the old OAP clusters could be discarded. + +`Canary Release` methods works for any version upgrade. + +## Online Hot Reboot Upgrade +The reason we required `Canary Release` is, SkyWalking agent has cache mechanisms, switching to a new cluster makes the +cache unavailable for new OAP cluster. +In the 6.5.0+(especially for agent version), we have [**Agent hot reboot trigger mechanism**](../setup/backend/backend-setup.md#agent-hot-reboot-trigger-mechanism-in-oap-server-upgrade). +By using that, we could do upgrade an easier way, **deploy a new cluster by using the latest(or new) version of SkyWalking OAP cluster with new database cluster**, +and shift the traffic to the new cluster once for all. Based on the mechanism, all agents will go into `cool_down` mode, then +back online. More detail, read the backend setup document. + +**NOTICE**, as a known bug in 6.4.0, its agent could have re-connection issue, so, even this bot reboot mechanism included in 6.4.0, +it may not work in some network scenarios, especially in k8s. + +## Agent Compatibility +All versions of SkyWalking 6.x(even 7.x) are compatible with each others, so users could only upgrade the OAP servers first. +The agent is also enhanced from version to version, so from SkyWalking team's recommendations, upgrade the agent once you have the chance. diff --git a/docs/en/setup/README.md b/docs/en/setup/README.md index a722eb9..447f4db 100644 --- a/docs/en/setup/README.md +++ b/docs/en/setup/README.md @@ -44,3 +44,6 @@ Follow [backend and UI setup document](backend/backend-ui-setup.md) to understan ## Changes log Backend, UI and Java agent changes are available [here](../../../CHANGES.md). + +## Upgrade FAQ +[6.x version upgrade FAQ](../FAQ/v6-version-upgrade.md) introduces the recommendation ways to do SkyWalking upgrade.