• Deploy and Configure MongoDB Database Resources >
• Deploy a MongoDB Database Resource >
• Deploy a Replica Set

Deploy a Replica Set

Note

At any place on this page that says Ops Manager, you can substitute Cloud Manager.

Important

• You can use the Kubernetes Operator to deploy MongoDB resources with Cloud Manager and with Ops Manager version 5.0.x or later.
• You can use the Atlas Operator to deploy MongoDB resources to Atlas.

Warning

Kubernetes Operator doesn’t support arbiter nodes.

A replica set is a group of MongoDB deployments that maintain the same data set. Replica sets provide redundancy and high availability and are the basis for all production deployments.

To learn more about replica sets, see the Replication Introduction in the MongoDB manual.

Use this procedure to deploy a new replica set that Ops Manager manages. After deployment, use Ops Manager to manage the replica set, including such operations as adding, removing, and reconfiguring members.

Considerations

When you deploy your replica set via the Kubernetes Operator, you must choose whether to encrypt connections using TLS certificates.

The following procedure for Non-Encrypted Connections:

• Doesn’t encrypt connections between MongoDB hosts in the replica set.
• Doesn’t encrypt connections between client applications and MongoDB deployments.
• Has fewer setup requirements than a deployment with TLS-encrypted connections.

The following procedure for TLS-Encrypted connections:

• Establishes TLS-encrypted connections between MongoDB hosts in the replica set.
• Establishes TLS-encrypted connections between client applications and MongoDB deployments.
• Requires valid certificates for TLS encryption.

Note

You can’t secure a Standalone Instance of MongoDB in a Kubernetes cluster.

To set up TLS encryption for a sharded cluster, see Deploy a Sharded Cluster.

Select the appropriate tab based on whether you want to encrypt your replica set connections with TLS.

• Non-Encrypted Connections
• TLS-Encrypted Connections

Prerequisites

To deploy a replica set using an object, you must:

• Have or create an Ops Manager instance or a Cloud Manager organization.
• Have or install the MongoDB Enterprise Kubernetes Operator.
• Create or generate a Kubernetes Operator ConfigMap.
• Create credentials for the Kubernetes Operator or configure a different secret storage tool.

This Kubernetes secret, along with other secrets that Kubernetes Operator creates, can later be migrated to a different secret storage tool to avoid storing secrets in Kubernetes.

• Generate one TLS certificate for each of the following components:

  • Your replica set. Ensure that you add SANs for each Kubernetes pod that hosts a member of your replica set to the certificate.

    In your TLS certificate, the SAN for each pod must use the following format:

    copy

    <pod-name>.<metadata.name>-svc.<namespace>.svc.cluster.local
    

  • Your project’s MongoDB Agent. For the MongoDB Agent certificate, ensure that you meet the following requirements:
    • The Common Name in the TLS certificate is not empty.
    • The combined Organization and Organizational Unit in each TLS certificate differs from the Organization and Organizational Unit in the TLS certificate for your replica set members.

• You must possess the CA certificate and the key that you used to sign your TLS certificates.

Important

For fresh Kubernetes Operator installations starting with version 1.13, the Kubernetes Operator uses kubernetes.io/tls secrets to store TLS certificates and private keys for Ops Manager and MongoDB resources.

Previous Kubernetes Operator versions required you to concatenate your TLS certificates and private keys into a PEM file and store this file in an Opaque secret.

To maintain backwards compatibility, the Kubernetes Operator continues to support storing PEM files in Opaque secrets. Support of this feature might be removed in a future release.

We recommend that you upgrade to Kubernetes Operator version 1.15.1 or later.

If you have a broken Application Database after upgrading to Kubernetes Operator version 1.14.0 or 1.15.0, see Ops Manager in Failed State.

Deploy a Replica Set

1

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

copy

kubectl config set-context $(kubectl config current-context) --namespace=<metadata.namespace>

2

Copy the highlighted section of this replica set resource.

Change the highlighted settings of this YAML file to match your desired replica set configuration.

copy

---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-replica-set>
spec:
  members: 3
  version: "4.2.2-ent"
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ReplicaSet
  persistent: true
...

3

Paste the copied example to create a new replica set resource.

