Skip to content

Commit 8c5aac4

Browse files
JuliaMongojwilliams-mongo
JuliaMongo
authored and
jwilliams-mongo
committed
(DOCSP-21605) Split-Horizon for multi-clusters (#908)
* (DOCSP-21605) Split-Horizon for multi-clusters * Build issues * Build issues * Build issues * Addressed initial tech review comments from Mircea, ready for a copy review now * Ready for a copy review * Address copy review, with the exception of examples * Build * Build * Fixing a step link * Fixing a step link * Finished applying copy review comments, added examples from tech review * Edits, ready for a final copy review * Edits, ready for a final copy review * Address tech review from Raj * Address one more comment from Raj * Edit, ready to merge
1 parent 3bf1bef commit 8c5aac4

13 files changed

+327
-41
lines changed

‎source/includes/prereqs/pem-file-domain-name.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@ Each certificate should include a valid Domain Name.
22

33
For each replica set or sharded cluster member, the Common Name, also
44
known as the Domain Name, for that member's certificate must match
5-
the |fqdn| of the POD on which this cluster member
6-
is deployed.
5+
the |fqdn| of the pod this cluster member is deployed on.
76

87
The |fqdn| name in each certificate has the following syntax:
98
``pod-name.service-name.namespace.svc.cluster.local``. This name is

‎source/includes/steps-connect-from-inside-k8s.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,4 +38,5 @@ content: |
3838
.. code-block:: none
3939
:copyable: false
4040
41-
mongo --host shardedcluster-mongos-0.shardedcluster-svc.mongodb.svc.cluster.local --port 27017
41+
mongosh --host shardedcluster-mongos-0.shardedcluster-svc.mongodb.svc.cluster.local \
42+
--port 27017

‎source/includes/steps-enable-external-sharded.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,8 @@ content: |
119119
.. code-block:: sh
120120
:copyable: false
121121
122-
mongo --host ec2-54-212-23-143.us-west-2.compute.amazonaws.com --port 30078
122+
mongosh --host ec2-54-212-23-143.us-west-2.compute.amazonaws.com \
123+
--port 30078
123124
124125
.. include:: /includes/admonitions/fact-get-external-dns.rst
125126

‎source/includes/steps-enable-external-standalone.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,8 @@ content: |
120120
.. code-block:: sh
121121
:copyable: false
122122
123-
mongo --host ec2-54-212-23-143.us-west-2.compute.amazonaws.com --port 30994
123+
mongosh --host ec2-54-212-23-143.us-west-2.compute.amazonaws.com \
124+
--port 30994
124125
125126
.. include:: /includes/admonitions/fact-get-external-dns.rst
126127

‎source/includes/steps-enable-split-horizon-openshift.yaml‎

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ content: |
2525
2626
If the `spec.selector` has entries that target headless
2727
services or applications, OpenShift may create a software
28-
firewall rule explicitly dropping connectivity. Review the
28+
firewall rule explicitly dropping connectivity. Review the
2929
selectors carefully and consider targeting the stateful set pod
30-
members directly as seen in the example. Routes in OpenShift
30+
members directly as seen in the example. Routes in OpenShift
3131
offer port 80 or port 443. This example service uses
3232
port 443.
3333
@@ -154,7 +154,7 @@ replacement:
154154
k8sResourceType: replica-set
155155

156156
---
157-
title: Test the connection to the replica set.
157+
title: "Test the connection to the replica set."
158158
level: 4
159159
stepnum: 11
160160
ref: k8s-ext-rs-test-conn-openshift
@@ -175,24 +175,37 @@ content: |
175175
176176
.. note::
177177
178-
In the following example, use your replica set names and replace ``{redacted}`` with the domain that you manage.
178+
In the following example, for each member of the replica set, use
179+
your replica set names and replace ``{redacted}`` with the domain
180+
that you manage.
179181
180182
.. code-block:: sh
181183
182-
mongo --host my-external/my-external-0.{redacted}:443,my-external-1.{redacted}:443,my-external-2.{redacted}:443 \
183-
--tls \
184+
mongosh --host my-external/my-external-0.{redacted} \
185+
--port 443
186+
--ssl \
184187
--tlsAllowInvalidCertificates
185188
186189
.. warning::
187190
188191
Don't use the ``--tlsAllowInvalidCertificates`` flag in production.
189-
In production, share the |k8s| |certauth| files with client tools
190-
or applications.
192+
193+
In production, for each host in a replica set, specify the |tls|
194+
certificate and the |certauth| to securely connect to client tools or
195+
applications:
196+
197+
.. code-block:: sh
198+
199+
mongosh --host my-external/my-external-0.{redacted} \
200+
--port 443 \
201+
--tls \
202+
--tlsCertificateKeyFile server.pem \
203+
--tlsCAFile ca-pem
191204
192205
If the connection succeeds, you should see:
193206
194207
.. code-block:: javascript
195208
196-
MongoDB Enterprise <my-replica-set>:PRIMARY
209+
Enterprise <my-replica-set> [primary]
197210
198211
...

‎source/includes/steps-enable-split-horizon.yaml‎

Lines changed: 8 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ content: |
1010
1111
You must enable |tls| for the replica set by providing a value for
1212
the :setting:`spec.security.certsSecretPrefix` setting. The replica
13-
set must use a custom certificate stored with
13+
set must use a custom |certauth| certificate stored with
1414
:setting:`spec.security.tls.ca`.
1515
1616
---
@@ -117,8 +117,8 @@ content: |
117117
:setting:`spec.connectivity.replicaSetHorizons` setting are correct.
118118
119119
External hostnames should match the |dns| names of |k8s| worker nodes.
120-
These can be *any* nodes in the |k8s| cluster. |k8s-nodes| do internal
121-
routing if the pod is run on another node.
120+
These can be *any* nodes in the |k8s| cluster. |k8s| nodes use internal
121+
routing if the pod runs on another node.
122122
123123
Set the ports in :setting:`spec.connectivity.replicaSetHorizons` to
124124
the NodePort values that you discovered.
@@ -152,29 +152,13 @@ source:
152152
replacement:
153153
k8sResource: :term:`replica set`
154154
k8sResourceType: replica-set
155+
155156
---
156-
title: Test the connection to the replica set.
157157
level: 4
158158
stepnum: 12
159-
ref: k8s-ext-rs-test-conn
160-
content: |
161-
162-
.. code-block:: sh
163-
164-
mongo --host <my-replica-set>/web1.example.com:30907,web2.example.com:32350,web3.example.com:31185 \
165-
--ssl \
166-
--sslAllowInvalidCertificates
167-
168-
.. warning::
169-
170-
Don't use the ``--sslAllowInvalidCertificates`` flag in production.
171-
In production, share the |k8s| |certauth| files with client tools
172-
or applications.
173-
174-
If the connection succeeds, you should see:
175-
176-
.. code-block:: javascript
177-
178-
MongoDB Enterprise <my-replica-set>:PRIMARY
159+
ref: k8s-ext-rs-test-conn-horizon
160+
inherit:
161+
file: steps-source-deploy-k8s-resource.yaml
162+
ref: k8s-ext-rs-test-conn
179163

180164
...

‎source/includes/steps-multi-cluster-enable-split-horizon.yaml‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: ":ref:`Deploy a Multi-Cluster Replica Set <multi-cluster-quick-start-ref>`."
3+
stepnum: 1
4+
level: 4
5+
ref: pre-deploy-replicaset
6+
content: |
7+
8+
---
9+
title: ":ref:`Secure the Multi-Cluster with TLS <multi-cluster-secure-tls>`."
10+
level: 4
11+
stepnum: 2
12+
ref: enable-tls--replicaset
13+
content: |
14+
15+
Provide values for:
16+
17+
- The |tls| secret in :setting:`spec.security.certsSecretPrefix`.
18+
- The custom |certauth| certificate in :setting:`spec.security.tls.ca`.
19+
20+
---
21+
title: "Add Subject Alternate Names to your |tls| certificates."
22+
level: 4
23+
stepnum: 3
24+
ref: remove-tls-existing-replicasets
25+
content: |
26+
27+
Add each external |dns| name to the certificate |san-dns|.
28+
29+
---
30+
title: "Create a ``NodePort`` service for each of the Pods in different clusters."
31+
level: 4
32+
stepnum: 4
33+
ref: k8s-ext-rs-create-nodeports
34+
content: |
35+
36+
When you create a ``NodePort`` service with ``kubectl``, it assigns a
37+
random port in the range from 30000 to 32767, inclusive.
38+
39+
1. Create a NodePort service.
40+
41+
- To create a NodePort service that uses a randomly assigned port, run
42+
the following command on each Pod in each cluster:
43+
44+
.. code-block:: sh
45+
46+
kubectl expose pod/<my-replica-set>-0 --type="NodePort" --port 27017
47+
48+
- To create a NodePort service that uses a deterministic port, on each
49+
Pod in each cluster, create a ``Nodeport`` service definition YAML
50+
file similar to the following example. Specify the port you want
51+
to use in the :setting:`spec.ports.NodePort` setting. This example
52+
configures a NodePort service on port 30007.
53+
54+
.. code-block:: yaml
55+
56+
apiVersion: v1
57+
kind: Service
58+
metadata:
59+
name: <my-replica-set>-0
60+
labels:
61+
controller: mongodb-enterprise-operator
62+
spec:
63+
type: NodePort
64+
selector:
65+
controller: mongodb-enterprise-operator
66+
ports:
67+
port: 27017
68+
targetPort: 27017
69+
nodePort: 30007
70+
71+
72+
Apply the YAML with ``kubectl apply -f <nodeport-conf>.yaml``.
73+
74+
---
75+
title: "Verify the NodePort services."
76+
level: 4
77+
stepnum: 5
78+
ref: k8s-ext-rs-discover-nodeports
79+
content: |
80+
81+
In each cluster, run this command to verify the NodePort services that
82+
you created:
83+
84+
.. code-block:: sh
85+
86+
$ kubectl get svc <node_port_service_name>
87+
88+
The command returns results similar to the following example:
89+
90+
.. code-block:: sh
91+
92+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
93+
<node_port_service_name> NodePort 10.102.27.116 <none> 27017:30007/TCP 8m30s
94+
95+
---
96+
title: "Update your replica set resource |yaml| file."
97+
level: 4
98+
stepnum: 6
99+
ref: update-replset-resource-mc-split-horizon
100+
content: |
101+
102+
Set the hostnames and ports in :setting:`spec.connectivity.replicaSetHorizons`
103+
to the NodePort values that you created in the previous step.
104+
105+
Confirm that you specified the correct external hostnames. External
106+
hostnames should match the |dns| names of |k8s| worker nodes.
107+
These can be *any* nodes in the |k8s| cluster. If the Pod runs on another
108+
node, |k8s| nodes use internal routing.
109+
110+
.. code-block:: sh
111+
112+
apiVersion: mongodb.com/v1
113+
kind: MongoDBMulti
114+
metadata:
115+
name: multi-cluster-replica-set
116+
namespace: mongodb
117+
spec:
118+
clusterSpecList:
119+
clusterSpecs:
120+
- clusterName: e2e.cluster1.mongokubernetes.com
121+
members: 1
122+
- clusterName: e2e.cluster2.mongokubernetes.com
123+
members: 1
124+
- clusterName: e2e.cluster3.mongokubernetes.com
125+
members: 1
126+
connectivity:
127+
replicaSetHorizons:
128+
- sample-horizon: web1.example.com:30907
129+
- sample-horizon: web2.example.com:30907
130+
- sample-horizon: web3.example.com:30907
131+
credentials: my-credentials
132+
duplicateServiceObjects: false
133+
opsManager:
134+
configMapRef:
135+
name: my-project
136+
persistent: true
137+
security:
138+
certsSecretPrefix: clustercert
139+
tls:
140+
ca: issuer-ca
141+
type: ReplicaSet
142+
version: 4.4.0-ent"
143+
144+
---
145+
title: "Apply the updated replica set file."
146+
level: 4
147+
stepnum: 7
148+
ref: apply-crd
149+
content: |
150+
151+
In each cluster, run this command to apply the updated replica set file:
152+
153+
.. code-block:: sh
154+
155+
$ Kubectl apply -f <file_name.yaml>
156+
157+
---
158+
level: 4
159+
stepnum: 8
160+
ref: k8s-ext-rs-test-conn-horizon-mc
161+
inherit:
162+
file: steps-source-deploy-k8s-resource.yaml
163+
ref: k8s-ext-rs-test-conn
164+
165+
...

‎source/includes/steps-source-deploy-k8s-resource.yaml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -739,4 +739,43 @@ content: |
739739
740740
kubectl create configmap custom-ca --from-file=ca-pem
741741
742+
---
743+
title: "Test the connection to the replica set."
744+
stepnum: 0
745+
level: 4
746+
ref: k8s-ext-rs-test-conn
747+
content: |
748+
749+
In the development environment, for each host in a replica set, run
750+
the following command:
751+
752+
.. code-block:: sh
753+
754+
mongosh --host <my-replica-set>/web1.example.com \
755+
--port 30907
756+
--ssl \
757+
--sslAllowInvalidCertificates
758+
759+
.. note::
760+
761+
Don't use the ``--sslAllowInvalidCertificates`` flag in production.
762+
763+
In production, for each host in a replica set, specify the |tls|
764+
certificate and the |certauth| to securely connect to client tools or
765+
applications:
766+
767+
.. code-block:: sh
768+
769+
mongosh --host <my-replica-set>/web1.example.com \
770+
--port 30907 \
771+
--tls \
772+
--tlsCertificateKeyFile server.pem \
773+
--tlsCAFile ca-pem
774+
775+
If the connection succeeds, you should see:
776+
777+
.. code-block:: javascript
778+
779+
Enterprise <my-replica-set> [primary]
780+
742781
...

‎source/multi-cluster-arch.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,17 @@ clusters are not available in the beta release of the |multi-clusters|:
2727
- Sharded cluster deployments
2828
- LDAP authentication
2929
- |onprem| version earlier than 5.0.7
30-
- Split Horizon
30+
31+
.. _multi-cluster-capabilities:
3132

3233
Multi-Cluster Capabilities
3334
--------------------------
3435

36+
This section describes the multi-cluster capabilities that you can
37+
configure using the same procedures as for single clusters deployed with
38+
the |k8s-op-short|. Other multi-cluster capabilities have their own
39+
documentation in this guide.
40+
3541
.. list-table::
3642
:header-rows: 1
3743
:widths: 30 70

0 commit comments

Comments
 (0)