Improve documentation
- replace the term gerrit master by gerrit primary
- explain which components need to be installed to use the
high-availability plugin
Change-Id: I185b6f00735fca4d6c1c600b678f5a1686bfa894
diff --git a/README.md b/README.md
index ef81595..1542d71 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
# Gerrit high-availability plugin
-This plugin allows deploying a cluster of multiple Gerrit masters
-on the same data-center sharing the same Git repositories.
+This plugin allows deploying a cluster of multiple Gerrit primary servers
+in the same data-center sharing the same Git repositories.
-Requirements for the Gerrit masters are:
+Requirements for the Gerrit primaries are:
- Externally mounted filesystem shared among the cluster
- Load-balancer (HAProxy or similar)
@@ -17,17 +17,29 @@
Refer to the [build instructions in the plugin documentation](src/main/resources/Documentation/build.md).
-## Sample configuration for two Gerrit masters in high-availability
+## Installation
-Assuming that the Gerrit masters in the clusters are `gerrit-01.mycompany.com` and
+Install
+
+- the `high-availability` plugin in the Gerrit site's `plugins` folder.
+
+> **NOTE** the `global-refdb` lib module in the Gerrit site's `lib` folder, even if it is not used or referenced as libModule in the `gerrit.config`, because of a bug in the high-availability plugin initialisation sequence.
+
+In active-active deployments with multiple Gerrit primaries, installation of a global-refdb
+implementation is needed to maintain consistent ref updates across all
+Gerrit primary sites.
+
+## Sample configuration for two Gerrit primaries in high-availability
+
+Assuming that the Gerrit primaries in the clusters are `gerrit-01.mycompany.com` and
`gerrit-02.mycompany.com`, listening on the HTTP port 8080, with a shared volume
mounted under `/shared`, see below the minimal configuration steps.
-1. Install one Gerrit master on the first node (e.g. `gerrit-01.mycompany.com`)
+1. Install one Gerrit primary on the first node (e.g. `gerrit-01.mycompany.com`)
with the repositories location under the shared volume (e.g. `/shared/git`).
Init the site in order to create the initial repositories.
-2. Copy all the files of the first Gerrit master onto the second node (e.g. `gerrit-02.mycompany.com`)
+2. Copy all the files of the first Gerrit primary onto the second node (e.g. `gerrit-02.mycompany.com`)
so that it points to the same repositories location.
3. Install the high-availability plugin into the `$GERRIT_SITE/plugins` directory of both
@@ -74,9 +86,9 @@
### Active-passive configuration
-It is the simplest and safest configuration, where only one Gerrit master at a
+It is the simplest and safest configuration, where only one Gerrit primary at a
time serves the incoming requests.
-In case of failure of the primary master, the traffic is forwarded to the backup.
+In case of failure of the active primary, the traffic is forwarded to the backup.
Assuming a load-balancing implemented using [HAProxy](http://www.haproxy.org/)
associated with the domain name `gerrit.mycompany.com`, exposing Gerrit cluster nodes
@@ -125,7 +137,7 @@
### Active-active configuration
-This is an evolution of the previous active-passive configuration, where only one Gerrit master at a
+This is an evolution of the previous active-passive configuration, where only one Gerrit primary at a
time serves the HTTP write operations (PUT,POST,DELETE) while the remaining HTTP traffic is sent
to both.
In case of failure of one of the nodes, all the traffic is forwarded to the other node.
@@ -164,8 +176,8 @@
## Gerrit canonical URL and further adjustments
-Both Gerrit masters are now part of the same cluster, accessible through the HAProxy load-balancer.
-Set the `gerrit.canoncalWebUrl` on both Gerrit masters to the domain name of HAProxy so that any
+Both Gerrit primaries are now part of the same cluster, accessible through the HAProxy load-balancer.
+Set the `gerrit.canoncalWebUrl` on both Gerrit primaries to the domain name of HAProxy so that any
location or URL generated by Gerrit would direct the traffic to the balancer and not to the instance
that served the incoming call.
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 6fcd2e2..f62c035 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -27,15 +27,18 @@
sharing or synchronizing them.
#### Caches
+
Every time a cache eviction occurs in one of the instances, the eviction will be
forwarded the other nodes so their caches do not contain stale entries.
#### Secondary indexes
+
Every time the secondary index is modified in one of the instances, e.g., a change
is added, updated or removed from the index, the others instances index are updated
accordingly. This way, both indexes are kept synchronized.
#### Stream events
+
Every time a stream event occurs in one of the instances
(see [more events info](https://gerrit-review.googlesource.com/Documentation/cmd-stream-events.html#events)),
the event is forwarded to the other instances which re-plays it. This way, the output
@@ -43,6 +46,7 @@
connected to.
#### Web session
+
The built-in Gerrit H2 based web session cache is replaced with a file based
implementation that is shared amongst the instances.
@@ -55,8 +59,8 @@
For the instances:
-* Configure gerrit.basePath in gerrit.config to the shared repositories location
-* Configure gerrit.serverId in gerrit.config based on [config](config.md)'s introduction
+* Configure `gerrit.basePath` in `gerrit.config` to the shared repositories location
+* Configure `gerrit.serverId` in `gerrit.config` based on [config](config.md)'s introduction
* Install and configure this @PLUGIN@ plugin [further](config.md) or based on below.
Here is an example of the minimal @PLUGIN@.config:
@@ -110,25 +114,34 @@
* Git repositories must be located on a shared file system
* A directory on a shared file system must be available for @PLUGIN@ to use
-* An implementation of global-refdb (e.g. Zookeeper) must be accessible from all the active
-instances
+* An implementation of `global-refdb` (e.g. Zookeeper) must be accessible from all the active
+ instances to maintain consistent ref updates across all Gerrit primary sites
+
+The following `global-refdb` implementations are available:
+
+* [zookeeper-refdb plugin](https://gerrit.googlesource.com/plugins/zookeeper-refdb/+/refs/heads/master)
+ using Apache Zookeeper
+* [aws-dynamodb-refdb plugin](https://gerrit.googlesource.com/plugins/aws-dynamodb-refdb/+/refs/heads/master)
+ using AWS DynamoDB
+* [spanner-refdb plugin](https://gerrit.googlesource.com/plugins/spanner-refdb/+/refs/heads/master)
+ using Google Cloud Spanner
For the instances:
-* Configure gerrit.basePath in gerrit.config to the shared repositories location
-* Configure gerrit.serverId in gerrit.config based on [config](config.md)'s introduction
+* Configure `gerrit.basePath` in `gerrit.config` to the shared repositories location
+* Configure `gerrit.serverId` in `gerrit.config` based on [config](config.md)'s introduction
* Install and configure this @PLUGIN@ plugin [further](config.md) or based on example
configuration
-* Install @PLUGIN@ plugin as a database module in $GERRIT_SITE/lib(please note that
-@PLUGIN plugin must be installed as a plugin and as a database module) and add
-`installDbModule = com.ericsson.gerrit.plugins.highavailability.ValidationModule`
-to the gerrit section in gerrit.config
-* Install [global-refdb library](https://mvnrepository.com/artifact/com.gerritforge/global-refdb) as a library module in $GERRIT_SITE/lib and add
-`installModule = com.gerritforge.gerrit.globalrefdb.validation.LibModule` to the gerrit
-section in gerrit.config
+* Install @PLUGIN@ plugin as a database module in `$GERRIT_SITE/lib` (please note that
+@PLUGIN plugin must be installed as a plugin and as a database module) and add <br/>
+`installDbModule = com.ericsson.gerrit.plugins.highavailability.ValidationModule` <br/>
+to the gerrit section in `gerrit.config`
+* Install [global-refdb library](https://mvnrepository.com/artifact/com.gerritforge/global-refdb) as a library module in $GERRIT_SITE/lib and add <br/>
+`installModule = com.gerritforge.gerrit.globalrefdb.validation.LibModule` <br/>
+to the `gerrit` section in `gerrit.config`
* Install and configure [zookeeper-refdb plugin](https://gerrit-ci.gerritforge.com/view/Plugins-master/job/plugin-zookeeper-refdb-bazel-master) based on [config.md](https://gerrit.googlesource.com/plugins/zookeeper-refdb/+/refs/heads/master/src/main/resources/Documentation/config.md)
-* Configure ref-database.enabled = true in @PLUGIN@.config to enable validation with
-global-refdb.
+* Configure `ref-database.enabled = true` in @PLUGIN@.config to enable validation with
+`global-refdb`.
Here is an example of the minimal @PLUGIN@.config:
@@ -166,12 +179,13 @@
enabled = true
```
-Minimal zookeeper-refdb.config for both active instances:
+Minimal `zookeeper-refdb.config` for both active instances:
```
[ref-database "zookeeper"]
connectString = zookeeperhost:2181
```
+
### Last index update timestamp storage
The plugin keeps track of the timestamp when it lastly updated an index.
@@ -180,6 +194,7 @@
sync with the primary, for example, after a node being offline for a long time.
The HA plugin keeps the last update timestamp for each index in the following files:
+
* `<gerrit_home>/data/high-availability/account`
* `<gerrit_home>/data/high-availability/change`
diff --git a/src/test/README.md b/src/test/README.md
index 16e4df9..b0aa3c4 100644
--- a/src/test/README.md
+++ b/src/test/README.md
@@ -1,8 +1,8 @@
# Gerrit high-availability docker setup example
The Docker Compose project in the docker directory contains a simple test
-environment of two Gerrit masters in HA configuration, with their git repos
-hosted on NFS filesystem.
+environment of two Gerrit primary servers in HA configuration, with their
+git repos hosted on NFS filesystem.
## How to build
