PSMDB-1750 Documented the horizons feature #1070

nastena1606 · 2025-10-10T14:02:20Z

modified:   docs/glossary.md
new file:   docs/horizon-setup.md
new file:   docs/horizon.md
modified:   mkdocs-base.yml

modified: docs/glossary.md new file: docs/horizon-setup.md new file: docs/horizon.md modified: mkdocs-base.yml

Copilot

Pull Request Overview

This PR adds comprehensive documentation for the horizons feature in Percona Server for MongoDB, which enables replica set members to advertise different hostnames for internal and external network access.

Key changes:

Added detailed explanation of the horizons feature and its use cases
Provided step-by-step setup instructions with Docker Compose configuration
Added glossary definition for the horizons concept

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
mkdocs-base.yml	Added navigation entries for the new horizon documentation pages
docs/horizon.md	Created overview document explaining what horizons are and when to use them
docs/horizon-setup.md	Created detailed configuration guide with Docker setup examples
docs/glossary.md	Added horizons definition to the glossary

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

docs/horizon-setup.md

Co-authored-by: Copilot <[email protected]>

igroene

LGTM

radoslawszulgo

Please improve the description of environments that benefit from horizons. This will help user to understand the feature and examples better.

Moreover, let's agree on using "Horizons" or "MongoDB Horizons" (with a capital letter) to refer to this feature to not confuse with a literal meaning of a "horizon".

mkdocs-base.yml

radoslawszulgo · 2025-10-14T12:47:16Z

docs/horizon-setup.md

@@ -0,0 +1,362 @@
+# Configure horizons in Percona Server for MongoDB


I miss here the introduction sentence -> that to configure connection from the external network we need to configure Horizons (+ link to the glossary).

radoslawszulgo · 2025-10-14T12:50:02Z

docs/horizon-setup.md

@@ -0,0 +1,362 @@
+# Configure horizons in Percona Server for MongoDB
+
+This document focuses on configuring horizons in Percona Server for MongoDB deployed in Docker. 


why on docker only? What about non-containerized environments?

I think we need to introduce here an example of environments we are talking about - when it makes sense to use Horizons. For non-containerized environments:

Imagine a company running its infrastructure on Virtual Machines (VMs) in a cloud provider (like AWS, Azure, GCP) or on-premise. They have a standard network setup:

a private network (e.g. VPC) where their database servers reside and within which members communicate with each other over internal DNS names like rs101.internal.perconalabs.com.

a public internet, from which external services like analytics tools or developers connect to databases. These connections must use a public DNS names like rs101.percona.com

In that case Horizons help to avoid setting up complicated VPNs or SSH tunnels for external access or exposing the entire MongoDB cluster over the internal which is insecure.

Here's a mermaid diagram we could use:

graph TD subgraph "External World" CLIENT_EXT[External Client/BI Tool] end subgraph "Cloud Provider / On-Premise" subgraph "Virtual Private Cloud (VPC)" subgraph "Public Subnet" NLB(Network Load Balancer/Proxy Public IP: 52.45.100.200 Public DNS: mongo.public.mycorp.com) end subgraph "Private Subnet" APP[Internal Application Server Private IP: 10.0.1.100] subgraph "MongoDB Replica Set (rs0)" MON1(MongoDB Node 1 Primary 10.0.1.10 mongo-1.internal.mycorp.local) MON2(MongoDB Node 2 Secondary 10.0.1.11 mongo-2.internal.mycorp.local) MON3(MongoDB Node 3 Secondary 10.0.1.12 mongo-3.internal.mycorp.local) end end end end CLIENT_EXT -- 1. Connects to Public DNS (SNI: mongo.public.mycorp.com) --> NLB NLB -- 2. Forwards to Primary --> MON1 MON1 -- 3. Horizons Reply (mongo.public.mycorp.com) --> NLB NLB -- 4. Routes Reply --> CLIENT_EXT APP -- 1. Connects to Internal DNS (SNI: mongo-1.internal.mycorp.local) --> MON1 MON1 -- 2. Normal Reply (internal hostnames) --> APP APP -- Connects to other nodes directly --> MON2 APP -- Connects to other nodes directly --> MON3 MON1 <--> MON2 MON1 <--> MON3 MON2 <--> MON3

Loading

What if we simplify it and go with something like the attached mockup?

I suggest leaving out backup and monitoring from the diagram, since they are not relevant to this topic. We should emphasize the difference between clients connecting from the same network vs clients connecting from remote sites, which might use a different FQDN to get to mongo

Thanks, will do. It is a quick AI generated mockup. My point is the initial mermaid diagram is too complicated. I'd like to have smth simpler. And move it out of the setup doc:)

radoslawszulgo · 2025-10-14T16:57:42Z

docs/horizon-setup.md

+
+* **You must use TLS in your deployment**. Horizons rely entirely on the Server Name Indication (SNI) during the TLS handshake. Connections without TLS will not allow the server to determine the correct identity via SNI, and horizons will not function.
+
+* **TLS certificates** must be Multi-SAN (Subject Alternative Name) certificates that cover both the internal hostname (e.g., `mongo1`) and the external hostname (e.g., `external.domain.com`).


Suggested change

* **TLS certificates** must be Multi-SAN (Subject Alternative Name) certificates that cover both the internal hostname (e.g., `mongo1`) and the external hostname (e.g., `external.domain.com`).

* **TLS certificates** must be Multi-SAN (Subject Alternative Name) certificates that cover both the internal hostname (e.g., `internal.perconalabs.com`) and the external hostname (e.g., `external.percona.com`).

Why do we want to use percona-specific domains?

to show a real-life scenario with valid domains. In most cases such domains are used by other organizations.

radoslawszulgo · 2025-10-14T17:09:24Z

docs/horizon-setup.md

+
+* **All-or-nothing configuration**. If one member defines a horizon, all other members must define one too. You cannot mix members with and without horizons.
+
+## Configuration


Suggested change

## Configuration

## Configuration example

radoslawszulgo · 2025-10-14T17:27:35Z

docs/horizon-setup.md

+            processId: ObjectId('68e786bf0223ec7011474d9b'),
+            counter: Long('40')
+          },
+          hosts: [ 'mongo1:27017', 'mongo2:27017', 'mongo3:27017' ],


Suggested change

hosts: [ 'mongo1:27017', 'mongo2:27017', 'mongo3:27017' ],

hosts: [ 'rs101.internal.perconalabs.com:27017', 'rs102.internal.perconalabs.com:27017', 'rs103.internal.perconalabs.com:27017' ],

radoslawszulgo · 2025-10-14T17:28:12Z

docs/horizon-setup.md

+1. Connect to the replica set from the MongoDB client (Compass or `mongosh`) using the external hostnames you defined in horizons:
+
+    ```{.bash data-prompt="$"}
+    $ mongosh "mongodb://localhost:27017,localhost:27018,localhost:27019/?replicaSet=rs0" --tls --tlsCertificateKeyFile /certs/mongo1-combined.pem --tlsCAFile /certs/ca.pem


Suggested change

$ mongosh "mongodb://localhost:27017,localhost:27018,localhost:27019/?replicaSet=rs0" --tls --tlsCertificateKeyFile /certs/mongo1-combined.pem --tlsCAFile /certs/ca.pem

$ mongosh "mongodb://rs101.percona.com:27017,rs102.percona.com:27018,rs103.percona.com:27019/?replicaSet=rs1" --tls --tlsCertificateKeyFile /certs/rs1-combined.pem --tlsCAFile /certs/ca.pem

radoslawszulgo · 2025-10-14T17:29:37Z

docs/horizon-setup.md

+
+        ```{.text .no-copy}
+        Current Mongosh Log ID: 68e90919857364d663248377
+        Connecting to:  mongodb://mongo1:27017,mongo2:27017,mongo3:27017/?replicaSet=rs0&tls=true&tlsCertificateKeyFile=%2Fcerts%2Fmongo1-combined.pem&tlsCAFile=%2Fcerts%2Fca.pem&appName=mongosh+{{mongosh}}


Suggested change

Connecting to: mongodb://mongo1:27017,mongo2:27017,mongo3:27017/?replicaSet=rs0&tls=true&tlsCertificateKeyFile=%2Fcerts%2Fmongo1-combined.pem&tlsCAFile=%2Fcerts%2Fca.pem&appName=mongosh+{{mongosh}}

Connecting to: mongodb://rs101.percona.com:27017,rs102.percona.com:27018,rs103.percona.com:27019/?replicaSet=rs1&tls=true&tlsCertificateKeyFile=%2Fcerts%2Frs1-combined.pem&tlsCAFile=%2Fcerts%2Fca.pem&appName=mongosh+{{mongosh}}

radoslawszulgo · 2025-10-14T17:29:57Z

docs/horizon-setup.md

+            processId: ObjectId('68e786bf0223ec7011474d9b'),
+            counter: Long('40')
+          },
+           hosts: [ 'localhost:27017', 'localhost:27018', 'localhost:27019' ],


Suggested change

hosts: [ 'localhost:27017', 'localhost:27018', 'localhost:27019' ],

hosts: [ 'rs101.percona.com:27017', 'rs102.percona.com:27018', 'rs103.percona.com:27019' ],

radoslawszulgo · 2025-10-14T17:40:51Z

docs/horizon.md

+
+This overview explains the horizons feature in Percona Server for MongoDB. If you're familiar with the concept and want to use it, switch to the [Configure horizons in Percona Server for MongoDB](horizon-setup.md).
+
+When you deploy Percona Server for MongoDB in Docker, Kubernetes, or other containerized environments, you may come across the issue that clients within the same network can reach the replica set just fine. However, backup or monitoring tools outside your cluster can't connect. Why does this happen?


