Skip to content

Commit 0150bdb

Browse files
corryrootjwilliams-mongo
corryroot
authored and
jwilliams-mongo
committed
(DOCSP-14708): Added OpenShift instructions for a replica set. (#523)
* (DOCSP-14708): Added Openshift instructions for a replica set. * (DOCSP-14708): Incorporated Zach's feedback. * (DOCSP-14708): Incorporated feedback from Rodrigo and Jack
1 parent 2c6584d commit 0150bdb

File tree

6 files changed

+376
-25
lines changed

6 files changed

+376
-25
lines changed

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

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
title: "Deploy a replica set with the |k8s-op-short|."
3+
stepnum: 1
4+
level: 4
5+
optional: true
6+
ref: pre-deploy-replica-set-openshift
7+
source:
8+
file: steps-enable-split-horizon.yaml
9+
ref: pre-deploy-replicaset
10+
11+
---
12+
title: "Configure services to ensure connectivity."
13+
stepnum: 2
14+
level: 4
15+
ref: configure-replica-set-services-openshift
16+
content: |
17+
18+
a. Paste the following example services into a text editor:
19+
20+
.. literalinclude:: /reference/k8s/example-openshift-service.yaml
21+
:linenos:
22+
:lineno-start: 1
23+
:emphasize-lines: 12-13, 26-27, 40-41
24+
25+
.. note::
26+
27+
If the `spec.selector` has entries that target headless
28+
services or applications, OpenShift may create a software
29+
firewall rule explicitly dropping connectivity. Review the
30+
selectors carefully and consider targeting the stateful set pod
31+
members directly as seen in the example. Routes in OpenShift
32+
offer port 80 or port 443. This example service uses
33+
port 443.
34+
35+
#. Change the settings to your preferred values.
36+
37+
#. Save this file with a ``.yaml`` file extension.
38+
39+
#. To create the services, invoke the following ``kubectl`` command
40+
on the services file you created:
41+
42+
.. code-block:: sh
43+
44+
kubectl apply -f <my-external-services>.yaml
45+
46+
---
47+
title: "Configure routes to ensure |tls| terminination passthrough."
48+
stepnum: 3
49+
level: 4
50+
ref: configure-replica-set-routes-openshift
51+
content: |
52+
53+
a. Paste the following example routes into a text editor:
54+
55+
.. literalinclude:: /reference/k8s/example-openshift-route.yaml
56+
:linenos:
57+
:lineno-start: 1
58+
:emphasize-lines: 7, 11-12, 19, 23-24, 31, 35-36
59+
60+
.. note::
61+
62+
To ensure the |tls| |sni| negotiation with |mongod| necessary
63+
for |mongod| to respond with the correct horizon replica set
64+
topology for the drivers to use, you must set |tls|
65+
termination passthrough.
66+
67+
#. Change the settings to your preferred values.
68+
69+
#. Save this file with a ``.yaml`` file extension.
70+
71+
#. To create the routes, invoke the following ``kubectl`` command on
72+
the routes file you created:
73+
74+
.. code-block:: sh
75+
76+
kubectl apply -f <my-external-routes>.yaml
77+
78+
---
79+
title: "Add Subject Alternate Names to your |tls| certificates."
80+
level: 4
81+
stepnum: 4
82+
optional: true
83+
ref: remove-tls-existing-replica-sets-openshift
84+
source:
85+
file: steps-enable-split-horizon.yaml
86+
ref: remove-tls-existing-replicasets
87+
88+
---
89+
title: "Open your replica set resource |yaml| file."
90+
level: 4
91+
stepnum: 5
92+
ref: open-replica-set-resource-openshift
93+
94+
---
95+
title: "Configure your replica set resource |yaml| file."
96+
stepnum: 6
97+
level: 4
98+
ref: configure-replica-set-resource-openshift
99+
content: |
100+
101+
Use the following example to edit your replica set resource |yaml|
102+
file:
103+
104+
.. literalinclude:: /reference/k8s/example-openshift-replica-set.yaml
105+
:linenos:
106+
:lineno-start: 1
107+
:emphasize-lines: 16-33
108+
109+
.. note::
110+
111+
OpenShift clusters require localhost horizons if you intend to use
112+
the |k8s-op-short| to create each |csr|. If you manually create
113+
your |tls| certificates, ensure you include localhost in
114+
the |san-dns| list.
115+
116+
---
117+
title: "Change the settings to your preferred values."
118+
level: 4
119+
stepnum: 7
120+
ref: change-replset-resource-openshift
121+
source:
122+
file: steps-enable-split-horizon.yaml
123+
ref: change-replset-resource
124+
125+
---
126+
level: 4
127+
stepnum: 8
128+
ref: save-object-spec-rs-openshift
129+
source:
130+
file: steps-source-deploy-k8s-resource.yaml
131+
ref: save-object-spec-update
132+
replacement:
133+
k8sResource: :term:`replica set`
134+
135+
---
136+
title: "Create the necessary |tls| certificates and |k8s| secrets."
137+
stepnum: 9
138+
level: 4
139+
optional: true
140+
ref: create-certs-openshift
141+
content: |
142+
143+
:ref:`Configure TLS for your replica set
144+
<tls-for-replica-set>`. Create one secret for the MongoDB replica set
145+
and one for the certificate authority. The |k8s-op-short| uses these
146+
secrets to place the |tls| files in the pods for MongoDB to use.
147+
148+
---
149+
title: "Approve |csr| requests."
150+
stepnum: 10
151+
level: 4
152+
optional: true
153+
ref: approve-csr-requests-openshift
154+
content: |
155+
156+
a. If you do not manually create the |tls| certificates for the
157+
deployment, check for pending |csr| approval requests:
158+
159+
.. code-block:: sh
160+
161+
oc get csr
162+
163+
#. When the requests come through, approve them:
164+
165+
.. code-block:: sh
166+
167+
oc adm certificate approve {certificate-0}.{namespace} ... {certificate-n}.{namespace}
168+
169+
---
170+
level: 4
171+
stepnum: 11
172+
ref: restart-k8s-deployment-rs-openshift
173+
source:
174+
file: steps-source-deploy-k8s-resource.yaml
175+
ref: restart-k8s-deployment
176+
replacement:
177+
k8sResource: :term:`replica set`
178+
k8sResourceType: replica-set
179+
180+
---
181+
title: Test the connection to the replica set.
182+
level: 4
183+
stepnum: 12
184+
ref: k8s-ext-rs-test-conn-openshift
185+
content: |
186+
187+
The |k8s-op-short| should deploy the MongoDB replica set,
188+
configured with the horizon routes created for ingress. After
189+
the |k8s-op-short| completes the deployment, you may connect with the
190+
horizon using |tls| connectivity. If the certificate authority is
191+
not present on your workstation, you can view and copy it from a
192+
MongoDB pod using the following command:
193+
194+
.. code-block:: sh
195+
196+
oc exec -it my-external-0 -- cat /mongodb-automation/ca.pem
197+
198+
To test the connections, run the following command:
199+
200+
.. note::
201+
202+
In the following example, use your replica set names and replace ``{redacted}`` with the domain that you manage.
203+
204+
.. code-block:: sh
205+
206+
mongo --host my-external/my-external-0.{redacted}:443,my-external-1.{redacted}:443,my-external-2.{redacted}:443 \
207+
--tls \
208+
--tlsAllowInvalidCertificates
209+
210+
.. warning::
211+
212+
Don't use the ``--tlsAllowInvalidCertificates`` flag in production.
213+
In production, share the |k8s| |certauth| files with client tools
214+
or applications.
215+
216+
If the connection succeeds, you should see:
217+
218+
.. code-block:: javascript
219+
220+
MongoDB Enterprise <my-replica-set>:PRIMARY
221+
222+
...

‎source/reference/k8s/example-openshift-replica-set.yaml

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
apiVersion: mongodb.com/v1
3+
kind: MongoDB
4+
metadata:
5+
name: my-external
6+
namespace: mongodb
7+
spec:
8+
type: ReplicaSet
9+
members: 3
10+
version: 4.2.2-ent
11+
opsManager:
12+
configMapRef:
13+
name: {redacted}
14+
credentials: {redacted}
15+
persistent: false
16+
security:
17+
tls:
18+
# TLS must be enabled to allow external connectivity
19+
enabled: true
20+
authentication:
21+
enabled: true
22+
modes: ["SCRAM","X509"]
23+
connectivity:
24+
# The "localhost" routes are there just to make sure the localhost
25+
# TLS SAN is created in the CSR, per OpenShift route requirements.
26+
# "ocroute" is the configured route in openshift
27+
replicaSetHorizons:
28+
- "ocroute": "my-external-0.{redacted}:443"
29+
"localhost": "localhost:27017"
30+
- "ocroute": "my-external-1.{redacted}:443"
31+
"localhost": "localhost:27018"
32+
- "ocroute": "my-external-2.{redacted}:443"
33+
"localhost": "localhost:27019"
34+
35+
...

‎source/reference/k8s/example-openshift-route.yaml

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
apiVersion: v1
3+
kind: Route
4+
metadata:
5+
name: my-external-0
6+
spec:
7+
host: my-external-0.{redacted}
8+
to:
9+
kind: Service
10+
name: my-external-0
11+
tls:
12+
termination: passthrough
13+
---
14+
apiVersion: v1
15+
kind: Route
16+
metadata:
17+
name: my-external-1
18+
spec:
19+
host: my-external-1.{redacted}
20+
to:
21+
kind: Service
22+
name: my-external-1
23+
tls:
24+
termination: passthrough
25+
---
26+
apiVersion: v1
27+
kind: Route
28+
metadata:
29+
name: my-external-2
30+
spec:
31+
host: my-external-2.{redacted}
32+
to:
33+
kind: Service
34+
name: my-external-2
35+
tls:
36+
termination: passthrough
37+
38+
...
39+

‎source/reference/k8s/example-openshift-service.yaml

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
kind: Service
3+
apiVersion: v1
4+
metadata:
5+
name: my-external-0
6+
spec:
7+
ports:
8+
- name: mongodb
9+
protocol: TCP
10+
port: 443
11+
targetPort: 27017
12+
selector:
13+
statefulset.kubernetes.io/pod-name: my-external-0
14+
15+
---
16+
kind: Service
17+
apiVersion: v1
18+
metadata:
19+
name: my-external-1
20+
spec:
21+
ports:
22+
- name: mongodb
23+
protocol: TCP
24+
port: 443
25+
targetPort: 27017
26+
selector:
27+
statefulset.kubernetes.io/pod-name: my-external-1
28+
29+
---
30+
kind: Service
31+
apiVersion: v1
32+
metadata:
33+
name: my-external-2
34+
spec:
35+
ports:
36+
- name: mongodb
37+
protocol: TCP
38+
port: 443
39+
targetPort: 27017
40+
selector:
41+
statefulset.kubernetes.io/pod-name: my-external-2
42+
43+
...

0 commit comments

Comments
 (0)