Create and connect to a MongoDB cluster

This tutorial shows how to create and connect to a MongoDB cluster.

Create a MongoDB cluster

Before you start

• Install kbcli if you want to create and connect a MySQL cluster by kbcli.

• Install KubeBlocks.

• Make sure the MongoDB Addon is enabled. If this addon is not enabled, enable it first.

  kbcli

  kbcli addon list
  >
  NAME                           TYPE   STATUS     EXTRAS         AUTO-INSTALL   
  ...
  mongodb                        Helm   Enabled                   true
  ...

  kubectl

  kubectl get addons.extensions.kubeblocks.io mongodb
  >
  NAME      TYPE   VERSION   PROVIDER   STATUS    AGE
  mongodb   Helm                        Enabled   23m

• View all the database types and versions available for creating a cluster.

  kbcli

  kbcli clusterdefinition list
  
  kbcli clusterversion list

  kubectl

  kubectl get clusterdefinition mongodb
  >
  NAME      TOPOLOGIES   SERVICEREFS   STATUS      AGE
  mongodb                              Available   23m

  kubectl get clusterversions -l clusterdefinition.kubeblocks.io/name=mongodb

• To keep things isolated, create a separate namespace called demo throughout this tutorial.

  kubectl create namespace demo
  >
  namespace/demo created

Create a cluster

KubeBlocks supports creating two types of MongoDB clusters: Standalone and ReplicaSet. Standalone only supports one replica and can be used in scenarios with lower requirements for availability. For scenarios with high availability requirements, it is recommended to create a ReplicaSet, which creates a cluster with two replicas to support automatic failover. To ensure high availability, all replicas are distributed on different nodes by default.

kbcli

1. Create a MongoDB cluster.

   kbcli cluster create mycluster --cluster-definition mongodb -n demo

   The commands above are some common examples to create a cluster with default settings. If you want to customize your cluster specifications, kbcli provides various options, such as setting cluster version, termination policy, CPU, and memory. You can view these options by adding --help or -h flag.

   kbcli cluster create mongodb --help
   kbcli cluster create mongodb -h

2. Verify whether this cluster is created successfully.

   kbcli cluster list -n demo
   >
   NAME        NAMESPACE   CLUSTER-DEFINITION   VERSION           TERMINATION-POLICY   STATUS    CREATED-TIME
   mycluster   demo        mongodb              mongodb-5.0       Delete               Running   Sep 20,2024 10:01 UTC+0800

kubectl

1. Create a MongoDB Standalone.

   KubeBlocks implements a Cluster CRD to define a cluster. Here is an example of creating a MongoDB Standalone.

   If you only have one node for deploying a ReplicaSet Cluster, set spec.affinity.topologyKeys as null. But for a production environment, it is not recommended to deploy all replicas on one node, which may decrease the cluster availability.

   cat <<EOF | kubectl apply -f -
   apiVersion: apps.kubeblocks.io/v1alpha1
   kind: Cluster
   metadata:
     name: mycluster
     namespace: demo
   spec:
     affinity:
       podAntiAffinity: Preferred
       tenancy: SharedNode
       topologyKeys:
       - kubernetes.io/hostname
     componentSpecs:
     - componentDef: mongodb
       name: mongodb
       replicas: 3
       resources:
         limits:
           cpu: "0.5"
           memory: 0.5Gi
         requests:
           cpu: "0.5"
           memory: 0.5Gi
       serviceVersion: 6.0.16
       volumeClaimTemplates:
       - name: data
         spec:
           accessModes:
           - ReadWriteOnce
           resources:
             requests:
               storage: 20Gi
     terminationPolicy: Delete
   EOF

   Field	Definition
   spec.terminationPolicy	It is the policy of cluster termination. The default value is Delete. Valid values are DoNotTerminate, Delete, WipeOut. For the detailed definition, you can refer to Termination Policy.
   spec.affinity	It defines a set of node affinity scheduling rules for the cluster's Pods. This field helps control the placement of Pods on nodes within the cluster.
   spec.affinity.podAntiAffinity	It specifies the anti-affinity level of Pods within a component. It determines how pods should spread across nodes to improve availability and performance.
   spec.affinity.topologyKeys	It represents the key of node labels used to define the topology domain for Pod anti-affinity and Pod spread constraints.
   spec.tolerations	It is an array that specifies tolerations attached to the cluster's Pods, allowing them to be scheduled onto nodes with matching taints.
   spec.componentSpecs	It is the list of components that define the cluster components. This field allows customized configuration of each component within a cluster.
   spec.componentSpecs.componentDefRef	It is the name of the component definition that is defined in the cluster definition and you can get the component definition names with kubectl get clusterdefinition mongodb -o json \| jq '.spec.componentDefs[].name'.
   spec.componentSpecs.name	It specifies the name of the component.
   spec.componentSpecs.replicas	It specifies the number of replicas of the component.
   spec.componentSpecs.resources	It specifies the resource requirements of the component.

   KubeBlocks operator watches for the Cluster CRD and creates the cluster and all dependent resources. You can get all the resources created by the cluster by running the command below.

   kubectl get all,secret,rolebinding,serviceaccount -l app.kubernetes.io/instance=mycluster -n demo

   Run the following command to view the created MongoDB cluster object.

   kubectl get cluster mycluster -n demo -o yaml

2. Verify whether this cluster is created successfully.

   kubectl get cluster mycluster -n demo
   >
   NAME        CLUSTER-DEFINITION   VERSION           TERMINATION-POLICY   STATUS    AGE
   mycluster   mongodb              mongodb-5.0       Delete               Running   12m

Connect to a MongoDB Cluster

kbcli

kbcli cluster connect mycluster -n demo

kubectl

You can use kubectl exec to exec into a Pod and connect to a database.

KubeBlocks operator has created a new Secret called mycluster-conn-credential to store the connection credential of the MongoDB cluster. This secret contains the following keys:

• username: the root username of the MongoDB cluster.
• password: the password of the root user.
• port: the port of the MongoDB cluster.
• host: the host of the MongoDB cluster.
• endpoint: the endpoint of the MongoDB cluster and it is the same as host:port.

1. Get the username and password to connect to this MongoDB cluster for the kubectl exec command.

   kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.username}' | base64 -d
   >
   root
   
   kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.password}' | base64 -d
   >
   266zfqx5

2. Exec into the Pod mycluster-mongodb-0 and connect to the database using username and password.

   kubectl exec -ti -n demo mycluster-mongodb-0 -- bash
   
   root@mycluster-mongodb-0:/# mongo --username root --password 266zfqx5 --authenticationDatabase admin

port-forward

You can also port forward the service to connect to the database from your local machine.

1. Run the following command to port forward the service.

   kubectl port-forward -n demo svc/mycluster-mongodb 27017:27017  

2. Open a new terminal and run the following command to connect to the database.

   root@mycluster-mongodb-0:/# mongo --username root --password 266zfqx5 --authenticationDatabase admin

For the detailed database connection guide, refer to Connect database.