From 0b38fae83cefcbd74b64e078702f0b641f2a71e1 Mon Sep 17 00:00:00 2001 From: Abby <78209557+abby-cyber@users.noreply.github.com> Date: Tue, 17 Oct 2023 17:38:11 +0800 Subject: [PATCH 1/4] upgrade-doc-for-3.6.0-ent --- .../upgrade-nebula-ent-from-3.x-3.4.md | 144 ++++++++++++++++-- 1 file changed, 133 insertions(+), 11 deletions(-) diff --git a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md index 4de0e82b5a4..2f0c761c22a 100644 --- a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md +++ b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md @@ -4,23 +4,131 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and ## Notes -- This upgrade is only applicable for upgrading the enterprise edition of NebulaGraph v3.x (x < 4) to v{{nebula.release}}. For upgrading from version 3.4.0 and above to {{nebula.release}}, you can directly replace the binary files for an upgrade. For more information, see [Upgrade NebulaGraph to {{nebula.release}}](https://docs.nebula-graph.com.cn/{{nebula.release}}/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-graph-to-latest/). - - !!! note - - If your version is below 3.0.0, please upgrade to enterprise edition 3.1.0 before upgrading to v{{nebula.release}}. For details, see [Upgrade NebulaGraph Enterprise Edition 2.x to 3.1.0](https://docs.nebula-graph.io/3.1.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-graph-to-latest/). +- Rolling Upgrade is not supported. You must stop all the NebulaGraph services before the upgrade. +- There is no upgrade script. You have to manually upgrade each server in the cluster. + - The IP address of the machine performing the upgrade operation must be the same as the original machine. +- You must have the sudo privileges to complete the steps in this topic. - The remaining disk space on the machine must be at least 1.5 times the size of the original data directory. -- Before upgrading a NebulaGraph cluster with full-text indexes deployed, you must manually delete the full-text indexes in Elasticsearch, and then run the `SIGN IN` command to log into ES and recreate the indexes after the upgrade is complete. +- Known issues that could cause data loss are listed on [GitHub known issues](https://github.com/vesoft-inc/nebula-graph/issues/857). The issues are all related to altering schema or default values. + +## Upgrade influences + + + +- Client compatibility + + After the upgrade, you will not be able to connect to NebulaGraph from old clients. You will need to upgrade all clients to a version compatible with NebulaGraph {{nebula.release}}. + +- Configuration changes + + A few configuration parameters have been changed. For more information, see the release notes and configuration docs. + +- nGQL compatibility + + The nGQL syntax is partially incompatible: + + - Disable the `YIELD` clause to return custom variables. + + - The `YIELD` clause is required in the `FETCH`, `GO`, `LOOKUP`, `FIND PATH` and `GET SUBGRAPH` statements. + + - It is required to specify a tag to query properties of a vertex in a `MATCH` statement. For example, from `return v.name` to `return v.player.name`. + +- Full-text indexes + + Before upgrading a NebulaGraph cluster with full-text indexes deployed, you must manually delete the full-text indexes in Elasticsearch, and then run the `SIGN IN` command to log into ES and recreate the indexes after the upgrade is complete. To manually delete the full-text indexes in Elasticsearch, you can use the curl command `curl -XDELETE -u : ':/'`, for example, `curl -XDELETE -u elastic:elastic 'http://192.168.8.xxx:9200/nebula_index_2534'`. If no username and password are set for Elasticsearch, you can omit the `-u :` part. + + +## Upgrading to {{nebula.release}} from version 3.4.0 and above + + +1. Stop all {{nebula.name}} services. + + ``` + /scripts/nebula.service stop all + ``` + + Replace `install_path` with the installation directory of the {{nebula.name}} instance you want to upgrade. + + Allow approximately 1 minute for the `storaged` process to flush data. You can continue by running the `nebula.service status all` command to confirm that all services have stopped. For detailed instructions on starting and stopping services, refer to [Managing Services](../manage-service.md). + + !!! note + + If services cannot be stopped within 20 minutes, abandon the upgrade, and contact customer support. + + !!! caution + + Starting from version 3.0.0, {{nebula.name}} supports inserting points without tags. To retain points without tags, add the `--graph_use_vertex_key=true` flag to the configuration file (`nebula-graphd.conf`) of all Graph services within the cluster and add the `--use_vertex_key=true` flag to the configuration file (`nebula-storaged.conf`) of all Storage services. + +2. Prepare the installation package for {{nebula.name}} {{nebula.release}} and extract it. You can specify any installation directory. + +3. In the directory of {{nebula.release}}, use the new binary files from its `bin` directory to replace the old binary files in the `bin` directory of the {{nebula.name}} installation path. + + !!! note + Update the binary files for each machine where {{nebula.name}} services are deployed. + + + +4. In the `/etc/nebula-metad.conf` configuration file of {{nebula.release}}, configure the `license_manager_url` parameter to specify the LM's path. + + The LM is used to verify {{nebula.name}}'s licensing information. For details, see [LM Configuration](../../9.about-license/2.license-management-suite/3.license-manager.md). !!! note + Starting from version 3.5.0, {{nebula.name}} enables license validation, so it's necessary to install and configure LM. + +5. Start all Meta services. + + ``` + /scripts/nebula-metad.service start + ``` + + After starting, the Meta services will elect a leader. This process takes a few seconds. + + Once started, you can start any Graph service node and connect to it using {{nebula.name}}. Run [`SHOW HOSTS meta`](../../3.ngql-guide/7.general-query-statements/6.show/6.show-hosts.md) and [`SHOW META LEADER`](../../3.ngql-guide/7.general-query-statements/6.show/19.show-meta-leader.md). If they return the status of the Meta node correctly, the Meta service has started successfully. + + !!! note + + If there are any exceptions during startup, abandon the upgrade, and contact customer support. + +5. Start all Graph and Storage services. + + !!! note + + If there are any exceptions during startup, abandon the upgrade, and contact customer support. - To manually delete the full-text indexes in Elasticsearch, you can use the curl command `curl -XDELETE -u : ':/'`, for example, `curl -XDELETE -u elastic:elastic 'http://192.168.8.223:9200/nebula_index_2534'`. If no username and password are set for Elasticsearch, you can omit the `-u :` part. +6. Connect to the new version of {{nebula.name}} and verify that the service is operational and that the data is intact. For information on connecting to the service, refer to [Connecting to Nebula Graph](../connect-to-nebula-graph.md). -## Steps + Some reference commands to test the upgrade are as follows: + + ```ngql + nebula> SHOW HOSTS; + nebula> SHOW HOSTS storage; + nebula> SHOW SPACES; + nebula> USE + nebula> SHOW PARTS; + nebula> SUBMIT JOB STATS; + nebula> SHOW STATS; + nebula> MATCH (v) RETURN v LIMIT 5; + ``` + +## Upgrade 3.x（x < 4）to {{nebula.release}} 1. [Contact us](https://www.nebula-graph.io/contact) to obtain the installation package of the enterprise edition of NebulaGraph v{{nebula.release}} and install it. @@ -32,7 +140,7 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and Please ensure that the number of storage paths set for the `--data_path` parameter in the Meta and Storage service configuration files of the {{nebula.release}} cluster is the same as that for the `--data_path` parameter in the configuration files of the 3.x cluster. Otherwise, the upgraded cluster will not start. -1. Stop the enterprise edition of v3.x services. For details see [Manage NebulaGraph services](https://docs.nebula-graph.io/3.5.0-sc/4.deployment-and-installation/manage-service/). +2. Stop the enterprise edition of v3.x services. For details see [Manage NebulaGraph services](https://docs.nebula-graph.io/3.5.0-sc/4.deployment-and-installation/manage-service/). Run the `nebula.service status all` command to confirm that all services have been stopped after running the command. @@ -89,7 +197,12 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and After the upgrade, a `data` directory will be generated in the v{{nebula.release}} installation directory, containing the upgraded data files. -4. Start and connect to the NebulaGraph v{{nebula.release}} enterprise edition service and verify that the data is correct. The following commands can be used as reference: +4. In the `/usr/local/nebula-ent-{{nebula.release}}/etc/nebula-metad.conf` file, set `license_manager_url` to the URL of [LM](../../9.about-license/2.license-management-suite/3.license-manager.md). + + !!! note + For the Enterprise Edition of NebulaGraph v3.5.0 or later, you need to install and configure LM to verify the license used to start NebulaGraph. + +5. Start and connect to the NebulaGraph v{{nebula.release}} enterprise edition service and verify that the data is correct. The following commands can be used as reference: ``` nebula> SHOW HOSTS; @@ -102,7 +215,16 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and nebula> MATCH (v) RETURN v LIMIT 5; ``` -## Docker Compose Deployment + +## Upgrading from previous versions to {{nebula.release}} + +If the your NebulaGraph database version is lower than 3.0.0, please upgrade to 3.1.0 first and then upgrade to {{nebula.release}}. For detailed steps, see [Upgrading {{nebula.name}} from 2.x to 3.1.0](https://docs.nebula-graph.io/3.1.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-graph-to-latest/). + +!!! note + + Before completing the upgrade and restarting the services, ensure that [LM](../../9.about-license/2.license-management-suite/3.license-manager.md) has been configured. + +## Docker Compose deployment upgrade !!! caution From 897e247cf4b2cb5e0e631f39c7664c87ce76e584 Mon Sep 17 00:00:00 2001 From: Abby <78209557+abby-cyber@users.noreply.github.com> Date: Tue, 17 Oct 2023 19:38:19 +0800 Subject: [PATCH 2/4] Update upgrade-nebula-ent-from-3.x-3.4.md --- .../upgrade-nebula-ent-from-3.x-3.4.md | 28 ++++++++++++++----- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md index 2f0c761c22a..1b22706215e 100644 --- a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md +++ b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md @@ -140,11 +140,29 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and Please ensure that the number of storage paths set for the `--data_path` parameter in the Meta and Storage service configuration files of the {{nebula.release}} cluster is the same as that for the `--data_path` parameter in the configuration files of the 3.x cluster. Otherwise, the upgraded cluster will not start. -2. Stop the enterprise edition of v3.x services. For details see [Manage NebulaGraph services](https://docs.nebula-graph.io/3.5.0-sc/4.deployment-and-installation/manage-service/). +2. Back up the data and the binary files in the subdirectory `bin` of the 3.x cluster. + + !!! note + + The backup is used for rollback in case of upgrade failure. The backup files are not used in the upgrade process. + +3. Stop the enterprise edition of v3.x services. For details see [Manage NebulaGraph services](https://docs.nebula-graph.io/3.5.0-sc/4.deployment-and-installation/manage-service/). Run the `nebula.service status all` command to confirm that all services have been stopped after running the command. -3. In the installation directory of the Enterprise Edition NebulaGraph v{{nebula.release}}, run the following commands to upgrade the Storage and Meta services. + +4. In the subdirectory `etc` of the {{nebula.name}} v{{nebula.release}} installation directory, update the configuration files (if there have been any configuration updates previously). + + !!! note + + If there were no configuration updates previously, you can skip this step. + +1. In the `nebula-metad.conf` file of {{nebula.name}} v{{nebula.release}}, set `license_manager_url` to the URL of [LM](../../9.about-license/2.license-management-suite/3.license-manager.md). + + !!! note + For the Enterprise Edition of NebulaGraph v3.5.0 or later, you need to install and configure LM to verify the license used to start NebulaGraph. + +6. In the installation directory of the Enterprise Edition NebulaGraph v{{nebula.release}}, run the following commands to upgrade the Storage and Meta services. - Upgrade the Storage service: @@ -197,12 +215,8 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and After the upgrade, a `data` directory will be generated in the v{{nebula.release}} installation directory, containing the upgraded data files. -4. In the `/usr/local/nebula-ent-{{nebula.release}}/etc/nebula-metad.conf` file, set `license_manager_url` to the URL of [LM](../../9.about-license/2.license-management-suite/3.license-manager.md). - - !!! note - For the Enterprise Edition of NebulaGraph v3.5.0 or later, you need to install and configure LM to verify the license used to start NebulaGraph. -5. Start and connect to the NebulaGraph v{{nebula.release}} enterprise edition service and verify that the data is correct. The following commands can be used as reference: +7. Start and connect to the NebulaGraph v{{nebula.release}} enterprise edition service and verify that the data is correct. The following commands can be used as reference: ``` nebula> SHOW HOSTS; From 83d0a25952cf6e782ece4615b5d70e30725cc7c5 Mon Sep 17 00:00:00 2001 From: Abby <78209557+abby-cyber@users.noreply.github.com> Date: Wed, 18 Oct 2023 09:55:55 +0800 Subject: [PATCH 3/4] Update upgrade-nebula-ent-from-3.x-3.4.md --- .../upgrade-nebula-ent-from-3.x-3.4.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md index 1b22706215e..4886f5df784 100644 --- a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md +++ b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md @@ -12,8 +12,6 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and - You must have the sudo privileges to complete the steps in this topic. - The remaining disk space on the machine must be at least 1.5 times the size of the original data directory. - -- Known issues that could cause data loss are listed on [GitHub known issues](https://github.com/vesoft-inc/nebula-graph/issues/857). The issues are all related to altering schema or default values. ## Upgrade influences @@ -49,6 +47,9 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and Before upgrading a NebulaGraph cluster with full-text indexes deployed, you must manually delete the full-text indexes in Elasticsearch, and then run the `SIGN IN` command to log into ES and recreate the indexes after the upgrade is complete. To manually delete the full-text indexes in Elasticsearch, you can use the curl command `curl -XDELETE -u : ':/'`, for example, `curl -XDELETE -u elastic:elastic 'http://192.168.8.xxx:9200/nebula_index_2534'`. If no username and password are set for Elasticsearch, you can omit the `-u :` part. + !!! note + + For upgrades from version 3.5.0 and later to {{nebula.release}}, there's no need to manually delete the full-text indexes. ## Upgrading to {{nebula.release}} from version 3.4.0 and above @@ -157,7 +158,7 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and If there were no configuration updates previously, you can skip this step. -1. In the `nebula-metad.conf` file of {{nebula.name}} v{{nebula.release}}, set `license_manager_url` to the URL of [LM](../../9.about-license/2.license-management-suite/3.license-manager.md). +5. In the `nebula-metad.conf` file of {{nebula.name}} v{{nebula.release}}, set `license_manager_url` to the URL of [LM](../../9.about-license/2.license-management-suite/3.license-manager.md). !!! note For the Enterprise Edition of NebulaGraph v3.5.0 or later, you need to install and configure LM to verify the license used to start NebulaGraph. @@ -230,19 +231,14 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and ``` -## Upgrading from previous versions to {{nebula.release}} + -!!! caution - - For NebulaGraph deployed using Docker Compose, it is recommended to redeploy the new version and import data. From 3fa62c2f4a49819075161d7b774e5be51c329213 Mon Sep 17 00:00:00 2001 From: Abby <78209557+abby-cyber@users.noreply.github.com> Date: Wed, 18 Oct 2023 10:45:45 +0800 Subject: [PATCH 4/4] Update upgrade-nebula-ent-from-3.x-3.4.md --- .../3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md index 4886f5df784..0bf3ff9a397 100644 --- a/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md +++ b/docs-2.0/4.deployment-and-installation/3.upgrade-nebula-graph/upgrade-nebula-ent-from-3.x-3.4.md @@ -87,7 +87,7 @@ This topic takes the enterprise edition of NebulaGraph v3.1.0 as an example and The default values of these parameters in version 2.x are not within the value range of the new version. Failure to modify them will result in a failed upgrade. For detailed parameter descriptions, refer to [Graph Service Configuration](../../5.configurations-and-logs/1.configurations/3.graph-config.md). --> -4. In the `/etc/nebula-metad.conf` configuration file of {{nebula.release}}, configure the `license_manager_url` parameter to specify the LM's path. +4. In the `nebula-metad.conf` configuration file of NebulaGraph, add the `license_manager_url` parameter and set it to the LM's path. The LM is used to verify {{nebula.name}}'s licensing information. For details, see [LM Configuration](../../9.about-license/2.license-management-suite/3.license-manager.md).