Skip to content

Commit d8420fa

Browse files
jdestefano-mongojwilliams-mongo
jdestefano-mongo
authored and
jwilliams-mongo
committed
(DOCSP-5656): Kubernetes X.509 project and internal cluster auth. (#45)
1 parent 5c470c1 commit d8420fa

15 files changed

+507
-55
lines changed

‎conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,8 @@
8686
'.. |cifs| replace:: :abbr:`CIFS (Common Internet File System)`',
8787
'.. |com| replace:: Cloud Manager or Ops Manager',
8888
'.. |compass| replace:: :compass:`MongoDB Compass </>`',
89+
'.. |csr| replace:: :abbr:`CSR (Certificate Signing Request)`',
90+
'.. |csrs| replace:: :abbr:`CSRs (Certificate Signing Requests)`',
8991
'.. |dns| replace:: :abbr:`DNS (Domain Name System)`',
9092
'.. |dns-srv| replace:: :abbr:`DNS (Domain Name System)` :abbr:`SRV (Service)`',
9193
'.. |ent-build| replace:: MongoDB Enterprise',

‎source/configuration.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,5 +21,5 @@ Configure the |k8s-op-short|
2121
.. toctree::
2222
:titlesonly:
2323

24-
/tutorial/create-project-using-configmap
2524
/tutorial/create-operator-credentials
25+
/tutorial/create-project-using-configmap

‎source/includes/list-table-configmap-keys-x509.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. list-table::
2+
:widths: 20 20 40 20
3+
:header-rows: 1
4+
5+
* - Key
6+
- Type
7+
- Description
8+
- Example
9+
10+
* - ``data.authenticationMode``
11+
- string
12+
- Requires all agents to use X.509 client authentication when
13+
communicating with MongoDB deployments.
14+
- ``x509``
15+
16+
* - ``data.credentials``
17+
- string
18+
- Name of the |k8s| secret containing the |com| username and Public
19+
API key. If you have not created these credentials yet,
20+
see :ref:`create-k8s-secret`.
21+
22+
- ``mycredentials``

‎source/includes/options-k8s-replica-set.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -299,4 +299,11 @@ inherit:
299299
name: spec.additionalMongodConfig.net.ssl.mode
300300
program: _shared
301301
file: options-k8s-shared.yaml
302+
---
303+
program: k8sRsConf
304+
name: spec.security.clusterAuthenticationMode
305+
inherit:
306+
name: spec.security.clusterAuthenticationMode
307+
program: _shared
308+
file: options-k8s-shared.yaml
302309
...

‎source/includes/options-k8s-shared.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -422,5 +422,21 @@ description: |
422422
The following are valid options:
423423
424424
.. include:: /includes/list-table-requiressl-modes.rst
425+
---
426+
program: _shared
427+
name: spec.security.clusterAuthenticationMode
428+
type: string
429+
directive: setting
430+
optional: true
431+
description: |
432+
433+
Set to ``x509`` to enable
434+
:ref:`X.509 internal cluster authentication <x509-internal-authentication>`.
435+
Requires |tls| on the resource by setting
436+
:setting:`spec.security.tls.enabled` to ``true``.
437+
438+
.. important::
425439
440+
Once internal cluster authentication is enabled, it can not be
441+
disabled.
426442
...

‎source/includes/steps-create-k8s-configmap-tls.yaml‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,15 +88,34 @@ source:
8888
---
8989
stepnum: 7
9090
level: 4
91+
ref: configure-configmap-x509-tls
92+
source:
93+
file: steps-create-k8s-configmap.yaml
94+
ref: configure-configmap-x509
95+
replacement:
96+
example: |
97+
.. literalinclude:: /reference/k8s/example-configmap-tls-x509.yaml
98+
:language: yaml
99+
:emphasize-lines: 16-17
100+
---
101+
stepnum: 8
102+
level: 4
91103
ref: create-k8s-configmap-tls
92104
source:
93105
file: steps-create-k8s-configmap.yaml
94106
ref: create-k8s-configmap
95107
---
96-
stepnum: 8
108+
stepnum: 9
97109
level: 4
98110
ref: verify-k8s-configmap-tls
99111
source:
100112
file: steps-create-k8s-configmap.yaml
101113
ref: verify-k8s-configmap
114+
---
115+
stepnum: 10
116+
level: 4
117+
ref: approve-agent-certificates-tls
118+
source:
119+
file: steps-create-k8s-configmap.yaml
120+
ref: approve-agent-certificates
102121
...

‎source/includes/steps-create-k8s-configmap.yaml‎

Lines changed: 83 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,51 @@ ref: configure-k8s-configmap
2121
content: |
2222
.. include:: /includes/list-table-configmap-keys.rst
2323
---
24-
title: "Save this file with a ``.yaml`` file extension."
24+
title: "(Optional) Enable X.509 authentication at the |com| project level."
2525
stepnum: 4
2626
level: 4
27+
ref: configure-configmap-x509
28+
content: |
29+
30+
Enabling X.509 authentication at the project level configures all agents
31+
to use X.509 client authentication when communicating with MongoDB
32+
deployments.
33+
34+
|cloud-short| or one of the following versions of |onprem| is required
35+
to use X.509 client authentication:
36+
37+
.. list-table::
38+
:widths: 50 50
39+
:header-rows: 1
40+
41+
* - |onprem| Version
42+
- Required Patch
43+
44+
* - |onprem| 4.1
45+
- 4.1.7
46+
47+
* - |onprem| 4.0
48+
- 4.0.11
49+
50+
To enable X.509 authentication, add the highlighted lines to your
51+
ConfigMap:
52+
53+
{{example}}
54+
55+
.. include:: /includes/list-table-configmap-keys-x509.rst
56+
replacement:
57+
example: |
58+
.. literalinclude:: /reference/k8s/example-configmap-x509.yaml
59+
:language: yaml
60+
:emphasize-lines: 13-14
61+
---
62+
title: "Save this file with a ``.yaml`` file extension."
63+
stepnum: 5
64+
level: 4
2765
ref: save-k8s-configmap
2866
---
2967
title: "Invoke the |k8s| command to create your |k8s-configmap|."
30-
stepnum: 5
68+
stepnum: 6
3169
level: 4
3270
ref: create-k8s-configmap
3371
content: |
@@ -42,7 +80,7 @@ content: |
4280
specified in your |k8s-configmap|.
4381
---
4482
title: "Invoke the |k8s| command to verify your |k8s-configmap|."
45-
stepnum: 6
83+
stepnum: 7
4684
level: 4
4785
ref: verify-k8s-configmap
4886
content: |
@@ -67,4 +105,46 @@ content: |
67105
Namespace: <metadata.namespace>
68106
Labels: <none>
69107
Annotations: <none>
108+
---
109+
title: "If X.509 is enabled, approve the X.509 client certificates for the agents."
110+
stepnum: 8
111+
level: 4
112+
ref: approve-agent-certificates
113+
content: |
114+
.. note::
115+
116+
If X.509 client authentication was *not* enabled in step 4, skip
117+
this step.
118+
119+
Run the following command to verify the agent certificate signing
120+
requests are pending:
121+
122+
.. code-block:: sh
123+
124+
kubectl get csr
125+
126+
The command returns the following output:
127+
128+
.. code-block:: sh
129+
:copyable: false
130+
131+
NAME AGE REQUESTOR CONDITION
132+
mms-automation-agent.mongodb 4s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
133+
mms-backup-agent.mongodb 0s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
134+
mms-monitoring-agent.mongodb 3s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
135+
136+
Approve the certificate for each agent using the ``NAME`` field
137+
above in the following command:
138+
139+
.. code-block:: sh
140+
141+
kubectl certificate approve <NAME>
142+
143+
The following commands approve the agent |csrs|:
144+
145+
.. code-block:: sh
146+
147+
kubectl certificate approve mms-automation-agent.mongodb
148+
kubectl certificate approve mms-backup-agent.mongodb
149+
kubectl certificate approve mms-monitoring-agent.mongodb
70150
...

‎source/includes/steps-deploy-k8s-replica-set-tls.yaml‎

Lines changed: 137 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ content: |
1111
1212
.. literalinclude:: /reference/k8s/example-replica-set-tls.yaml
1313
:language: yaml
14-
:emphasize-lines: 5-7,9-13,16-22
14+
:emphasize-lines: 5-7,9-13,16-24
1515
---
1616
stepnum: 2
1717
level: 4
@@ -55,6 +55,20 @@ content: |
5555
accept TLS encrypted connections.
5656
- ``true``
5757
58+
* - :setting:`spec.security.clusterAuthenticationMode`
59+
- string
60+
- *Optional.* Enables :ref:`X.509 internal cluster authentication <x509-internal-authentication>`.
61+
62+
Remove this field from your ConfigMap to disable X.509 internal
63+
cluster authentication.
64+
65+
.. important::
66+
67+
Once internal cluster authentication is enabled, it can not be
68+
disabled.
69+
70+
- ``x509``
71+
5872
* - :setting:`spec.additionalMongodConfig.net.ssl.mode`
5973
- string
6074
- *Optional.* Changes the :setting:`TLS mode <net.ssl.mode>`
@@ -125,26 +139,136 @@ level: 4
125139
ref: approve-certificates-tls
126140
content: |
127141
128-
Approve the certificate for each host using the following command:
142+
Retrieve the |csrs| for each host by running the following command:
129143
130144
.. code-block:: sh
131145
132-
kubectl certificate approve <metadata.name>-<member>.<namespace>
146+
kubectl get csr
147+
148+
The output of the command and number of certificates to approve
149+
depend on whether X.509 internal cluster authentication is enabled by
150+
setting :setting:`spec.security.clusterAuthenticationMode` to
151+
``x509`` in step 4.
152+
153+
.. tabs::
154+
155+
tabs:
156+
- id: x509disabled
157+
name: X.509 Disabled
158+
content: |
159+
The command's output resembles the following:
160+
161+
.. code-block:: sh
162+
163+
NAME AGE REQUESTOR CONDITION
164+
my-secure-rs-0.mongodb 33s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
165+
my-secure-rs-1.mongodb 31s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
166+
my-secure-rs-2.mongodb 24s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
167+
168+
Using the ``NAME`` field above, approve each certificate from the
169+
previous command's output using the following command:
170+
171+
.. code-block:: sh
172+
173+
kubectl certificate approve <NAME>
174+
175+
.. example::
176+
177+
The following commands approve the certificates for the
178+
replica set example in the previous step:
179+
180+
.. code-block:: sh
181+
:copyable: false
182+
183+
kubectl certificate approve my-secure-rs-0.mongodb
184+
kubectl certificate approve my-secure-rs-1.mongodb
185+
kubectl certificate approve my-secure-rs-2.mongodb
186+
187+
|kubectl| prints a message to the console when a certificate
188+
is approved.
189+
190+
- id: x509enabled
191+
name: X.509 Enabled
192+
content: |
193+
194+
The command's output resembles the following:
195+
196+
.. code-block:: sh
197+
198+
NAME AGE REQUESTOR CONDITION
199+
mms-automation-agent.mongodb 15m system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
200+
mms-backup-agent.mongodb 15m system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
201+
mms-monitoring-agent.mongodb 15m system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
202+
my-secure-rs-0.mongodb 6s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
203+
my-secure-rs-1.mongodb 4s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
204+
my-secure-rs-2.mongodb 1s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
205+
206+
Using the ``NAME`` field above, approve each certificate from the
207+
previous command's output using the following command:
208+
209+
.. code-block:: sh
210+
211+
kubectl certificate approve <NAME>
212+
213+
.. example::
214+
215+
The following commands approve the certificates for the
216+
replica set example in the previous step:
217+
218+
.. code-block:: sh
219+
:copyable: false
220+
221+
kubectl certificate approve my-secure-rs-0.mongodb
222+
kubectl certificate approve my-secure-rs-1.mongodb
223+
kubectl certificate approve my-secure-rs-2.mongodb
224+
225+
|kubectl| prints a message to the console when a certificate
226+
is approved.
227+
228+
When :setting:`spec.security.clusterAuthenticationMode` is set to
229+
``x509`` an additional |csr| will be generated per host for the
230+
clusterfile.
231+
232+
After the first batch of certificates are approved, run the
233+
command to retrieve the |csrs| again:
234+
235+
.. code-block:: sh
236+
237+
kubectl get csr
238+
239+
The clusterfile |csrs| are now present in the output:
240+
241+
.. code-block:: sh
242+
:copyable: false
243+
244+
NAME AGE REQUESTOR CONDITION
245+
mms-automation-agent.mongodb 17m system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
246+
mms-backup-agent.mongodb 17m system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
247+
mms-monitoring-agent.mongodb 17m system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
248+
my-secure-rs-0-clusterfile.mongodb 13s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
249+
my-secure-rs-0.mongodb 105s system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
250+
my-secure-rs-1-clusterfile.mongodb 7s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
251+
my-secure-rs-1.mongodb 103s system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
252+
my-secure-rs-2-clusterfile.mongodb 3s system:serviceaccount:mongodb:mongodb-enterprise-operator Pending
253+
my-secure-rs-2.mongodb 100s system:serviceaccount:mongodb:mongodb-enterprise-operator Approved,Issued
254+
255+
Approve the clusterfile |csrs| using the same command:
256+
257+
.. code-block:: sh
133258
134-
.. example::
259+
kubectl certificate approve <NAME>
135260
136-
The following commands approve the certificates for the
137-
replica set example in the previous step:
261+
.. example::
138262
139-
.. code-block:: sh
140-
:copyable: false
263+
The following commands approve the clusterfile
264+
certificates:
141265
142-
kubectl certificate approve my-secure-rs-0.my-namespace
143-
kubectl certificate approve my-secure-rs-1.my-namespace
144-
kubectl certificate approve my-secure-rs-2.my-namespace
266+
.. code-block:: sh
267+
:copyable: false
145268
146-
The |k8s-op-short| prints a message to the console when a certificate
147-
is approved.
269+
kubectl certificate approve my-secure-rs-0-clusterfile.mongodb
270+
kubectl certificate approve my-secure-rs-1-clusterfile.mongodb
271+
kubectl certificate approve my-secure-rs-2-clusterfile.mongodb
148272
---
149273
title: "Track the status of your deployment."
150274
level: 4

0 commit comments

Comments
 (0)