Skip to content

Commit 814ee27

Browse files
jwilliams-mongojwilliams-mongo
authored
(DOCSP-11114): OM arch in k8s (#426)
* (DOCSP-11114): OM arch in k8s * (DOCSP-11114): copy review feedback * (DOCSP-11114): replace stale build * (DOCSP-11114): tech review feedback * (DOCSP-11114): tech review feedback pt 2 * (DOCSP-11114): add redirects
1 parent b54ed8c commit 814ee27

File tree

8 files changed

+235
-36
lines changed

8 files changed

+235
-36
lines changed

‎conf.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -134,8 +134,8 @@
134134
'.. |k8s-crb| replace:: `ClusterRoleBinding <https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding>`__',
135135
'.. |k8s-configmaps| replace:: `ConfigMaps <https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/>`__',
136136
'.. |k8s-configmap| replace:: `ConfigMap <https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/>`__',
137-
'.. |k8s-custom-resource| replace:: `Custom Resource <https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/>`__',
138-
'.. |k8s-custom-resources| replace:: `Custom Resources <https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/>`__',
137+
'.. |k8s-custom-resource| replace:: `custom resource <https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/>`__',
138+
'.. |k8s-custom-resources| replace:: `custom resources <https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/>`__',
139139
'.. |k8s-crds| replace:: `CustomResourceDefinitions <https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/>`__',
140140
'.. |k8s-crd| replace:: `CustomResourceDefinition <https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/>`__',
141141
'.. |k8s-mdbrscs| replace:: MongoDB Kubernetes resources',
@@ -159,6 +159,7 @@
159159
'.. |k8s-sc| replace:: `StorageClass <https://kubernetes.io/docs/concepts/storage/storage-classes/>`__',
160160
'.. |k8s-secrets| replace:: `secrets <https://kubernetes.io/docs/concepts/configuration/secret/>`__',
161161
'.. |k8s-secret| replace:: `secret <https://kubernetes.io/docs/concepts/configuration/secret/>`__',
162+
'.. |k8s-service| replace:: `service <https://kubernetes.io/docs/concepts/services-networking/service/>`__',
162163
'.. |k8s-statefulsets| replace:: `StatefulSets <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`__',
163164
'.. |k8s-statefulset| replace:: `StatefulSet <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`__',
164165
'.. |k8s-webhook| replace:: `Webhook <https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#what-are-admission-webhooks>`__',

‎config/redirects

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ raw: kubernetes-operator/release-notes -> ${base}/stable/release-notes
5252
[*-v1.3]: kubernetes-operator/${version}/tutorial/plan-k8s-operator-install -> ${base}/${version}/tutorial/install-k8s-operator
5353
[*-v1.3]: kubernetes-operator/${version}/tutorial/modify-resource-image -> ${base}/${version}/
5454

55+
# v1.6 and earlier:
56+
[*-v1.6]: kubernetes-operator/${version}/tutorial/om-arch -> ${base}/${version}/tutorial/plan-om-resource
57+
5558
# v1.7 and later
5659
[v1.7-*]: kubernetes-operator/${version}/tutorial/upgrade-k8s-operator-v9-and-earlier -> ${base}/${version}/tutorial/upgrade-k8s-operator-v161-and-earlier
5760

‎source/images/meko-arch.svg

Lines changed: 1 addition & 0 deletions
Loading

‎source/images/meko-reconciliation.svg

Lines changed: 1 addition & 0 deletions
Loading

‎source/om-resources.txt

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,11 @@ Deploy and Configure Ops Manager Resources
88

99
.. include:: /includes/styles/corrections.rst
1010

11+
:ref:`meko-om-arch`
12+
Review the |onprem| resource architecture.
13+
1114
:ref:`plan-om-resource`
12-
Review the |onprem| resource architecture, considerations, and
15+
Review the |onprem| resource considerations and
1316
prerequisites.
1417

1518
:ref:`deploy-om-container`
@@ -37,6 +40,7 @@ Deploy and Configure Ops Manager Resources
3740
.. toctree::
3841
:titlesonly:
3942

43+
/tutorial/om-arch
4044
/tutorial/plan-om-resource
4145
/tutorial/deploy-om-container
4246
/tutorial/deploy-om-container-remote-mode

‎source/reference/helm-operator-settings.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ operator.watchedResources
144144
operator:
145145
watchedResources:
146146
- mongodbusers
147-
- mongodb
147+
- mongodb
148148
- opsmanagers
149149

150150
registry.appDb

‎source/tutorial/om-arch.txt

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
.. _meko-om-arch:
2+
3+
==============================
4+
|onprem| Architecture in |k8s|
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+
You can use the |k8s-op-short| to deploy |onprem| and MongoDB resources
16+
to a |k8s| cluster. The |k8s-op-short| manages the lifecycle of each of
17+
these deployments differently.
18+
19+
The ``MongoDBOpsManager`` Custom Resource Definition
20+
----------------------------------------------------
21+
22+
The |k8s-op-short| manages |onprem| deployments using the
23+
``MongoDBOpsManager`` |k8s-custom-resource|. The |k8s-op-short| watches
24+
the custom resource's specification for changes. When the
25+
specification changes, the |k8s-op-short| validates the changes and
26+
makes the appropriate updates to the resources in the |k8s| cluster.
27+
28+
``MongoDBOpsManager`` |k8s-custom-resource|\s specification defines the
29+
following |onprem| components:
30+
31+
- the Application Database,
32+
- the |onprem| application, and
33+
- the Backup Daemon.
34+
35+
.. figure:: /images/meko-arch.svg
36+
:alt: Diagram showing the high-level architecture of the MongoDB
37+
Enterprise Kubernetes Operator
38+
:figwidth: 600px
39+
40+
Application Database
41+
~~~~~~~~~~~~~~~~~~~~
42+
43+
For the Application Database, the |k8s-op-short| deploys a MongoDB
44+
replica set as a |k8s-statefulset| to the |k8s| cluster. |k8s| creates
45+
one Pod in the StatefulSet for each member
46+
that comprises your Application Database replica set. Each Pod in
47+
the StatefulSet runs a {+mdbagent+} instance.
48+
49+
By default, each {+mdbagent+} starts the bundled |mongod| on its
50+
Pod in the StatefulSet. If you want to use a specific MongoDB Server
51+
version for the Application Database instead, specify the version that
52+
you want to start using the :opsmgrkube:`spec.applicationDatabase.version`
53+
setting. Each {+mdbagent+} downloads the |mongod| version you
54+
specify from the Internet and starts it on its Pod in the StatefulSet.
55+
56+
After each {+mdbagent+} starts |mongod|\s on its Application Database
57+
Pod, the {+mdbagent+}\s add all |mongod| processes to the Application
58+
Database replica set.
59+
60+
You configure the number of replicas in and other
61+
configuration options for the Application Database replica set in the
62+
:opsmgrkube:`spec.applicationDatabase` collection in the
63+
``MongoDBOpsManager`` custom resource. The |k8s-op-short| passes
64+
this configuration to the {+mdbagent+}\s using a |k8s-secret| that the
65+
|k8s-op-short| mounts to each Pod in the Application Database StatefulSet.
66+
67+
Each time that you update
68+
the :opsmgrkube:`spec.applicationDatabase` collection, the
69+
|k8s-op-short| applies the changes to the {+mdbagent+} configuration and
70+
the StatefulSet specification, if applicable. If the StatefulSet
71+
specification changes, |k8s| upgrades the Pods in a rolling
72+
fashion and restarts each Pod.
73+
74+
The |k8s-op-short| creates a |k8s-service| with ``clusterIp=none`` to
75+
provide connectivity to each Application Database Pod from within the
76+
|k8s| cluster.
77+
78+
If you set :opsmgrkube:`spec.applicationDatabase.persistent` to
79+
**true**, the |k8s-op-short| creates a |k8s-pvc| for each Pod in the
80+
Application Database StatefulSet.
81+
82+
.. note::
83+
84+
Depending on the |k8s-sc| or the environment to which you deploy the
85+
|k8s-op-short|, |k8s| might create the |k8s-pvs| using
86+
:k8sdocs:`dynamic volume provisioning </concepts/storage/dynamic-provisioning/>`.
87+
88+
You can customize the |k8s-pvcs| for the Application Database Pods using
89+
the :opsmgrkube:`spec.applicationDatabase.podSpec.persistence.single
90+
<spec.applicationDatabase>` or
91+
:opsmgrkube:`spec.applicationDatabase.podSpec.persistence.multiple
92+
<spec.applicationDatabase>` options.
93+
94+
|application|
95+
~~~~~~~~~~~~~
96+
97+
After the Application Database reaches a **Running** state, the
98+
|k8s-op-short| starts the |application|. For |onprem|, the
99+
|k8s-op-short| deploys a StatefulSet to the |k8s| cluster. |k8s|
100+
creates one Pod in the StatefulSet for each |onprem| replica that
101+
you want to deploy. Each Pod contains one |application| process.
102+
103+
.. note::
104+
105+
:ref:`Deploy <deploy-om-container>` multiple |onprem| replicas to
106+
make your deployment highly available in the event of an |onprem| Pod
107+
failure.
108+
109+
The |k8s-op-short| creates a |k8s-service| with ``clusterIp=none`` to
110+
allow clients deployed to the |k8s| cluster to connect to |onprem|. To
111+
allow clients external to the |k8s| cluster to connect to |onprem|,
112+
configure the :opsmgrkube:`spec.externalConnectivity` collection in the
113+
specification for your |onprem| deployment.
114+
115+
Backup Daemon
116+
~~~~~~~~~~~~~
117+
118+
If :opsmgrkube:`spec.backup.enabled` is **true**, the |k8s-op-short|
119+
starts the Backup Daemon after the |application| reaches a **Running**
120+
stage. For the Backup Daemon, |k8s-op-short| deploys a StatefulSet
121+
to the |k8s| cluster. |k8s| creates one pod in the
122+
StatefulSet for the Backup Daemon.
123+
124+
If you enable backup, you must provide additional fields in the
125+
:opsmgrkube:`spec.backup <spec.backup.enabled>` collection to configure:
126+
the :term:`oplog store <oplog store database>` and a :term:`blockstore
127+
<Backup Blockstore Database>` or an |s3| :term:`snapshot store <S3
128+
Snapshot Store>`.
129+
130+
If you enable backup, the |k8s-op-short| creates a |k8s-pvc| for the
131+
Backup Daemon's :term:`head database`. You can
132+
configure the head database using the :opsmgrkube:`spec.backup.headDB`
133+
setting.
134+
135+
The |k8s-op-short| invokes |onprem| APIs to ensure that the
136+
|application|\'s backup configuration matches the one that you define in
137+
the custom resource definition.
138+
139+
Reconciling the ``MongoDBOpsManager`` Custom Resource
140+
-----------------------------------------------------
141+
142+
The following diagram describes how the |k8s-op-short| reconciles
143+
changes to the ``MongoDBOpsManager`` |k8s-crd|.
144+
145+
.. figure:: /images/meko-reconciliation.svg
146+
:alt: Diagram describing how the MongoDB Enterprise Kubernetes
147+
Operator reconciles changes to the MongoDBOpsManager
148+
Custom Resource Definition
149+
:figwidth: 600px
150+
151+
1. The |k8s-op-short| creates or updates the
152+
``<om_resource_name>-db-config`` Secret. This secret contains
153+
the configurations that the {+mdbagent+} uses to start the
154+
Application Database replica set.
155+
156+
2. The |k8s-op-short| creates or updates the ``<om_resource_name>-db``
157+
Application Database StatefulSet. This StatefulSet contains at
158+
least three |k8s-pods|.
159+
160+
- Each Pod runs one {+mdbagent+} instance. Each {+mdbagent+} starts a
161+
|mongod| instance on its pod.
162+
- The |k8s-op-short| mounts the ``<om_resource_name>-db-config``
163+
Secret to each Pod. The {+mdbagent+} uses this secret to
164+
configure the Application Database replica set.
165+
166+
3. The |k8s-op-short| creates or updates the ``<om_resource_name>``
167+
StatefulSet. This StatefulSet contains one Pod for each
168+
|onprem| replica. Each |onprem| replica connects to the Application
169+
Database.
170+
171+
.. note::
172+
173+
Most changes to the ``MongoDBOpsManager`` |k8s-custom-resource|
174+
trigger a rolling upgrade of the Pods in the
175+
``<om_resource_name>`` StatefulSet. :ref:`Enabling TLS for the
176+
Application Database <secure-om-db-tls>` also triggers a rolling
177+
restart because the connection string to the Application Database
178+
changes.
179+
180+
Changes to the following ``MongoDBOpsManager``
181+
|k8s-custom-resource| collections don't trigger a rolling upgrade:
182+
183+
- :opsmgrkube:`spec.backup <spec.backup.enabled>`
184+
- :opsmgrkube:`spec.applicationDatabase`
185+
186+
4. The |k8s-op-short| invokes |onprem| APIs to create an admin user.
187+
The |k8s-op-short| saves this admin user's credentials in the
188+
``<om_resource_name>-admin-key`` Secret. The |k8s-op-short|
189+
uses these credentials for all other |onprem| API invocations.
190+
191+
.. note::
192+
193+
This reconciliation step happens only once: when you use the
194+
|k8s-op-short| to create an |onprem| resource. The
195+
|k8s-op-short| skips this step when it updates the resource.
196+
197+
5. The |k8s-op-short| performs a rolling upgrade of the Pods in the
198+
``<om_resource_name>-db`` Application Database StatefulSet
199+
to enable |onprem| to monitor it.
200+
201+
.. note::
202+
203+
This reconciliation step happens only when you enable Monitoring
204+
for an application database for the first time. This happens most
205+
often when you deploy a new |onprem| resource.
206+
207+
6. If :opsmgrkube:`spec.backup.enabled` is **true**, the |k8s-op-short|
208+
creates the ``<om_resource_name>-backup-daemon`` StatefulSet or
209+
verifies that it is running. The |k8s-op-short| mounts a |k8s-pv| for
210+
the head database.
211+
212+
.. note::
213+
214+
The Backup Daemon connects to the same Application Database as the
215+
|onprem| deployment.
216+
217+
7. If :opsmgrkube:`spec.backup.enabled` is **true**, the |k8s-op-short|
218+
invokes |onprem| APIs to ensure that the |application|\'s backup
219+
configuration matches the one that you define in the custom resource
220+
definition.

‎source/tutorial/plan-om-resource.txt

Lines changed: 1 addition & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -28,38 +28,7 @@ the :ref:`prerequisites <om-rsrc-prereqs>`.
2828
Architecture
2929
------------
3030

31-
The |k8s-op-short| manages and monitors each ``MongoDBOpsManager``
32-
:k8sdocs:`custom resource
33-
</concepts/extend-kubernetes/api-extension/custom-resources/>` through
34-
a :ref:`resource definition file <k8s-om-specification>` that you
35-
:ref:`create <deploy-om-container>`. Every time you create or update a
36-
resource definition, the |k8s-op-short| performs the following
37-
reconciliation process:
38-
39-
1. The |k8s-op-short| creates or updates the |k8s-statefulset| that
40-
runs the :ref:`mms-application-database`. The Application Database
41-
is always deployed as a :ref:`replica-set <app-db-topology>` with
42-
:ref:`SCRAM-SHA authentication <app-db-auth>` enabled. Each database
43-
|k8s-pod| runs an instance of the MongoDB Agent which is configured
44-
directly by the |k8s-op-short|.
45-
46-
#. The |k8s-op-short| creates or updates the |k8s-statefulset| that
47-
runs the |onprem| |k8s-pods|. The |onprem| instance connects to the
48-
Application Database.
49-
50-
#. The |k8s-op-short| ensures the |k8s-statefulset| for the
51-
:ref:`backup-daemon` is running unless :ref:`backup
52-
<om-rsrc-backup>` is disabled. The |k8s-statefulset| consists of a
53-
single |k8s-pod|. The Backup Daemon connects to the Application
54-
Database.
55-
56-
#. The |k8s-op-short| registers the :ref:`first user <om-first-user>`
57-
with the :authrole:`Global Owner` role and saves a public API key to a secret for later use.
58-
59-
#. The |k8s-op-short| configures the Backup Daemon using
60-
|onprem| |api| according to the :opsmgrkube:`spec.backup.enabled`
61-
specification in the |onprem| :ref:`resource definition
62-
<k8s-om-specification>`.
31+
For |onprem| resource architecture details, see :ref:`meko-om-arch`.
6332

6433
.. _om-rsrc-considerations:
6534

0 commit comments

Comments
 (0)