Install Percona Server for MongoDB on OpenShift¶

Percona Operator for Percona Server for MongoDB is a Red Hat Certified Operator . This means that Percona Operator is portable across hybrid clouds and fully supports the Red Hat OpenShift lifecycle.

To install Percona Server for MongoDB on OpenShift means:

Install the Percona Operator for MongoDB Deployment,
Install Percona Server for MongoDB using the Operator.

Prerequisites¶

OpenShift cluster with administrative access
oc command-line tool installed
Git client installed

Before you start¶

Check the System Requirements to ensure your environment meets the necessary prerequisites.

You can install Percona Operator for MongoDB on OpenShift using either:

The Operator Lifecycle Manager web interface
The command-line interface

Choose the method that best suits your needs. The web interface is recommended for beginners, while the CLI method offers more control and automation capabilities.

Install the Operator via the Operator Lifecycle Manager (OLM)¶

Operator Lifecycle Manager (OLM) is a part of the Operator Framework that allows you to install, update, and manage the Operators lifecycle on the OpenShift platform.

Login to the OpenShift console.
Navigate to Ecosystem -> Software Catalog
Search for “Percona Distribution for MongoDB Operator” and click the needed Operator on the OperatorHub page. You may need to change the project for your user::
Then click “Continue”, and “Install”.
A new page opens where you choose the Operator version and the Namespace / OpenShift project you would like to install the Operator into. You can create a namespace (an OpenShift project) right away by clicking the Create Project and filling in project details like name, display name and description.
Click “Install”.

You can track the install process on the Installed Operators page. The Operator should report the Succeeded status.

Deploy Percona Server for MongoDB¶

Now you can deploy Percona Server for MongoDB.

Click the Operator you installed.
On the Details page, find the PerconaServerMongoDB Custom Resource.
Click “Create instance”
Edit the Custom Resource manifest to fine-tune your cluster configuration. Refer to Custom Resource reference for the description of available options.
Click “Create”
Upon successful installation, you should see the “Ready” status for the database cluster.

Install the Operator via the command-line interface¶

The following steps install the latest version of the Operator with default parameters. To install a specific version, replace the v1.23.0 tag with your value. See the full list of tags in the Operator repository on GitHub.

To install the Operator with customized parameters, see Install Percona Server for MongoDB with customized parameters.

Choose the approach that fits your needs:

Quick install — Apply a single bundle file. Use this when you want to get started quickly with default settings.
Step-by-step install — Run each installation step separately. Use this when you want more control over the installation process or you need to customize the installation.

Quick install¶

Clone the percona-server-mongodb-operator repository and change the directory to percona-server-mongodb-operator.

Important

You must specify the correct branch with the -b option while cloning the code on this step. Please be careful.
```
git clone -b v1.23.0 https://github.com/percona/percona-server-mongodb-operator
cd percona-server-mongodb-operator
```
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.
```
oc create namespace <namespace>
```
Expected output
```
namespace/<namespace> was created
```

A bundle.yaml is a Kubernetes manifest that packages Operator metadata and resources. By applying this file, Kubernetes creates the Custom Resource Definition, sets up role-based access control and installs the Operator in one single action. Replace the <namespace> placeholder with your value:

oc apply --server-side -f 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
customresourcedefinition.apiextensions.k8s.io/perconaservermongodbclustersyncs.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

Step-by-step installation¶

This section splits the installation flow into separate steps giving you more control over the process.

Step 1: Clone the repository¶

Use the following commands to clone the percona-server-mongodb-operator repository and change the directory to percona-server-mongodb-operator.

Important

You must specify the correct branch with the -b option while cloning the code on this step. Please be careful.

git clone -b v1.23.0 https://github.com/percona/percona-server-mongodb-operator
cd percona-server-mongodb-operator

Step 2: Create the Custom Resource Definition¶

At this step you must create the Custom Resource Definition for Percona Operator for MongoDB from the deploy/crd.yaml file.

The Custom Resource Definition extends the standard set of resources which Kubernetes “knows” about with new items.

You create the Custom Resource Definition only once. It is not bound to a specific namespace and all other deployments will use this Custom Resource Definition.

Use the following command to create the Custom Resource Definition:

oc apply --server-side -f deploy/crd.yaml

Warning

This step requires cluster-admin privileges. If you’re using a non-privileged user, you’ll need to set up additional permissions.

Step 3: (optional) Set up user permissions¶

If you’re using a non-privileged user, grant the required permissions by applying the following clusterrole:

oc create clusterrole psmdb-admin --verb="*" --resource=perconaservermongodbs.psmdb.percona.com,perconaservermongodbs.psmdb.percona.com/status,perconaservermongodbbackups.psmdb.percona.com,perconaservermongodbbackups.psmdb.percona.com/status,perconaservermongodbrestores.psmdb.percona.com,perconaservermongodbrestores.psmdb.percona.com/status
oc adm policy add-cluster-role-to-user psmdb-admin <some-user>

If you have a cert-manager installed, add these permissions to manage certificates with a non-privileged user:

oc create clusterrole cert-admin --verb="*" --resource=issuers.certmanager.k8s.io,certificates.certmanager.k8s.io
oc adm policy add-cluster-role-to-user cert-admin <some-user>

Step 4: Create a project¶

A project in OpenShift corresponds to a Kubernetes namespace. When you create a new project, you isolate workloads in it.

oc new-project psmdb

Sample output

Now using project “psmdb” on server “https://api.openshift-4-15-my-cluster.example.com:6443”.

The command automatically sets context to this project so that all further resources are created in it.

Step 5: Configure RBAC¶

Role-Based Access Control (RBAC) manages resource access in OpenShift. The Operator needs specific permissions to run Percona Server for MongoDB properly. These permissions are defined within roles.

oc apply -f deploy/rbac.yaml

Step 6: Deploy the Operator¶

Now you can deploy the Operator with the following command:

oc apply -f deploy/operator.yaml

Install Percona Server for MongoDB¶

After installing the Operator, you can deploy Percona Server for MongoDB. This section guides you through the process of setting up secrets, certificates, and creating your first cluster.

Step 1: Configure secrets (optional)¶

By default, the Operator generates users Secrets automatically, so you don’t have to do anything. Yet if you wish to use your own Secrets, here’s how:

Edit the deploy/secrets.yaml file to set up your MongoDB users and passwords as plain text in the stringData section. See Users and Kubernetes documentation for details.
Apply the secrets:
```
oc create -f deploy/secrets.yaml
```

Step 2: Configure certificates (optional)¶

The Operator handles certificate generation automatically, so you don’t have to do anything. However, if you need custom certificates:

Generate your certificates
Create a Secret with your certificates
Reference the Secret in your cluster configuration

See TLS instructions for detailed guidance.

Step 3: Deploy the database cluster¶

Uncomment the deploy/cr.yaml field #platform: and set it to platform: openshift. The result should look like this:

apiVersion: psmdb.percona.com/v1
kind: PerconaServerMongoDB
metadata:
  name: my-cluster-name
spec:
  platform: openshift
...

(optional) If you’re using Minishift, set the anti-affinity policy to none:
```
affinity:
  antiAffinityTopologyKey: "none"
...
```

Apply the Custom Resource file:

oc apply -f deploy/cr.yaml

Expected output

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

It may take up to 10 minutes to complete the cluster deployment. Monitor it with:

oc get psmdb

Expected output

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

The ready status indicates that your cluster is fully operational.

Verify the cluster operation¶

When oc get psmdb shows 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:
```
oc 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

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

oc 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:
```
oc 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:
```
oc 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:

oc get secret <secret-name> -n <namespace> -o jsonpath='{.data.MONGODB_DATABASE_ADMIN_USER}' | base64 --decode && echo
oc 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"

Last update: August 3, 2026
Created: August 3, 2026