Deploy and Configure a MongoDB Resource

The /config/samples directory contains example MongoDB resources that you can modify and deploy.

Deploy a Replica Set

To deploy your first replica set:

Replace <your-password-here> in config/samples/mongodb.com_v1_mongodbcommunity_cr.yaml to the password you wish to use.

Invoke the following kubectl command:

kubectl apply -f config/samples/mongodb.com_v1_mongodbcommunity_cr.yaml --namespace <my-namespace>

Verify that the MongoDB resource deployed:

kubectl get mongodbcommunity --namespace <my-namespace>

The Community Kubernetes Operator creates secrets that contains users' connection strings and credentials.

The secrets follow this naming convention: <metadata.name>-<auth-db>-<username>, where:

Variable	Description	Value in Sample
`<metadata.name>`	Name of the MongoDB database resource.	`example-mongodb`
`<auth-db>`	Authentication database where you defined the database user.	`admin`
`<username>`	Username of the database user.	`my-user`

Update the variables in the following command, then run it to retrieve a user's connection strings to the replica set from the secret:

NOTE: The following command requires jq version 1.6 or higher.

kubectl get secret <metadata.name>-<auth-db>-<username> -n <my-namespace> \ 
-o json | jq -r '.data | with_entries(.value |= @base64d)'

The command returns the replica set's standard and DNS seed list connection strings in addition to the user's name and password:

{
  "connectionString.standard": "mongodb://<username>:<password>@example-mongodb-0.example-mongodb-svc.mongodb.svc.cluster.local:27017,example-mongodb-1.example-mongodb-svc.mongodb.svc.cluster.local:27017,example-mongodb-2.example-mongodb-svc.mongodb.svc.cluster.local:27017/admin?ssl=true",
  "connectionString.standardSrv": "mongodb+srv://<username>:<password>@example-mongodb-svc.mongodb.svc.cluster.local/admin?ssl=true",
  "password": "<password>",
  "username": "<username>"
}

NOTE: The Community Kubernetes Operator sets the ssl connection option to true if you Secure MongoDB Resource Connections using TLS.

You can use the connection strings in this secret in your application:

containers:
 - name: test-app
   env:
    - name: "CONNECTION_STRING"
      valueFrom:
        secretKeyRef:
          name: <metadata.name>-<auth-db>-<username>
          key: connectionString.standardSrv

Connect to one of your application's pods in the Kubernetes cluster:

NOTE: You can access your replica set only from a pod in the same Kubernetes cluster. You can't access your replica set from outside of the Kubernetes cluster.
```
kubectl -n <my-namespace> exec --stdin --tty <your-application-pod> -- /bin/bash
```
When you connect to your application pod, a shell prompt appears for your application's container:
```
user@app:~$
```
Use one of the connection strings returned in step 4 to connect to the replica set. The following example uses mongosh to connect to a replica set:
```
mongosh "mongodb+srv://<username>:<password>@example-mongodb-svc.mongodb.svc.cluster.local/admin?ssl=true"
```

Scale a Replica Set

You can scale up (increase) or scale down (decrease) the number of members in a replica set.

Consider the following example MongoDB resource definition:

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: example-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "4.2.7"

To scale a replica set:

Edit the resource definition.

Update members to the number of members that you want the replica set to have.

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: example-mongodb
spec:
  members: 5
  type: ReplicaSet
  version: "4.2.7"

Reapply the configuration to Kubernetes:
```
kubectl apply -f <example>.yaml --namespace <my-namespace>
```
NOTE: When you scale down a MongoDB resource, the Community Operator might take several minutes to remove the StatefulSet replicas for the members that you remove from the replica set.

Add Arbiters to a Replica Set

To add arbiters to your replica set, add the spec.arbiters field to your MongoDB resource definition.

The value of the spec.arbiters field must be:

a positive integer, and
less than the value of the spec.members field.

NOTE: At least one replica set member must not be an arbiter.

Consider the following MongoDB resource definition example:

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: example-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "4.2.7"

To add arbiters:

Edit the resource definition.

Add the spec.arbiters field and assign its value to the number of arbiters that you want the replica set to have.

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: example-mongodb
spec:
  members: 3
  type: ReplicaSet
  arbiters: 3
  version: "4.2.7"

If necessary, update the value of the spec.members field to ensure that you have at least one member that is not an arbiter:

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: example-mongodb
spec:
  members: 5
  type: ReplicaSet
  arbiters: 3
  version: "4.2.7"

Reapply the configuration to Kubernetes:

kubectl apply -f <example>.yaml --namespace <my-namespace>

Upgrade your MongoDB Resource Version and Feature Compatibility Version

You can upgrade the major, minor, and/or feature compatibility versions of your MongoDB resource. These settings are configured in your resource definition YAML file.

To upgrade your resource's major and/or minor versions, set the spec.version setting to the desired MongoDB version.
To modify your resource's feature compatibility version, set the spec.featureCompatibilityVersion setting to the desired version.

If you update spec.version to a later version, consider setting spec.featureCompatibilityVersion to the current working MongoDB version to give yourself the option to downgrade if necessary. To learn more about feature compatibility, see setFeatureCompatibilityVersion in the MongoDB Manual.

Example

Consider the following example MongoDB resource definition:

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: example-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "4.0.6"

To upgrade this resource from 4.0.6 to 4.2.7:

Edit the resource definition.

a. Update spec.version to 4.2.7.

b. Update spec.featureCompatibilityVersion to 4.0.

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: example-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "4.2.7"
  featureCompatibilityVersion: "4.0"

NOTE: Setting featureCompatibilityVersion to 4.0 disables 4.2 features incompatible with MongoDB 4.0.

Reapply the configuration to Kubernetes:

kubectl apply -f <example>.yaml --namespace <my-namespace>

Deploy Replica Sets on OpenShift

To deploy the operator on OpenShift you will have to provide the environment variable MANAGED_SECURITY_CONTEXT set to true for the operator deployment.

See here for an example of how to provide the required configuration for a MongoDB replica set.

See here for an example of how to configure the Operator deployment.

Define a Custom Database Role

You can define custom roles to give you fine-grained access control over your MongoDB database resource.

NOTE: Custom roles are scoped to a single MongoDB database resource.

To define a custom role:

Add the following fields to the MongoDB resource definition:

Key	Type	Description	Required?
`spec.security.authentication.ignoreUnknownUsers`	boolean	Flag that indicates whether you can add users that don't exist in the `MongoDBCommunity` resource. If omitted, defaults to `true`.	No
`spec.security.roles`	array	Array that defines custom roles roles that give you fine-grained access control over your MongoDB deployment.	Yes
`spec.security.roles.role`	string	Name of the custom role.	Yes
`spec.security.roles.db`	string	Database in which you want to store the user-defined role.	Yes
`spec.security.roles.authenticationRestrictions`	array	Array that defines the IP address from which and to which users assigned this role can connect.	No
`spec.security.roles.authenticationRestrictions.clientSource`	array	Array of IP addresses or CIDR blocks from which users assigned this role can connect. MongoDB servers reject connection requests from users with this role if the requests come from a client that is not present in this array.	No
`spec.security.roles.authenticationRestrictions.serverAddress`	array	Array of IP addresses or CIDR blocks to which users assigned this role can connect. MongoDB servers reject connection requests from users with this role if the client requests to connect to a server that is not present in this array.	No
`spec.security.roles.privileges`	array	List of actions that users granted this role can perform. For a list of accepted values, see Privilege Actions in the MongoDB Manual for the MongoDB versions you deploy with the Kubernetes Operator.	Yes
`spec.security.roles.privileges.actions`	array	Name of the role. Valid values are built-in roles.	Yes
`spec.security.roles.privileges.resource.database`	string	Database for which the privilege `spec.security.roles.privileges.actions` apply. An empty string (`""`) indicates that the privilege actions apply to all databases. If you provide a value for this setting, you must also provide a value for `spec.security.roles.privileges.resource.collection`.	Conditional
`spec.security.roles.privileges.resource.collection`	string	Collection for which the privilege `spec.security.roles.privileges.actions` apply. An empty string (`""`) indicates that the privilege actions apply to all of the database's collections. If you provide a value for this setting, you must also provide a value for `spec.security.roles.privileges.resource.database`.	Conditional
`spec.security.roles.privileges.resource.cluster`	string	Flag that indicates that the privilege `spec.security.roles.privileges.actions` apply to all databases and collections in the MongoDB deployment. If omitted, defaults to `false`. If set to `true`, do not provide values for `spec.security.roles.privileges.resource.database` and `spec.security.roles.privileges.resource.collection`.	Conditional
`spec.security.roles.roles`	array	An array of roles from which this role inherits privileges. You must include the roles field. Use an empty array (`[]`) to specify no roles to inherit from.	Yes
`spec.security.roles.roles.role`	string	Name of the role to inherit from.	Conditional
`spec.security.roles.roles.database`	string	Name of database that contains the role to inherit from.	Conditional

