Docs Menu
Docs Home
/
MongoDB Enterprise Kubernetes Operator
/
Deploy Database Resources
/
Deploy

Deploy a Replica Set

On this page

  • Considerations
  • Prerequisites
  • 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 6.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 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.

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.

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.

Prerequisites

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

Note

To avoid storing secrets in single-cluster Kubernetes deployments, you can migrate all secrets to a secret storage tool. Deployments on multiple Kubernetes clusters don't support storing secrets in secret storage tools, such as HashiCorp Vault.

  • 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:

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

      Important

      If you're using an ACME based service provider such as Let's Encrypt to issue TLS certificates, the provider might prohibit you from adding the Pod's default FQDNs (*.svc.cluster.local) to SANs in the certificate.

      To use an ACME based certificate, you must configure the certificate for your replica set resource. To learn more, see the step about ACME based TLS certificates in the procedure.

    • 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 have the CA certificate file and name it ca-pem.

  • You must have the key that you used to sign your TLS certificates.

Important

The Kubernetes Operator uses kubernetes.io/tls secrets to store TLS certificates and private keys for Ops Manager and MongoDB resources. Starting in Kubernetes Operator version 1.17.0, the Kubernetes Operator doesn't support concatenated PEM files stored as Opaque secrets.

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

Note

To avoid storing secrets in single-cluster Kubernetes deployments, you can migrate all secrets to a secret storage tool. Deployments on multiple Kubernetes clusters don't support storing secrets in secret storage tools, such as HashiCorp Vault.

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.

Note

If you are deploying an Ops Manager resource in a multi-Kubernetes cluster MongoDB deployment:

  • Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".

  • Set the --namespace to the same scope that you used for your multi-Kubernetes cluster MongoDB deployment, such as: kubectl config --namespace "mongodb".

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:

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

Note

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

For 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:

kubectl create secret tls <prefix>-<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 and specify the CA certificate file.

Important

The Kubernetes Operator requires that the certificate for the MongoDB resource is named ca-pem in the ConfigMap.

kubectl create configmap custom-ca --from-file=ca-pem=<your-custom-ca-file>
5

Copy the sample replica set resource.

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

1---
2apiVersion: mongodb.com/v1
3kind: MongoDB
4metadata:
5  name: <my-replica-set>
6spec:
7  members: 3
8  version: "4.2.2-ent"
9  opsManager:
10    configMapRef:
11           # Must match metadata.name in ConfigMap file
12      name: <configMap.metadata.name>
13  credentials: <mycredentials>
14  type: ReplicaSet
15  persistent: true
16...
16  security:
17    tls:
18      ca: <custom-ca>
19    certsSecretPrefix: <prefix>
20...
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 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.

To learn more, see metadata.name and 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.

6.0.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.

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

IMPORTANT: The Kubernetes Operator tracks any changes to the ConfigMap and reconciles the state of the MongoDB 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.

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

<mycredentials>

spec.type

string

Type of MongoDB resource to create.

ReplicaSet

spec.persistent

string

Optional.

Flag indicating if this MongoDB resource should use Persistent Volumes for storage. Persistent volumes are not deleted when the MongoDB 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:

WARNING: Grant your containers permission to write to your Persistent Volume. The Kubernetes Operator sets fsGroup = 2000, runAsUser = 2000, and runAsNonRoot = true in securityContext. Kubernetes Operator sets fsgroup equal to runAsUser to make the volume writable for a user that runs the main process in the container. To learn more, see Configure a Security Context for a Pod or Container and the related discussion in the Kubernetes documentation. If redeploying the resource doesn't fix issues with your Persistent Volume, contact MongoDB Support.

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 (CA).

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

Key
Type
Necessity
Description
Example
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
.certsSecretPrefix

string

Required

Add the <prefix> of the secret name that contains your MongoDB deployment's TLS certificates.

For 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

Optional: Configure ACME based TLS certificates for your replica set resource.

If you're using an ACME based service provider such as Let's Encrypt to issue TLS certificates, the provider might prohibit you from adding the Pod's default FQDNs (*.svc.cluster.local) to SANs in the certificate.

To configure a certificate that doesn't contain the pod's FQDNs:

  1. Issue the certificate for an external domain. For more information, see the Let's Encrypt documentation or the documentation for your provider.

  2. Ensure that your certificate contains all hostnames that you plan to deploy in the replica set. Alternatively, you can issue a wildcard certificate for *.<externalDomain>.

  3. To use a certificate containing only external domains for your replica set deployment, you must change the default hostname used by the replica set:

    • If you prefer to configure the hostname while creating your Kubernetes cluster, change the default domain from cluster.local to the external domain when creating or recreating your Kubernetes cluster. Then, set this domain in your MongoDB resource by using the spec.clusterDomain setting.

    • Otherwise, create your MongoDB deployment with the following settings configured in your Kubernetes object:

Key
Type
Necessity
Description
spec.externalAccess
.externalDomain

string

Required

An external domain used to externally expose your replica set deployment.

By default, each replica set member uses the Kubernetes Pod's FQDN (*.svc.cluster.local) as the default hostname. However, if you add an external domain to this setting, the replica set uses a hostname that is a subdomain of the specified domain instead. This hostname uses the following format:

<replica-set-name>-<pod-idx>.<externalDomain>

For example:

replica-set-1.example.com

After you deploy the replica set with this setting, the Kubernetes Operator uses the hostname with the external domain to override the processes[n].hostname field in the Ops Manager automation configuration. Then, the MongoDB Agent uses this hostname to connect to mongod.

To specify other hostnames for connecting to the replica set, you can use the spec.connectivity.replicaSetHorizons setting. However, the following connections still use the hostname with the external domain:

WARNING: Specifying this field changes how Ops Manager registers mongod processes. You can specify this field only for new replica set deployments starting in Kubernetes Operator version 1.19. You can't change the value of this field or any processes[n].hostname fields in the Ops Manager automation configuration for a running replica set deployment.

spec.externalAccess
.externalService.spec

collection

Optional

Configuration for the ServiceSpec.

When you set the spec.externalAccess setting, the Kubernetes Operator automatically creates an external load balancer service with default values. You can override certain values or add new values depending on your needs. For example, if you intend to create NodePort services and don't need a load balancer, you must configure overrides in your Kubernetes specification:

externalAccess:
  externalService:
    annotations:
      # cloud-specific annotations for the service
    spec:
      type: NodePort # default is LoadBalancer
      # you can specify other spec overrides if necessary

For more information about the Kubernetes specification, see ServiceSpec in the Kubernetes documentation.

spec.externalAccess
.externalService.annotations

collection

Optional

Key-value pairs that let you add cloud provider-specific configuration settings to all clusters in your deployment. To learn more, see annotations and the documentation for your Kubernetes cloud provider.

You can specify placeholder values to customize your annotations. To learn more, see spec.externalAccess.externalService.annotations.

10

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:

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.

11

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

12

Start your replica set deployment.

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

kubectl apply -f <replica-set-conf>.yaml
13

Track the status of your replica set deployment.

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

kubectl get mdb <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.

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

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.

Note

If you are deploying an Ops Manager resource in a multi-Kubernetes cluster MongoDB deployment:

  • Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".

  • Set the --namespace to the same scope that you used for your multi-Kubernetes cluster MongoDB deployment, such as: kubectl config --namespace "mongodb".

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:

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

Note

If you are deploying an Ops Manager resource in a multi-Kubernetes cluster MongoDB deployment:

  • Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".

  • Set the --namespace to the same scope that you used for your multi-Kubernetes cluster MongoDB deployment, such as: kubectl config --namespace "mongodb".

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

Copy the sample replica set resource.

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

1---
2apiVersion: mongodb.com/v1
3kind: MongoDB
4metadata:
5  name: <my-replica-set>
6spec:
7  members: 3
8  version: "4.2.2-ent"
9  opsManager:
10    configMapRef:
11           # Must match metadata.name in ConfigMap file
12      name: <configMap.metadata.name>
13  credentials: <mycredentials>
14  type: ReplicaSet
15  persistent: true
16...
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 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.

To learn more, see metadata.name and 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.

6.0.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.

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

IMPORTANT: The Kubernetes Operator tracks any changes to the ConfigMap and reconciles the state of the MongoDB 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.

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

<mycredentials>

spec.type

string

Type of MongoDB resource to create.

ReplicaSet

spec.persistent

string

Optional.

Flag indicating if this MongoDB resource should use Persistent Volumes for storage. Persistent volumes are not deleted when the MongoDB 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:

WARNING: Grant your containers permission to write to your Persistent Volume. The Kubernetes Operator sets fsGroup = 2000, runAsUser = 2000, and runAsNonRoot = true in securityContext. Kubernetes Operator sets fsgroup equal to runAsUser to make the volume writable for a user that runs the main process in the container. To learn more, see Configure a Security Context for a Pod or Container and the related discussion in the Kubernetes documentation. If redeploying the resource doesn't fix issues with your Persistent Volume, contact MongoDB Support.

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:

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:

kubectl apply -f <replica-set-conf>.yaml
8

Track the status of your replica set deployment.

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

kubectl get mdb <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.

Back

Standalone Instance

Next

Sharded Cluster