Skip to content

Percona Operator for MongoDB API Documentation

Percona Operator for MongoDB provides an aggregation-layer extension for the Kubernetes API. Please refer to the official Kubernetes API documentation on the API access and usage details. The following subsections describe the Percona XtraDB Cluster API provided by the Operator.

Prerequisites

  1. Create the namespace name you will use, if not exist:

    $ kubectl create namespace my-namespace-name
    

    Trying to create an already-existing namespace will show you a self-explanatory error message. Also, you can use the defalut namespace.

    Note

    In this document default namespace is used in all examples. Substitute default with your namespace name if you use a different one.

  2. Prepare:

    # set correct API address
    KUBE_CLUSTER=$(kubectl config view --minify -o jsonpath='{.clusters[0].name}')
    API_SERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$KUBE_CLUSTER\")].cluster.server}" | sed -e 's#https://##')
    
    # create service account and get token
    kubectl apply --server-side -f deploy/crd.yaml -f deploy/rbac.yaml -n default
    KUBE_TOKEN=$(kubectl get secret $(kubectl get serviceaccount percona-server-mongodb-operator -o jsonpath='{.secrets[0].name}' -n default) -o jsonpath='{.data.token}' -n default | base64 --decode )
    

Create new Percona Server for MongoDB cluster

Description:

The command to create a new Percona Server for MongoDB cluster

Kubectl Command:

$ kubectl apply -f percona-server-mongodb-operator/deploy/cr.yaml

URL:

https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs

Authentication:

Authorization: Bearer $KUBE_TOKEN

cURL Request:

$ curl -k -v -XPOST "https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs" \
            -H "Content-Type: application/json" \
            -H "Accept: application/json" \
            -H "Authorization: Bearer $KUBE_TOKEN" \
            -d "@cluster.json"

Request Body (cluster.json):

Example

Inputs:

Metadata:

  1. Name (String, min-length: 1) : contains name of cluster

Spec:

  1. secrets[users] (String, min-length: 1) : contains name of secret for the users

  2. allowUnsafeConfigurations (Boolean, Default: false) : allow unsafe configurations to run

  3. image (String, min-length: 1) : name of the Percona Server for MongoDB cluster image

replsets:

  1. name (String, min-length: 1) : name of monogo replicaset

  2. size (Integer, min-value: 1) : contains size of MongoDB replicaset

  3. expose[exposeType] (Integer, min-value: 1) : type of service to expose replicaset

  4. arbiter (Object) : configuration for mongo arbiter

mongod:

  1. net:

    1. port (Integer, min-value: 0) : contains mongod container port

    2. hostPort (Integer, min-value: 0) : host port to expose mongod on

  2. security:

    1. enableEncryption (Boolean, Default: true) : enable encrypting mongod storage

    2. encryptionKeySecret (String, min-length: 1) : name of encryption key secret

    3. encryptionCipherMode (String, min-length: 1) : type of encryption cipher to use

  3. setParameter (Object): configure mongod enginer paramters

  4. storage:

    1. engine (String, min-length: 1, default “wiredTiger”): name of mongod storage engine

    2. inMemory (Object) : wiredTiger engine configuration

    3. wiredTiger (Object) : wiredTiger engine configuration

pmm:

  1. serverHost (String, min-length: 1) : serivce name for monitoring

  2. image (String, min-length: 1) : name of pmm image

backup:

  1. image (String, min-length: 1) : name of MngoDB backup docker image

  2. serviceAccountName (String, min-length: 1) name of service account to use for backup

  3. storages (Object) : storage configuration object for backup

Response:

Example

List Percona Server for MongoDB clusters

Description:

Lists all Percona Server for MongoDB clusters that exist in your kubernetes cluster

Kubectl Command:

$ kubectl get psmdb

URL:

https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs?limit=500

Authentication:

Authorization: Bearer $KUBE_TOKEN

cURL Request:

$ curl -k -v -XGET "https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs?limit=500" \
            -H "Accept: application/json;as=Table;v=v1;g=meta.k8s.io,application/json;as=Table;v=v1beta1;g=meta.k8s.io,application/json" \
            -H "Authorization: Bearer $KUBE_TOKEN"

Request Body:

None

Response:

Example

Get status of Percona Server for MongoDB cluster

Description:

Gets all information about specified Percona Server for MongoDB cluster

Kubectl Command:

$ kubectl get psmdb/my-cluster-name -o json

