Apply suggestions from code review

yirensum · renetapopova · web-flow · commit f5ab5f537bcc · 2024-08-06T10:57:54.000+01:00
Co-authored-by: Reneta Popova &lt;reneta.popova@neo4j.com&gt;
diff --git a/modules/ROOT/pages/clustering/setup/discovery.adoc b/modules/ROOT/pages/clustering/setup/discovery.adoc
@@ -232,7 +232,7 @@ For more information, see <<clustering-discovery-k8s>>.
 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.
+. 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:
 +
@@ -245,8 +245,9 @@ dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.c
 . 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`
+. 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[]
@@ -261,6 +262,7 @@ CALL dbms.cluster.showParallelDiscoveryState();
 +
 They should display "Matching" in the `stateComparison`.
 +
+.Expected result
 [queryresult]
 ----
 +----------------------------------------------------------------+
@@ -276,9 +278,9 @@ If they are not, wait and try again.
 +
 image:discovery-service/in-place-1-v2-over-v1.png[]
 +
-. Run `Show servers;` and ensure that all three members are alive.
+. 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`
+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[]
@@ -292,8 +294,8 @@ Note that `stateComparison` is `N/A` because you do not have v1 to compare state
 
 [[discovery-v1-to-v2-new-server]]
 === New server rolling
-. New server rolling will require 3 currently running servers, and 3 new servers.
-For all the servers, ensure that new settings are added to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[preparation] section.
+The new server rolling requires three running servers and three new servers.
+. 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:
 +
@@ -315,9 +317,10 @@ This can be done using via `./cypher-shell -a bolt://localhost:7685 -d system` f
 CALL dbms.cluster.showParallelDiscoveryState();
 ----
 +
-The expected result should show `v2ServerCount` to be 3.
-A stateComparison which is not matching is fine at this point.
+The expected result should display `v2ServerCount` as 3.
+`stateComparison` that does show matching is fine at this point.
 +
+.Expected result
 [queryresult]
 ----
  +---------------------------------------------------------------------------------------------------------+
@@ -327,13 +330,14 @@ A stateComparison which is not matching is fine at this point.
  +---------------------------------------------------------------------------------------------------------+
 ----
 +
-. Deallocate, drop, and shut down servers 1, 2, 3. Run `neo4j-admin unbind` on these three servers.
+. Deallocate, drop, and shut down servers 1, 2, 3. 
+. Run `neo4j-admin unbind` on these three servers.
 +
 . Start up servers 1, 2, 3 again, this time with the setting `dbms.cluster.discovery.version=V2_OVER_V1`.
 +
 image:discovery-service/v2_over_v1.png[]
 +
-. Using `bolt://`, connect to the system database of servers 1, 2, 3, and run the following procedure.
+. Using `bolt://`, connect to the system database of servers 1, 2, and 3, and run the following procedure:
 +
 [source,cypher]
 ----
@@ -343,6 +347,7 @@ CALL dbms.cluster.showParallelDiscoveryState();
 The output should display `Matching` in the `stateComparison`.
 If they are not, wait and try again till matching.
 +
+.Expected result
 [queryresult]
 ----
 +----------------------------------------------------------------+
@@ -352,22 +357,23 @@ If they are not, wait and try again till matching.
 +----------------------------------------------------------------+
 ----
 +
-. Deallocate, drop, and shut down servers 4, 5, 6. Run `neo4j-admin unbind` on these three servers.
+. Deallocate, drop, and shut down servers 4, 5, and 6.
+. Run `neo4j-admin unbind` on these three servers.
 +
-. Start up servers 4, 5, 6 again, this time with the setting `dbms.cluster.discovery.version=V2_ONLY`.
+. Start up servers 4, 5, and 6, this time with the setting `dbms.cluster.discovery.version=V2_ONLY`.
 +
 image:discovery-service/v2_only.png[]
 . Deallocate, drop, and shut down servers 1, 2, 3.
 +
-. Finally, one final check. Using `bolt://`, connect to the system database of servers 4, 5, 6, and run the following procedure.
+. Finally, using `bolt://`, connect to the system database of servers 4, 5, and 6, and run the following procedure to check the version of the discovery service:
 +
 [source,cypher]
 ----
 CALL dbms.cluster.showParallelDiscoveryState();
 ----
 +
-One should see the following:
 +
+.Expected result
 [queryresult]
 ----
 +-------------------------------------------------------------+
@@ -385,7 +391,7 @@ One should see the following:
 // 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.
 
-. For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[preparation] 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.
 +
 As an example, for those using the list resolver, the settings for all the servers should include:
 +
@@ -396,7 +402,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
 ```
 +
-. Using Cypher Shell, connect to the system database of server01 using `bolt://`.
+. In Cypher Shell, connect to the system database of server01 using `bolt://`.
 It is important to connect via `bolt://` because otherwise the procedure might be routed and executed not on the intended server.
 +
 [source, shell, role=nocopy noplay]
@@ -413,6 +419,7 @@ CALL dbms.cluster.showParallelDiscoveryState();
 +
 The output indicates mode `V1_ONLY`, i.e., only v1 is running on this server.
 +
+.Expected result
 [queryresult]
 ----
 +-------------------------------------------------------------+
@@ -438,6 +445,7 @@ 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 not matching yet.
 +
+.Expected result
 [queryresult]
 ----
 +-------------------------------------------------------------------------------------------------------+
@@ -448,7 +456,7 @@ Now the returned mode for this server must be `V1_OVER_V2` and the `stateCompari
 ----
 +
 The score is a measure of how different the states are.
-The serverCounts tells us how many servers can be found by v1 and v2 of the discovery service.
+`serverCounts` displays how many servers can be found by v1 and v2 of the discovery service, respectively.
 The score is 0 when the states are matching.
 When some members are running just one of the discovery services (v1 or v2) and other members run both, the score stays permanently high.
 This is no reason for worry.
@@ -460,6 +468,7 @@ This is no reason for worry.
 It should show that the states are `Matching`.
 Both serverCounts should be 3.
 +
+.Expected result
 [queryresult]
 ----
 +----------------------------------------------------------------+
@@ -478,6 +487,7 @@ CALL dbms.cluster.switchDiscoveryServiceVersion("V2_OVER_V1");
 +
 At this point, v2 is the service that is running the cluster, with v1 running in the background.
 +
+.Expected result
 [queryresult]
 ----
 +----------------------------------------------------------------+
@@ -498,6 +508,7 @@ CALL dbms.cluster.switchDiscoveryServiceVersion("V2_ONLY");
 .  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.
 +
+.Expected result
 [queryresult]
 ----
 +-------------------------------------------------------------+

Original file line number	Diff line number	Diff line change
`@@ -232,7 +232,7 @@ For more information, see <<clustering-discovery-k8s>>.`
`232`	`232`	`In-place rolling reduces fault tolerance temporarily because you are restarting a running server.`
`233`	`233`	`To keep fault-tolerance, you can introduce a fourth server temporarily.`
`234`	`234`	`====`
`235`		`-. For all the servers, ensure that new settings are added to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[preparation] section.`
	`235`	`+. For all the servers, ensure that new settings are added to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section.`
`236`	`236`	`+`
`237`	`237`	`As an example, for those using the list resolver, the settings for all the servers should include:`
`238`	`238`	`+`
`@@ -245,8 +245,9 @@ dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.c`
`245`	`245`	. Restart server01 with the new setting `dbms.cluster.discovery.version=V1_OVER_V2`.
`246`	`246`	`+`
`247`	`247`	`image:discovery-service/in-place-1-v1-over-v2.png[]`
`248`		-. Run `Show servers;` and ensure that all three members are alive.
`249`		-. Then repeat steps 2 and 3 for server02 and server03. Ensure that they are set to `dbms.cluster.discovery.version=V1_OVER_V2`
	`248`	+. Run `SHOW SERVERS` and ensure that all three members are alive.
	`249`	`+. Then repeat steps 2 and 3 for server02 and server03.`
	`250`	+Ensure that they are set to `dbms.cluster.discovery.version=V1_OVER_V2`.
`250`	`251`	`Restart them sequentially, not in parallel.`
`251`	`252`	`+`
`252`	`253`	`image:discovery-service/in-place-23-v1-over-v2.png[]`
`@@ -261,6 +262,7 @@ CALL dbms.cluster.showParallelDiscoveryState();`
`261`	`262`	`+`
`262`	`263`	They should display "Matching" in the `stateComparison`.
`263`	`264`	`+`
	`265`	`+.Expected result`
`264`	`266`	`[queryresult]`
`265`	`267`	`----`
`266`	`268`	`+----------------------------------------------------------------+`
`@@ -276,9 +278,9 @@ If they are not, wait and try again.`
`276`	`278`	`+`
`277`	`279`	`image:discovery-service/in-place-1-v2-over-v1.png[]`
`278`	`280`	`+`
`279`		-. Run `Show servers;` and ensure that all three members are alive.
	`281`	+. Run `SHOW SERVERS` and ensure that all three members are alive.
`280`	`282`	`. Then repeat steps 6 and 7 for servers 2 and 3.`
`281`		-Ensure that they are set to `dbms.cluster.discovery.version=V2_OVER_V1`
	`283`	+Ensure that they are set to `dbms.cluster.discovery.version=V2_OVER_V1`.
`282`	`284`	`Restart them sequentially, not in parallel.`
`283`	`285`	`+`
`284`	`286`	`image:discovery-service/in-place-23-v2-over-v1.png[]`
@@ -292,8 +294,8 @@ Note that `stateComparison` is `N/A` because you do not have v1 to compare state
`292`	`294`
`293`	`295`	`[[discovery-v1-to-v2-new-server]]`
`294`	`296`	`=== New server rolling`
`295`		`-. New server rolling will require 3 currently running servers, and 3 new servers.`
`296`		`-For all the servers, ensure that new settings are added to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[preparation] section.`
	`297`	`+The new server rolling requires three running servers and three new servers.`
	`298`	`+. For all the servers, ensure that new settings are added to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section.`
`297`	`299`	`+`
`298`	`300`	`As an example, for those using the list resolver, the settings for all the servers should include:`
`299`	`301`	`+`
@@ -315,9 +317,10 @@ This can be done using via `./cypher-shell -a bolt://localhost:7685 -d system` f
`315`	`317`	`CALL dbms.cluster.showParallelDiscoveryState();`
`316`	`318`	`----`
`317`	`319`	`+`
`318`		-The expected result should show `v2ServerCount` to be 3.
`319`		`-A stateComparison which is not matching is fine at this point.`
	`320`	+The expected result should display `v2ServerCount` as 3.
	`321`	+`stateComparison` that does show matching is fine at this point.
