Skip to content

Commit 50d1d31

Browse files
NataliaIvakinanick-giles-neo
NataliaIvakina
and
nick-giles-neo
authored
Update instructions on how to set up a basic cluster with DS V2 (#1754)
Co-authored-by: Nick Giles <[email protected]>
1 parent 2ba0d35 commit 50d1d31

File tree

4 files changed

+132
-18
lines changed

4 files changed

+132
-18
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@
134134
135135
* xref:clustering/index.adoc[]
136136
** xref:clustering/introduction.adoc[]
137-
** Set up a cluster
137+
** Setting up a cluster
138138
*** xref:clustering/setup/deploy.adoc[]
139139
*** xref:clustering/setup/analytics-cluster.adoc[]
140140
*** xref:clustering/setup/single-to-cluster.adoc[]

‎modules/ROOT/pages/clustering/index.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
This chapter describes the following:
77

88
* xref:clustering/introduction.adoc[Introduction] -- An overview of the clustering architecture.
9-
* Set up a cluster -- The basics of configuring and deploying a new cluster.
9+
* Setting up a cluster -- The basics of configuring and deploying a new cluster.
1010
** xref:clustering/setup/deploy.adoc[Deploy a basic cluster] -- How to set up a basic cluster.
1111
** xref:clustering/setup/analytics-cluster.adoc[Deploy an analytics cluster] -- How to deploy a special case Neo4j cluster for analytic queries.
1212
** xref:clustering/setup/single-to-cluster.adoc[Move from single server to cluster] -- This section describes how to move from a single Neo4j server to Neo4j cluster.

‎modules/ROOT/pages/clustering/settings.adoc‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -45,22 +45,21 @@ Possible values are:
4545

4646
[.compact]
4747
`LIST`::
48-
Treats `dbms.cluster.discovery.endpoints` as a list of addresses of servers to contact for discovery.
48+
Treats `dbms.cluster.discovery.endpoints` (or `dbms.cluster.discovery.v2.endpoints`, if you use discovery service v2 available as of Neo4j 5.23) as a list of addresses of servers to contact for discovery.
4949
`DNS`::
50-
Treats `dbms.cluster.discovery.endpoints` as a domain name to resolve via DNS.
50+
Treats `dbms.cluster.discovery.endpoints` (or `dbms.cluster.discovery.v2.endpoints`, if you use discovery service v2 available as of Neo4j 5.23) as a domain name to resolve via DNS.
5151
Expect DNS resolution to provide A records with hostnames or IP addresses of servers to contact for discovery, on the port specified by `dbms.cluster.discovery.endpoints`.
5252
`SRV`::
53-
Treats `dbms.cluster.discovery.endpoints` as a domain name to resolve via DNS.
53+
Treats `dbms.cluster.discovery.endpoints` (or `dbms.cluster.discovery.v2.endpoints`, if you use discovery service v2 available as of Neo4j 5.23) as a domain name to resolve via DNS.
5454
Expect DNS resolution to provide SRV records with hostnames or IP addresses and ports, of servers to contact for discovery.
5555
`K8S`::
5656
Accesses the Kubernetes list service API to derive addresses of servers to contact for discovery.
5757
Requires `dbms.kubernetes.label_selector` to be a Kubernetes label selector for Kubernetes services running a server each and `dbms.kubernetes.service_port_name` to be a service port name identifying the discovery port of cluster servers services.
58-
The value of `dbms.cluster.discovery.endpoints` is ignored for this option.
58+
The value of `dbms.cluster.discovery.endpoints` (or `dbms.cluster.discovery.v2.endpoints`, if you use discovery service v2 available as of Neo4j 5.23) is ignored for this option.
59+
For more details, see xref:clustering/setup/discovery.adoc#clustering-discovery-k8s[Discovery in Kubernetes].
5960

60-
The value of this setting determines how `dbms.cluster.discovery.endpoints` is interpreted.
61-
Detailed information about discovery and discovery configuration options is given in xref:clustering/setup/discovery.adoc#clustering-discovery-dns[Discovery using DNS with multiple records].
62-
63-
**Example:** `clustering-discovery-dns=DNS` combined with `dbms.cluster.discovery.endpoints=cluster01.example.com:5000` fetch all DNS A records for _cluster01.example.com_ and attempt to reach Neo4j instances listening on port `5000` for each A record's IP address.
61+
From Neo4j 5.23, depending on which version of the discovery service you are using, you need to set either `dbms.cluster.discovery.endpoints` or `dbms.cluster.discovery.v2.endpoints` in the _neo4j.conf_ file.
62+
Detailed information about discovery and discovery configuration options is given in xref:clustering/setup/discovery.adoc#clustering-discovery-methods[Methods for server discovery].
6463

6564
| xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.endpoints[`dbms.cluster.discovery.endpoints`] label:deprecated[Deprecated in 5.23]
6665
| One or more network addresses used to discover other servers in the cluster.
@@ -69,14 +68,14 @@ In the default case, the initial discovery members are given as a comma-separate
6968

7069
It is good practice to set this parameter to the same value on all servers in the cluster.
7170

72-
The behavior of this setting can be modified by configuring the setting `dbms.cluster.discovery.resolver_type`.
73-
This is described in detail in xref:clustering/setup/discovery.adoc#clustering-discovery-dns[Discovery using DNS with multiple records].
74-
7571
**Example:** `dbms.cluster.discovery.resolver_type=LIST` combined with `server01.example.com:5000,server02.example.com:5000,server03.example.com:5000` attempt to reach Neo4j instances listening on _server01.example.com_, _server02.example.com_ and _server03.example.com_; all on port `5000`.
7672

7773
|xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.v2.endpoints[`dbms.cluster.discovery.v2.endpoints`] label:new[Introduced in 5.22]
7874
|A comma-separated list of endpoints that a server should contact in order to discover other cluster members.
79-
Typically, all cluster members, including the current server, must be specified in this list. The setting configures the endpoints for discovery service v2.
75+
Typically, all cluster members, including the current server, must be specified in this list.
76+
The setting configures the endpoints for discovery service v2.
77+
78+
**Example:** `dbms.cluster.discovery.resolver_type=LIST` combined with `server01.example.com:6000,server02.example.com:6000,server03.example.com:6000` attempt to reach Neo4j instances listening on _server01.example.com_, _server02.example.com_ and _server03.example.com_; all on port `6000`.
8079

8180
|xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.version[`dbms.cluster.discovery.version`] label:new[Introduced in 5.22]
8281
|This setting allows you to select which discovery service should be started.
@@ -90,6 +89,8 @@ Possible values are:
9089
9190
* V2_ONLY -- it runs only discovery service v2.
9291
92+
The default value is `V1_ONLY`.
93+
9394
Discovery services v1 and v2 are designed to run in parallel.
9495
They are completely independent of each other, thus allowing you to keep the cluster functioning while switching over from v1 to v2.
9596
For details on how to move from discovery service v1 to v2, see xref:clustering/setup/discovery.adoc#clustering-discovery-v1-to-v2[Moving from discovery service v1 to v2].

‎modules/ROOT/pages/clustering/setup/deploy.adoc‎

Lines changed: 117 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ The following configuration settings are important to consider when deploying a
99
//Remember to update the settings and link below.
1010
See also xref:clustering/settings.adoc[Settings reference] for more detailed descriptions and examples.
1111

12+
Starting with Neo4j 5.23, you get the option to choose between two discovery services: v1 or v2.
13+
They are designed to run independently and in parallel.
14+
However, the new version, v2, is recommended for new deployments, as v1 has been considered deprecated since Neo4j 5.23.
15+
For more details, see xref:clustering/setup/discovery.adoc[].
1216

1317
.Important settings for clusters
1418
[options="header",cols="<3,<4"]
@@ -21,11 +25,16 @@ In the typical case, this should be set to the fully qualified domain name or th
2125
| xref:configuration/configuration-settings.adoc#config_server.default_listen_address[`server.default_listen_address`]
2226
| The address or network interface this machine uses to listen for incoming messages.
2327
Setting this value to `0.0.0.0` makes Neo4j bind to all available network interfaces.
24-
| xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.endpoints[`dbms.cluster.discovery.endpoints`]
28+
| xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.endpoints[`dbms.cluster.discovery.endpoints`] label:deprecated[Deprecated in 5.23]
2529
| The discovery network address for all the members of the cluster, including this server.
2630
The setting must be set to the same value on all cluster members.
2731
The behavior of this setting can be modified by configuring the setting `dbms.cluster.discovery.resolver_type`.
2832
This is described in detail in xref:clustering/setup/discovery.adoc[].
33+
| xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.v2.endpoints[`dbms.cluster.discovery.v2.endpoints`] label:new[Introduced in 5.22]
34+
| A comma-separated list of endpoints that a server should contact in order to discover other cluster members. Typically, all cluster members, including the current server, must be specified in this list.
35+
The setting configures the endpoints for **discovery service v2**.
36+
| xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.version[`dbms.cluster.discovery.version`] label:new[Introduced in 5.22]
37+
| This setting allows you to select which discovery service should be started.
2938
| xref:configuration/configuration-settings.adoc#config_initial.dbms.default_primaries_count[`initial.dbms.default_primaries_count`]
3039
| The number of initial database hostings in primary mode.
3140
If not specified, it defaults to one hosting in primary mode.
@@ -42,7 +51,6 @@ See xref:clustering/databases.adoc#_create_database[`CREATE DATABASE`] for more
4251
To view the current default settings, use the xref:reference/procedures.adoc#procedure_dbms_showTopologyGraphConfig[`dbms.showTopologyGraphConfig`] procedure.
4352
====
4453

45-
The following example shows how to set up a basic cluster with three servers with primary hosting capabilities.
4654

4755
[CAUTION]
4856
====
@@ -54,10 +62,19 @@ Make sure you understand the security implications and strongly consider setting
5462
[[cluster-example-configure-a-three-primary-cluster]]
5563
== Configure a cluster with three servers
5664

57-
The following example shows how to set up a basic cluster with three members hosting the default database, `neo4j` (in addition to the `system` database), in primary mode.
65+
The following example shows how to set up a basic cluster with three members hosting the default database, `neo4j` (in addition to the `system` database), in primary mode, using the method of server addresses list.
66+
67+
Depending on the type of xref:configuration/configuration-settings.adoc#config_dbms.cluster.discovery.resolver_type[`dbms.cluster.discovery.resolver_type`] currently in use, the discovery service can use a list of server addresses, DNS records, or Kubernetes services to discover other servers in the cluster.
68+
69+
In this case, you set `dbms.cluster.discovery.resolver_type=LIST`.
70+
5871

5972
.Configure a cluster with three servers in primary mode
60-
====
73+
74+
[.tabbed-example]
75+
=====
76+
[role=include-with-Discovery-service-v1 label--deprecated-5.23]
77+
======
6178

6279
In this example, three servers named `server01.example.com`, `server02.example.com` and `server03.example.com` are configured.
6380
Neo4j Enterprise Edition is installed on all three servers.
@@ -130,15 +147,111 @@ SHOW SERVERS YIELD *;
130147
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Enabled" | "Available" | ["system", "neo4j"] | ["system", "neo4j"] | [] | [] | [] | "NONE" | "5.0.0" |
131148
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
132149
----
150+
151+
[TIP]
152+
.Startup time
153+
====
154+
The instance may appear unavailable while it is joining the cluster.
155+
If you want to follow along with the startup, you can see the messages in xref:configuration/file-locations.adoc[_neo4j.log_].
133156
====
134157

158+
======
159+
[role=include-with-Discovery-service-v2 label--new-5.23]
160+
======
161+
162+
163+
In this example, three servers named `server01.example.com`, `server02.example.com` and `server03.example.com` are configured.
164+
Neo4j Enterprise Edition is installed on all three servers.
165+
They are configured by preparing xref:configuration/file-locations.adoc[_neo4j.conf_] on each server.
166+
167+
Note that they are all identical, except for the configuration of `server.default_advertised_address`.
168+
169+
To use discovery service v2:
170+
171+
* You have to set the configuration of `dbms.cluster.discovery.version` to `V2_ONLY`.
172+
173+
* Instead of `dbms.cluster.discovery.endpoints`, use `dbms.cluster.discovery.v2.endpoints`.
174+
175+
176+
._neo4j.conf_ on server01.example.com:
177+
[source, properties]
178+
----
179+
server.default_listen_address=0.0.0.0
180+
server.default_advertised_address=server01.example.com
181+
dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000
182+
dbms.cluster.discovery.version=V2_ONLY
183+
initial.dbms.default_primaries_count=3
184+
----
185+
186+
._neo4j.conf_ on server02.example.com:
187+
[source, properties]
188+
----
189+
server.default_listen_address=0.0.0.0
190+
server.default_advertised_address=server02.example.com
191+
dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000
192+
dbms.cluster.discovery.version=V2_ONLY
193+
initial.dbms.default_primaries_count=3
194+
----
195+
196+
._neo4j.conf_ on server03.example.com:
197+
[source, properties]
198+
----
199+
server.default_listen_address=0.0.0.0
200+
server.default_advertised_address=server03.example.com
201+
dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000
202+
dbms.cluster.discovery.version=V2_ONLY
203+
initial.dbms.default_primaries_count=3
204+
----
205+
206+
The Neo4j servers are ready to be started.
207+
The startup order does not matter.
208+
209+
After the cluster has started, it is possible to connect to any of the instances and run `SHOW SERVERS` to check the status of the cluster.
210+
This shows information about each member of the cluster:
211+
212+
[source, cypher, role=noplay]
213+
----
214+
SHOW SERVERS;
215+
----
216+
217+
[queryresult]
218+
----
219+
+-----------------------------------------------------------------------------------------------------------+
220+
| name | address | state | health | hosting |
221+
+-----------------------------------------------------------------------------------------------------------+
222+
| "d6fbe54b-0c6a-4959-9bcb-dcbbe80262a4" | "server01:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
223+
| "e56b49ea-243f-11ed-861d-0242ac120002" | "server02:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
224+
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
225+
+-----------------------------------------------------------------------------------------------------------+
226+
----
227+
228+
For more extensive information about each server, use the `SHOW SERVERS YIELD *` command:
229+
230+
[source, cypher, role=noplay]
231+
----
232+
SHOW SERVERS YIELD *;
233+
----
234+
235+
[queryresult]
236+
----
237+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
238+
| serverId | name | address | state | health | hosting | requestedHosting | tags | allowedDatabases | deniedDatabases | modeConstraint | version |
239+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
240+
| "d6fbe54b-0c6a-4959-9bcb-dcbbe80262a4" | "d6fbe54b-0c6a-4959-9bcb-dcbbe80262a4" | "server01:7687" | "Enabled" | "Available" | ["system", "neo4j"] | ["system", "neo4j"] | [] | [] | [] | "NONE" | "5.0.0" |
241+
| "e56b49ea-243f-11ed-861d-0242ac120002" | "e56b49ea-243f-11ed-861d-0242ac120002" | "server02:7687" | "Enabled" | "Available" | ["system", "neo4j"] | ["system", "neo4j"] | [] | [] | [] | "NONE" | "5.0.0" |
242+
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Enabled" | "Available" | ["system", "neo4j"] | ["system", "neo4j"] | [] | [] | [] | "NONE" | "5.0.0" |
243+
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
244+
----
245+
135246
[TIP]
136247
.Startup time
137248
====
138249
The instance may appear unavailable while it is joining the cluster.
139250
If you want to follow along with the startup, you can see the messages in xref:configuration/file-locations.adoc[_neo4j.log_].
140251
====
141252

253+
======
254+
=====
142255

143256
[[cluster-example-create-databases-on-cluster]]
144257
== Create new databases in a cluster

0 commit comments

Comments
 (0)