percona-server-mongodb-operator

percona-server-mongodb-operator

A Kubernetes operator for Percona Server for MongoDB based on the Operator SDK.

Table of Contents

1. DISCLAIMER
2. Requirements
3. Run the Operator
4. Connect to the MongoDB Replica Set
   1. Static Endpoints List
5. Required Secrets
   1. MongoDB System Users
      1. Development Mode
   2. MongoDB Internal Authentication Key (optional)
6. Configuration
   1. Spec
   2. Secrets
   3. Replsets
   4. Mongod

DISCLAIMER

This code is incomplete, expect major issues and changes until this repo has stabilised!

Requirements

The operator was developed/tested for:

1. Percona Server for MongoDB 3.6 or greater with:
   1. Authentication enabled
   2. Replication enabled
2. Kubernetes version 1.10 to 1.11 or OpenShift 3.9 to 3.11
3. Go 1.11

Run the Operator

1. Add the 'psmdb' Namespace

   on Kubernetes:

   kubectl create namespace psmdb
   kubectl config set-context $(kubectl config current-context) --namespace=psmdb
   

   on OpenShift:

   oc new-project psmdb
   

2. Add the MongoDB Users secrets to Kubernetes. Update mongodb-users.yaml with new passwords!

   on Kubernetes:

   kubectl create -f deploy/mongodb-users.yaml
   

   on OpenShift:

   oc create -f deploy/mongodb-users.yaml
   

3. Extra step for Google Kubernetes Engine

   kubectl create clusterrolebinding cluster-admin-binding1 --clusterrole=cluster-admin --user=<myname@example.org>
   

4. Create RBAC and CustomResourceDefinition

   This step require that your user needs to have cluster-admin role privileges.

   Detailed about users and roles:

   Kubernetes: documentation

   OpenShift: documentation

   on Kubernetes:

   kubectl create -f deploy/crd.yaml
   kubectl create -f deploy/rbac.yaml
   

   on OpenShift:

   oc project mykola-psmdb
   oc create -f deploy/crd.yaml
   oc create -f deploy/rbac.yaml
   

5. Extra step for OpenShift, if you want to manage PSMDB cluster from non-privilegied user, you can grant permissions by applying next clusterrole

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

6. Start the percona-server-mongodb-operator within Kubernetes:

   kubectl create -f deploy/operator.yaml
   

7. Create the Percona Server for MongoDB cluster:

   on Kubernetes:

   kubectl apply -f deploy/cr.yaml
   

   on OpenShift:

   1. Uncomment the deploy/cr.yaml field '#platform:' and set it to 'platform: openshift'. Example:

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

   1. Create/apply the CR:

   oc apply -f deploy/cr.yaml
   

8. Wait for the operator and replica set pod reach Running state:

   $ kubectl get pods
   NAME                                               READY   STATUS    RESTARTS   AGE
   my-cluster-name-rs0-0                              1/1     Running   0          8m
   my-cluster-name-rs0-1                              1/1     Running   0          8m
   my-cluster-name-rs0-2                              1/1     Running   0          7m
   percona-server-mongodb-operator-754846f95d-sf6h6   1/1     Running   0          9m
   

Connect to the MongoDB Replica Set

1. From a 'mongo' shell add a readWrite user for use with an application (hostname/replicaSet in mongo uri may vary for your situation):

   $ kubectl run -i --rm --tty percona-client --image=percona/percona-server-mongodb:3.6 --restart=Never -- bash -il
   mongodb@percona-client:/$ mongo "mongodb+srv://userAdmin:userAdmin123456@my-cluster-name-rs0.psmdb.svc.cluster.local/admin?replicaSet=rs0&ssl=false"
   rs0:PRIMARY> db.createUser({
       user: "myApp",
       pwd: "myAppPassword",
       roles: [
         { db: "myApp", role: "readWrite" }
       ]
   })
   Successfully added user: {
   	"user" : "myApp",
   	"roles" : [
   		{
   			"db" : "myApp",
   			"role" : "readWrite"
   		}
   	]
   }
   

2. Again from a 'mongo' shell, insert and retrieve a test document in the 'myApp' database as the new application user:

   $ kubectl run -i --rm --tty percona-client --image=percona/percona-server-mongodb:3.6 --restart=Never -- bash -il
   mongodb@percona-client:/$ mongo "mongodb+srv://myApp:myAppPassword@my-cluster-name-rs0.psmdb.svc.cluster.local/admin?replicaSet=rs0&ssl=false"
   rs0:PRIMARY> use myApp
   switched to db myApp
   rs0:PRIMARY> db.test.insert({ x: 1 })
   WriteResult({ "nInserted" : 1 })
   rs0:PRIMARY> db.test.findOne()
   { "_id" : ObjectId("5bc74ef05c0ec73be760fcf9"), "x" : 1 }
   

Static Endpoints List

If you prefer to use a static server list (instead of using mongodb+srv:// to detect servers) use 'kubectl describe service' to gather the list of endpoints.

Example (see 'Endpoints:' below): $ kubectl describe service my-cluster-name-rs0 | grep 'Endpoints:' Endpoints: 172.17.0.10:27017,172.17.0.12:27017,172.17.0.9:27017

Required Secrets

The operator requires Kubernetes Secrets to be deployed before it is started.

The name of the required secrets can be set in deploy/cr.yaml under the section spec.secrets.

MongoDB System Users

Default Secret name: my-cluster-name-mongodb-users Secret name field: spec.secrets.users

The operator requires system-level MongoDB Users to automate the MongoDB deployment. These users should not be used to run an application!

Development Mode

Note: Do not use the default MongoDB Users in Production!

To make development/testing easier a secrets file with default MongoDB System User/Passwords is located at 'deploy/mongodb-users.yaml'.

The development-mode credentials from deploy/mongodb-users.yaml are:

MongoDB Internal Authentication Key (optional)

Default Secret name: my-cluster-name-mongodb-key Secret name field: spec.secrets.key

By default, the operator will create a random, 1024-byte key for MongoDB Internal Authentication if it does not already exist.

If you would like to deploy a different key, create the secret manually before starting the operator.

Configuration

The operator is configured via the spec section of the deploy/cr.yaml file.

Spec

YAML Path: spec

Secrets

YAML Path: spec.secrets

Replsets

YAML Path: spec.replsets

Mongod

YAML Path: spec.mongod