`320`	`322`	`+`
	`323`	`+.Expected result`
`321`	`324`	`[queryresult]`
`322`	`325`	`----`
`323`	`326`	`+---------------------------------------------------------------------------------------------------------+`
`@@ -327,13 +330,14 @@ A stateComparison which is not matching is fine at this point.`
`327`	`330`	`+---------------------------------------------------------------------------------------------------------+`
`328`	`331`	`----`
`329`	`332`	`+`
`330`		-. Deallocate, drop, and shut down servers 1, 2, 3. Run `neo4j-admin unbind` on these three servers.
	`333`	`+. Deallocate, drop, and shut down servers 1, 2, 3.`
	`334`	+. Run `neo4j-admin unbind` on these three servers.
`331`	`335`	`+`
`332`	`336`	. Start up servers 1, 2, 3 again, this time with the setting `dbms.cluster.discovery.version=V2_OVER_V1`.
`333`	`337`	`+`
`334`	`338`	`image:discovery-service/v2_over_v1.png[]`
`335`	`339`	`+`
`336`		-. Using `bolt://`, connect to the system database of servers 1, 2, 3, and run the following procedure.
	`340`	+. Using `bolt://`, connect to the system database of servers 1, 2, and 3, and run the following procedure:
`337`	`341`	`+`
`338`	`342`	`[source,cypher]`
`339`	`343`	`----`
`@@ -343,6 +347,7 @@ CALL dbms.cluster.showParallelDiscoveryState();`
`343`	`347`	The output should display `Matching` in the `stateComparison`.
`344`	`348`	`If they are not, wait and try again till matching.`
`345`	`349`	`+`
	`350`	`+.Expected result`
`346`	`351`	`[queryresult]`
`347`	`352`	`----`
`348`	`353`	`+----------------------------------------------------------------+`
`@@ -352,22 +357,23 @@ If they are not, wait and try again till matching.`
`352`	`357`	`+----------------------------------------------------------------+`
`353`	`358`	`----`
`354`	`359`	`+`
`355`		-. Deallocate, drop, and shut down servers 4, 5, 6. Run `neo4j-admin unbind` on these three servers.
	`360`	`+. Deallocate, drop, and shut down servers 4, 5, and 6.`
	`361`	+. Run `neo4j-admin unbind` on these three servers.
`356`	`362`	`+`
`357`		-. Start up servers 4, 5, 6 again, this time with the setting `dbms.cluster.discovery.version=V2_ONLY`.
	`363`	+. Start up servers 4, 5, and 6, this time with the setting `dbms.cluster.discovery.version=V2_ONLY`.
`358`	`364`	`+`
`359`	`365`	`image:discovery-service/v2_only.png[]`
`360`	`366`	`. Deallocate, drop, and shut down servers 1, 2, 3.`
`361`	`367`	`+`
`362`		-. Finally, one final check. Using `bolt://`, connect to the system database of servers 4, 5, 6, and run the following procedure.
	`368`	+. Finally, using `bolt://`, connect to the system database of servers 4, 5, and 6, and run the following procedure to check the version of the discovery service:
`363`	`369`	`+`
`364`	`370`	`[source,cypher]`
`365`	`371`	`----`
`366`	`372`	`CALL dbms.cluster.showParallelDiscoveryState();`
`367`	`373`	`----`
`368`	`374`	`+`
`369`		`-One should see the following:`
`370`	`375`	`+`
	`376`	`+.Expected result`
`371`	`377`	`[queryresult]`
`372`	`378`	`----`
`373`	`379`	`+-------------------------------------------------------------+`
`@@ -385,7 +391,7 @@ One should see the following:`
`385`	`391`	`// so no lighthouse-specific server restarts are required if all is done correctly.`
`386`	`392`	`//Note that the settings detailed above must first be set and the servers restarted to allow the settings to take effect.`
`387`	`393`
`388`		`-. For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[preparation] section.`
	`394`	`+. For all the servers, ensure that new settings are updated to the configuration as detailed the xref:clustering/setup/discovery.adoc#_preparation[Preparation] section.`
`389`	`395`	`+`
`390`	`396`	`As an example, for those using the list resolver, the settings for all the servers should include:`
`391`	`397`	`+`
`@@ -396,7 +402,7 @@ dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:`
`396`	`402`	`dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000`
`397`	`403`	```
`398`	`404`	`+`
`399`		-. Using Cypher Shell, connect to the system database of server01 using `bolt://`.
	`405`	+. In Cypher Shell, connect to the system database of server01 using `bolt://`.
`400`	`406`	It is important to connect via `bolt://` because otherwise the procedure might be routed and executed not on the intended server.
`401`	`407`	`+`
`402`	`408`	`[source, shell, role=nocopy noplay]`
`@@ -413,6 +419,7 @@ CALL dbms.cluster.showParallelDiscoveryState();`
`413`	`419`	`+`
`414`	`420`	The output indicates mode `V1_ONLY`, i.e., only v1 is running on this server.
`415`	`421`	`+`
	`422`	`+.Expected result`
`416`	`423`	`[queryresult]`
`417`	`424`	`----`
`418`	`425`	`+-------------------------------------------------------------+`
`@@ -438,6 +445,7 @@ CALL dbms.cluster.showParallelDiscoveryState();`
`438`	`445`	`+`
`439`	`446`	Now the returned mode for this server must be `V1_OVER_V2` and the `stateComparison` must show that the states are not matching yet.
`440`	`447`	`+`
	`448`	`+.Expected result`
`441`	`449`	`[queryresult]`
`442`	`450`	`----`
`443`	`451`	`+-------------------------------------------------------------------------------------------------------+`
@@ -448,7 +456,7 @@ Now the returned mode for this server must be `V1_OVER_V2` and the `stateCompari
`448`	`456`	`----`
`449`	`457`	`+`
`450`	`458`	`The score is a measure of how different the states are.`
`451`		`-The serverCounts tells us how many servers can be found by v1 and v2 of the discovery service.`
	`459`	+`serverCounts` displays how many servers can be found by v1 and v2 of the discovery service, respectively.
`452`	`460`	`The score is 0 when the states are matching.`
`453`	`461`	`When some members are running just one of the discovery services (v1 or v2) and other members run both, the score stays permanently high.`
`454`	`462`	`This is no reason for worry.`
`@@ -460,6 +468,7 @@ This is no reason for worry.`
`460`	`468`	It should show that the states are `Matching`.
`461`	`469`	`Both serverCounts should be 3.`
`462`	`470`	`+`
	`471`	`+.Expected result`
`463`	`472`	`[queryresult]`
`464`	`473`	`----`
`465`	`474`	`+----------------------------------------------------------------+`
`@@ -478,6 +487,7 @@ CALL dbms.cluster.switchDiscoveryServiceVersion("V2_OVER_V1");`
`478`	`487`	`+`
`479`	`488`	`At this point, v2 is the service that is running the cluster, with v1 running in the background.`
`480`	`489`	`+`
	`490`	`+.Expected result`
`481`	`491`	`[queryresult]`
`482`	`492`	`----`
`483`	`493`	`+----------------------------------------------------------------+`
`@@ -498,6 +508,7 @@ CALL dbms.cluster.switchDiscoveryServiceVersion("V2_ONLY");`
`498`	`508`	. Verify that `CALL dbms.cluster.showParallelDiscoveryState();` now shows `V2_ONLY` running.
`499`	`509`	Note that `stateComparison` is `N/A` because you do not have v1 to compare states anymore.
`500`	`510`	`+`
	`511`	`+.Expected result`
`501`	`512`	`[queryresult]`
`502`	`513`	`----`
`503`	`514`	`+-------------------------------------------------------------+`