Install Percona Server for MongoDB on Rancher Kubernetes Engine (RKE2)¶

This guide shows you how to deploy Percona Operator for MongoDB on Rancher Kubernetes Engine (RKE2) . RKE2 is a CNCF-certified Kubernetes distribution that you can run standalone or manage with the Rancher Kubernetes management platform.

The document assumes some experience with the platform. For more information, see the RKE2 official documentation .

Prerequisites¶

The following tools and access are required:

Linux hosts that meet the RKE2 requirements . For a production-like setup, use at least 3 nodes so the Operator can schedule a replica set according to the system requirements.
Root or sudo access on each host to install and start RKE2 services.
kubectl to manage and deploy applications on Kubernetes. Install it following the official installation instructions . RKE2 also ships a kubectl binary under /var/lib/rancher/rke2/bin/ on server nodes.
Optionally, a Rancher management server if you prefer to provision and manage the RKE2 cluster from the Rancher UI instead of installing RKE2 manually. See the Rancher documentation .

Create the RKE2 cluster¶

You can create the cluster with the RKE2 installation script or provision it through Rancher . Both approaches give you a standard Kubernetes API endpoint that the Operator uses.

Configure kubectl access¶

On a server node, RKE2 writes the kubeconfig to /etc/rancher/rke2/rke2.yaml. Copy it to your workstation and point kubectl at it:

mkdir -p ~/.kube
sudo cat /etc/rancher/rke2/rke2.yaml > ~/.kube/rke2.yaml
export KUBECONFIG=~/.kube/rke2.yaml

If you connect from a remote machine, replace 127.0.0.1 in the kubeconfig server: URL with the reachable address of your RKE2 server node.

Verify that the nodes are ready:

kubectl get nodes

Configure storage¶

Percona Server for MongoDB needs PersistentVolumes for database data. Confirm that your cluster has a default StorageClass (or note the StorageClass name to set in the Custom Resource):

kubectl get storageclass

RKE2 does not always ship a default StorageClass. For testing, you can install the Local Path Provisioner . For production, use a CSI driver appropriate for your infrastructure, such as Longhorn when you manage the cluster with Rancher.

Install the Operator and deploy your MongoDB cluster¶

Deploy the Operator. By default deployment will be done in the default namespace. If that’s not the desired one, you can create a new namespace and/or set the context for the namespace as follows (replace the <namespace name> placeholder with some descriptive name):

kubectl create namespace <namespace name>
kubectl config set-context $(kubectl config current-context) --namespace=<namespace name>

At success, you will see the message that namespace/<namespace name> was created, and the context was modified.

Deploy the Operator, using the following command:

kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.23.0/deploy/bundle.yaml

Expected output

customresourcedefinition.apiextensions.k8s.io/perconaservermongodbs.psmdb.percona.com serverside-applied
customresourcedefinition.apiextensions.k8s.io/perconaservermongodbbackups.psmdb.percona.com serverside-applied
customresourcedefinition.apiextensions.k8s.io/perconaservermongodbrestores.psmdb.percona.com serverside-applied
role.rbac.authorization.k8s.io/percona-server-mongodb-operator serverside-applied
serviceaccount/percona-server-mongodb-operator serverside-applied    
rolebinding.rbac.authorization.k8s.io/service-account-percona-server-mongodb-operator serverside-applied
deployment.apps/percona-server-mongodb-operator serverside-applied

The Operator has been started, and you can deploy your MongoDB cluster:

kubectl apply -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.23.0/deploy/cr.yaml

Expected output

perconaservermongodb.psmdb.percona.com/my-cluster-name created

The creation process may take some time. When the process is over your cluster will obtain the ready status. You can check it with the following command:

kubectl get psmdb

Expected output

NAME              ENDPOINT                                           STATUS   AGE
my-cluster-name   my-cluster-name-mongos.default.svc.cluster.local   ready    5m26s

Congratulations! You have deployed Percona Server for MongoDB with the default configuration, which includes three mongod, three mongos, and three config server instances.

For how to install Percona Server for MongoDB with customize parameters, see Install Percona Operator for MongoDB with customized parameters.

Verifying the cluster operation¶

It may take ten minutes to get the cluster started. When kubectl get psmdb command finally shows you the cluster status as ready, you can try to connect to the cluster.

To connect to Percona Server for MongoDB, use the connection string Secret that the Operator creates for the databaseAdmin user. This Secret is available starting with Operator version 1.23.0 and newer. For previous versions, refer to the Connect manually section.

