Navigation

Deploy Replica Sets in a Multi-Kubernetes Cluster

On this page

Use this procedure to create a new replica set in a member Kubernetes cluster in a multi-Kubernetes-cluster deployment.

This procedure allows you to set different settings for the replica set resource, such as overrides for statefulSet configuration. As an alternative to using this procedure, you can use the Multi-Kubernetes-Cluster Quick Start, which creates a multi-Kubernetes-cluster deployment with default settings.

Before you begin:

Deploy a MongoDBMultiCluster Resource

You can use the following procedures in this TLS-Encrypted Connections tab:

  • Deploy a MongoDBMultiCluster resource
  • Renew TLS Certificates for a MongoDBMultiCluster resource

These procedures establish TLS-encrypted connections between MongoDB hosts in a replica set, and between client applications and MongoDB deployments.

Before you begin, you must have valid certificates for TLS encryption.

Deploy a ``MongoDBMultiCluster`` Resource

1

Create the secret for the TLS certificate of your MongoDBMultiCluster resource.

Run the kubectl command to create a new secret that stores the MongoDBMultiCluster resource certificate:

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
  --namespace=<metadata.namespace> \
  create secret tls <prefix>-<metadata.name>-cert \
  --cert=<resource-tls-cert> \
  --key=<resource-tls-key>

Note

You must prefix your secrets with <prefix>-<metadata.name>.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

2
3

Configure kubectl to use the central cluster’s namespace.

If you have not done so already, run the following commands to run all kubectl commands on the central cluster in the default namespace.

copy 
kubectl config use-context $MDB_CENTRAL_CLUSTER_FULL_NAME
kubectl config set-context $(kubectl config current-context) \
  --namespace=mongodb
4

Copy and paste the sample resource.

  1. Copy the sample replica set YAML file and paste it into a new text file.
  2. Change the file’s settings to match your desired replica set configuration.
copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# This example provides statefulSet overrides per cluster.

apiVersion: mongodb.com/v1
kind: MongoDBMultiCluster
metadata:
  name: multi-replica-set
spec:
  version: 4.4.0-ent
  type: ReplicaSet
  duplicateServiceObjects: false
  credentials: my-credentials
  opsManager:
    configMapRef:
      name: my-project
  clusterSpecList:
    - clusterName: cluster1.example.com
      members: 2
      statefulSet:
        spec:
          template:
            spec:
              containers:
                # Example of custom sidecar containers. Remove it before using the file in production.
                - name: sidecar1
                  image: busybox
                  command: [ "sleep" ]
                  args: [ "infinity" ]
          # Use the following settings to override the default storage size of the "data" Persistent Volume.
          volumeClaimTemplates:
            - metadata:
                name: data
              spec:
                resources:
                  requests:
                    storage: 1Gi
    - clusterName: cluster2.example.com
      members: 1
      statefulSet:
        spec:
          template:
            spec:
              containers:
                # Example of custom sidecar containers. Remove it before using the file in production.
                - name: sidecar2
                  image: busybox
                  command: [ "sleep" ]
                  args: [ "infinity" ]
          volumeClaimTemplates:
            - metadata:
                name: data
              spec:
                resources:
                  requests:
                    storage: 1Gi
    - clusterName: cluster3.example.com
      members: 1
      statefulSet:
        spec:
          template:
            spec:
              containers:
                # Example of custom sidecar containers. Remove it before using the file in production.
                - name: sidecar3
                  image: busybox
                  command: [ "sleep" ]
                  args: [ "infinity" ]
          volumeClaimTemplates:
            - metadata:
                name: data
              spec:
                resources:
                  requests:
                    storage: 1Gi

...
5

Change the settings to your preferred values.

Key Type Description Example
metadata.name string

Label for the MongoDBMultiCluster resource.

Resource names must be 44 characters or less.

See also metadata.name and names in the Kubernetes documentation.

 multi-replica-set
spec.version string

Version of MongoDB that this MongoDBMultiCluster resource should run.

The format should be X.Y.Z for the Community edition and X.Y.Z-ent for the Enterprise edition.

Important

Ensure that you choose a compatible MongoDB Server version.

Compatible versions differ depending on the base image that the MongoDB database resource uses.

To learn more about MongoDB versioning, see MongoDB Versioning in the MongoDB Manual.

 4.4.0-ent
spec
.opsManager
.configMapRef
.name
 string

Name of the ConfigMap with the Ops Manager connection configuration. The spec.cloudManager.configMapRef.name setting is an alias for this setting and can be used in its place.

