Skip to content

Commit 800b5a6

Browse files
davidhou17jwilliams-mongo
davidhou17
authored and
jwilliams-mongo
committed
(DOCSP-24201): Move Production Notes to other parts of the documentation (#1432)
* Move prod notes to considerations and create security section * copy review feedback * Update considerations page order * copy review {cont.) * tech review feedback
1 parent 2e85967 commit 800b5a6

16 files changed

+945
-858
lines changed

‎config/redirects

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,7 @@ raw: docs/kubernetes-operator/release-notes -> ${base}/stable/release-notes/
109109

110110
[*-v1.18]: docs/kubernetes-operator/${version}/openshift-tutorials -> ${base}/
111111
[*-v1.18]: docs/kubernetes-operator/${version}/restricted-network-tutorial -> ${base}/
112+
113+
# Add redirect for production notes refactor
114+
115+
[v1.19-*]: docs/kubernetes-operator/${version}/reference/production-notes -> ${base}/stable/tutorial/plan-k8s-op-considerations

‎source/authentication.txt

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
.. _k8s-authentication:
2+
3+
=====================
4+
Enable Authentication
5+
=====================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
The |k8s-op-short| supports :ref:`X.509 <create-x509-certs>`, LDAP,
16+
and :ref:`SCRAM <add-db-user-scram>` user authentication.
17+
18+
.. note::
19+
For LDAP configuration, see the
20+
:setting:`spec.security.authentication.ldap.automationLdapGroupDN`
21+
setting.
22+
23+
You must create an additional |k8s-crd| for your
24+
MongoDB users and the {+mdbagent+} instances.
25+
The |k8s-op-short| generates and distributes the certificate.
26+
27+
See the full X.509 certificates configuration examples in the
28+
:github:`x509 Authentication
29+
</mongodb/mongodb-enterprise-kubernetes/tree/master/samples/mongodb/authentication/x509>` directory in
30+
the :github:`Authentication </mongodb/mongodb-enterprise-kubernetes/tree/master/samples/mongodb/authentication>`
31+
samples directory. This directory also contains sample LDAP and SCRAM configurations.
32+
33+
Example Deployment CRD
34+
----------------------
35+
36+
.. code-block:: yaml
37+
:copyable: false
38+
:emphasize-lines: 14-17
39+
:linenos:
40+
41+
apiVersion: mongodb.com/v1
42+
kind: MongoDB
43+
metadata:
44+
name: my-tls-enabled-rs
45+
spec:
46+
type: ReplicaSet
47+
members: 3
48+
version: "4.0.4-ent"
49+
project: my-project
50+
credentials: my-credentials
51+
security:
52+
tls:
53+
enabled: true
54+
authentication:
55+
enabled: true
56+
modes: ["X509"]
57+
internalCluster: "X509"
58+
59+
Example User CRD
60+
----------------
61+
62+
.. code-block:: yaml
63+
:copyable: false
64+
:linenos:
65+
66+
apiVersion: mongodb.com/v1
67+
kind: MongoDBUser
68+
metadata:
69+
name: user-with-roles
70+
spec:
71+
username: "CN=mms-user-1,OU=cloud,O=MongoDB,L=New York,ST=New York,C=US"
72+
db: "$external"
73+
project: my-project
74+
roles:
75+
- db: "admin"
76+
name: "clusterAdmin"
77+
78+
.. seealso::
79+
80+
- :ref:`mongodbuser-specification`
81+
- :setting:`spec.security.authentication.ldap.automationLdapGroupDN`
82+
- :ref:`Manage Database Users Using X.509 Authentication <create-x509-certs>`
83+
- :ref:`Manage Database Users Using SCRAM Authentication <add-db-user-scram>`

‎source/encryption.txt

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
.. _k8s-encryption:
2+
3+
====================
4+
Configure Encryption
5+
====================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Enable HTTPS
16+
------------
17+
18+
The |k8s-op-short| supports configuring |onprem| to run over
19+
:ref:`HTTPS <config-https>`.
20+
21+
Enable |https| before deploying your |onprem| resources to avoid a situation
22+
where the |k8s-op-short| reports your resources' status as ``Failed``.
23+
24+
.. seealso::
25+
26+
- :ref:`https-enablement-issues`
27+
28+
Enable TLS
29+
----------
30+
31+
The |k8s-op-short| supports |tls| encryption.
32+
Use |tls| with your MongoDB deployment to encrypt your data over
33+
the network.
34+
35+
The configuration in the following example enables |tls| for the replica
36+
set. When |tls| is enabled, all traffic between members of the replica
37+
set and clients is encrypted using |tls| certificates.
38+
39+
To learn more about securing your MongoDB deployments using |tls|, see
40+
:ref:`secure-tls`.
41+
42+
The default |tls| mode is ``requireTLS``. You can customize it using the
43+
:setting:`spec.additionalMongodConfig.net.ssl.mode` configuration
44+
parameter, as shown in the following abbreviated example.
45+
46+
.. code-block:: yaml
47+
:copyable: false
48+
:emphasize-lines: 15-18,21-24
49+
:linenos:
50+
51+
apiVersion: mongodb.com/v1
52+
kind: MongoDB
53+
metadata:
54+
name: my-tls-enabled-rs
55+
spec:
56+
type: ReplicaSet
57+
members: 3
58+
version: 4.4.0-ent
59+
60+
opsManager:
61+
configMapRef:
62+
name: my-project
63+
credentials: my-credentials
64+
65+
security:
66+
tls:
67+
enabled: true
68+
ca: <custom-ca>
69+
70+
...
71+
additionalMongodConfig:
72+
net:
73+
ssl:
74+
mode: "preferSSL"
75+
76+
See the full |tls| configuration example in
77+
:github:`replica-set.yaml </mongodb/mongodb-enterprise-kubernetes/tree/master/samples/mongodb/tls/replica-set>`
78+
in the :github:`TLS </mongodb/mongodb-enterprise-kubernetes/tree/master/samples/mongodb/tls>`
79+
samples directory. This directory also contains sample |tls| configurations for
80+
sharded clusters and standalone deployments.

‎source/includes/facts/fact-readiness-probe-override.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
If you create custom services that require external access to MongoDB custom
2+
resources deployed by the |k8s-op-short| and use readiness probes
3+
in |k8s|, set the ``publishNotReadyAddresses`` setting in |k8s| to ``true``.
4+
5+
The ``publishNotReadyAddresses`` setting indicates that an agent that
6+
interacts with endpoints for this service should disregard the service's
7+
:k8sdocs:`ready </concepts/services-networking/endpoint-slices/#ready>`
8+
state. Setting ``publishNotReadyAddresses`` to ``true`` overrides the
9+
behavior of the readiness probe configured for the Pod hosting your service.
10+
11+
By default, the ``publishNotReadyAddresses`` setting is set to ``false``.
12+
In this case, when the Pods that host the MongoDB custom resources in the
13+
|k8s-op-short| lose connectivity to |cloud-short| or |onprem|, the
14+
readiness probes configured for these Pods fail.
15+
However, when you set the ``publishNotReadyAddresses`` setting to ``true``:
16+
17+
- |k8s| does not shut down the service whose readiness probe fails.
18+
- |k8s| considers all endpoints as :k8sdocs:`ready </concepts/services-networking/endpoint-slices/#ready>`
19+
even if the probes for the Pods hosting the services for these endpoints
20+
indicate that they aren't ready.
21+
- MongoDB custom resources are still available for read and write operations.
22+
23+
.. seealso::
24+
25+
- |k8s-api-ref| and search for ``publishNotReadyAddresses``
26+
- :k8sdocs:`DNS for Services in Pods </concepts/services-networking/dns-pod-service/>`
27+
- :k8sdocs:`Configure Readiness Probes </tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes>`

‎source/includes/list-tables/default-k8s-object-permissions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
:header-rows: 1
44

55
* - Kubernetes Resources
6-
- Verbs
6+
- API Verbs
77

88
* - Configmaps
99
- Require the following permissions:

‎source/index.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ optimal performance.
5252
Quick Start </kind-quick-start>
5353
OpenShift Tutorials </openshift-tutorials>
5454
Kubernetes Operator Architecture </tutorial/plan-k8s-op-architecture>
55+
Security </security>
5556
Install the Operator </installation>
5657
Deploy Ops Manager Resources </om-resources>
5758
Deploy MongoDB Database Resources </mdb-resources>
@@ -60,7 +61,6 @@ optimal performance.
6061
/reference
6162
FAQ </faq.txt>
6263
Release Notes </release-notes>
63-
Production Notes </reference/production-notes>
6464
/reference/troubleshooting
6565
Known Issues </reference/known-issues>
6666
MongoDB Community Kubernetes Operator <https://github.com/mongodb/mongodb-kubernetes-operator>

‎source/opa-gatekeeper.txt

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
2+
.. _OPA-gatekeeper:
3+
.. _k8s-gatekeeper:
4+
5+
=============================
6+
Apply OPA Gatekeeper Policies
7+
=============================
8+
9+
.. default-domain:: mongodb
10+
11+
.. contents:: On this page
12+
:local:
13+
:backlinks: none
14+
:depth: 1
15+
:class: singlecol
16+
17+
To control, audit, and debug your production deployments, you can use policies
18+
for the `Gatekeeper <https://github.com/open-policy-agent/gatekeeper>`__
19+
Open Policy Agent (OPA). Gatekeeper contains |k8s-crds| for creating and extending
20+
deployment constraints through the
21+
:gatekeeper:`constraint templates </constrainttemplates/>`.
22+
23+
Control Your Deployments with Gatekeeper Policies
24+
-------------------------------------------------
25+
26+
The |k8s-op-short| offers a :ref:`list of Gatekeeper policies <gatekeeper-policies-list>`
27+
that you can customize and apply to your deployments.
28+
29+
Each Gatekeeper policy consists of:
30+
31+
- ``<policy_name>.yaml`` file
32+
- ``constraints.yaml`` file that is based on the :gatekeeper:`constraint template </constrainttemplates/>`
33+
34+
You can use binary and configurable Gatekeeper policies:
35+
36+
- Binary policies allow or prevent specific configurations, such as
37+
preventing deployments that don't use TLS, or deploying only specific
38+
MongoDB or |onprem| versions.
39+
40+
- Configurable policies allow you to specify configurations, such as the
41+
total number of replica sets that will be deployed for a specific
42+
MongoDB or |onprem| custom resource.
43+
44+
To use and apply Gatekeeper sample policies with the |k8s-op-short|:
45+
46+
1. :gatekeeper:`Install the OPA Gatekeeper </install/>` on your Kubernetes cluster.
47+
48+
2. Review the list of available constraint templates and constraints:
49+
50+
.. code-block:: sh
51+
52+
kubectl get constrainttemplates
53+
kubectl get constraints
54+
55+
3. Navigate to the policy directory, select a policy from the list and
56+
apply it and its constraints file:
57+
58+
.. code-block:: sh
59+
60+
cd <policy_directory>
61+
kubectl apply -f <policy_name>.yaml
62+
kubectl apply -f constraints.yaml
63+
64+
4. Review the Gatekeeper policies that are currently applied:
65+
66+
.. code-block:: sh
67+
68+
kubectl get constrainttemplates
69+
kubectl get contstraints
70+
71+
.. _gatekeeper-policies-list:
72+
73+
List of Sample OPA Gatekeeper Policies
74+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75+
76+
The |k8s-op-short| offers the following sample policies in this
77+
:github:`OPA examples </mongodb/mongodb-enterprise-kubernetes/tree/master/opa_examples>`
78+
GitHub directory:
79+
80+
.. list-table::
81+
:widths: 40 60
82+
:header-rows: 1
83+
84+
* - Location
85+
- Policy Description
86+
87+
* - :github:`Debugging </mongodb/mongodb-enterprise-kubernetes/tree/master/opa_examples/debugging>`
88+
- Blocks all MongoDB and |onprem| resources. This allows you to use
89+
the log output to craft your own policies. To learn more, see
90+
:gatekeeper:`Gatekeeper Debugging </debug/>`.
91+
92+
* - :github:`mongodb_allow_replicaset </mongodb/mongodb-enterprise-kubernetes/tree/master/opa_examples/mongodb_allow_replicaset>`
93+
- Allows deploying only replica sets for MongoDB resources and
94+
prevents deploying sharded clusters.
95+
96+
* - :github:`mongodb_allowed_versions </mongodb/mongodb-enterprise-kubernetes/tree/master/opa_examples/mongodb_allowed_versions>`
97+
- Allows deploying only specific MongoDB versions.
98+
99+
* - :github:`ops_manager_allowed_versions </mongodb-enterprise-kubernetes/tree/master/opa_examples/ops_manager_allowed_versions>`
100+
- Allows deploying only specific |onprem| versions.
101+
102+
* - :github:`mongodb_strict_tls </10gen/mongodb-enterprise-kubernetes/tree/master/opa_examples/mongodb_strict_tls>`
103+
- Allows using strict TLS mode for MongoDB deployments.
104+
105+
* - :github:`ops_manager_replica_members </10gen/mongodb-enterprise-kubernetes/tree/master/opa_examples/ops_manager_replica_members>`
106+
- Allows deploying a specified number of |onprem| replica set and
107+
Application Database members.
108+
109+
* - :github:`ops_manager_wizardless </10gen/mongodb-enterprise-kubernetes/tree/master/opa_examples/ops_manager_wizardless>`
110+
- Allows installing |onprem| in a non-interactive mode.

‎source/permissions.txt

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.. _k8s-permissions:
2+
3+
==================
4+
Verify Permissions
5+
==================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Objects in the |k8s-op-short| configuration use
16+
default permissions. These are the minimum
17+
permissions for the |k8s-op-short| to deploy and manage |onprem|
18+
and MongoDB resources in a |k8s| cluster.
19+
20+
Default Permissions for Kubernetes Operator Objects
21+
---------------------------------------------------
22+
23+
Use the following chart to verify that the
24+
objects in your |k8s-op-short| configuration have access to the
25+
required |k8s| :k8sdocs:`API verbs </reference/using-api/api-concepts/#api-verbs>`:
26+
27+
.. include:: /includes/list-tables/default-k8s-object-permissions.rst

0 commit comments

Comments
 (0)