Install Percona Server for MongoDB using kubectl¶

A Kubernetes Operator is a special type of controller introduced to simplify complex deployments. The Operator extends the Kubernetes API with custom resources.

The Percona Operator for MongoDB is based on best practices for configuration and setup of a Percona Server for MongoDB and Percona Backup for MongoDB in a Kubernetes-based environment on-premises or in the cloud.

We recommend installing the Operator with the kubectl command line utility. It is the universal way to interact with Kubernetes. Alternatively, you can install it using the Helm package manager.

Install with kubectl Install with Helm

Prerequisites¶

To install Percona Distribution for MongoDB, you need the following:

The kubectl tool to manage and deploy applications on Kubernetes, included in most Kubernetes distributions. If you don’t have it installed, you can install it by following the official installation instructions .
A Kubernetes environment. You can deploy it on Minikube for testing purposes or using any cloud provider of your choice. Check the list of our officially supported platforms.
See also

What you will install¶

The Operator - the custom controller that uses the custom resources to install and manage the lifecycle of your database cluster. It consists of the following components:
- the Operator Deployment - the controller Pod
- the CustomResourceDefinitions (CRDs) are a way to add new API types (custom resources) to Kubernetes so that it understands and handles them
- Role-based access control (RBAC) is the system that controls who can perform which actions on which resources, using roles and bindings to enforce safe, predictable access.
The database cluster - the actual Percona Server for MongoDB cluster that the Operator creates for you when you apply the Custom Resource or install the Helm chart. It includes StatefulSets for mongod/mongos/config servers, Services, Secrets, and optional components like backups and PMM.

The default Percona Server for MongoDB configuration includes three mongod, three mongos, and three config server instances with enabled sharding.

Procedure¶

Here’s a sequence of steps to follow:

Create the Kubernetes namespace for your cluster. It is a good practice to isolate workloads in Kubernetes by installing the Operator in a custom namespace. Replace the <namespace> placeholder with your value.
```
kubectl create namespace <namespace>
```
Expected output
```
namespace/<namespace> was created
```

Deploy the Operator using the following command:

kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.22.0/deploy/bundle.yaml -n <namespace>

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

As the result you will have the Operator Pod up and running.

Deploy Percona Server for MongoDB:

kubectl apply -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.22.0/deploy/cr.yaml -n <namespace>

Expected output

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

Check the Operator and the Percona Server for MongoDB Pods status.

kubectl get psmdb -n <namespace>

The creation process may take some time. When the process is over your cluster obtains the ready status.

Expected output

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

You have successfully installed and deployed the Operator with default parameters.

You can check the rest of the Operator’s parameters in the Custom Resource options reference.

Next steps¶

Connect to Percona Server for MongoDB

Useful links¶

Install Percona Server for MongoDB with customized parameters

Last update: March 4, 2026
Created: March 4, 2026