From f25f96d6032e2a324450c57602254d3453afac71 Mon Sep 17 00:00:00 2001 From: akarasavov Date: Tue, 15 Oct 2024 09:53:59 +0100 Subject: [PATCH 01/23] descirbe semi-automated procedure --- .../pages/clustering/setup/discovery.adoc | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 2e50cc0e0..4df73f105 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -558,6 +558,27 @@ As such, ensure that `dbms.cluster.discovery.version=V2_ONLY`, and that `dbms.cl are set as required, so that the servers start with v2 running on the next restart. ==== +[[discovery-v1-to-v2-semi-automated-procedure]] +=== Semi-automated procedure + +Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process +It automates the approach described in the xref:clustering/setup/discovery.adoc#_using_procedures[previous section]. + +. Make sure that server side routing is enabled as detailed in xref:https://neo4j.com/docs/operations-manual/current/clustering/setup/routing/#clustering-routing[Server-side routing] section +. For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. +. Connect to any server using server-side routing ++ +[source,cypher] +---- +./cypher-shell -a neo4j://localhost:7691 -d system +---- +. Run the following procedure three times to move all members from `V1_ONLY` to `V2_ONLY`. If the procedure fails, read the error message and resolve the issue manually. +One possible reason for failure is that some members might have had inconsistent `dbms.cluster.discovery.version` settings initially. +Refer to the previous section for guidance on debugging and fixing issues. +[source,cypher] +---- +CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); +---- == Monitoring the progress and metrics From b0b8965f2ff92ca96717d7f15d491349af146df5 Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Tue, 15 Oct 2024 11:42:38 +0100 Subject: [PATCH 02/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 4df73f105..6cac98f6f 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -564,7 +564,7 @@ are set as required, so that the servers start with v2 running on the next resta Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process It automates the approach described in the xref:clustering/setup/discovery.adoc#_using_procedures[previous section]. -. Make sure that server side routing is enabled as detailed in xref:https://neo4j.com/docs/operations-manual/current/clustering/setup/routing/#clustering-routing[Server-side routing] section +. Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section . For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. . Connect to any server using server-side routing + From 28f002c0f74e9f8e9335c167fb91728a0ac58094 Mon Sep 17 00:00:00 2001 From: akarasavov Date: Tue, 15 Oct 2024 11:49:34 +0100 Subject: [PATCH 03/23] Added an additional step in semi-automated procedure --- modules/ROOT/pages/clustering/setup/discovery.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 6cac98f6f..9f2a4b50d 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -562,7 +562,7 @@ are set as required, so that the servers start with v2 running on the next resta === Semi-automated procedure Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process -It automates the approach described in the xref:clustering/setup/discovery.adoc#_using_procedures[previous section]. +It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[previous section]. . Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section . For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. @@ -572,14 +572,17 @@ It automates the approach described in the xref:clustering/setup/discovery.adoc# ---- ./cypher-shell -a neo4j://localhost:7691 -d system ---- + . Run the following procedure three times to move all members from `V1_ONLY` to `V2_ONLY`. If the procedure fails, read the error message and resolve the issue manually. One possible reason for failure is that some members might have had inconsistent `dbms.cluster.discovery.version` settings initially. Refer to the previous section for guidance on debugging and fixing issues. ++ [source,cypher] ---- CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); ---- +. In the last step, set the `dbms.cluster.discovery.version=V2_ONLY` for each member of the cluster, so that the version change is retained after a restart. == Monitoring the progress and metrics From 49097b9fc5aceccf4f34acda591fd592a3c7d306 Mon Sep 17 00:00:00 2001 From: akarasavov Date: Tue, 15 Oct 2024 12:10:12 +0100 Subject: [PATCH 04/23] How to check that procedure was successful --- modules/ROOT/pages/clustering/setup/discovery.adoc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 9f2a4b50d..10b913a9f 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -581,7 +581,16 @@ Refer to the previous section for guidance on debugging and fixing issues. ---- CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); ---- - +. To check that the migration was successful, you can execute `CALL dbms.cluster.showParallelDiscoveryState()` on all members of the cluster. You should see that V2_ONLY is the current version. ++ +[queryresult] +---- ++-------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++-------------------------------------------------------------+ +| "V2_ONLY" | "N/A" | "N/A" | "3" | ++-------------------------------------------------------------+ +---- . In the last step, set the `dbms.cluster.discovery.version=V2_ONLY` for each member of the cluster, so that the version change is retained after a restart. == Monitoring the progress and metrics From 8e00975c4d4d9a65111e1315518ea1e70b44d5b9 Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Tue, 15 Oct 2024 14:41:31 +0100 Subject: [PATCH 05/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: Nick Giles <100630647+nick-giles-neo@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 10b913a9f..be9bbb193 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -591,7 +591,7 @@ CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); | "V2_ONLY" | "N/A" | "N/A" | "3" | +-------------------------------------------------------------+ ---- -. In the last step, set the `dbms.cluster.discovery.version=V2_ONLY` for each member of the cluster, so that the version change is retained after a restart. +. In the last step, add `dbms.cluster.discovery.version=V2_ONLY` to the config file for each member of the cluster, so that the version change is retained after a restart. == Monitoring the progress and metrics From 43410f739b11907df1ef4aa90e444331e1316d6a Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Tue, 15 Oct 2024 14:42:33 +0100 Subject: [PATCH 06/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: Nick Giles <100630647+nick-giles-neo@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index be9bbb193..04a37a134 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -566,7 +566,7 @@ It automates the approach described in the xref:clustering/setup/discovery.adoc# . Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section . For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. -. Connect to any server using server-side routing +. Connect to any server. + [source,cypher] ---- From ea61259230dd7d6b2db4542fd5ba021ae1d3445e Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Tue, 15 Oct 2024 16:08:07 +0100 Subject: [PATCH 07/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: Nick Giles <100630647+nick-giles-neo@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 04a37a134..34e0c7f59 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -561,7 +561,7 @@ are set as required, so that the servers start with v2 running on the next resta [[discovery-v1-to-v2-semi-automated-procedure]] === Semi-automated procedure -Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process +Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process. It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[previous section]. . Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section From 99270ad333941ceff0ceacf99c6df8f61251bc31 Mon Sep 17 00:00:00 2001 From: akarasavov Date: Wed, 16 Oct 2024 08:48:04 +0100 Subject: [PATCH 08/23] move semi-automated procedure before the manual one --- .../pages/clustering/setup/discovery.adoc | 80 ++++++++++--------- 1 file changed, 44 insertions(+), 36 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 34e0c7f59..9b3c87db0 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -412,8 +412,51 @@ CALL dbms.cluster.showParallelDiscoveryState(); +-------------------------------------------------------------+ ---- +[[discovery-v1-to-v2-semi-automated-procedure]] +=== Semi-automated procedure + +Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process +It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[next section]. + +. Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section +. For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. +. Connect to any server using server-side routing ++ +[source,cypher] +---- +./cypher-shell -a neo4j://localhost:7691 -d system +---- + +. Run the following procedure three times to move all members from `V1_ONLY` to `V2_ONLY`. ++ +[source,cypher] +---- +CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); +---- +After each call `internal.dbms.cluster.moveToNextDiscoveryVersion()` you need to make sure that `dbms.cluster.showParallelDiscoveryState()` display `Matching` in the `stateComparison` column. +If they are not, wait and try again till matching. + +The output should display `Matching` in the `stateComparison` column. +If they are not, wait and try again till matching. + +If the procedure fails, read the error message and resolve the issue manually. +One possible reason for failure is that some members might have had inconsistent `dbms.cluster.discovery.version` settings initially. +Refer to the next section for guidance on debugging and fixing issues. + +. To check that the migration was successful, you can execute `CALL dbms.cluster.showParallelDiscoveryState()` on all members of the cluster. You should see that V2_ONLY is the current version. ++ +[queryresult] +---- ++-------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++-------------------------------------------------------------+ +| "V2_ONLY" | "N/A" | "N/A" | "3" | ++-------------------------------------------------------------+ +---- +. In the last step, set the `dbms.cluster.discovery.version=V2_ONLY` for each member of the cluster, so that the version change is retained after a restart. + [[discovery-v1-to-v2-procedures]] -=== Using procedures +=== Manual procedures // By using just procedures, the nice thing is that during the user's normal version upgrade, they can also add the new settings required for v2 discovery service. // Then, when they are ready to migrate to v2, they can use the procedures and then finally, set the version to 'V2' in the neo4j.conf at the very end - which can just sit there till the next restart @@ -558,41 +601,6 @@ As such, ensure that `dbms.cluster.discovery.version=V2_ONLY`, and that `dbms.cl are set as required, so that the servers start with v2 running on the next restart. ==== -[[discovery-v1-to-v2-semi-automated-procedure]] -=== Semi-automated procedure - -Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process. -It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[previous section]. - -. Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section -. For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. -. Connect to any server. -+ -[source,cypher] ----- -./cypher-shell -a neo4j://localhost:7691 -d system ----- - -. Run the following procedure three times to move all members from `V1_ONLY` to `V2_ONLY`. If the procedure fails, read the error message and resolve the issue manually. -One possible reason for failure is that some members might have had inconsistent `dbms.cluster.discovery.version` settings initially. -Refer to the previous section for guidance on debugging and fixing issues. -+ -[source,cypher] ----- -CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); ----- -. To check that the migration was successful, you can execute `CALL dbms.cluster.showParallelDiscoveryState()` on all members of the cluster. You should see that V2_ONLY is the current version. -+ -[queryresult] ----- -+-------------------------------------------------------------+ -| mode | stateComparison | v1ServerCount | v2ServerCount | -+-------------------------------------------------------------+ -| "V2_ONLY" | "N/A" | "N/A" | "3" | -+-------------------------------------------------------------+ ----- -. In the last step, add `dbms.cluster.discovery.version=V2_ONLY` to the config file for each member of the cluster, so that the version change is retained after a restart. - == Monitoring the progress and metrics When moving from the current discovery service v1 to the new version v2, you can monitor the progress using the procedure `CALL dbms.cluster.showParallelDiscoveryState()`. From 93260c27ef31567c43088e42b2a91aab1f4a3890 Mon Sep 17 00:00:00 2001 From: akarasavov Date: Wed, 16 Oct 2024 09:30:54 +0100 Subject: [PATCH 09/23] Update the semi-automated approach --- .../pages/clustering/setup/discovery.adoc | 117 +++++++++++++++--- 1 file changed, 102 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 9b3c87db0..611e8b1db 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -415,36 +415,114 @@ CALL dbms.cluster.showParallelDiscoveryState(); [[discovery-v1-to-v2-semi-automated-procedure]] === Semi-automated procedure -Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process +Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process. It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[next section]. . Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section . For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. -. Connect to any server using server-side routing ++ +As an example, for those using the list resolver, the settings for all the servers should include: ++ +[source, parameters] +---- +dbms.cluster.discovery.resolver_type=LIST + +dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000 +dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000 +---- ++ +. In Cypher Shell, connect to the `system` database of any server + [source,cypher] ---- -./cypher-shell -a neo4j://localhost:7691 -d system +./cypher-shell -a bolt://localhost:7683 -d system ---- - -. Run the following procedure three times to move all members from `V1_ONLY` to `V2_ONLY`. +. Run the procedure: ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +The output indicates mode `V1_ONLY`, i.e., only v1 is running on this server. ++ +.Expected result +[queryresult] +---- ++-------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++-------------------------------------------------------------+ +| "V1_ONLY" | "N/A" | "3" | "N/A" | ++-------------------------------------------------------------+ +---- +. Run the following procedure to turn on `V2` in the background for all servers, but keep `V1` running in the foreground. +If the procedure fails, read the error message and resolve the issue manually. +One possible reason for failure is that some members might have had inconsistent `dbms.cluster.discovery.version` settings initially. + [source,cypher] ---- CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); ---- -After each call `internal.dbms.cluster.moveToNextDiscoveryVersion()` you need to make sure that `dbms.cluster.showParallelDiscoveryState()` display `Matching` in the `stateComparison` column. +. Check the state again: ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +Now the returned mode for this server must be `V1_OVER_V2` and the `stateComparison` must show that the states are matching. If they are not, wait and try again till matching. - -The output should display `Matching` in the `stateComparison` column. ++ +.Expected result +[queryresult] +---- ++----------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++----------------------------------------------------------------+ +| "V1_OVER_V2" | "Matching" | "3" | "3" | ++----------------------------------------------------------------+ +---- +. Run the once again the following procedure to turn on `V1` in the background for all servers, but keep `V2` running in the foreground. ++ +[source,cypher] +---- +CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); +---- +. Check that transition to `V2_OVER_V1` was successful: ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +Now the returned mode for this server must be `V2_OVER_V1` and the `stateComparison` must show that the states are matching. If they are not, wait and try again till matching. - -If the procedure fails, read the error message and resolve the issue manually. -One possible reason for failure is that some members might have had inconsistent `dbms.cluster.discovery.version` settings initially. -Refer to the next section for guidance on debugging and fixing issues. - -. To check that the migration was successful, you can execute `CALL dbms.cluster.showParallelDiscoveryState()` on all members of the cluster. You should see that V2_ONLY is the current version. + +.Expected result +[queryresult] +---- ++----------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++----------------------------------------------------------------+ +| "V2_OVER_V1" | "Matching" | "3" | "3" | ++----------------------------------------------------------------+ +---- +. Finally, turn off `V1` by running the following procedure: ++ +[source,cypher] +---- +CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); +---- +. Check that transition to `V2_ONLY` was successful: ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +Note that stateComparison is `N/A` because you do not have v1 to compare states anymore. ++ +.Expected result [queryresult] ---- +-------------------------------------------------------------+ @@ -453,7 +531,16 @@ Refer to the next section for guidance on debugging and fixing issues. | "V2_ONLY" | "N/A" | "N/A" | "3" | +-------------------------------------------------------------+ ---- -. In the last step, set the `dbms.cluster.discovery.version=V2_ONLY` for each member of the cluster, so that the version change is retained after a restart. ++ +.Important +[IMPORTANT] +==== +Remember to update the _neo4j.conf_ files for all the servers. +The switching using procedures does not persist anything to disk. +Therefore, when a server restarts, it starts right back with only v1 running. +As such, ensure that `dbms.cluster.discovery.version=V2_ONLY`, and that `dbms.cluster.discovery.v2.endpoints` or `dbms.kubernetes.discovery.v2.service_port_name` +are set as required, so that the servers start with v2 running on the next restart. +==== [[discovery-v1-to-v2-procedures]] === Manual procedures From 18df8b42492f99052a7cae7a040a74095f893e8a Mon Sep 17 00:00:00 2001 From: akarasavov Date: Wed, 16 Oct 2024 09:41:05 +0100 Subject: [PATCH 10/23] Style fixes --- modules/ROOT/pages/clustering/setup/discovery.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 611e8b1db..f80645e61 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -433,9 +433,9 @@ dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.c + . In Cypher Shell, connect to the `system` database of any server + -[source,cypher] +[source, shell, role=nocopy noplay] ---- -./cypher-shell -a bolt://localhost:7683 -d system +./cypher-shell -a bolt://localhost:7681 -d system ---- . Run the procedure: + @@ -444,7 +444,7 @@ dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.c CALL dbms.cluster.showParallelDiscoveryState(); ---- + -The output indicates mode `V1_ONLY`, i.e., only v1 is running on this server. +The output indicates mode `V1_ONLY`, i.e., only `V1` is running on this server. + .Expected result [queryresult] @@ -520,7 +520,7 @@ CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); CALL dbms.cluster.showParallelDiscoveryState(); ---- + -Note that stateComparison is `N/A` because you do not have v1 to compare states anymore. +Note that stateComparison is `N/A` because you do not have `V1` to compare states anymore. + .Expected result [queryresult] From 4e999d80d021c2e824b9f433d6c9cbd9fe7a2417 Mon Sep 17 00:00:00 2001 From: akarasavov Date: Thu, 17 Oct 2024 09:31:29 +0100 Subject: [PATCH 11/23] Change the order of subsections --- .../pages/clustering/setup/discovery.adoc | 389 +++++++++--------- 1 file changed, 197 insertions(+), 192 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index f80645e61..87b9673de 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -200,7 +200,7 @@ From Neo4j 5.23, you can move from the current discovery service v1 to the new v The v1 and v2 discovery services are designed to be able to run in parallel. They are completely independent of each other, thus allowing you to keep the cluster functioning while switching over from v1 to v2. -There are three ways to move from the current discovery service v1 to the new version v2 depending on the environment and the requirements of the cluster. +There are four ways to move from the current discovery service v1 to the new version v2 depending on the environment and the requirements of the cluster. === Preparation @@ -223,197 +223,8 @@ For more information, see <>. It is important that both `dbms.kubernetes.service_port_name` and `dbms.kubernetes.discovery.v2.service_port_name` are set during the operation. For more information, see <>. -[[discovery-v1-to-v2-in-place]] -=== In-place rolling - -[IMPORTANT] -==== -In-place rolling reduces fault tolerance temporarily because you are restarting a running server. -To keep fault-tolerance, you can introduce a fourth server temporarily. -==== -. For all the servers, ensure that new settings are added to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. -+ -As an example, for those using the list resolver, the settings for all the servers should include: -+ -[source, parameters] ----- -dbms.cluster.discovery.resolver_type=LIST - -dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000 -dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000 ----- -. Restart server01 with the new setting `dbms.cluster.discovery.version=V1_OVER_V2`. -+ -image:discovery-service/in-place-1-v1-over-v2.png[] -. Run `SHOW SERVERS` and ensure that all three members are alive. -. Then repeat steps 2 and 3 for server02 and server03. -Ensure that they are set to `dbms.cluster.discovery.version=V1_OVER_V2`. -Restart them sequentially, not in parallel. -+ -image:discovery-service/in-place-23-v1-over-v2.png[] - -. Using `bolt://`, connect to the system database of servers 1, 2, 3, and run the following procedure. -This can be done using via `./cypher-shell -a bolt://localhost:7681 -d system` for example. -+ -[source,cypher] ----- -CALL dbms.cluster.showParallelDiscoveryState(); ----- -+ -They should display "Matching" in the `stateComparison` column. -+ -.Expected result -[queryresult] ----- -+----------------------------------------------------------------+ -| mode | stateComparison | v1ServerCount | v2ServerCount | -+----------------------------------------------------------------+ -| "V1_OVER_V2" | "Matching" | "3" | "3" | -+----------------------------------------------------------------+ ----- -+ -If they are not, wait and try again. -+ -. Restart server01 again with the new setting `dbms.cluster.discovery.version=V2_OVER_V1`. -+ -image:discovery-service/in-place-1-v2-over-v1.png[] -+ -. Run `SHOW SERVERS` and ensure that all three members are alive. -. Then repeat steps 6 and 7 for servers 2 and 3. -Ensure that they are set to `dbms.cluster.discovery.version=V2_OVER_V1`. -Restart them sequentially, not in parallel. -+ -image:discovery-service/in-place-23-v2-over-v1.png[] - -. Similar to step 5, verify that `stateComparison` shows `Matching`. - -. Repeat steps 6, 7, 8, 9, restarting servers 1, 2, and 3 sequentially, with the new setting `dbms.cluster.discovery.version=V2_ONLY` -image:discovery-service/in-place-123-v2-only.png[] -. Verify that `CALL dbms.cluster.showParallelDiscoveryState()` now shows `V2_ONLY` running. -Note that `stateComparison` is `N/A` because you do not have v1 to compare states anymore. - -[[discovery-v1-to-v2-new-server]] -=== New server rolling -The new server rolling requires three running servers and three new servers. - -. Start up the three new servers with the setting `dbms.cluster.discovery.version=V1_OVER_V2`. -+ -image:discovery-service/v1_over_v2.png[] -+ -The new servers should have settings which are updated as detailed in the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. -The discovery addresses should include addresses of the new members, and the previous members. -+ -As an example, for those using the list resolver, the settings for the new servers should include: -+ -[source, parameters] ----- -dbms.cluster.discovery.resolver_type=LIST -dbms.cluster.discovery.version=V1_OVER_V2 - -dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000,server04.example.com:5000,server05.example.com:5000,server06.example.com:5000 -dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000,server06.example.com:6000 ----- -+ -. Using `bolt://`, connect to the system database of servers 4, 5, 6, and run the following procedure. -This can be done using via `./cypher-shell -a bolt://localhost:7685 -d system` for example. -+ -[source,cypher] ----- -CALL dbms.cluster.showParallelDiscoveryState(); ----- -+ -The expected result should display `v2ServerCount` as 3. -`stateComparison` is not expected to match at this stage because the original servers are not visible to the V2 discovery service. -+ -.Expected result -[queryresult] ----- - +---------------------------------------------------------------------------------------------------------+ - | mode | stateComparison | v1ServerCount | v2ServerCount | - +---------------------------------------------------------------------------------------------------------+ - | "V1_OVER_V2" | "States are not matching after PT55M36.693S: (score:29)" | "6" | "3" | - +---------------------------------------------------------------------------------------------------------+ ----- -+ -. Deallocate, drop, and shut down servers 1, 2, 3. -+ -. Start up servers 7, 8, 9, this time with the setting `dbms.cluster.discovery.version=V2_OVER_V1`. -+ -image:discovery-service/v2_over_v1.png[] -+ -The discovery addresses in the settings should include addresses of the new members, and the previous members. -+ -As an example, for those using the list resolver, the settings for the new servers should include: -+ -[source, parameters] ----- -dbms.cluster.discovery.resolver_type=LIST -dbms.cluster.discovery.version=V2_OVER_V1 - -dbms.cluster.discovery.endpoints=server04.example.com:5000,server05.example.com:5000,server06.example.com:5000,server07.example.com:5000,server08.example.com:5000,server09.example.com:5000 -dbms.cluster.discovery.v2.endpoints=server04.example.com:6000,server05.example.com:6000,server06.example.com:6000,server07.example.com:6000,server08.example.com:6000,server09.example.com:6000 ----- -+ -. Using `bolt://`, connect to the system database of servers 7, 8, 9 and run the following procedure: -+ -[source,cypher] ----- -CALL dbms.cluster.showParallelDiscoveryState(); ----- -+ -The output should display `Matching` in the `stateComparison` column. -If they are not, wait and try again till matching. -+ -.Expected result -[queryresult] ----- -+----------------------------------------------------------------+ -| mode | stateComparison | v1ServerCount | v2ServerCount | -+----------------------------------------------------------------+ -| "V2_OVER_V1" | "Matching" | "6" | "6" | -+----------------------------------------------------------------+ ----- -+ -. Deallocate, drop, and shut down servers 4, 5, and 6. -+ -. Start up servers 10, 11, 12, this time with the setting `dbms.cluster.discovery.version=V2_ONLY`. -+ -image:discovery-service/v2_only.png[] -+ -The discovery addresses in the settings should include addresses of the new members, and the previous members. -Note that only the v2 settings are required. -+ -As an example, for those using the list resolver, the settings for the new servers should include: -+ -[source, parameters] ----- -dbms.cluster.discovery.resolver_type=LIST -dbms.cluster.discovery.version=V2_ONLY - -dbms.cluster.discovery.v2.endpoints=server07.example.com:6000,server08.example.com:6000,server09.example.com:6000,server10.example.com:6000,server11.example.com:6000,server12.example.com:6000 ----- -+ -. Deallocate, drop, and shut down servers 7, 8, 9. -+ -. Finally, using `bolt://`, connect to the system database of servers 10, 11, 12, and run the following procedure to check the version of the discovery service: -+ -[source,cypher] ----- -CALL dbms.cluster.showParallelDiscoveryState(); ----- -+ -.Expected result -[queryresult] ----- -+-------------------------------------------------------------+ -| mode | stateComparison | v1ServerCount | v2ServerCount | -+-------------------------------------------------------------+ -| "V2_ONLY" | "N/A" | "N/A" | "3" | -+-------------------------------------------------------------+ ----- - [[discovery-v1-to-v2-semi-automated-procedure]] -=== Semi-automated procedure +=== Moving whole cluster with a procedure Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process. It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[next section]. @@ -543,13 +354,18 @@ are set as required, so that the servers start with v2 running on the next resta ==== [[discovery-v1-to-v2-procedures]] -=== Manual procedures +=== Per server procedure // By using just procedures, the nice thing is that during the user's normal version upgrade, they can also add the new settings required for v2 discovery service. // Then, when they are ready to migrate to v2, they can use the procedures and then finally, set the version to 'V2' in the neo4j.conf at the very end - which can just sit there till the next restart // so no lighthouse-specific server restarts are required if all is done correctly. //Note that the settings detailed above must first be set and the servers restarted to allow the settings to take effect. +[IMPORTANT] +==== +If the cluster procedure had problems, or you need to change individual servers to resolve an issue, this approach will let you do so. +==== + . For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. + As an example, for those using the list resolver, the settings for all the servers should include: @@ -688,6 +504,195 @@ As such, ensure that `dbms.cluster.discovery.version=V2_ONLY`, and that `dbms.cl are set as required, so that the servers start with v2 running on the next restart. ==== +[[discovery-v1-to-v2-in-place]] +=== In-place rolling + +[IMPORTANT] +==== +In-place rolling reduces fault tolerance temporarily because you are restarting a running server. +To keep fault-tolerance, you can introduce a fourth server temporarily. +==== +. For all the servers, ensure that new settings are added to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. ++ +As an example, for those using the list resolver, the settings for all the servers should include: ++ +[source, parameters] +---- +dbms.cluster.discovery.resolver_type=LIST + +dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000 +dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000 +---- +. Restart server01 with the new setting `dbms.cluster.discovery.version=V1_OVER_V2`. ++ +image:discovery-service/in-place-1-v1-over-v2.png[] +. Run `SHOW SERVERS` and ensure that all three members are alive. +. Then repeat steps 2 and 3 for server02 and server03. +Ensure that they are set to `dbms.cluster.discovery.version=V1_OVER_V2`. +Restart them sequentially, not in parallel. ++ +image:discovery-service/in-place-23-v1-over-v2.png[] + +. Using `bolt://`, connect to the system database of servers 1, 2, 3, and run the following procedure. +This can be done using via `./cypher-shell -a bolt://localhost:7681 -d system` for example. ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +They should display "Matching" in the `stateComparison` column. ++ +.Expected result +[queryresult] +---- ++----------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++----------------------------------------------------------------+ +| "V1_OVER_V2" | "Matching" | "3" | "3" | ++----------------------------------------------------------------+ +---- ++ +If they are not, wait and try again. ++ +. Restart server01 again with the new setting `dbms.cluster.discovery.version=V2_OVER_V1`. ++ +image:discovery-service/in-place-1-v2-over-v1.png[] ++ +. Run `SHOW SERVERS` and ensure that all three members are alive. +. Then repeat steps 6 and 7 for servers 2 and 3. +Ensure that they are set to `dbms.cluster.discovery.version=V2_OVER_V1`. +Restart them sequentially, not in parallel. ++ +image:discovery-service/in-place-23-v2-over-v1.png[] + +. Similar to step 5, verify that `stateComparison` shows `Matching`. + +. Repeat steps 6, 7, 8, 9, restarting servers 1, 2, and 3 sequentially, with the new setting `dbms.cluster.discovery.version=V2_ONLY` +image:discovery-service/in-place-123-v2-only.png[] +. Verify that `CALL dbms.cluster.showParallelDiscoveryState()` now shows `V2_ONLY` running. +Note that `stateComparison` is `N/A` because you do not have v1 to compare states anymore. + +[[discovery-v1-to-v2-new-server]] +=== New server rolling +The new server rolling requires three running servers and three new servers. + +. Start up the three new servers with the setting `dbms.cluster.discovery.version=V1_OVER_V2`. ++ +image:discovery-service/v1_over_v2.png[] ++ +The new servers should have settings which are updated as detailed in the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. +The discovery addresses should include addresses of the new members, and the previous members. ++ +As an example, for those using the list resolver, the settings for the new servers should include: ++ +[source, parameters] +---- +dbms.cluster.discovery.resolver_type=LIST +dbms.cluster.discovery.version=V1_OVER_V2 + +dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000,server04.example.com:5000,server05.example.com:5000,server06.example.com:5000 +dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000,server06.example.com:6000 +---- ++ +. Using `bolt://`, connect to the system database of servers 4, 5, 6, and run the following procedure. +This can be done using via `./cypher-shell -a bolt://localhost:7685 -d system` for example. ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +The expected result should display `v2ServerCount` as 3. +`stateComparison` is not expected to match at this stage because the original servers are not visible to the V2 discovery service. ++ +.Expected result +[queryresult] +---- + +---------------------------------------------------------------------------------------------------------+ + | mode | stateComparison | v1ServerCount | v2ServerCount | + +---------------------------------------------------------------------------------------------------------+ + | "V1_OVER_V2" | "States are not matching after PT55M36.693S: (score:29)" | "6" | "3" | + +---------------------------------------------------------------------------------------------------------+ +---- ++ +. Deallocate, drop, and shut down servers 1, 2, 3. ++ +. Start up servers 7, 8, 9, this time with the setting `dbms.cluster.discovery.version=V2_OVER_V1`. ++ +image:discovery-service/v2_over_v1.png[] ++ +The discovery addresses in the settings should include addresses of the new members, and the previous members. ++ +As an example, for those using the list resolver, the settings for the new servers should include: ++ +[source, parameters] +---- +dbms.cluster.discovery.resolver_type=LIST +dbms.cluster.discovery.version=V2_OVER_V1 + +dbms.cluster.discovery.endpoints=server04.example.com:5000,server05.example.com:5000,server06.example.com:5000,server07.example.com:5000,server08.example.com:5000,server09.example.com:5000 +dbms.cluster.discovery.v2.endpoints=server04.example.com:6000,server05.example.com:6000,server06.example.com:6000,server07.example.com:6000,server08.example.com:6000,server09.example.com:6000 +---- ++ +. Using `bolt://`, connect to the system database of servers 7, 8, 9 and run the following procedure: ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +The output should display `Matching` in the `stateComparison` column. +If they are not, wait and try again till matching. ++ +.Expected result +[queryresult] +---- ++----------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++----------------------------------------------------------------+ +| "V2_OVER_V1" | "Matching" | "6" | "6" | ++----------------------------------------------------------------+ +---- ++ +. Deallocate, drop, and shut down servers 4, 5, and 6. ++ +. Start up servers 10, 11, 12, this time with the setting `dbms.cluster.discovery.version=V2_ONLY`. ++ +image:discovery-service/v2_only.png[] ++ +The discovery addresses in the settings should include addresses of the new members, and the previous members. +Note that only the v2 settings are required. ++ +As an example, for those using the list resolver, the settings for the new servers should include: ++ +[source, parameters] +---- +dbms.cluster.discovery.resolver_type=LIST +dbms.cluster.discovery.version=V2_ONLY + +dbms.cluster.discovery.v2.endpoints=server07.example.com:6000,server08.example.com:6000,server09.example.com:6000,server10.example.com:6000,server11.example.com:6000,server12.example.com:6000 +---- ++ +. Deallocate, drop, and shut down servers 7, 8, 9. ++ +. Finally, using `bolt://`, connect to the system database of servers 10, 11, 12, and run the following procedure to check the version of the discovery service: ++ +[source,cypher] +---- +CALL dbms.cluster.showParallelDiscoveryState(); +---- ++ +.Expected result +[queryresult] +---- ++-------------------------------------------------------------+ +| mode | stateComparison | v1ServerCount | v2ServerCount | ++-------------------------------------------------------------+ +| "V2_ONLY" | "N/A" | "N/A" | "3" | ++-------------------------------------------------------------+ +---- + == Monitoring the progress and metrics When moving from the current discovery service v1 to the new version v2, you can monitor the progress using the procedure `CALL dbms.cluster.showParallelDiscoveryState()`. From 99250217c2f0d4c71ba356f759d10ee1abc27bcd Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Sun, 20 Oct 2024 22:27:33 +0100 Subject: [PATCH 12/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: Nick Giles <100630647+nick-giles-neo@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 87b9673de..13d074924 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -226,7 +226,7 @@ For more information, see <>. [[discovery-v1-to-v2-semi-automated-procedure]] === Moving whole cluster with a procedure -Another way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process. +The simplest way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process. It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[next section]. . Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section From 510a4eeae04df35e176e0ed38c352d8c8fd62401 Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 15:37:40 +0100 Subject: [PATCH 13/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 13d074924..744338a99 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -293,7 +293,7 @@ If they are not, wait and try again till matching. | "V1_OVER_V2" | "Matching" | "3" | "3" | +----------------------------------------------------------------+ ---- -. Run the once again the following procedure to turn on `V1` in the background for all servers, but keep `V2` running in the foreground. +. Once again, run the following procedure to turn on `V1` in the background for all servers, but keep `V2` running in the foreground. + [source,cypher] ---- From fc5e213eaf7ba961bbc726ee4106011901e88e2e Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 15:38:33 +0100 Subject: [PATCH 14/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 744338a99..16e0de6d0 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -268,7 +268,7 @@ The output indicates mode `V1_ONLY`, i.e., only `V1` is running on this server. ---- . Run the following procedure to turn on `V2` in the background for all servers, but keep `V1` running in the foreground. If the procedure fails, read the error message and resolve the issue manually. -One possible reason for failure is that some members might have had inconsistent `dbms.cluster.discovery.version` settings initially. +One possible reason for failure is that some servers might have had inconsistent xref:configuration/configuration.settings.adoc#config_dbms.cluster.discovery.version[`dbms.cluster.discovery.version`] settings initially. + [source,cypher] ---- From 15d932a7afe615b08f68f76349221bd5f5fb57b9 Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 15:38:53 +0100 Subject: [PATCH 15/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 16e0de6d0..72f519b3e 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -226,7 +226,7 @@ For more information, see <>. [[discovery-v1-to-v2-semi-automated-procedure]] === Moving whole cluster with a procedure -The simplest way to migrate from Discovery Service `V1` to `V2` is to use a semi-automated procedure, which simplifies the migration process. +The first way to migrate from discovery service v1 to v2 is to use a semi-automated procedure, which simplifies the migration process. It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[next section]. . Make sure that server side routing is enabled as detailed in xref:clustering/setup/routing.adoc#clustering-routing[Server-side routing] section From cf0b82522b3766af8dd28017a960fcd24b69a33c Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 15:39:03 +0100 Subject: [PATCH 16/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 72f519b3e..cce63f597 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -224,7 +224,7 @@ It is important that both `dbms.kubernetes.service_port_name` and `dbms.kubernet For more information, see <>. [[discovery-v1-to-v2-semi-automated-procedure]] -=== Moving whole cluster with a procedure +=== Moving an entire cluster with a procedure The first way to migrate from discovery service v1 to v2 is to use a semi-automated procedure, which simplifies the migration process. It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[next section]. From 3b26578c9ffe7108e3ccd3ce2f072752013641b1 Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 15:39:12 +0100 Subject: [PATCH 17/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index cce63f597..37ef8f92b 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -242,7 +242,7 @@ dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com: dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000 ---- + -. In Cypher Shell, connect to the `system` database of any server +. In Cypher Shell, connect to the `system` database of any server: + [source, shell, role=nocopy noplay] ---- From b217b83d31fae94a1cc9fa9e6ef7514f1f67b4e8 Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 15:39:34 +0100 Subject: [PATCH 18/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 37ef8f92b..3df043216 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -331,7 +331,7 @@ CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); CALL dbms.cluster.showParallelDiscoveryState(); ---- + -Note that stateComparison is `N/A` because you do not have `V1` to compare states anymore. +Note that `stateComparison` is `N/A` because you do not have `V1` to compare states anymore. + .Expected result [queryresult] From eb04d1303880452cb271a18aba8191e4506c1015 Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 15:39:43 +0100 Subject: [PATCH 19/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 3df043216..588b041a8 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -354,7 +354,7 @@ are set as required, so that the servers start with v2 running on the next resta ==== [[discovery-v1-to-v2-procedures]] -=== Per server procedure +=== Running a procedure on each server // By using just procedures, the nice thing is that during the user's normal version upgrade, they can also add the new settings required for v2 discovery service. // Then, when they are ready to migrate to v2, they can use the procedures and then finally, set the version to 'V2' in the neo4j.conf at the very end - which can just sit there till the next restart From 7dc5eb66974ec5d08d842fe0f523c4e336f71d0c Mon Sep 17 00:00:00 2001 From: Aleksey Karasavov Date: Mon, 21 Oct 2024 16:14:23 +0100 Subject: [PATCH 20/23] Update modules/ROOT/pages/clustering/setup/discovery.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 588b041a8..227822374 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -363,7 +363,7 @@ are set as required, so that the servers start with v2 running on the next resta [IMPORTANT] ==== -If the cluster procedure had problems, or you need to change individual servers to resolve an issue, this approach will let you do so. +If the semi-automated procedure fails, or you need to change individual servers to resolve an issue, this approach will let you do so. ==== . For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section. From c76040e4e6eba5f40460f55bf1c2937702aa20ba Mon Sep 17 00:00:00 2001 From: akarasavov Date: Mon, 21 Oct 2024 16:28:19 +0100 Subject: [PATCH 21/23] Change the titles of the sections --- modules/ROOT/pages/clustering/setup/discovery.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 227822374..b98edcf26 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -224,7 +224,7 @@ It is important that both `dbms.kubernetes.service_port_name` and `dbms.kubernet For more information, see <>. [[discovery-v1-to-v2-semi-automated-procedure]] -=== Moving an entire cluster with a procedure +=== Procedure for moving an entire cluster The first way to migrate from discovery service v1 to v2 is to use a semi-automated procedure, which simplifies the migration process. It automates the approach described in the xref:clustering/setup/discovery.adoc#discovery-v1-to-v2-procedures[next section]. @@ -354,7 +354,7 @@ are set as required, so that the servers start with v2 running on the next resta ==== [[discovery-v1-to-v2-procedures]] -=== Running a procedure on each server +=== Per server procedure // By using just procedures, the nice thing is that during the user's normal version upgrade, they can also add the new settings required for v2 discovery service. // Then, when they are ready to migrate to v2, they can use the procedures and then finally, set the version to 'V2' in the neo4j.conf at the very end - which can just sit there till the next restart From a187ddf1ffe6bbed3fe7b736ce93a0292c6f3863 Mon Sep 17 00:00:00 2001 From: akarasavov Date: Tue, 22 Oct 2024 11:56:39 +0100 Subject: [PATCH 22/23] Added the description move to next discovery version --- .../pages/clustering/setup/discovery.adoc | 6 +++--- modules/ROOT/pages/reference/procedures.adoc | 19 +++++++++++++++++++ 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index b98edcf26..34c7c55b8 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -272,7 +272,7 @@ One possible reason for failure is that some servers might have had inconsistent + [source,cypher] ---- -CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); +CALL dbms.cluster.moveToNextDiscoveryVersion(); ---- . Check the state again: + @@ -297,7 +297,7 @@ If they are not, wait and try again till matching. + [source,cypher] ---- -CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); +CALL dbms.cluster.moveToNextDiscoveryVersion(); ---- . Check that transition to `V2_OVER_V1` was successful: + @@ -322,7 +322,7 @@ If they are not, wait and try again till matching. + [source,cypher] ---- -CALL internal.dbms.cluster.moveToNextDiscoveryVersion(); +CALL dbms.cluster.moveToNextDiscoveryVersion(); ---- . Check that transition to `V2_ONLY` was successful: + diff --git a/modules/ROOT/pages/reference/procedures.adoc b/modules/ROOT/pages/reference/procedures.adoc index fc7e5d99a..7ccaf2f4d 100644 --- a/modules/ROOT/pages/reference/procedures.adoc +++ b/modules/ROOT/pages/reference/procedures.adoc @@ -293,6 +293,11 @@ In 4.2, signature changed to `db.listLocks() :: (mode :: STRING, resourceType :: | label:yes[] | label:new[Introduced in 5.22] label:admin-only[] +| xref:reference/procedures.adoc#procedure_dbms_cluster_movetonextdiscoveryversion[`dbms.cluster.moveToNextDiscoveryVersion()`] +| label:no[] +| label:yes[] +| label:new[Introduced in 5.26] label:admin-only[] + | xref:reference/procedures.adoc#procedure_dbms_cluster_deallocateDatabaseFromServer[`dbms.cluster.deallocateDatabaseFromServer()`] | label:no[] | label:yes[] @@ -1913,6 +1918,20 @@ m| dbms.cluster.showParallelDiscoveryState() :: (mode :: STRING, stateComparison m|DBMS |=== +[[procedure_dbms_cluster_movetonextdiscoveryversion]] +[role=label--enterprise-edition label--new-5.26 label--admin-only ] +.dbms.cluster.moveToNextDiscoveryVersion() +[cols="<15s,<85"] +|=== +| Description +a| The procedure triggers a switch to the next discovery service version for all known members of the cluster (as listed in the system database and discovery). +For example, if the current member's discovery version is V1_ONLY, it will switch all members to V1_OVER_V2. In case of failure, the user must manually resolve the issue. +| Signature +m| dbms.cluster.moveToNextDiscoveryVersion() +| Mode +m|DBMS +|=== + [[procedure_dbms_cluster_deallocateDatabaseFromServer]] [role=label--enterprise-edition label--new-5.23] .dbms.cluster.deallocateDatabaseFromServer() From b2238895ff30865215ca7e35f901f6d862ef1b07 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:10:23 +0200 Subject: [PATCH 23/23] Fix xref --- modules/ROOT/pages/clustering/setup/discovery.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc index 34c7c55b8..155e82ab7 100644 --- a/modules/ROOT/pages/clustering/setup/discovery.adoc +++ b/modules/ROOT/pages/clustering/setup/discovery.adoc @@ -268,7 +268,7 @@ The output indicates mode `V1_ONLY`, i.e., only `V1` is running on this server. ---- . Run the following procedure to turn on `V2` in the background for all servers, but keep `V1` running in the foreground. If the procedure fails, read the error message and resolve the issue manually. -One possible reason for failure is that some servers might have had inconsistent xref:configuration/configuration.settings.adoc#config_dbms.cluster.discovery.version[`dbms.cluster.discovery.version`] settings initially. +One possible reason for failure is that some servers might have had inconsistent xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.version[`dbms.cluster.discovery.version`] settings initially. + [source,cypher] ----