Open your preferred text editor and paste the object specification into a new text file.

4

Change the highlighted settings to your preferred values.

Key	Type	Description	Example
metadata.name	string	Label for this Kubernetes replica set object. Resource names must be 44 characters or less. See also metadata.name Kubernetes documentation on names.	myproject
spec.members	integer	Number of members of the replica set.	3
spec.version	string	Version of MongoDB that this replica set 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.	3.6.7
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.	<myconfigmap>
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.	ReplicaSet
spec.persistent	string	Optional. Flag indicating if this MongoDB Kubernetes resource should use Persistent Volumes for storage. Persistent volumes are not deleted when the MongoDB Kubernetes resource is stopped or restarted. If this value is true, then spec.podSpec.persistence.single is set to its default value of 16Gi. To change your Persistent Volume Claims configuration, configure the following collections to meet your deployment requirements: If you want one Persistent Volume for each Pod, configure the spec.podSpec.persistence.single collection. If you want separate Persistent Volumes for data, journals, and logs for each Pod, configure the following collections: spec.podSpec.persistence.multiple.data spec.podSpec.persistence.multiple.journal spec.podSpec.persistence.multiple.logs Warning Your containers must have permissions to write to your Persistent Volume. The Kubernetes Operator sets fsGroup = 2000 in securityContext This makes Kubernetes try to fix write permissions for the Persistent Volume. If redeploying the deployment item does not fix issues with your Persistent Volumes, contact MongoDB Support. Note If you do not use Persistent Volumes, the Disk Usage and Disk IOPS charts cannot be displayed in either the Processes tab on the Deployment page or in the Metrics page when reviewing the data for this deployment.	true

5

Add any additional accepted settings for a replica set deployment.

You can also add any of the following optional settings to the object specification file for a replica set deployment:

• spec.additionalMongodConfig
• spec.backup.mode
• spec.clusterDomain
• spec.connectivity.replicaSetHorizons
• spec.featureCompatibilityVersion
• spec.logLevel
• spec.podSpec.persistence.single
• spec.podSpec.persistence.multiple.data
• spec.podSpec.persistence.multiple.journal
• spec.podSpec.persistence.multiple.logs
• spec.podSpec.podAffinity
• spec.podSpec.podAntiAffinityTopologyKey
• spec.podSpec.nodeAffinity
• spec.podSpec.podTemplate.metadata
• spec.podSpec.podTemplate.spec

Warning

You must set spec.clusterDomain if your Kubernetes cluster has a default domain other than the default cluster.local. If you neither use the default nor set the spec.clusterDomain option, the Kubernetes Operator might not function as expected.

6

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

7

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

8

Track the status of your replica set deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

copy

kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when the configuration changes until the status phase achieves the Running state.

See Troubleshoot the Kubernetes Operator for information about the resource deployment statuses.

1

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

copy

kubectl config set-context $(kubectl config current-context) --namespace=<metadata.namespace>

2

Create the secret for your replica set’s TLS certificate.

Run this kubectl command to create a new secret that stores the replica set’s certificate:

copy

kubectl create secret tls <metadata.name>-cert \
  --cert=<replica-set-tls-cert> \
  --key=<replica-set-tls-key>

Note

You must prefix your secrets with <prefix>-<metadata.name> if both of the following items are true:

• You set spec.security.certsSecretPrefix or spec.security.tls.secretRef.prefix
• You omit spec.security.tls.secretRef.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.

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

To learn about your options for secret storage, see Configure Secret Storage.

3

Create the secret for your agent’s TLS certificate.

Run this kubectl command to create a new secret that stores the agent’s TLS certificate:

copy

kubectl create secret tls <metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

4

Create the ConfigMap to link your CA with your deployment.

Run this kubectl command to link your CA to your replica set:

copy

kubectl create configmap custom-ca --from-file=ca-pem

5

Copy the highlighted section of this replica set resource.

Change the highlighted settings of this YAML file to match your desired replica set configuration.

copy

---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-replica-set>
spec:
  members: 3
  version: "4.2.2-ent"
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ReplicaSet
  persistent: true

copy

  security:
    tls:
      enabled: true
      ca: <custom-ca>
      secretRef:
        prefix: <prefix>
...

6

