MongoDB Community Kubernetes Operator

This is a Kubernetes Operator which deploys MongoDB Community into Kubernetes clusters.

If you are a MongoDB Enterprise customer, or need Enterprise features such as Backup, you can use the MongoDB Enterprise Operator for Kubernetes.

Install the Operator
- Prerequisites
- Procedure
Upgrade the Operator
Deploy & Configure MongoDB Resources
- Deploy a Replica Set
- Upgrade MongoDB Version & FCV
Supported Features
Contribute
License

Install the Operator

Prerequisites

Before you install the MongoDB Community Kubernetes Operator, you must:

Install kubectl.
Have a Kubernetes solution available to use. If you need a Kubernetes solution, see the Kubernetes documentation on picking the right solution. For testing, MongoDB recommends Kind.

Clone this repository.

git clone https://github.com/mongodb/mongodb-kubernetes-operator.git

Procedure

The MongoDB Community Kubernetes Operator is a Custom Resource Definition and a controller.

To install the MongoDB Community Kubernetes Operator:

Change to the directory in which you cloned the repository.
Install the Custom Resource Definitions.

a. Invoke the following kubectl command:
```
kubectl create -f deploy/crds/mongodb.com_mongodb_crd.yaml
```
b. Verify that the Custom Resource Definitions installed successfully:
```
kubectl get crd/mongodb.mongodb.com
```
Install the Operator.

a. Invoke the following kubectl command to install the Operator in the specified namespace:
```
kubectl create -f deploy/ --namespace <my-namespace>
```
b. Verify that the Operator installed successsfully:
```
kubectl get pods --namespace <my-namespace>
```

Upgrade the Operator

To upgrade the MongoDB Community Kubernetes Operator:

Change to the directory in which you cloned the repository.
Invoke the following kubectl command to upgrade the Custom Resource Definitions.
```
kubectl apply -f deploy/crds/mongodb.com_mongodb_crd.yaml
```

Deploy and Configure a MongoDB Resource

The /deploy/crds directory contains example MongoDB resources that you can modify and deploy.

Deploy a Replica Set

To deploy your first replica set:

Invoke the following kubectl command:

kubectl apply -f deploy/crds/mongodb.com_v1_mongodb_cr.yaml --namespace <my-namespace>

Verify that the MongoDB resource deployed:

kubectl get mongodb --namespace <my-namespace>

Upgrade your MongoDB Resource Version and Feature Compatibility Version

You can upgrade the major, minor, and/or feature compatibility versions of your MongoDB resource. These settings are configured in your resource definition YAML file.

To upgrade your resource's major and/or minor versions, set the spec.version setting to the desired MongoDB version.
To modify your resource's feature compatibility version, set the spec.featureCompatibilityVersion setting to the desired version.

If you update spec.version to a later version, consider setting spec.featureCompatibilityVersion to the current working MongoDB version to give yourself the option to downgrade if necessary. To learn more about feature compatibility, see setFeatureCompatibilityVersion in the MongoDB Manual.

Example

Consider the following example MongoDB resource definition:

apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: example-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "4.0.6"

To upgrade this resource from 4.0.6 to 4.2.7:

Edit the resource definition.

a. Update spec.version to 4.2.7.

b. Update spec.featureCompatibilityVersion to 4.0.
```
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: example-mongodb
spec:
  members: 3
  type: ReplicaSet
  version: "4.2.7"
  featureCompatibilityVersion: "4.0"
```
NOTE: Setting featureCompatibilityVersion to 4.0 disables 4.2 features incompatible with MongoDB 4.0.

Reapply the configuration to Kubernetes:

kubectl apply -f <example>.yaml --namespace <my-namespace>

Supported Features

The MongoDB Community Kubernetes Operator supports the following features:

MongoDB Topology: replica sets
Upgrading and downgrading MongoDB server version
Scaling replica sets up and down
Reading from and writing to the replica set while scaling, upgrading, and downgrading. These operations are done in an "always up" manner.
Reporting of MongoDB server state via the MongoDB resource status field
Use of any of the available Docker MongoDB images
Clients inside the Kubernetes cluster can connect to the replica set (no external connectivity)

Planned Features

TLS support for client/server communication
Server internal authentication via keyfile
Creating users with SCRAM-SHA authentication

Contribute

Before you contribute to the MongoDB Community Kubernetes Operator, please read:

Please file issues before filing PRs. For PRs to be accepted, contributors must sign our CLA.

Reviewers, please ensure that the CLA has been signed by referring to the contributors tool (internal link).

License

The source code of this Operator is available under the Apache v2 license.

The MongoDB Agent binary in the agent/ directory may be used under the "Free for Commercial Use" license found in agent/LICENSE.

zavgorodny/mongodb-kubernetes-operator