Note

This value must exist on the same namespace as the resource you want to create.

Operator manages changes to the ConfigMap

The Kubernetes Operator tracks any changes to the ConfigMap and reconciles the state of the MongoDB Kubernetes resource.

 <my-project>
spec
.clusterSpecList
.clusterName
 string Name of the cluster in the MongoDBMultiCluster resource. cluster1.example.com
spec
.clusterSpecList
.members
 integer The number of members in this cluster. 2
spec
.clusterSpecList
.statefulSet
.spec
 collection

Optional.

Provides the configuration for the StatefulSet override for each of the cluster’s StatefulSets in a multi-Kubernetes-cluster deployment. If specified at an individual cluster level under clusterSpecList, overrides the global configuration for the StatefulSet for the entire multi-Kubernetes-cluster deployment. See Multi-Kubernetes-Cluster Resource Specification and StatefulSet v1 apps Kubernetes documentation.

 See the example.
spec
.clusterSpecList
.statefulSet
.spec
.volumeClaimTemplates
.spec
 collection Optional. If specified, provides a per-cluster override for the default storage size of the volumeClaimtemplates, for the persistent volume that stores the data. See the example.
spec.credentials string

Name of the secret you created as Ops Manager API authentication credentials for the Kubernetes Operator to communicate with Ops Manager.

The Ops Manager Kubernetes Secret object holding the Credentials must exist on the same Namespace as the resource you want to create.

Operator manages changes to the Secret

The Kubernetes Operator tracks any changes to the Secret and reconciles the state of the MongoDB Kubernetes resource.

 <mycredentials>
spec.type string Type of MongoDB Kubernetes resource to create. The only supported value for this field is ReplicaSet. See Limitations. ReplicaSet
6

Add any additional accepted settings for a MongoDBMultiCluster resource deployment.

You can also add any optional settings to the object specification. See Multi-Kubernetes-Cluster Resource Specification.

7

Save this replica set config file with a .yaml extension.

8

Start your replica set deployment.

In any directory, invoke the following Kubernetes command to create your replica set:

copy 
kubectl apply -f <replica-set-conf>.yaml
9

Track the status of your multi-Kubernetes-cluster deployment.

To check the status of your MongoDBMultiCluster resource, use the following command on the central cluster:

copy 
kubectl get mdbmc <resource-name> -o yaml -w

With the -w (watch) flag set, when the configuration changes, the output refreshes immediately until the status phase achieves the Running state. To learn more about resource deployment statuses, see Troubleshoot the Kubernetes Operator.

Renew TLS Certificates for a ``MongoDBMultiCluster`` Resource

Renew your TLS certificates periodically using the following procedure.

1

Renew the secret for a MongoDBMultiCluster resource.

Run this kubectl command to renew an existing secret that stores the certificates for the MongoDBMultiCluster resource:

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
--namespace=<metadata.namespace> \
create secret tls <prefix>-<metadata.name>-cert \
--cert=<resource-tls-cert> \
--key=<resource-tls-key> \
--dry-run=client \
-o yaml |
kubectl apply -f -

This procedure doesn’t encrypt connections between MongoDB hosts in a replica set, and between client applications and MongoDB deployments.

Deploy a ``MongoDBMultiCluster`` Resource

1

Configure kubectl to use the central cluster’s namespace.

If you have not done so already, run the following commands to run all kubectl commands on the central cluster in the default namespace.

copy 
kubectl config use-context $MDB_CENTRAL_CLUSTER_FULL_NAME
kubectl config set-context $(kubectl config current-context) \
  --namespace=mongodb
2

Copy and paste the sample resource.

  1. Copy the sample replica set YAML file and paste it into a new text file.
  2. Change the file’s settings to match your desired replica set configuration.
copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# This example provides statefulSet overrides per cluster.

apiVersion: mongodb.com/v1
kind: MongoDBMultiCluster
metadata:
  name: multi-replica-set