URL:

https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs/my-cluster-name

Authentication:

Authorization: Bearer $KUBE_TOKEN

cURL Request:

$ curl -k -v -XGET "https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs/my-cluster-name" \
            -H "Accept: application/json" \
            -H "Authorization: Bearer $KUBE_TOKEN"

Request Body:

None

Response:

Example

Scale up/down Percona Server for MongoDB cluster

Description:

Increase or decrease the size of the Percona Server for MongoDB cluster nodes to fit the current high availability needs

Kubectl Command:

$ kubectl patch psmdb my-cluster-name --type=merge --patch '{
"spec": {"replsets":{ "size": "5" }
}}'

URL:

https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs/my-cluster-name

Authentication:

Authorization: Bearer $KUBE_TOKEN

cURL Request:

$ curl -k -v -XPATCH "https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs/my-cluster-name" \
            -H "Authorization: Bearer $KUBE_TOKEN" \
            -H "Content-Type: application/merge-patch+json"
            -H "Accept: application/json" \
            -d '{
                  "spec": {"replsets":{ "size": "5" }
                  }}'

Request Body:

Example

Input:

spec:

replsets

  1. size (Int or String, Defaults: 3): Specifiy the sie of the replsets cluster to scale up or down to

Response:

Example

Update Percona Server for MongoDB cluster image

Description:

Change the image of Percona Server for MongoDB containers inside the cluster

Kubectl Command:

$ kubectl patch psmdb my-cluster-name --type=merge --patch '{
"spec": {"psmdb":{ "image": "percona/percona-server-mongodb-operator:1.4.0-mongod4.2" }
}}'

URL:

https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs/my-cluster-name

Authentication:

Authorization: Bearer $KUBE_TOKEN

cURL Request:

$ curl -k -v -XPATCH "https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbs/my-cluster-name" \
            -H "Authorization: Bearer $KUBE_TOKEN" \
            -H "Accept: application/json" \
            -H "Content-Type: application/merge-patch+json"
            -d '{
              "spec": {"psmdb":{ "image": "percona/percona-server-mongodb-operator:1.4.0-mongod4.2" }
              }}'

Request Body:

Example

Input:

spec:

psmdb:

  1. image (String, min-length: 1) : name of the image to update for Percona Server for MongoDB

Response:

Example

Backup Percona Server for MongoDB cluster

Description:

Takes a backup of the Percona Server for MongoDB cluster containers data to be able to recover from disasters or make a roll-back later

Kubectl Command:

$ kubectl apply -f percona-server-mongodb-operator/deploy/backup/backup.yaml

URL:

https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbbackups

Authentication:

Authorization: Bearer $KUBE_TOKEN

cURL Request:

$ curl -k -v -XPOST "https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbbackups" \
            -H "Accept: application/json" \
            -H "Content-Type: application/json" \
            -d "@backup.json" -H "Authorization: Bearer $KUBE_TOKEN"

Request Body (backup.json):

Example

Input:

  1. metadata:

name(String, min-length:1) : name of backup to create

  1. spec:
1. psmdbCluster(String, min-length:1) : `name of Percona Server for MongoDB cluster`

2. storageName(String, min-length:1) : `name of storage claim to use`

Response:

Example

Restore Percona Server for MongoDB cluster

Description:

Restores Percona Server for MongoDB cluster data to an earlier version to recover from a problem or to make a roll-back

Kubectl Command:

$ kubectl apply -f percona-server-mongodb-operator/deploy/backup/restore.yaml

URL:

https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbrestores

Authentication:

Authorization: Bearer $KUBE_TOKEN

cURL Request:

$ curl -k -v -XPOST "https://$API_SERVER/apis/psmdb.percona.com/v1/namespaces/default/perconaservermongodbrestores" \
            -H "Accept: application/json" \
            -H "Content-Type: application/json" \
            -d "@restore.json" \
            -H "Authorization: Bearer $KUBE_TOKEN"

Request Body (restore.json):

Example

Input:

  1. metadata:

name(String, min-length:1): name of restore to create

  1. spec:
1. clusterName(String, min-length:1) : `name of Percona Server for MongoDB cluster`

2. backupName(String, min-length:1) : `name of backup to restore from`

Response:

Example

Get expert help

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services. Join K8S Squad to benefit from early access to features and “ask me anything” sessions with the Experts.


Last update: 2024-02-27