Paste the copied example to create a new replica set resource.

Open your preferred text editor and paste the object specification into a new text file.

7

Change the highlighted settings to your preferred values.

Key	Type	Description	Example
metadata.name	string	Label for this Kubernetes replica set object. Resource names must be 44 characters or less. See also metadata.name Kubernetes documentation on names.	myproject
spec.members	integer	Number of members of the replica set.	3
spec.version	string	Version of MongoDB that this replica set 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.	3.6.7
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.	<myconfigmap>
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.	ReplicaSet
spec.persistent	string	Optional. Flag indicating if this MongoDB Kubernetes resource should use Persistent Volumes for storage. Persistent volumes are not deleted when the MongoDB Kubernetes resource is stopped or restarted. If this value is true, then spec.podSpec.persistence.single is set to its default value of 16Gi. To change your Persistent Volume Claims configuration, configure the following collections to meet your deployment requirements: If you want one Persistent Volume for each Pod, configure the spec.podSpec.persistence.single collection. If you want separate Persistent Volumes for data, journals, and logs for each Pod, configure the following collections: spec.podSpec.persistence.multiple.data spec.podSpec.persistence.multiple.journal spec.podSpec.persistence.multiple.logs Warning Your containers must have permissions to write to your Persistent Volume. The Kubernetes Operator sets fsGroup = 2000 in securityContext This makes Kubernetes try to fix write permissions for the Persistent Volume. If redeploying the deployment item does not fix issues with your Persistent Volumes, contact MongoDB Support. Note If you do not use Persistent Volumes, the Disk Usage and Disk IOPS charts cannot be displayed in either the Processes tab on the Deployment page or in the Metrics page when reviewing the data for this deployment.	true

8

Configure the TLS settings for your replica set resource using a Custom Certificate Authority.

To enable TLS in your deployment, configure the following settings in your Kubernetes object:

Key	Type	Necessity	Description	Example
spec.security .tls.enabled	boolean	Required	If this value is true, TLS is enabled on the MongoDB deployment. By default, Kubernetes Operator requires hosts to use and accept TLS encrypted connections.	true
spec.security .tls.ca	string	Required	Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates.	<custom-ca>
spec.security .tls.certsSecretPrefix	string	Optional	If applicable, add the <prefix> of the secret name that contains your MongoDB deployment’s TLS certificates. 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.	devDb

9

Add any additional accepted settings for a replica set deployment.

You can also add any of the following optional settings to the object specification file for a replica set deployment:

• spec.additionalMongodConfig
• spec.backup.mode
• spec.clusterDomain
• spec.connectivity.replicaSetHorizons
• spec.featureCompatibilityVersion
• spec.logLevel
• spec.podSpec.persistence.single
• spec.podSpec.persistence.multiple.data
• spec.podSpec.persistence.multiple.journal
• spec.podSpec.persistence.multiple.logs
• spec.podSpec.podAffinity
• spec.podSpec.podAntiAffinityTopologyKey
• spec.podSpec.nodeAffinity
• spec.podSpec.podTemplate.metadata
• spec.podSpec.podTemplate.spec

Warning

You must set spec.clusterDomain if your Kubernetes cluster has a default domain other than the default cluster.local. If you neither use the default nor set the spec.clusterDomain option, the Kubernetes Operator might not function as expected.

10

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

11

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

12

Track the status of your replica set deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

copy

kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when the configuration changes until the status phase achieves the Running state.

See Troubleshoot the Kubernetes Operator for information about the resource deployment statuses.

After you encrypt your database resource with TLS, you can secure the following:

• Client authentication with LDAP
• Client authentication with X.509
• Internal authentication with X.509

Renew TLS Certificates for a Replica Set

Renew your TLS certificates periodically using the following procedure:

1

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

copy

kubectl config set-context $(kubectl config current-context) --namespace=<metadata.namespace>

2

Renew the secret for your TLS certificates.

Run this kubectl command to renew an existing secret that stores the replica set’s certificates:

copy

kubectl create secret tls <metadata.name>-cert \
  --cert=<replica-set-tls-cert> \
  --key=<replica-set-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

←   Deploy a Standalone MongoDB Instance Deploy a Sharded Cluster  →

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