spec:
  version: 4.4.0-ent
  type: ReplicaSet
  duplicateServiceObjects: false
  credentials: my-credentials
  opsManager:
    configMapRef:
      name: my-project
  clusterSpecList:
    - clusterName: cluster1.example.com
      members: 2
      statefulSet:
        spec:
          template:
            spec:
              containers:
                # Example of custom sidecar containers. Remove it before using the file in production.
                - name: sidecar1
                  image: busybox
                  command: [ "sleep" ]
                  args: [ "infinity" ]
          # Use the following settings to override the default storage size of the "data" Persistent Volume.
          volumeClaimTemplates:
            - metadata:
                name: data
              spec:
                resources:
                  requests:
                    storage: 1Gi
    - clusterName: cluster2.example.com
      members: 1
      statefulSet:
        spec:
          template:
            spec:
              containers:
                # Example of custom sidecar containers. Remove it before using the file in production.
                - name: sidecar2
                  image: busybox
                  command: [ "sleep" ]
                  args: [ "infinity" ]
          volumeClaimTemplates:
            - metadata:
                name: data
              spec:
                resources:
                  requests:
                    storage: 1Gi
    - clusterName: cluster3.example.com
      members: 1
      statefulSet:
        spec:
          template:
            spec:
              containers:
                # Example of custom sidecar containers. Remove it before using the file in production.
                - name: sidecar3
                  image: busybox
                  command: [ "sleep" ]
                  args: [ "infinity" ]
          volumeClaimTemplates:
            - metadata:
                name: data
              spec:
                resources:
                  requests:
                    storage: 1Gi

...
3

Change the settings to your preferred values.

Key Type Description Example
metadata.name string

Label for the MongoDBMultiCluster resource.

Resource names must be 44 characters or less.

See also metadata.name and names in the Kubernetes documentation.

 multi-replica-set
spec.version string

Version of MongoDB that this MongoDBMultiCluster resource should run.

The format should be X.Y.Z for the Community edition and X.Y.Z-ent for the Enterprise edition.

Important

Ensure that you choose a compatible MongoDB Server version.

Compatible versions differ depending on the base image that the MongoDB database resource uses.

To learn more about MongoDB versioning, see MongoDB Versioning in the MongoDB Manual.

 4.4.0-ent
spec
.opsManager
.configMapRef
.name
 string

Name of the ConfigMap with the Ops Manager connection configuration. The spec.cloudManager.configMapRef.name setting is an alias for this setting and can be used in its place.

Note

This value must exist on the same namespace as the resource you want to create.

Operator manages changes to the ConfigMap

The Kubernetes Operator tracks any changes to the ConfigMap and reconciles the state of the MongoDB Kubernetes resource.

 <my-project>
spec
.clusterSpecList
.clusterName
 string Name of the cluster in the MongoDBMultiCluster resource. cluster1.example.com
spec
.clusterSpecList
.members
 integer The number of members in this cluster. 2
spec
.clusterSpecList
.statefulSet
.spec
 collection

Optional.

Provides the configuration for the StatefulSet override for each of the cluster’s StatefulSets in a multi-Kubernetes-cluster deployment. If specified at an individual cluster level under clusterSpecList, overrides the global configuration for the StatefulSet for the entire multi-Kubernetes-cluster deployment. See Multi-Kubernetes-Cluster Resource Specification and StatefulSet v1 apps Kubernetes documentation.

 See the example.
spec
.clusterSpecList
.statefulSet
.spec
.volumeClaimTemplates
.spec
 collection Optional. If specified, provides a per-cluster override for the default storage size of the volumeClaimtemplates, for the persistent volume that stores the data. See the example.
spec.credentials string

Name of the secret you created as Ops Manager API authentication credentials for the Kubernetes Operator to communicate with Ops Manager.

The Ops Manager Kubernetes Secret object holding the Credentials must exist on the same Namespace as the resource you want to create.

Operator manages changes to the Secret

The Kubernetes Operator tracks any changes to the Secret and reconciles the state of the MongoDB Kubernetes resource.

 <mycredentials>
spec.type string Type of MongoDB Kubernetes resource to create. The only supported value for this field is ReplicaSet. See Limitations. ReplicaSet
4

Add any additional accepted settings for a MongoDBMultiCluster resource deployment.

You can also add any optional settings to the object specification. See Multi-Kubernetes-Cluster Resource Specification.

5

Save this replica set config file with a .yaml extension.

6

Start your replica set deployment.

In any directory, invoke the following Kubernetes command to create your replica set:

copy 
kubectl apply -f <replica-set-conf>.yaml
7

Track the status of your multi-Kubernetes-cluster deployment.

To check the status of your MongoDBMultiCluster resource, use the following command on the central cluster:

copy 
kubectl get mdbmc <resource-name> -o yaml -w

With the -w (watch) flag set, when the configuration changes, the output refreshes immediately until the status phase achieves the Running state. To learn more about resource deployment statuses, see Troubleshoot the Kubernetes Operator.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.