Not only containerized environments - also any other private, hybrid, or public cloud deployments

PSMDB-1750 Documented the horizons feature

4d52ed1

modified: docs/glossary.md new file: docs/horizon-setup.md new file: docs/horizon.md modified: mkdocs-base.yml

nastena1606 requested a review from Copilot October 10, 2025 14:02

it-percona deployed to PSMDB-1750-Horizons-7.0 - psmdb-docs-7.0 PR #1070 October 10, 2025 14:02 — with Render View deployment

Copilot AI reviewed Oct 10, 2025

View reviewed changes

docs/horizon-setup.md Outdated Show resolved Hide resolved

docs/horizon-setup.md Outdated Show resolved Hide resolved

Update docs/horizon-setup.md

89342a0

Co-authored-by: Copilot <[email protected]>

it-percona temporarily deployed to PSMDB-1750-Horizons-7.0 - psmdb-docs-7.0 PR #1070 October 10, 2025 21:10 — with Render Destroyed

Update docs/horizon-setup.md

3bdd575

Co-authored-by: Copilot <[email protected]>

it-percona deployed to PSMDB-1750-Horizons-7.0 - psmdb-docs-7.0 PR #1070 October 10, 2025 21:10 — with Render View deployment

nastena1606 requested review from igroene and radoslawszulgo October 13, 2025 12:33

igroene approved these changes Oct 13, 2025

View reviewed changes

radoslawszulgo requested changes Oct 14, 2025

View reviewed changes

		@@ -0,0 +1,362 @@
		# Configure horizons in Percona Server for MongoDB

		@@ -0,0 +1,362 @@
		# Configure horizons in Percona Server for MongoDB

		This document focuses on configuring horizons in Percona Server for MongoDB deployed in Docker.


		* You must use TLS in your deployment. Horizons rely entirely on the Server Name Indication (SNI) during the TLS handshake. Connections without TLS will not allow the server to determine the correct identity via SNI, and horizons will not function.

		* TLS certificates must be Multi-SAN (Subject Alternative Name) certificates that cover both the internal hostname (e.g., `mongo1`) and the external hostname (e.g., `external.domain.com`).


		* All-or-nothing configuration. If one member defines a horizon, all other members must define one too. You cannot mix members with and without horizons.

		## Configuration

	hosts: [ 'mongo1:27017', 'mongo2:27017', 'mongo3:27017' ],
	hosts: [ 'rs101.internal.perconalabs.com:27017', 'rs102.internal.perconalabs.com:27017', 'rs103.internal.perconalabs.com:27017' ],

	$ mongosh "mongodb://localhost:27017,localhost:27018,localhost:27019/?replicaSet=rs0" --tls --tlsCertificateKeyFile /certs/mongo1-combined.pem --tlsCAFile /certs/ca.pem
	$ mongosh "mongodb://rs101.percona.com:27017,rs102.percona.com:27018,rs103.percona.com:27019/?replicaSet=rs1" --tls --tlsCertificateKeyFile /certs/rs1-combined.pem --tlsCAFile /certs/ca.pem

	Connecting to: mongodb://mongo1:27017,mongo2:27017,mongo3:27017/?replicaSet=rs0&tls=true&tlsCertificateKeyFile=%2Fcerts%2Fmongo1-combined.pem&tlsCAFile=%2Fcerts%2Fca.pem&appName=mongosh+{{mongosh}}
	Connecting to: mongodb://rs101.percona.com:27017,rs102.percona.com:27018,rs103.percona.com:27019/?replicaSet=rs1&tls=true&tlsCertificateKeyFile=%2Fcerts%2Frs1-combined.pem&tlsCAFile=%2Fcerts%2Fca.pem&appName=mongosh+{{mongosh}}

	hosts: [ 'localhost:27017', 'localhost:27018', 'localhost:27019' ],
	hosts: [ 'rs101.percona.com:27017', 'rs102.percona.com:27018', 'rs103.percona.com:27019' ],


		This overview explains the horizons feature in Percona Server for MongoDB. If you're familiar with the concept and want to use it, switch to the [Configure horizons in Percona Server for MongoDB](horizon-setup.md).

		When you deploy Percona Server for MongoDB in Docker, Kubernetes, or other containerized environments, you may come across the issue that clients within the same network can reach the replica set just fine. However, backup or monitoring tools outside your cluster can't connect. Why does this happen?

PSMDB-1750 Documented the horizons feature #1070

Are you sure you want to change the base?

PSMDB-1750 Documented the horizons feature #1070

Conversation

nastena1606 commented Oct 10, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

igroene left a comment

Choose a reason for hiding this comment

Uh oh!

radoslawszulgo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants