deploy-configure.md

Deploy and Configure a MongoDBCommunity Resource

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

Table of Contents

• Deploy a Replica Set
• Scale a Replica Set
• Add Arbiters to a Replica Set
• Upgrade your MongoDBCommunity 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

Deploy a Replica Set

Warning: When you delete MongoDB resources, persistent volumes remain to help ensure that no unintended data loss occurs. If you create a new MongoDB resource with the same name and persistent volumes, the pre-existing data might cause issues if the new MongoDB resources have a different topology than the previous ones.

To deploy your first replica set:

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

2. Invoke the following kubectl command:

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

3. Verify that the MongoDBCommunity resource deployed:

   kubectl get mongodbcommunity --namespace <my-namespace>
   

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

   NOTE: Alternatively, you can specify an optional users[i].connectionStringSecretName field in the MongoDBCommunity custom resource to specify the name of the connection string secret that the Community Kubernetes Operator creates.

   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 <connection-string-secret-name> -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 MongoDBCommunity 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
   

5. 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:~$
   

6. 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 MongoDBCommunity 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:

1. 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"

2. Reapply the configuration to Kubernetes:

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

   NOTE: When you scale down a MongoDBCommunity 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 MongoDBCommunity resource definition. This attribute configures the absolute amount of arbiters in this Replica Set, this is, the amount of mongod instances will be spec.members + spec.arbiters.

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 MongoDBCommunity resource definition example, with a PSS (Primary-Secondary-Secondary) configuration:

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

To add arbiters:

1. 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:
     type: ReplicaSet
     members: 3
     arbiters: 1
     version: "4.4.13"

2. Reapply the configuration to Kubernetes:

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

The resulting Replica Set has a PSSA (Primary-Secondary-Secondary-Arbiter) configuration.

Upgrade your MongoDBCommunity Resource Version and Feature Compatibility Version

You can upgrade the major, minor, and/or feature compatibility versions of your MongoDBCommunity 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. Make sure to specify a full image tag, such as 5.0.3. Setting the spec.version to loosely-defined tags such as 5.0 is not currently supported.

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

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

2. 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:

1. Add the following fields to the MongoDBCommunity 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

2. Save the file.

3. Apply the updated MongoDBCommunity 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!

Operator Configurations

Modify cluster domain for MongoDB service objects

To configure the cluster domain for the MongoDB service object, i.e use a domain other than the default cluster.local you can specify it as an environment variable in the operator deployment under CLUSTER_DOMAIN key.

For ex:

env:
  - name: CLUSTER_DOMAIN
    value: $CUSTOM_DOMAIN