List the Secrets objects:
```
kubectl get secrets -n <namespace>
```
The connection string Secret is named my-cluster-name-databaseadmin-conn-str by default.

Retrieve the connection string

Sharding is onSharding is off

kubectl get secret <clusterName>-databaseadmin-conn-str -n <namespace> \
 -o jsonpath='{.data.databaseAdmin_mongos_connectionString}' | base64 --decode && echo

kubectl get secret <clusterName>-databaseadmin-conn-str -n <namespace> \
-o jsonpath='{.data.databaseAdmin_rs0_connectionStringSrv}' | base64 --decode && echo

See Connection secrets for other available keys.

Run a container with a MongoDB client and connect its console output to your terminal. The following command does this, naming the new Pod percona-client:
```
kubectl run -i --rm --tty percona-client --image=percona/percona-server-mongodb:8.0.26-11 --restart=Never -- bash -il
```
Executing it may require some time to deploy the corresponding Pod.
Connect using the connection string from step 2:
```
mongosh "<connection-string>"
```

Connect manually (alternative)¶

If you need to build a connection URI yourself, retrieve credentials from the user Secret and construct the URI.

List the Secrets objects:
```
kubectl get secrets -n <namespace>
```
The Secrets object you are interested in has the <cluster-name>-secrets name. (For the cluster my-cluster-name, the Secret name is my-cluster-name-secrets).

Retrieve the admin username and password:

kubectl get secret <secret-name> -n <namespace> -o jsonpath='{.data.MONGODB_DATABASE_ADMIN_USER}' | base64 --decode && echo
kubectl get secret <secret-name> -n <namespace> -o jsonpath='{.data.MONGODB_DATABASE_ADMIN_PASSWORD}' | base64 --decode && echo

Run a container with a MongoDB client and connect its console output to your terminal. The following command does this, naming the new Pod percona-client:
```
kubectl -n <namespace> run -i --rm --tty percona-client --image=percona/percona-server-mongodb:8.0.26-11 --restart=Never -- bash -il
```
It may take some time to deploy the corresponding Pod.
Now run mongosh tool inside the percona-client command shell using the admin user credentials you obtained from the Secret, and a proper namespace name instead of the <namespace name> placeholder. The command will look different depending on whether sharding is on (the default behavior) or off:
sharding is onsharding is off
mongosh "mongodb://databaseAdmin:databaseAdminPassword@my-cluster-name-mongos.<namespace name>.svc.cluster.local/admin?ssl=false"
mongosh "mongodb+srv://databaseAdmin:databaseAdminPassword@my-cluster-name-rs0.<namespace name>.svc.cluster.local/admin?replicaSet=rs0&ssl=false"

Troubleshooting¶

If kubectl get psmdb command doesn’t show ready status too long, you can check the creation process with the kubectl get pods command:

kubectl get pods

Expected output

NAME                                               READY   STATUS    RESTARTS   AGE
my-cluster-name-cfg-0                              2/2     Running   0          11m
my-cluster-name-cfg-1                              2/2     Running   1          10m
my-cluster-name-cfg-2                              2/2     Running   1          9m
my-cluster-name-mongos-0                           1/1     Running   0          11m
my-cluster-name-mongos-1                           1/1     Running   0          11m
my-cluster-name-mongos-2                           1/1     Running   0          11m
my-cluster-name-rs0-0                              2/2     Running   0          11m
my-cluster-name-rs0-1                              2/2     Running   0          10m
my-cluster-name-rs0-2                              2/2     Running   0          9m
percona-server-mongodb-operator-665cd69f9b-xg5dl   1/1     Running   0          37m

If the command output had shown some errors, you can examine the problematic Pod with the kubectl describe <pod name> command as follows:

kubectl describe pod my-cluster-name-rs0-2

Review the detailed information for Warning statements and then correct the configuration. An example of a warning is as follows:

Warning FailedScheduling 68s (x4 over 2m22s) default-scheduler 0/1 nodes are available: 1 node(s) didn’t match pod affinity/anti-affinity, 1 node(s) didn’t satisfy existing pods anti-affinity rules.

If Pods stay in the Pending state because volumes cannot be provisioned, confirm that a StorageClass exists and that your Custom Resource references the correct one.

Removing the RKE2 cluster¶

To tear down a manually installed RKE2 cluster, run the uninstall script on each node (agent nodes first, then server nodes):

/usr/local/bin/rke2-uninstall.sh

If you provisioned the cluster with Rancher, delete the cluster from the Rancher UI instead.

Warning

After deleting the cluster, all data stored in it will be lost!

Last update: July 23, 2026
Created: July 23, 2026