Skip to content

Commit 5c470c1

Browse files
jdestefano-mongojwilliams-mongo
jdestefano-mongo
authored and
jwilliams-mongo
committed
(DOCSP-5093): Kubernetes TLS/SSL docs (#44)
* (DOCSP-5093): Kubernetes TLS/SSL documentation> * (DOCSP-5093): Additional tightening up. * (DOCSP-5093): Update security toc. * (DOCSP-5093): Move resource TLS stuff onto deployment pages. * (DOCSP-5093): Refactored tutorial page content into ConfigMap and resource deploy pages. * (DOCSP-5093): Remove unneeded pages from initial draft. * (DOCSP-5093): Additional cleanup. * Apply suggestions from code review Co-Authored-By: Anthony Sansone <[email protected]> * (DOCSP-5093) - Additional TLS/SSL -> SSL cleanup. * (DOCSP-5093): Reflow. * (DOCSP-5093): Add example blocks. * CA replacements. Co-Authored-By: Anthony Sansone <[email protected]> * (DOCSP-5093): Fix sharded cluster example pod names. * (DOCSP-5093): Review edits.
1 parent c166402 commit 5c470c1

21 files changed

+870
-161
lines changed

‎conf.py

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,9 @@
5858

5959
source_constants = {
6060
'version': version,
61-
'k8s-op-short': 'Kubernetes Operator'
61+
'k8s-op-short': 'Kubernetes Operator',
62+
'aagent': 'MongoDB Agent or legacy Automation Agent',
63+
'aagents': 'MongoDB Agents or legacy Automation Agents'
6264
}
6365

6466
rst_epilog = '\n'.join([
@@ -83,6 +85,7 @@
8385
'.. |cidr| replace:: :abbr:`CIDR (Classless Inter-Domain Routing)`',
8486
'.. |cifs| replace:: :abbr:`CIFS (Common Internet File System)`',
8587
'.. |com| replace:: Cloud Manager or Ops Manager',
88+
'.. |compass| replace:: :compass:`MongoDB Compass </>`',
8689
'.. |dns| replace:: :abbr:`DNS (Domain Name System)`',
8790
'.. |dns-srv| replace:: :abbr:`DNS (Domain Name System)` :abbr:`SRV (Service)`',
8891
'.. |ent-build| replace:: MongoDB Enterprise',
@@ -188,6 +191,7 @@
188191
'cloudmgr': ('http://docs.cloudmanager.mongodb.com/%s', ''),
189192
'atlas': ('http://docs.atlas.mongodb.com/%s', ''),
190193
'bic': ('https://docs.mongodb.com/bi-connector/current%s',''),
194+
'compass': ('https://docs.mongodb.com/compass/current%s',''),
191195
'product': ('http://www.mongodb.com/products/%s?jmp=docs',''),
192196
'dl': ('http://www.mongodb.com/download-center/%s?jmp=docs','')
193197
}

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

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
.. list-table::
2+
:widths: 20 20 40 20
3+
:header-rows: 1
4+
5+
* - Key
6+
- Type
7+
- Description
8+
- Example
9+
10+
* - ``metadata.name``
11+
- string
12+
- Label for a |k8s| |k8s-obj|.
13+
14+
.. seealso::
15+
16+
- :setting:`metadata.name`
17+
- |k8s| documentation on `names <https://kubernetes.io/docs/concepts/overview/working-with-objects/names/>`__.
18+
This name must follow :rfc:`RFC1123 <1123>` naming
19+
conventions, using only lowercase alphanumeric
20+
characters, '-' or '.', and must start and end with an
21+
alphanumeric character.
22+
23+
- ``myconfigmap``
24+
25+
* - ``metadata.namespace``
26+
- string
27+
- Scope of object names. Used to limit what can be managed to
28+
a subset of all |k8s-objs|. The default value is ``mongodb``.
29+
30+
.. important::
31+
The |k8s-op-short|, |k8s-secret|, and |k8s-mdbrsc|\s
32+
*must* be created in the same |k8s-ns|.
33+
34+
.. seealso::
35+
36+
- :setting:`metadata.namespace`
37+
- |k8s| documentation on |k8s-nss|
38+
39+
- ``mongodb``
40+
41+
* - ``data.projectName``
42+
- string
43+
- Label for your |mms|
44+
:opsmgr:`Project </tutorial/manage-projects>`.
45+
46+
.. admonition:: Let |k8s-op-short| create the Project
47+
:class: important
48+
49+
The |k8s-op-short| creates the |mms| Project if it does
50+
not exist. It is **strongly recommended** to use the
51+
Operator to create a new Project for |k8s| to manage. The
52+
Operator adds additional internal information to Projects
53+
that it creates.
54+
55+
If you need or want to use an existing Project, you can find
56+
the ``projectName`` by clicking the :guilabel:`All Clusters`
57+
link at the top left of the screen, then either search by
58+
name in the :guilabel:`Search` box or scroll to find the
59+
name in the list. Each card in this list represents the
60+
combination of one **Organization** and **Project**.
61+
62+
- ``Development``
63+
64+
* - ``data.orgId``
65+
- string
66+
- 24 character hex string that uniquely identifies your
67+
MongoDB :opsmgr:`Organization </tutorial/manage-organizations>`.
68+
You can find the ``orgId`` in your |onprem| |url|:
69+
70+
1. Click the :guilabel:`Context` menu.
71+
2. Select your Organization.
72+
3. View the current |url| in your browser and copy the value
73+
displayed in the ``<orgId>`` placeholder below:
74+
75+
| ``https://ops.example.com:8443/``
76+
| ``v2#/org/<orgId>/projects``
77+
78+
.. important::
79+
80+
This field is *optional*. If you omit the ``orgId``,
81+
|onprem| creates an Organization called ``projectName``
82+
that contains a Project also called ``projectName``.
83+
84+
You must have the :authrole:`Organization Project Creator`
85+
role to create a new project
86+
*within an existing organization*.
87+
88+
.. admonition:: Limited to |com| Organizations
89+
90+
If you set this value, it can be for a |com|
91+
organization only. If you try to use an Atlas
92+
organization, the |k8s-op-short| may not work as
93+
intended.
94+
95+
- | ``5cc9b333dd3e384a625a6615``
96+
97+
* - ``data.baseUrl``
98+
- string
99+
- |url| to your |application| including the |fqdn| and port
100+
number.
101+
102+
.. note::
103+
104+
You may use |cloud-short| for the ``data.baseUrl`` value.
105+
106+
- ``https://ops.example.com:8443``

‎source/includes/list-table-requiressl-modes.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. list-table::
2+
:header-rows: 1
3+
:widths: 20 40
4+
5+
* - Value
6+
7+
- Description
8+
9+
* - ``allowSSL``
10+
11+
- Connections between servers do not use |tls|. For incoming
12+
connections, the server accepts both |tls| and
13+
non-TLS.
14+
15+
* - ``preferSSL``
16+
17+
- Connections between servers use |tls|. For incoming
18+
connections, the server accepts both |tls| and
19+
non-TLS.
20+
21+
* - ``requireSSL``
22+
23+
- The server uses and accepts only |tls| encrypted connections.

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

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -285,5 +285,18 @@ inherit:
285285
name: spec.logLevel
286286
program: _shared
287287
file: options-k8s-shared.yaml
288-
288+
---
289+
program: k8sRsConf
290+
name: spec.security.tls.enabled
291+
inherit:
292+
name: spec.security.tls.enabled
293+
program: _shared
294+
file: options-k8s-shared.yaml
295+
---
296+
program: k8sRsConf
297+
name: spec.additionalMongodConfig.net.ssl.mode
298+
inherit:
299+
name: spec.additionalMongodConfig.net.ssl.mode
300+
program: _shared
301+
file: options-k8s-shared.yaml
289302
...

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -393,5 +393,34 @@ description: |
393393
- ``WARN``
394394
- ``ERROR``
395395
- ``FATAL``
396+
---
397+
program: _shared
398+
name: spec.security.tls.enabled
399+
type: boolean
400+
directive: setting
401+
optional: true
402+
default: "``false``"
403+
description: |
404+
Encrypts communications using TLS certificates between:
405+
406+
- MongoDB hosts in a replica set or sharded cluster configuration
407+
- Clients (|mongo| shell, drivers, |compass|, and others)
408+
and the MongoDB deployment
409+
410+
By default, :setting:`net.ssl.mode` is set to ``requireSSL``. To change the
411+
|tls| mode used for client and database connections, see
412+
:setting:`spec.additionalMongodConfig.net.ssl.mode`.
413+
---
414+
program: _shared
415+
name: spec.additionalMongodConfig.net.ssl.mode
416+
type: string
417+
directive: setting
418+
optional: true
419+
default: "``requireSSL``"
420+
description: |
421+
Specifies which :setting:`sslMode` is used for network connections.
422+
The following are valid options:
423+
424+
.. include:: /includes/list-table-requiressl-modes.rst
396425
397426
...

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

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: "Create a ConfigMap for the Certificate Authority certificate."
3+
level: 1
4+
ref: create-configmap-ca
5+
content: |
6+
The |k8s-op-short| requires the root |certauth| certificate of the
7+
Certificate Authority that issued the |mms| host's certificate. Run
8+
the following command to create a |k8s-configmap| containing the root
9+
CA certificate in the same namespace of your database pods:
10+
11+
.. code-block:: sh
12+
13+
kubectl -n <namespace> create configmap <root-ca-configmap-name> \
14+
--from-file=mms-ca.crt
15+
16+
.. important::
17+
18+
The |k8s-op-short| requires that the certificate is named
19+
``mms-ca.crt`` in the ConfigMap.
20+
21+
---
22+
title: "Copy the following example ``ConfigMap``."
23+
stepnum: 2
24+
level: 4
25+
ref: copy-k8s-configmap-tls
26+
content: |
27+
28+
.. literalinclude:: /reference/k8s/example-configmap-tls.yaml
29+
:language: yaml
30+
:emphasize-lines: 5-6,8-10,12-13
31+
32+
---
33+
stepnum: 3
34+
level: 4
35+
ref: paste-k8s-configmap-tls
36+
source:
37+
file: steps-create-k8s-configmap.yaml
38+
ref: paste-k8s-configmap
39+
---
40+
stepnum: 4
41+
level: 4
42+
ref: configure-k8s-configmap-tls
43+
source:
44+
file: steps-create-k8s-configmap.yaml
45+
ref: configure-k8s-configmap
46+
---
47+
title: "Specify the TLS settings"
48+
level: 5
49+
ref: configure-project-tls
50+
content: |
51+
Change the following |tls| keys:
52+
53+
.. list-table::
54+
:widths: 25 25 25 25
55+
:header-rows: 1
56+
57+
* - Key
58+
- Type
59+
- Description
60+
- Example
61+
62+
* - ``sslMMSCAConfigMap``
63+
- string
64+
- Name of the |k8s-configmap| created in the first step
65+
containing the Root |certauth| certificate used to sign the |onprem|
66+
host's certificate. This mounts the CA certificate to the
67+
|k8s-op-short| and database resources.
68+
- ``my-root-ca``
69+
70+
* - ``sslRequireValidMMSServerCertificates``
71+
- boolean
72+
- Forces the Operator to require a valid |tls| certificate
73+
from |mms|.
74+
75+
.. important::
76+
77+
The value must be enclosed in single quotes or the operator
78+
will throw an error.
79+
80+
- ``'true'``
81+
---
82+
stepnum: 6
83+
level: 4
84+
ref: save-k8s-configmap-tls
85+
source:
86+
file: steps-create-k8s-configmap.yaml
87+
ref: save-k8s-configmap
88+
---
89+
stepnum: 7
90+
level: 4
91+
ref: create-k8s-configmap-tls
92+
source:
93+
file: steps-create-k8s-configmap.yaml
94+
ref: create-k8s-configmap
95+
---
96+
stepnum: 8
97+
level: 4
98+
ref: verify-k8s-configmap-tls
99+
source:
100+
file: steps-create-k8s-configmap.yaml
101+
ref: verify-k8s-configmap
102+
...

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

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: "Copy the following example ConfigMap."
3+
stepnum: 1
4+
level: 4
5+
ref: copy-k8s-configmap
6+
content: |
7+
8+
.. literalinclude:: /reference/k8s/example-configmap.yaml
9+
:language: yaml
10+
:emphasize-lines: 5-6, 8-10
11+
---
12+
title: "Open your preferred text editor and paste the example |k8s-configmap| into a new text file."
13+
stepnum: 2
14+
level: 4
15+
ref: paste-k8s-configmap
16+
---
17+
title: "Change the highlighted four lines."
18+
stepnum: 3
19+
level: 4
20+
ref: configure-k8s-configmap
21+
content: |
22+
.. include:: /includes/list-table-configmap-keys.rst
23+
---
24+
title: "Save this file with a ``.yaml`` file extension."
25+
stepnum: 4
26+
level: 4
27+
ref: save-k8s-configmap
28+
---
29+
title: "Invoke the |k8s| command to create your |k8s-configmap|."
30+
stepnum: 5
31+
level: 4
32+
ref: create-k8s-configmap
33+
content: |
34+
.. code-block:: sh
35+
36+
kubectl apply -f <myconfigmap.yaml>
37+
38+
.. important::
39+
40+
All subsequent ``kubectl`` commands you invoke must add the
41+
``-n`` option with the :setting:`metadata.namespace` you
42+
specified in your |k8s-configmap|.
43+
---
44+
title: "Invoke the |k8s| command to verify your |k8s-configmap|."
45+
stepnum: 6
46+
level: 4
47+
ref: verify-k8s-configmap
48+
content: |
49+
.. code-block:: sh
50+
51+
kubectl describe configmaps <myconfigmap> -n <metadata.namespace>
52+
53+
.. admonition:: *Always include the namespace option with* ``kubectl``
54+
:class: important
55+
56+
|kubectl| defaults to an empty namespace if you do not specify
57+
the ``-n`` option, resulting in deployment failures. You must
58+
specify the value of the ``<metadata.namespace>`` field.
59+
The |k8s-op-short|, |k8s-secret|, and |k8s-mdbrsc|\s should
60+
run in the same unique namespace.
61+
62+
This command returns a ConfigMap description in the shell:
63+
64+
.. code-block:: sh
65+
66+
Name: <myconfigmap>
67+
Namespace: <metadata.namespace>
68+
Labels: <none>
69+
Annotations: <none>
70+
...

0 commit comments

Comments
 (0)