Add a new guide on deploying multi-region cluster (#2559) (#2590)

Co-authored-by: Nick Giles <[email protected]>

Author: NataliaIvakina

modules/ROOT/content-nav.adoc

@@ -143,6 +143,7 @@
 *** xref:clustering/setup/deploy.adoc[]
 *** xref:clustering/setup/analytics-cluster.adoc[]
 *** xref:clustering/setup/single-to-cluster.adoc[]
+*** xref:clustering/setup/reconciler.adoc[]
 *** xref:clustering/setup/discovery.adoc[]
 *** xref:clustering/setup/routing.adoc[]
 *** xref:clustering/setup/encryption.adoc[]
@@ -153,14 +154,13 @@
 *** xref:clustering/monitoring/show-databases-monitoring.adoc[]
 *** xref:clustering/monitoring/endpoints.adoc[]
 *** xref:clustering/monitoring/status-check.adoc[]
-** xref:clustering/disaster-recovery.adoc[]
+** Resilient cluster deployment
+*** xref:clustering/multi-region-deployment/geo-redundant-deployment.adoc[]
+*** xref:clustering/multi-region-deployment/multi-data-center-routing.adoc[]
+*** xref:clustering/multi-region-deployment/disaster-recovery.adoc[]
 //** xref:clustering/internals.adoc[]
 ** xref:clustering/settings.adoc[]
 ** xref:clustering/server-syntax.adoc[]
-** xref:clustering/clustering-advanced/index.adoc[]
-*** xref:clustering/clustering-advanced/default-database.adoc[]
-*** xref:clustering/clustering-advanced/multi-data-center-routing.adoc[]
-*** xref:clustering/clustering-advanced/reconciler.adoc[]
 ** xref:clustering/glossary.adoc[]
 
 * xref:backup-restore/index.adoc[]

modules/ROOT/images/2dc-balanced-membership.svg

@@ -364,7 +364,58 @@ Allowed and denied are mutually exclusive.
 If not set, there are no mode constraints on the server.
 
 [[cluster-default-database]]
-== Change the default database
+== Default database in a cluster
+
+The default database, as defined by xref:configuration/configuration-settings.adoc#config_initial.dbms.default_database[`initial.dbms.default_database`], is automatically created when the DBMS starts for the first time.
+This provides a user database to experiment with immediately.
+However, this creation is 'best effort' for reasons explained below, and users are encouraged to create their own default database for production use.
+If you create your own default database, even if you just run `DROP DATABASE neo4j` and `CREATE DATABASE neo4j`, you do not have to be aware of the complexities below.
+
+[[default-database-automatic-creation]]
+=== Automatic default database creation
+
+The initial default database is created when the DBMS starts for the first time.
+It uses the following settings:
+
+* xref:configuration/configuration-settings.adoc#config_initial.dbms.default_database[`initial.dbms.default_database`] -- the name of the database.
+* xref:configuration/configuration-settings.adoc#config_initial.dbms.default_primaries_count[`initial.dbms.default_primaries_count`] -- the number of primaries requested for the default database.
+* xref:configuration/configuration-settings.adoc#config_initial.dbms.default_secondaries_count[`initial.dbms.default_secondaries_count`] -- the number of secondaries requested for the default database.
+
+However, it uses the default primary and secondary counts (topology) as maximums, not as hard requirements.
+This is different to normal database creation, where if the requested topology cannot be satisfied, creation fails.
+For the automatic creation of the default database alone, if the requested topology cannot be satisfied, you get as many of each hosting type as can be satisfied by the current cluster.
+This means you may end up with a default database with as few as one primary and no secondaries, despite the default values being higher.
+It is also possible to configure a cluster where automatic creation of the default database is not possible when the DBMS starts up.
+In this case, creation fails, a warning is logged, and creation *is not be re-attempted*.
+
+Automatic creation of the initial default database works as follows:
+
+* As the cluster starts for the first time, there is a configured threshold for how many servers are required to create the DBMS - `dbms.cluster.minimum_initial_system_primaries_count`.
+* Once *a minimum* of this many servers have discovered each other, the `system` database bootstraps, allowing creation of the DBMS.
+* The initial default database is created with those servers as the possible hosts.
+* If any of the servers block hosting the default database (see xref:configuration/configuration-settings.adoc#config_initial.server.denied_databases[`initial.server.denied_databases`]), they are not used.
+* If any of the servers restrict the mode they can host a database in, that is obeyed (see xref:configuration/configuration-settings.adoc#config_initial.server.mode_constraint[`initial.server.mode_constraint`]).
+* If there are too few servers to allocate the requested number of primaries, whichever ones available are used.
+If there are zero available primaries, automatic creation fails.
+* If there are too few servers remaining after the primary allocation to satisfy the requested number of secondaries, whicever ones available are used.
+
+Some possible behaviours that may be observed as a result of the above approach:
+
+* If `initial.dbms.default_primaries_count` is larger than `dbms.cluster.minimum_initial_system_primaries_count`, you are likely to get an initial default database with fewer primaries than the default.
+This is because DBMS initialisation only waits for the minimum system primaries.
+* If `initial.dbms.default_secondaries_count` plus `initial.dbms.default_primaries_count` is larger than `dbms.cluster.minimum_initial_system_primaries_count`, you are likely to get an initial default database with fewer secondaries than the default.
+This is because DBMS initialisation only waits for the minimum number of system primaries.
+* If you use `initial.server.denied_databases` to prevent the allocation of your default database to any of your initial servers, you may end up with fewer copies of the database than the default request, and possibly even no default database.
+* If you use `initial.server.mode_constraint=SECONDARY` for any of your initial servers, you may end up with fewer primary copies of the database than the default request, and possibly even no default database.
+
+[[default-database-change-topology]]
+=== Changing default database topology
+
+If the default database is initially created for you with a topology different to what you want, you can update it in the same way as any database, see <<alter-topology, Alter topology>>.
+
+
+[[change-default-database]]
+=== Change the default database
 
 You can use the procedure xref:procedures.adoc#procedure_dbms_setDefaultDatabase[`dbms.setDefaultDatabase("newDefaultDatabaseName")`] to change the default database for a DBMS.
 
@@ -374,11 +425,6 @@ You can use the procedure xref:procedures.adoc#procedure_dbms_setDefaultDatabase
 . Run `CALL dbms.setDefaultDatabase("newDefaultDatabaseName")` against the `system` database to set the new default database.
 . Optionally, you can start the previous default database as non-default by using `START DATABASE <database-name>`.
 
-[NOTE]
-====
-Be aware that the automatically created _initial_ default database may have a different topology to the default configuration values.
-See xref:clustering/clustering-advanced/default-database.adoc[Default database in a cluster] for more information.
-====
 
 [[cluster-database-error-handling]]
 == Handling errors
@@ -387,4 +433,4 @@ Databases can get into error states.
 Typically you can observe this with the `SHOW DATABASES` command, and use the xref:database-administration/standard-databases/errors.adoc[error handling guidance] to help.
 
 In more serious cases you may be dealing with a disaster situation, where the whole DBMS may not be responding correctly, or some specific databases cannot be restored without downtime.
-Refer to the xref:clustering/disaster-recovery.adoc[disaster recovery guide] for those situations.
+Refer to the xref:clustering/multi-region-deployment/disaster-recovery.adoc[disaster recovery guide] for those situations.

modules/ROOT/images/2dc-unbalanced-membership.svg

@@ -10,23 +10,23 @@ This chapter describes the following:
 ** xref:clustering/setup/deploy.adoc[Deploy a basic cluster] -- How to set up a basic cluster.
 ** xref:clustering/setup/analytics-cluster.adoc[Deploy an analytics cluster] -- How to deploy a special case Neo4j cluster for analytic queries.
 ** xref:clustering/setup/single-to-cluster.adoc[Move from a standalone deployment to a cluster] -- This section describes how to move from a single Neo4j server to Neo4j cluster.
+** xref:clustering/setup/reconciler.adoc[Reconciler] -- An internal component that observes the requested state of a server and makes changes to the server to match that state.
 ** xref:clustering/setup/discovery.adoc[Cluster server discovery] -- How servers in a cluster discover each other and form a cluster.
 ** xref:clustering/setup/routing.adoc[Leadership, routing and load balancing] -- Election of leaders, routing and load balancing.
 ** xref:clustering/setup/encryption.adoc[Intra-cluster encryption] -- How to secure the cluster communication.
-* xref:clustering/servers.adoc[Managing servers in a cluster] -- How to manage manage the servers in a cluster.
+* xref:clustering/servers.adoc[Managing servers in a cluster] -- How to manage the servers in a cluster.
 * xref:clustering/databases.adoc[Managing databases in a cluster] -- How to manage the databases in a cluster.
 * Monitoring -- Monitoring of a cluster.
 ** xref:clustering/monitoring/show-servers-monitoring.adoc[Monitor servers] -- The tools available for monitoring the servers in a cluster.
 ** xref:clustering/monitoring/show-databases-monitoring.adoc[Monitor databases] -- The tools available for monitoring the databases in a cluster.
 ** xref:clustering/monitoring/endpoints.adoc[Monitor cluster endpoints for status information] -- The endpoints and semantics of endpoints used to monitor the health of the cluster.
 ** xref:clustering/monitoring/status-check.adoc[Monitor replication status] label:new[Introduced in 5.24] -- The procedure to monitor which members of a clustered database are up-to-date and can participate in a successful replication.
-* xref:clustering/disaster-recovery.adoc[Disaster recovery] -- How to recover a cluster in the event of a disaster.
+* Resilient cluster deployment -- Recommendations and guidance on how to set up a resilient cluster which ensures your database stays available, fast, and recoverable even under failures.
+** xref:clustering/multi-region-deployment/geo-redundant-deployment.adoc[] -- Recommended patterns of cluster deployment across multiple cloud regions / data centers.
+** xref:clustering/multi-region-deployment/multi-data-center-routing.adoc[Multi-data center routing] -- Clusters on multi-data centers.
+** xref:clustering/multi-region-deployment/disaster-recovery.adoc[Disaster recovery] -- How to recover a cluster in the event of a disaster.
 * xref:clustering/settings.adoc[Settings reference] -- A summary of the most important cluster settings.
 * xref:clustering/server-syntax.adoc[Server commands reference] -- Reference of Cypher administrative commands to add and manage servers.
-* xref:clustering/clustering-advanced/index.adoc[Advanced clustering] -- Some more advanced features of Neo4j clusters.
-** xref:clustering/clustering-advanced/default-database.adoc[Default database in a cluster] -- The initial default database created when the DBMS starts for the first time.
-** xref:clustering/clustering-advanced/multi-data-center-routing.adoc[Multi-data center routing] -- Clusters on mutli-data centers.
-** xref:clustering/clustering-advanced/reconciler.adoc[Reconciler] -- An internal component that observes the requested state of a server and makes changes to the server to match that state.
 * xref:clustering/glossary.adoc[Clustering glossary] -- A glossary of terms related to the Neo4j clustering.