---
apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: custom-role-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "4.2.6"
  security:
    authentication:
      modes: ["SCRAM"]
    roles: # custom roles are defined here
      - role: testRole
        db: admin
        privileges:
          - resource:
              db: "test"
              collection: "" # an empty string indicates any collection
            actions:
              - find
        roles: []
  users:
    - name: my-user
      db: admin
      passwordSecretRef: # a reference to the secret that will be used to generate the user's password
        name: my-user-password
      roles:
        - name: clusterAdmin
          db: admin
        - name: userAdminAnyDatabase
          db: admin
        - name: testRole # apply the custom role to the user
          db: admin
      scramCredentialsSecretName: my-scram

Save the file.

Apply the updated MongoDB resource definition:

kubectl apply -f <mongodb-crd>.yaml --namespace <my-namespace>

Specify Non-Default Values for Readiness Probe

Under some circumstances it might be necessary to set your own custom values for the ReadinessProbe used by the MongoDB Community Operator. To do so, you should use the statefulSet attribute in resource.spec, as in the following provided example yaml file. Only those attributes passed will be set, for instance, given the following structure:

spec:
  statefulSet:
    spec:
      template:
        spec:
          containers:
            - name: mongodb-agent
              readinessProbe:
                failureThreshold: 40
                initialDelaySeconds: 5

Only the values of failureThreshold and initialDelaySeconds will be set to their custom, specified values. The rest of the attributes will be set to their default values.

Please note that these are the actual values set by the Operator for our MongoDB Custom Resources.

When to specify custom values for the Readiness Probe

In some cases, for instance, with a less than optimal download speed from the image registry, it could be necessary for the Operator to tolerate a Pod that has taken longer than expected to restart or upgrade to a different version of MongoDB. In these cases we want the Kubernetes API to wait a little longer before giving up, we could increase the value of failureThreshold to 60.

In other cases, if the Kubernetes API is slower than usual, we would increase the value of periodSeconds to 20, so the Kubernetes API will do half of the requests it normally does (default value for periodSeconds is 10).

Please note that these are referential values only!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

deploy-configure.md

deploy-configure.md

Deploy and Configure a MongoDB Resource

Table of Contents

Deploy a Replica Set

Scale a Replica Set

Add Arbiters to a Replica Set

Upgrade your MongoDB Resource Version and Feature Compatibility Version

Example

Deploy Replica Sets on OpenShift

Define a Custom Database Role

Specify Non-Default Values for Readiness Probe

When to specify custom values for the Readiness Probe

Files

deploy-configure.md

Latest commit

History

deploy-configure.md

File metadata and controls

Deploy and Configure a MongoDB Resource

Table of Contents

Deploy a Replica Set

Scale a Replica Set

Add Arbiters to a Replica Set

Upgrade your MongoDB Resource Version and Feature Compatibility Version

Example

Deploy Replica Sets on OpenShift

Define a Custom Database Role

Specify Non-Default Values for Readiness Probe

When to specify custom values for the Readiness Probe