diff --git a/content/en/docs/configuration/oauth-server.md b/content/en/docs/configuration/mock-oauth-server.md similarity index 100% rename from content/en/docs/configuration/oauth-server.md rename to content/en/docs/configuration/mock-oauth-server.md diff --git a/content/en/docs/configuration/mongodb-standby-tool.md b/content/en/docs/configuration/mongodb-standby-tool.md new file mode 100644 index 00000000..77e333cc --- /dev/null +++ b/content/en/docs/configuration/mongodb-standby-tool.md @@ -0,0 +1,69 @@ +--- + +title: 'MongoDB Standby Tool' +description: 'MongoDB Standby Tool overview' +date: '2024-06-26' +categories: [configuration, deployment, disaster recovery] +keywords: [configuration, mongodb, disaster recovery] +weight: 11 +--- + +MongoDB Standby Tool is used to reconfigure some of the MongoDB replica set members to be in a hidden and secondary state. For example, you can have a replica set where members are running in multiple regions for disaster recovery purposes. + +## Docker Image + +```bash +docker pull ghcr.io/plgd-dev/hub/mongodb-standby-tool:latest +``` + +## YAML Configuration + +A configuration template is available at [tools/mongodb/standby-tool/config.yaml](https://github.com/plgd-dev/hub/blob/main/tools/mongodb/standby-tool/config.yaml). + +### Logging + +| Property | Type | Description | Default | +|----------|------|-------------|---------| +| `log.level` | string | `Logging enabled from this level.` | `"info"` | +| `log.encoding` | string | `Logging format. Supported values are: "json", "console".` | `"json"` | +| `log.stacktrace.enabled` | bool | `Log stacktrace.` | `false` | +| `log.stacktrace.level` | string | `Stacktrace from this level.` | `"warn"` | +| `log.encoderConfig.timeEncoder` | string | `Time format for logs. Supported values are: "rfc3339nano", "rfc3339".` | `"rfc3339nano"` | + +## Mode + +When the tool is started, it is in standby mode by default. In this mode, all members in the replica set are available, and members in the standby list are set as hidden, without votes, priority, and with a delay. All other members are reconfigured as secondary members. You can change the mode to active by setting the `mode` property to `active`. In this mode, standby members are set as secondary members with votes, priority, and without delay, and other members are set as hidden, without votes, priority, and with a delay. + +| Property | Type | Description | Default | +|----------|------|-------------|---------| +| `mode` | string | `Set the running mode of the tool. Supported modes are "standby" and "active".` | `"standby"` | + +### Replica Set + +| Property | Type | Description | Default | +|----------|------|-------------|---------| +| `replicaSet.forceUpdate` | bool | `Update the replica set configuration with the force flag. More info [here](https://www.mongodb.com/docs/manual/reference/method/rs.reconfig/#std-label-rs-reconfig-method-force).` | `false` | +| `replicaSet.maxReadyWaits` | int | `Set the maximum number of retries for members to be ready.` | `10` | +| `replicaSet.standby.members` | []string | `List of the MongoDB members in the replica set which are used as hidden (mode == "standby") or secondary (mode == "active") members. All other members are reconfigured to the opposite.` | `[]` | +| `replicaSet.standby.delays` | string | `Set the delay for syncing the hidden members with the secondary/primary members.` | `6m` | +| `replicaSet.secondary.priority` | int | `Used to configure the secondary members' priority.` | `10` | +| `replicaSet.secondary.votes` | int | `Set the number of votes for the secondary members.` | `1` | + +### MongoDB + +The tool uses the first member in the standby list (`replicaSet.standby.members`) to connect to MongoDB. + +| Property | Type | Description | Default | +|----------|------|-------------|---------| +| `clients.storage.mongoDB.timeout` | string | `The maximum duration for the entire request operation.` | `"20s"` | +| `clients.storage.mongoDB.tls.enabled` | bool | `If true, use TLS for the connection.` | `false` | +| `clients.storage.mongoDB.tls.caPool` | []string | `File paths to the root certificates in PEM format. The file may contain multiple certificates.` | `[]` | +| `clients.storage.mongoDB.tls.keyFile` | string | `File path to the private key in PEM format.` | `""` | +| `clients.storage.mongoDB.tls.certFile` | string | `File path to the certificate in PEM format.` | `""` | +| `clients.storage.mongoDB.tls.useSystemCAPool` | bool | `If true, use the system certification pool.` | `false` | + +{{< note >}} + +Note that string types related to time (i.e. timeout, idleConnTimeout, expirationTime) are decimal numbers, each with an optional fraction and a unit suffix, such as "300ms", "1.5h", or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h". + +{{< /note >}} diff --git a/content/en/docs/tutorials/disaster-recovery-replica-set.md b/content/en/docs/tutorials/disaster-recovery-replica-set.md index cdd9969c..ac960448 100644 --- a/content/en/docs/tutorials/disaster-recovery-replica-set.md +++ b/content/en/docs/tutorials/disaster-recovery-replica-set.md @@ -446,7 +446,7 @@ After some time for the pods to start, you can access the Hub at `https://primar ### Deploy plgd on the Standby Cluster -Deploying plgd to the standby cluster is similar to deploying it to the primary cluster. The differences are that the domain is `standby.plgd.cloud`, different internal and storage certificates are used, the standby flag is set to `true`, NATs is disabled, and MongoDB is configured to use the master DB at `mongodb.primary.plgd.cloud`. Additionally, the `mongodb-standby-tool` job is enabled to configure the MongoDB replica set. +Deploying plgd to the standby cluster is similar to deploying it to the primary cluster. The differences are that the domain is `standby.plgd.cloud`, different internal and storage certificates are used, the standby flag is set to `true`, NATs is disabled, and MongoDB is configured to use the master DB at `mongodb.primary.plgd.cloud`. Additionally, the [mongodb-standby-tool](/docs/configuration/mongodb-standby-tool) job is enabled to configure the MongoDB replica set. ```bash # Set variables @@ -613,7 +613,7 @@ sudo systemctl restart dnsmasq It is important that the `global.standby` flag is set to `true`, which means that plgd pods are not running on the standby cluster. {{< /note >}} -Once the MongoDB pods are running, we need to run the `mongodb-standby-tool` job to configure the MongoDB replica set. This configuration demotes the secondary members to hidden members. +Once the MongoDB pods are running, we need to run the [mongodb-standby-tool](/docs/configuration/mongodb-standby-tool) job to configure the MongoDB replica set. This configuration demotes the secondary members to hidden members. ```bash kubectl -n plgd patch job/$(kubectl -n plgd get jobs | grep mongodb-standby-tool | awk '{print $1}') --type=strategic --patch '{"spec":{"suspend":false}}' @@ -633,7 +633,7 @@ When the primary cluster is down, you need to switch to the standby cluster. #### Promote the Standby Cluster -First, promote the hidden members to secondary members by upgrading the Helm chart with the `mongodb.standbyTool.mode` set to `active`. The active mode reconfigures the MongoDB replica set, promoting hidden members to secondary members and demoting the previous members to hidden. Begin by deleting the `mongodb-standby-tool` job, then upgrade the Helm chart to initiate a new job. +First, promote the hidden members to secondary members by upgrading the Helm chart with the `mongodb.standbyTool.mode` set to `active`. The active mode reconfigures the MongoDB replica set, promoting hidden members to secondary members and demoting the previous members to hidden. Begin by deleting the [mongodb-standby-tool](/docs/configuration/mongodb-standby-tool) job, then upgrade the Helm chart to initiate a new job. ```bash kubectl -n plgd delete job/$(kubectl -n plgd get jobs | grep mongodb-standby-tool | awk '{print $1}') @@ -670,14 +670,14 @@ When the primary cluster is ready for devices, switch back to the primary cluste #### Demote the Standby Cluster -First, promote the primary cluster's MongoDB hidden members to secondary members and demote the standby cluster's MongoDB secondary members to hidden. Upgrade the Helm chart with the `mongodb.standbyTool.mode` set to `standby`. To do this, delete the `mongodb-standby-tool` job and upgrade the Helm chart, which will create a new job. +First, promote the primary cluster's MongoDB hidden members to secondary members and demote the standby cluster's MongoDB secondary members to hidden. Upgrade the Helm chart with the `mongodb.standbyTool.mode` set to `standby`. To do this, delete the [mongodb-standby-tool](/docs/configuration/mongodb-standby-tool) job and upgrade the Helm chart, which will create a new job. ```bash kubectl -n plgd delete job/$(kubectl -n plgd get jobs | grep mongodb-standby-tool | awk '{print $1}') helm upgrade -i -n plgd --create-namespace -f values.yaml --set mongodb.standbyTool.mode=standby hub plgd/plgd-hub ``` -Next, patch the `mongodb-standby-tool` job to resume it and configure the MongoDB replica set. +Next, patch the [mongodb-standby-tool](/docs/configuration/mongodb-standby-tool) job to resume it and configure the MongoDB replica set. ```bash kubectl -n plgd patch job/$(kubectl -n plgd get jobs | grep mongodb-standby-tool | awk '{print $1}') --type=strategic --patch '{"spec":{"suspend":false}}'