Added an example of using external arbiter to the multi-cluster setup

docs/arbiter.md

@@ -18,7 +18,7 @@ Besides the primary and regular secondaries in a MongoDB replica set, you can ha
 
 ### Arbiter nodes
 
-An Arbiter node participates in the replica set elections but does not store any data. Its primary role is to act as a tiebreaker in a replica set with an even number of data-bearing nodes, ensuring that a primary can always be elected. By not storing data, Arbiter nodes require minimal resources, which can help reduce your overall costs. An does not demand a persistent volume.
+An Arbiter node participates in the replica set elections but does not store any data. Its primary role is to act as a tiebreaker in a replica set with an even number of data-bearing nodes, ensuring that a primary can always be elected. By not storing data, Arbiter nodes require minimal resources, which can help reduce your overall costs. An arbiter does not demand a persistent volume.
 
 To add an Arbiter node, you can update your `deploy/cr.yaml` file by adding an `arbiter` section under `replsets` and setting the `enabled` and `size` options to your desired values.
 
@@ -107,7 +107,7 @@ replsets:
 
 Find the description of other available options in the [replsets.nonvoting section](operator.md#replsetsnonvotingenabled) of the [Custom Resource options reference](operator.md).
 
-Note that you can add a non-voting node in the edge location through the `externalNodes` option. Please see [cross-site replication documentation](replication.md) for details.
+Note that you can add a non-voting node or an external arbiter in another location through the `externalNodes` option. See [Voting members across sites](replication.md#voting-members-across-sites) and [Deploy Primary-Secondary-Arbiter across sites](replication-multi-dc.md#deploy-primary-secondary-arbiter-across-sites) for details.
 
 ## Hidden nodes
 

docs/expose.md

@@ -129,20 +129,21 @@ my-cluster-name-mongos-1   NodePort       10.38.155.250   <none>         27017:3
 
 Starting from v1.14, the Operator configures replica set members using local fully-qualified domain names (FQDN), which are resolvable and available only from inside the Kubernetes cluster. Exposing the replica set using the options described above will not affect hostname usage in the replica set configuration.
 
-
 !!! note
 
     Before v1.14, the Operator used the exposed IP addresses in the replica set configuration in the case of the exposed replica set.
 
-It is still possible to restore the old behavior. For example, it may be useful to have the replica set configured with external IP addresses for [multi-cluster deployments](replication.md). The `clusterServiceDNSMode` field in the Custom Resource controls this Operator behavior. You can set `clusterServiceDNSMode` to one of the following values:
+You can still restore the previous behavior. For example, to configure the replica set with external IP addresses for [multi-cluster deployments](replication.md). 
+
+The `clusterServiceDNSMode` field in the Custom Resource controls which addresses the Operator writes into the replica set configuration. You can set it to one of the following values:
 
 1. **`Internal`**: Use local FQDNs (i.e., `cluster1-rs0-0.cluster1-rs0.psmdb.svc.cluster.local`) in replica set configuration even if the replica set is exposed. **This is the default value.**
 
 2. **`ServiceMesh`**: Use a special FQDN using the Pod name (i.e., `cluster1-rs0-0.psmdb.svc.cluster.local`), assuming it's resolvable and available in all clusters. This mode is designed for service mesh environments where Pod names are resolvable across clusters. Starting with version 1.22.0, the integration with service meshes is improved. See [application protocol support](#application-protocol-support-for-service-mesh-integrations) to learn more.
 
 3. **`External`**: Use exposed IP addresses in replica set configuration if the replica set is exposed; otherwise, use local FQDN. **This copies the behavior of the Operator v1.13.**
 
-   !!! warning
+!!! warning
 
     Be careful with the `clusterServiceDNSMode=External` variant. Using IP addresses instead of DNS hostnames is discouraged in MongoDB. IP addresses make reconfiguration and recovery more complicated, and are **generally problematic in scenarios where IP addresses change**. In particular, if you delete and recreate the cluster with `clusterServiceDNSMode=External` without deleting its volumes (having `percona.com/delete-psmdb-pvc` finalizer unset), your cluster will crash and there will be no straightforward way to recover it.
 
@@ -156,7 +157,52 @@ To make a manual restart, run the `kubectl rollout restart sts
 Alternatively, you can simply
 [restart your cluster](pause.md).
 
+### Override hostnames with external domain names
+
+When members must be reachable by externally resolvable DNS names such as through an Ingress, TransportServer, LoadBalancer hostname, or another cross-cluster DNS entry — use [`replsets.replsetOverrides`](operator.md#replsetsreplsetoverridesmember-namehost) instead of relying on `clusterServiceDNSMode=External` and IP addresses.
+
+With `replsetOverrides`, you replace the default local FQDN of each Pod with a custom host and, optionally, port in the MongoDB replica set configuration. Typical use cases include:
+
+* Cross-cluster or multi-data-center replica sets where sites reach each other by external domain names
+* Ingress or TLS passthrough endpoints (for example `r1.example.com:443`) in front of each Pod’s Service
+
+**Important considerations:**
+
+- The Operator does **not** validate overridden hostnames. **You must ensure DNS resolution and network connectivity from every replica set member to those names**.
+- Include every overridden hostname in your TLS certificates. Operator-generated certificates usually are not enough for external domain names; [generate certificates manually](tls-manual.md) when needed.
+- [Expose the Pods](#connecting-from-outside-kubernetes) so the external name can route to the correct Service.
+- After you set replica set name overrides, the Operator updates replica set hosts one by one (secondaries first, primary last).
+
+Set `replsetOverrides` under the replica set in `deploy/cr.yaml`. Each key must be the **Pod name**. The value of `host` is the external domain name. Also include the port if it is not the default `27017` port:
+
+```yaml
+...
+replsets:
+- name: rs0
+  size: 3
+  expose:
+    enabled: true
+    type: ClusterIP
+  replsetOverrides:
+    my-cluster-name-rs0-0:
+      host: rs0-0.example.com:27017
+    my-cluster-name-rs0-1:
+      host: rs0-1.example.com:27017
+    my-cluster-name-rs0-2:
+      host: rs0-2.example.com:27017
+```
+
+You can also add custom tags to members under the same override:
+
+```yaml
+replsetOverrides:
+  my-cluster-name-rs0-0:
+    host: rs0-0.example.com:27017
+    tags:
+      team: cloud
+```
 
+You can use these external domain names when you [split a replica set across multiple data centers](replication-multi-dc.md). Override each local member with `replsetOverrides`, and register remote members with `externalNodes` using the same style of externally reachable hostnames.
 
 ### Application protocol support for service mesh integrations
 

docs/operator.md

@@ -607,7 +607,7 @@ What to do with a Pod if it doesn't satisfy the [Kubernetes Pod Topology Spread
 
 ### `replsets.replsetOverrides.MEMBER-NAME.host`
 
-Use if you need to [override the replica set members FQDNs with custom host names](replication-multi-dc.md). Each key (`MEMBER-NAME`) under `replsetOverrides` should be name of a Pod. The Operator won’t perform any validation for hostnames, so it's the user’s responsibility to ensure connectivity.
+Use if you need to [override the replica set members FQDNs with custom host names](expose.md#override-hostnames-with-external-domain-names) (for example, external domain names). Each key (`MEMBER-NAME`) under `replsetOverrides` should be name of a Pod. The Operator won’t perform any validation for hostnames, so it's the user’s responsibility to ensure connectivity.
 
 | Value type  | Example    |
 | ----------- | ---------- |
@@ -663,7 +663,7 @@ The [priority :octicons-link-external-16:](https://docs.mongodb.com/manual/refer
 
 ### `replsets.externalNodes.arbiterOnly`
 
-Defines whether this [external replset instance](replication-main.md) acts as an [arbiter :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/replica-set-arbiter/) and makes an odd number of voting members in the multi-cluster setup.
+Defines whether this [external replset instance](replication-multi-dc.md) acts as an [arbiter :octicons-link-external-16:](https://www.mongodb.com/docs/manual/core/replica-set-arbiter/) and makes an odd number of voting members in the multi-cluster setup. Available with the Operator version 1.23.0+.
 
 | Value type  | Example    |
 | ----------- | ---------- |

docs/replication-interconnect.md

@@ -1,11 +1,20 @@
 # Interconnect sites for replication
 
-At this step, you should let the clusters know about each other and interconnect them for replication. To do so, you need to add the Replica site's nodes as external nodes for the Main site. In the same way, you add the Main's site nodes as external ones for the Replica site. 
+At this step, you should let the clusters know about each other and interconnect them for replication. To do so, you need to add the Replica site's nodes as external nodes for the Main site. In the same way, you add the Main's site nodes as external ones for the Replica site.
 
 Every site has three replica set members and three config server replica set members. But you add only two of them as voting members, while the third member is added as a non-voting one. In doing so, you avoid split-brain situations and prevent the primary elections if the Replica site is down or there is a network disruption between the sites.
 
-In this way, the `main` cluster managed by the Operator is able to reach the 
-the `replica` nodes.
+In this way, the `main` cluster managed by the Operator is able to reach the `replica` nodes.
+
+!!! admonition "Using the arbiter node"
+
+    You can also add an **external arbiter** as a voting member when you interconnect sites. For example, if you run the arbiter node in the third location. This ability requires the Operator version 1.23.0 and above.
+
+    Set `arbiterOnly: true` with `votes: 1` and `priority: 0` on that `externalNodes` entry. 
+
+    The requirements to the site with the arbiter are the same as for the replica site. 
+
+    To learn how to deploy the site with the arbiter node, see [Deploy the Arbiter site](replication-multi-dc.md#deploy-the-arbiter-site).
 
 ## List the services
 
@@ -45,21 +54,17 @@ kubectl get services
     main-cluster-rs0-2    ClusterIP      34.118.225.3     <none>          27017/TCP         42m
     ```
 
-## Add the Replica site nodes to the Main site 
+## Add the Replica site nodes to the Main site
 
-1. Modify the `deploy/cr-main.yaml` file of the Main site and define the exposed nodes of the Replica site in the 
-`replsets.externalNodes` and `sharding.configsvrReplset.externalNodes`
-subsections. For each node, specify the following:
+1. Modify the `deploy/cr-main.yaml` file of the Main site and define the exposed nodes of the Replica site in the
+`replsets.externalNodes` and `sharding.configsvrReplSet.externalNodes` subsections. For each node, specify the following:
 
     - set `host` to the URL of the external replset instance. When exposed, a node has its own service, recognized by the domain name `<service-name>.<namespace>.svc.clusterset.local`
-    - set `port` to the port number of the external node. If not set, the default `27017`
-       port is used,
-    - set `priority` to define the [priority  :octicons-link-external-16:](https://docs.mongodb.com/manual/reference/replica-configuration/#mongodb-rsconf-rsconf.members-n-.priority)
-        of the external node. The default priority for local members of the cluster is `2`. When you add external nodes, set the lower priority to avoid an unmanaged node being elected
-        as a primary. A zero `0` priority adds the node as a [non-voting member](arbiter.md#non-voting-nodes).
-    - set `votes` to the number of [votes  :octicons-link-external-16:](https://docs.mongodb.com/manual/reference/replica-configuration/#mongodb-rsconf-rsconf.members-n-.votes)
-        an external node can cast in a replica set election (`0` is default and
-        should be used for non-voting members of the cluster).
+    - set `port` to the port number of the external node. If not set, the default `27017` port is used,
+    - set `priority` to define the [priority  :octicons-link-external-16:](https://docs.mongodb.com/manual/reference/replica-configuration/#mongodb-rsconf-rsconf.members-n-.priority) of the external node. The default priority for local members of the cluster is `2`. When you add external nodes, set the lower priority to avoid an unmanaged node being elected
+    as a primary. A zero `0` priority adds the node as a [non-voting member](arbiter.md#non-voting-nodes).
+    - set `votes` to the number of [votes  :octicons-link-external-16:](https://docs.mongodb.com/manual/reference/replica-configuration/#mongodb-rsconf-rsconf.members-n-.votes) an external node can cast in a replica set election (`0` is default and
+    should be used for non-voting members of the cluster).
 
     Here is an example:
 
@@ -83,6 +88,9 @@ subsections. For each node, specify the following:
       replsets:
       - name: rs0
         size: 3
+        expose:
+          enabled: true
+          type: ClusterIP
         externalNodes:
         - host: replica-cluster-rs0-0.psmdb.svc.clusterset.local
           votes: 1
@@ -92,15 +100,15 @@ subsections. For each node, specify the following:
           priority: 1
         - host: replica-cluster-rs0-2.psmdb.svc.clusterset.local
           votes: 0
-          priority: 0
-          expose:
-          enabled: true
-          type: ClusterIP   
+          priority: 0  
 
       sharding:
         enabled: true
         configsvrReplSet:
           size: 3
+          expose:
+            enabled: true
+            type: ClusterIP
           externalNodes:
           - host: replica-cluster-cfg-0.psmdb.svc.clusterset.local
             votes: 1
@@ -111,15 +119,11 @@ subsections. For each node, specify the following:
           - host: replica-cluster-cfg-2.psmdb.svc.clusterset.local
             votes: 0
             priority: 0
-          expose:
-            enabled: true
-            type: ClusterIP
 
         mongos:
           size: 3
           expose:
             type: ClusterIP
-
     ```
 
 2. Apply the changes:
@@ -130,43 +134,43 @@ subsections. For each node, specify the following:
 
 ## Add Main site nodes to the Replica site
 
-1. Modify the `deploy/cr-main.yaml` file of the Replica site and define the exposed nodes of the Main site in the
-`replsets.externalNodes` and `sharding.configsvrReplset.externalNodes`
-subsections. For each node, specify the following:
-    
+1. Modify the `deploy/cr-replica.yaml` file of the Replica site and define the exposed nodes of the Main site in the
+`replsets.externalNodes` and `sharding.configsvrReplSet.externalNodes`
+subsections.
+
     ```yaml
     apiVersion: psmdb.percona.com/v1
     kind: PerconaServerMongoDB
     metadata:
       name: replica-cluster
     spec:
-    ... 
+    ...
       replsets:
       - name: rs0
         size: 3
         externalNodes:
         - host: main-cluster-rs0-0.psmdb.svc.clusterset.local
+          votes: 1
+          priority: 1
+        - host: main-cluster-rs0-1.psmdb.svc.clusterset.local
+          votes: 1
+          priority: 1
+        - host: main-cluster-rs0-2.psmdb.svc.clusterset.local
+          votes: 0
+          priority: 0
+
+      sharding:
+        configsvrReplSet:
+          externalNodes:
+          - host: main-cluster-cfg-0.psmdb.svc.clusterset.local
             votes: 1
             priority: 1
-        - host: main-cluster-rs0-1.psmdb.svc.clusterset.local
+          - host: main-cluster-cfg-1.psmdb.svc.clusterset.local
             votes: 1
             priority: 1
-        - host: main-cluster-rs0-2.psmdb.svc.clusterset.local
+          - host: main-cluster-cfg-2.psmdb.svc.clusterset.local
             votes: 0
             priority: 0
-
-      sharding:
-        configsvrReplSet:
-            externalNodes:
-            - host: main-cluster-cfg-0.psmdb.svc.clusterset.local
-              votes: 1
-              priority: 1
-            - host: main-cluster-cfg-1.psmdb.svc.clusterset.local
-              votes: 1
-              priority: 1
-            - host: main-cluster-cfg-2.psmdb.svc.clusterset.local
-              votes: 0
-              priority: 0
     ```
 
 2. Apply the configuration: