Configure concurrency for a cluster reconciliation

Reconciliation is the process by which the Operator continuously compares the desired state with the actual state of the cluster. The desired state is defined in a Kubernetes custom resource, like PerconaServerMongoDB.

If the actual state does not match the desired state, the Operator takes actions to bring the system into alignment. This means creating, updating, or deleting Kubernetes resources (Pods, Services, ConfigMaps, etc.) or performing database-specific operations like scaling, backups, or failover.

Reconciliation is triggered by a variety of events, including:

• Changes to the cluster configuration
• Changes to the cluster state
• Changes to the cluster resources

You can tune reconciliation behavior with two environment variables in the percona-server-mongodb-operator Deployment:

• MAX_CONCURRENT_RECONCILES — how many clusters the Operator can reconcile in parallel
• RECONCILE_INTERVAL — how long the Operator waits before re-queuing reconciliation for each cluster

See Configure Operator environment variables for the full list of supported values and defaults.

Configure concurrent reconciliation workers

By default, the Operator has one reconciliation worker. This means that if you deploy or update 2 clusters at the same time, the Operator will reconcile them sequentially.

The MAX_CONCURRENT_RECONCILES environment variable controls the number of concurrent workers that can reconcile resources in Percona Server for MongoDB clusters in parallel.

Thus, to extend the previous example, if you set the number of reconciliation workers to 2, the Operator will reconcile both clusters in parallel. This also helps you with benchmarking the Operator performance.

The general recommendation is to set the number of concurrent workers equal to the number of Percona Server for MongoDB clusters. When the number of workers is greater, the excessive workers will remain idle.

Set the number of reconciliation workers

1. Check the index of the MAX_CONCURRENT_RECONCILES environment variable using the following command:

   kubectl get deployment percona-server-mongodb-operator -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="MAX_CONCURRENT_RECONCILES")].value}'
   

   Sample output

   1
   

2. To set a new value and verify it’s been updated, run the following command:

   kubectl patch deployment percona-server-mongodb-operator \
   --type='strategic' \
   -o yaml \
   -p='{
       "spec": {
           "template": {
               "spec": {
                   "containers": [
                       {
                           "name": "percona-server-mongodb-operator",
                           "env": [
                               {
                                   "name": "MAX_CONCURRENT_RECONCILES",
                                   "value": "2"
                               }
                           ]
                       }
                   ]
               }
           }
       }
   }'\
   -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="MAX_CONCURRENT_RECONCILES")].value}'
   

The command does the following:

• Patches the deployment to update the MAX_CONCURRENT_RECONCILES environment variable
• Sets the value to 2.
• Outputs the result

You can set the value to any number greater than 0.

Sample output

2

Configure the reconciliation interval

After each reconcile loop, the Operator schedules the next one using the RECONCILE_INTERVAL environment variable. The default is 5s.

Increasing this value reduces Kubernetes API traffic from the Operator. This can be useful in large environments where the default interval generates more requests than needed. Values below 5s, zero, negative, or invalid duration strings fall back to 5s.

Set the reconciliation interval

1. Check the current value:

   kubectl -n <namespace> get deployment percona-server-mongodb-operator -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="RECONCILE_INTERVAL")].value}'
   

   Sample output

   5s
   

2. To set a new value and verify it’s been updated, run the following command:

   kubectl -n <namespace> patch deployment percona-server-mongodb-operator \
   --type='strategic' \
   -o yaml \
   -p='{
       "spec": {
           "template": {
               "spec": {
                   "containers": [
                       {
                           "name": "percona-server-mongodb-operator",
                           "env": [
                               {
                                   "name": "RECONCILE_INTERVAL",
                                   "value": "30s"
                               }
                           ]
                       }
                   ]
               }
           }
       }
   }'\
   -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="RECONCILE_INTERVAL")].value}'
   

The command does the following:

• Patches the deployment to update the RECONCILE_INTERVAL environment variable
• Sets the value to 30s
• Outputs the result

Sample output

30s

---

Last update: July 20, 2026
Created: July 20, 2026