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.

Installing Percona Server for MongoDB on OpenShift includes two steps:

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

Install the Operator¶

You can install Percona Operator for MongoDB on OpenShift using the web interface (the Operator Lifecycle Manager ), or using the command line interface.

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.

Following steps will allow you to deploy the Operator and Percona Server for MongoDB on your OLM installation:

Login to the OLM and click the needed Operator on the OperatorHub page:

Then click “Contiune”, and “Install”.
A new page will allow you to choose the Operator version and the Namespace / OpenShift project you would like to install the Operator into.

Click “Install” button to actually install the Operator.
When the installation finishes, you can deploy your MongoDB cluster. In the “Operator Details” you will see Provided APIs (Custom Resources, available for installation). Click “Create instance” for the PerconaServerMongoDB Custom Resource.

You will be able to edit manifest to set needed Custom Resource options, and then click “Create” button to deploy your database cluster.

Install the Operator via the command-line interface¶

Clone the percona-server-mongodb-operator repository:
```
$ git clone -b v1.20.1 https://github.com/percona/percona-server-mongodb-operator
$ cd percona-server-mongodb-operator
```
Note

It is crucial to specify the right branch with -b option while cloning the code on this step. Please be careful.
The Custom Resource Definition for Percona Server for MongoDB should be created from the deploy/crd.yaml file. The Custom Resource Definition extends the standard set of resources which Kubernetes “knows” about with the new items, in our case these items are the core of the operator.

This step should be done only once; it does not need to be repeated with other deployments.

Apply it as follows:
```
$ oc apply --server-side -f deploy/crd.yaml
```
Note

Setting Custom Resource Definition requires your user to have cluster-admin role privileges.

If you want to manage Percona Server for MongoDB cluster with a non-privileged user, the necessary permissions can be granted by applying the next 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, then you have to execute two more commands to be able to manage certificates with a non-privileged user:
```
$ oc create clusterrole cert-admin --verb="*" --resource=iissuers.certmanager.k8s.io,certificates.certmanager.k8s.io
$ oc adm policy add-cluster-role-to-user cert-admin <some-user>
```
Create a new psmdb project:
```
$ oc new-project psmdb
```
Add role-based access control (RBAC) for Percona Server for MongoDB is configured with the deploy/rbac.yaml file. RBAC is based on clearly defined roles and corresponding allowed actions. These actions are allowed on specific Kubernetes resources. The details about users and roles can be found in OpenShift documentation .
```
$ oc apply -f deploy/rbac.yaml
```
Start the Operator within OpenShift:
```
$ oc apply -f deploy/operator.yaml
```

Install Percona Server for MongoDB¶

Add the MongoDB Users secrets to OpenShift. These secrets should be placed as plain text in the stringData section of the deploy/secrets.yaml file as login name and passwords for the user accounts (see Kubernetes documentation for details).

After editing the yaml file, the secrets should be created with the following command:
```
$ oc create -f deploy/secrets.yaml
```
More details about secrets can be found in Users.
Now certificates should be generated. By default, the Operator generates certificates automatically, and no actions are required at this step. Still, you can generate and apply your own certificates as secrets according to the TLS instructions.
Percona Server for MongoDB cluster can be created at any time with the following steps:
1. Uncomment the deploy/cr.yaml field #platform: and edit the field to platform: openshift. The result should be like this:
```
apiVersion: psmdb.percona.com/v1alpha1
kind: PerconaServerMongoDB
metadata:
  name: my-cluster-name
spec:
  platform: openshift
...
```
2. (optional) In you’re using minishift, please adjust antiaffinity policy to none
```
   affinity:
     antiAffinityTopologyKey: "none"
...
```
3. Create/apply the Custom Resource file:
```
$ oc apply -f deploy/cr.yaml
```
  The creation process will take time. When the process is over your cluster will obtain the ready status. You can check it with the following command:
```
$ oc get psmdb
```
  Expected output
```
NAME              ENDPOINT                                           STATUS   AGE
my-cluster-name   my-cluster-name-mongos.default.svc.cluster.local   ready    5m26s
```

Verifying the cluster operation¶

It may take ten minutes to get the cluster started. When oc 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 you need to construct the MongoDB connection URI string. It includes the credentials of the admin user, which are stored in the Secrets object.

List the Secrets objects
```
$ oc get secrets -n <namespace>
```
The Secrets object you are interested in has the my-cluster-name-secrets name by default.
View the Secret contents to retrieve the admin user credentials.
```
$ oc get secret my-cluster-name-secrets -o yaml
```
The command returns the YAML file with generated Secrets, including the MONGODB_DATABASE_ADMIN_USER and MONGODB_DATABASE_ADMIN_PASSWORD strings, which should look as follows:
Sample output
```
...
data:
  ...
  MONGODB_DATABASE_ADMIN_PASSWORD: aDAzQ0pCY3NSWEZ2ZUIzS1I=
  MONGODB_DATABASE_ADMIN_USER: ZGF0YWJhc2VBZG1pbg==
```
The actual login name and password on the output are base64-encoded. To bring it back to a human-readable form, run:
```
$ echo 'MONGODB_DATABASE_ADMIN_USER' | base64 --decode
$ echo 'MONGODB_DATABASE_ADMIN_PASSWORD' | base64 --decode
```
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:7.0.18-11 --restart=Never -- bash -il
```
Executing it may require some time to deploy the corresponding Pod.
Now run mongosh tool inside the percona-client command shell using the admin user credentialds 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:
if sharding is onif sharding 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: 2025-06-17