Skip to content

Commit df5f32f

Browse files
jvincent-mongodbjvincent-mongodb
authored
DOCSP-5680 -- Topology and Specific Storage Tutorial (#1630)
* DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 -- wip * DOCSP-5680 add full affinity example * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- divide steps into seperate headings * DOCSP-5680 -- group review feedback revisions * DOCSP-5680 -- group review feedback revisions * DOCSP-5680 -- group review feedback revisions * DOCSP-5680 -- group review feedback revisions * DOCSP-5680 -- group review feedback revisions * DOCSP-5680 -- group review feedback revisions * DOCSP-5680 -- group review feedback revisions * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- refactor into two tutorials * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- add settings pages * DOCSP-5680 -- add settings pages * DOCSP-5680 -- add settings pages * DOCSP-5680 -- add include directives * DOCSP-5680 -- add include directives * DOCSP-5680 -- add include directives * DOCSP-5680 -- add include directives * DOCSP-5680 -- add include directives * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- fix table rows * DOCSP-5680 -- remove table * DOCSP-5680 -- fix includes indentation * DOCSP-5680 -- fix indentation * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * DOCSP-5680 -- copy review revisions * Update snooty.toml * DOCSP-5680 -- remove paragraph that moved to second tutorial
1 parent eab3453 commit df5f32f

12 files changed

+356
-0
lines changed

‎snooty.toml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,7 @@ kdc = ":abbr:`KDC (Key Distribution Center)`"
171171
kind = ":abbr:`Kind (Kubernetes in Docker)`"
172172
kmip = ":abbr:`KMIP (Key Management Interoperability)`"
173173
kms = ":abbr:`KMS (Key Management Service)`"
174+
labels = "`labels <https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/>`__"
174175
ldaps = ":abbr:`LDAPS (Secure Lightweight Directory Access Protocol)`"
175176
ldap = ":abbr:`LDAP (Lightweight Directory Access Protocol)`"
176177
mms-full = ":opsmgr:`MongoDB Ops Manager </>`"
@@ -189,6 +190,8 @@ kubectl-mongodb = "``kubectl mongodb`` plugin"
189190
onprem = "Ops Manager"
190191
onprem-link = ":opsmgr:`Ops Manager </>`"
191192
nfs = ":abbr:`NFS (Network File System)`"
193+
node-labels = "`node labels <https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#built-in-node-labels>`__"
194+
node-affinity = "`node affinity <https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/>`__"
192195
ntp = ":abbr:`NTP (Network Time Protocol)`"
193196
nvme-clusters = "clusters with local NVMe SSDs"
194197
pem = ":abbr:`PEM (Privacy-Enhanced Mail)`"
@@ -229,3 +232,4 @@ utc = ":abbr:`UTC (Coordinated Universal Time)`"
229232
vault-short = "Vault"
230233
vpc = ":abbr:`VPC (Virtual Private Cloud)`"
231234
yaml = ":abbr:`YAML (Yet Another Markup Language)`"
235+

‎source/includes/code-examples/yaml-files/example-sharded-cluster.yaml

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -557,3 +557,134 @@ START-exposed-sharded-tls-lower
557557
- "additional-cert-test.com"
558558
...
559559
END-exposed-sharded-tls-lower
560+
561+
562+
START-affinity-sharded
563+
---
564+
apiVersion: mongodb.com/v1
565+
kind: MongoDB
566+
metadata:
567+
name: my-sharded-cluster
568+
spec:
569+
shardCount: 2
570+
mongodsPerShardCount: 3
571+
mongosCount: 2
572+
configServerCount: 3
573+
version: 6.0.0
574+
service: my-service
575+
576+
opsManager:
577+
configMapRef:
578+
name: my-project
579+
credentials: my-credentials
580+
type: ShardedCluster
581+
582+
persistent: true
583+
configSrvPodSpec:
584+
podTemplate:
585+
affinity:
586+
podAffinity:
587+
requiredDuringSchedulingIgnoredDuringExecution:
588+
- labelSelector:
589+
matchExpressions:
590+
- key: security
591+
operator: In
592+
values:
593+
- S1
594+
topologyKey: failure-domain.beta.kubernetes.io/zone
595+
nodeAffinity:
596+
requiredDuringSchedulingIgnoredDuringExecution:
597+
nodeSelectorTerms:
598+
- matchExpressions:
599+
- key: kubernetes.io/e2e-az-name
600+
operator: In
601+
values:
602+
- e2e-az1
603+
- e2e-az2
604+
podAntiAffinity:
605+
requiredDuringSchedulingIgnoredDuringExecution:
606+
topologyKey: nodeId
607+
mongosPodSpec:
608+
podTemplate:
609+
affinity:
610+
podAffinity:
611+
requiredDuringSchedulingIgnoredDuringExecution:
612+
- labelSelector:
613+
matchExpressions:
614+
- key: security
615+
operator: In
616+
values:
617+
- S1
618+
topologyKey: failure-domain.beta.kubernetes.io/zone
619+
nodeAffinity:
620+
requiredDuringSchedulingIgnoredDuringExecution:
621+
nodeSelectorTerms:
622+
- matchExpressions:
623+
- key: kubernetes.io/e2e-az-name
624+
operator: In
625+
values:
626+
- e2e-az1
627+
- e2e-az2
628+
podAntiAffinity:
629+
requiredDuringSchedulingIgnoredDuringExecution:
630+
topologyKey: nodeId
631+
shardPodSpec:
632+
podTemplate:
633+
affinity:
634+
podAffinity:
635+
requiredDuringSchedulingIgnoredDuringExecution:
636+
- labelSelector:
637+
matchExpressions:
638+
- key: security
639+
operator: In
640+
values:
641+
- S1
642+
topologyKey: failure-domain.beta.kubernetes.io/zone
643+
nodeAffinity:
644+
requiredDuringSchedulingIgnoredDuringExecution:
645+
nodeSelectorTerms:
646+
- matchExpressions:
647+
- key: kubernetes.io/e2e-az-name
648+
operator: In
649+
values:
650+
- e2e-az1
651+
- e2e-az2
652+
podAntiAffinity:
653+
requiredDuringSchedulingIgnoredDuringExecution:
654+
topologyKey: nodeId
655+
...
656+
END-affinity-sharded
657+
658+
START-specific-storage
659+
---
660+
apiVersion: mongodb.com/v1
661+
kind: MongoDB
662+
metadata:
663+
name: my-sharded-cluster
664+
spec:
665+
shardCount: 2
666+
mongodsPerShardCount: 3
667+
mongosCount: 2
668+
configServerCount: 3
669+
version: "6.0.0"
670+
service: my-service
671+
type: ShardedCluster
672+
673+
persistent: true
674+
675+
configSrvPodSpec:
676+
persistence:
677+
single: true
678+
679+
shardPodSpec:
680+
persistence:
681+
multiple:
682+
# if the child of "multiple" is omitted then the default size will be used.
683+
# 16GB for "data", 1GB for "journal", 3GB for "logs"
684+
data:
685+
storage: "20Gi"
686+
logs:
687+
storage: "4Gi"
688+
storageClass: standard
689+
...
690+
END-specific-storage

‎source/includes/setting-k8sSaConf-spec.podSpec.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. setting:: spec.podSpec
2+
3+
*Type*: object
4+
5+
Object that contains the specifications for the MongoDB |k8s-crd| Pods.

‎source/includes/setting-k8sScConf-spec.configSrvPodSpec.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. setting:: spec.configSrvPodSpec
2+
3+
*Type*: object
4+
5+
Object that contains the specifications for the MongoDB |k8s-crd| config server Pods.

‎source/includes/setting-k8sScConf-spec.shardPodSpec.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. setting:: spec.shardPodSpec
2+
3+
*Type*: object
4+
5+
Object that contains the specifications for the MongoDB |k8s-crd| shard Pods.

‎source/includes/setting.k8sScConf-spec.mongosPodSpec.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. setting:: spec.mongosPodSpec
2+
3+
*Type*: object
4+
5+
Object that contains the specifications for the MongoDB |k8s-crd| mongos Pods.
6+

‎source/includes/steps-configure-storage.yaml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
stepnum: 1
3+
ref: steps-configure-storeage
4+
title: "Update your MongoDB custom resource."
5+
content: |
6+
7+
Populate the ``persistence`` sections of your MongoDB CRD
8+
definition as shown in the following example:
9+
10+
.. literalinclude:: /includes/code-examples/yaml-files/example-sharded-cluster.yaml
11+
:language: yaml
12+
:start-after: START-specific-storage
13+
:end-before: END-specific-storage
14+
:linenos:
15+
16+
---
17+
stepnum: 2
18+
ref: steps-apply-configured-storage
19+
title: "Apply your changes."
20+
content: |
21+
22+
.. code-block:: sh
23+
:copyable: true
24+
25+
kubectl apply -f mongodb-crd.yaml

‎source/includes/steps-configure-topology.yaml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
stepnum: 1
3+
ref: steps-configure-topology
4+
title: "Update your MongoDB CRD manifest."
5+
content: |
6+
7+
Populate the ``podTemplate.affinity`` sections of your MongoDB Sharded Cluster
8+
definition as shown in the following example:
9+
10+
.. literalinclude:: /includes/code-examples/yaml-files/example-sharded-cluster.yaml
11+
:language: yaml
12+
:start-after: START-affinity-sharded
13+
:end-before: END-affinity-sharded
14+
:linenos:
15+
16+
---
17+
stepnum: 2
18+
ref: steps-apply-configure-topology
19+
title: "Apply your changes."
20+
content: |
21+
22+
.. code-block:: sh
23+
:copyable: true
24+
25+
kubectl apply -f mongodb-crd.yaml

‎source/mdb-resources.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,5 +48,7 @@ from the |k8s| |api|, without having to configure them in
4848
/tutorial/edit-deployment
4949
/tutorial/secure-client-connections
5050
/tutorial/back-up-mdb-resources
51+
/tutorial/configure-mongodb-cluster-topology
52+
/tutorial/configure-mongodb-specific-storage
5153
/manage-users
5254
/connect

‎source/reference/k8s-operator-specification.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ Standalone Settings
126126
.. include:: /includes/setting-k8sSaConf-spec.additionalMongodConfig.rst
127127
.. include:: /includes/setting-k8sSaConf-spec.agent.rst
128128
.. include:: /includes/setting-k8sSaConf-spec.agent.startupOptions.rst
129+
.. include:: /includes/setting-k8sSaConf-spec.podSpec.rst
129130

130131
.. _spec-external-access:
131132

@@ -257,6 +258,7 @@ The following settings apply only to sharded cluster resource types:
257258
.. include:: /includes/setting-k8sScConf-spec.configSrv.additionalMongodConfig.rst
258259
.. include:: /includes/setting-k8sScConf-spec.configSrv.agent.rst
259260
.. include:: /includes/setting-k8sScConf-spec.configSrv.agent.startupOptions.rst
261+
.. include:: /includes/setting-k8sScConf-spec.configSrvPodSpec.rst
260262
.. include:: /includes/setting-k8sScConf-spec.configSrvPodSpec.persistence.single.rst
261263
.. include:: /includes/setting-k8sScConf-spec.configSrvPodSpec.persistence.multiple.data.rst
262264
.. include:: /includes/setting-k8sScConf-spec.configSrvPodSpec.persistence.multiple.journal.rst
@@ -273,6 +275,7 @@ The following settings apply only to sharded cluster resource types:
273275
.. include:: /includes/setting-k8sScConf-spec.mongos.additionalMongodConfig.rst
274276
.. include:: /includes/setting-k8sScConf-spec.mongos.agent.rst
275277
.. include:: /includes/setting-k8sScConf-spec.mongos.agent.startupOptions.rst
278+
.. include:: /includes/setting.k8sScConf-spec.mongosPodSpec.rst
276279
.. include:: /includes/setting-k8sScConf-spec.mongosPodSpec.podTemplate.rst
277280
.. include:: /includes/setting-k8sScConf-spec.mongosPodSpec.podTemplate.affinity.podAffinity.rst
278281
.. include:: /includes/setting-k8sScConf-spec.mongosPodSpec.podTemplate.affinity.nodeAffinity.rst
@@ -284,6 +287,8 @@ The following settings apply only to sharded cluster resource types:
284287
.. include:: /includes/setting-k8sScConf-spec.shard.additionalMongodConfig.rst
285288
.. include:: /includes/setting-k8sScConf-spec.shard.agent.rst
286289
.. include:: /includes/setting-k8sScConf-spec.shard.agent.startupOptions.rst
290+
.. include:: /includes/setting-k8sScConf-spec.shardPodSpec.rst
291+
.. include:: /includes/setting-k8sScConf-spec.shardPodSpec.persistence.multiple.data.rst
287292
.. include:: /includes/setting-k8sScConf-spec.shardPodSpec.persistence.single.rst
288293
.. include:: /includes/setting-k8sScConf-spec.shardPodSpec.persistence.multiple.data.rst
289294
.. include:: /includes/setting-k8sScConf-spec.shardPodSpec.persistence.multiple.journal.rst

‎source/tutorial/configure-mongodb-cluster-topology.txt

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
.. _configure-mongodb-topology:
2+
3+
================================================
4+
Configure Cluster Topology for MongoDB Resources
5+
================================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. meta::
10+
:keywords: nodes affinity topology
11+
12+
.. facet::
13+
:name: genre
14+
:values: tutorial
15+
16+
.. contents:: On this page
17+
:local:
18+
:backlinks: none
19+
:depth: 1
20+
:class: singlecol
21+
22+
You can configure the deployment topology of your MongoDB resources within
23+
|k8s| by defining ``NodeAffinity`` and ``PodAffinity``.
24+
``NodeAffinity`` and ``PodAffinity`` specify
25+
where |k8s| deploys MongoDB custom resources in your |k8s| cluster.
26+
27+
You can implement |node-affinity| by applying |node-labels| to specific
28+
nodes within your |k8s| cluster and defining ``labelSelector`` fields
29+
with corrosponding labels in your MongoDB |k8s-crd|. When you apply
30+
|node-labels| and matching ``labelSelector`` values, |k8s| only
31+
deploys a given MongoDB |k8s-crd| on the nodes you
32+
specify within your |k8s| cluster. Implementing node affinity rules can be useful when
33+
deploying MongoDB resources in heterogeneous node groups, as it allows you
34+
to deploy specific resources on specific node varieties.
35+
36+
Similarly, you can implement Pod affinity by applying |labels| to Pods that are
37+
running in your cluster and aligning those label values with ``labelSelector``
38+
values defined in your MongoDB |k8s-crd|. When you apply |labels|
39+
and matching ``labelSelector`` values, |k8s| colocates MongoDB
40+
custom resource-managed Pods with Pods with matching labels applied. By
41+
collocating Pods, you can improve system performance and reduce latency
42+
between Pods that communicate regularly. You can also define Pod antiaffinity
43+
rules which allow you to specify Pods which should not be colocated.
44+
45+
For Standalone and Replica Set deployments, you can apply these affinity rules
46+
to the :setting:`spec.podSpec` of your MongoDB |k8s-crd|.
47+
For Sharded Cluster deployments, you can apply these affinity rules to the
48+
:setting:`spec.configSrvPodSpec`, :setting:`spec.shardPodSpec`,
49+
and :setting:`spec.mongosPodSpec` sections of your MongoDB |k8s-crd|.
50+
51+
You must deploy MonogDB resources, such as ``mongos``, shards,
52+
and config servers in the case of a Sharded Cluster deployment,
53+
in the same namespace as the MongoDB resource. However, within that namespace,
54+
you can configure the ``nodeAffinity`` and ``podAffinity`` for ``mongos``,
55+
shards, and config server resource types in the ``ShardedCluster`` |k8s-crd|.
56+
57+
Prerequisites
58+
-------------
59+
60+
To configure the deployment topology for your
61+
MongoDB deployment, you must either have a MongoDB replica set deployed
62+
through the MongoDB |k8s-op-short| along with labels applied
63+
to the |k8s| resources that will align with ``labelSelectors`` defined
64+
in the MongoDB |k8s-crd| or meet the following prerequisites:
65+
66+
- An :ref:`Ops Manager instance <deploy-om-container>` or a :opsmgr:`Cloud Manager organization </tutorial/manage-organizations/#create-organization>`.
67+
68+
- The :ref:`MongoDB Enterprise Kubernetes Operator <install-k8s>`.
69+
70+
- A :ref:`Kubernetes Operator ConfigMap <create-k8s-project>`.
71+
72+
- :ref:`Credentials for the Kubernetes Operator <create-k8s-credentials>` or
73+
configure :ref:`a different secret storage tool <k8s-set-secret-storage-tool>`.
74+
75+
- Labels applied to the |k8s| resources that will align with ``labelSelectors``
76+
defined in the MongoDB |k8s-crd|.
77+
78+
Procedure
79+
---------
80+
81+
.. include:: /includes/steps/configure-topology.rst

0 commit comments

Comments
 (0)