Quick Start for the Kubernetes Operator

Add the MongoDB Helm Charts for Kubernetes repository to Helm.

helm repo add mongodb https://mongodb.github.io/helm-charts

Install the MongoDB Controllers for Kubernetes Operator

To install the Kubernetes Operator with Helm, see the instructions in the repository.

Example

The following command installs the MongoDB Controllers for Kubernetes Operator in the mongodb namespace with the optional --create-namespace option. By default, Kubernetes Operator uses the default namespace.

helm install kubernetes-operator mongodb/mongodb-kubernetes --namespace mongodb --create-namespace

Configure kubectl to default to your namespace.

If you haven't already, run the following command to execute all kubectl commands in the namespace you created:

kubectl config set-context $(kubectl config current-context) --namespace=mongodb

Create the Ops Manager admin credentials secret.

Create a secret that contains the initial Ops Manager admin user credentials. The Kubernetes Operator uses this secret to configure the first admin user when it deploys the Ops Manager resource.

Run the following command, replacing the placeholder values with your preferred credentials:

kubectl create secret generic ops-manager-admin-secret \
  --from-literal=Username="<admin-email>" \
  --from-literal=Password="<admin-password>" \
  --from-literal=FirstName="<first-name>" \
  --from-literal=LastName="<last-name>"

Deploy the Ops Manager resource.

1. Copy and save the following YAML file as ops-manager.yaml:

   apiVersion: mongodb.com/v1
   kind: MongoDBOpsManager
   metadata:
     name: ops-manager
     namespace: mongodb
   spec:
     replicas: 1
     version: "8.0.0"
     adminCredentials: ops-manager-admin-secret
     externalConnectivity:
       type: NodePort
     configuration:
       mms.ignoreInitialUiSetup: "true"
       automation.versions.source: "mongodb"
       mms.fromEmailAddr: admin@example.com
       mms.replyToEmailAddr: admin@example.com
       mms.adminEmailAddr: admin@example.com
       mms.mail.transport: smtp
       mms.mail.hostname: localhost
       mms.mail.port: "25"
     backup:
       enabled: false
     applicationDatabase:
       topology: SingleCluster
       members: 3
       version: "8.0.0"

   To learn more, see the Ops Manager Resource Specification.

2. Run the following command:

   kubectl apply -f ops-manager.yaml

Wait for the Ops Manager resource to reach the Running state.

The Kubernetes Operator first deploys the Application Database replica set, then starts the Ops Manager application. This process can take several minutes.

Run the following command to track the resource status:

kubectl get om -o yaml -w

Wait until the output shows the following phases:

status:
  applicationDatabase:
    phase: Running
  opsManager:
    phase: Running

When both components reach Running, retrieve the Ops Manager URL:

kubectl get om ops-manager -o jsonpath='{.status.opsManager.url}'

Note this URL. You need it for the ConfigMap in a later step.

Configure the Kubernetes Operator for Ops Manager.

You can use the Ops Manager UI to generate the ConfigMap and Secret, or you can create them manually.

First, forward the Ops Manager service port to your local machine so you can access the UI in your browser:

kubectl port-forward svc/ops-manager-svc-ext 8080:8080

Then, open http://localhost:8080 in your browser and log in with the credentials you created in the admin secret.

To use the Ops Manager UI:

1. Go to the Kubernetes Setup Page in the Ops Manager UI.

2. Click Create New API Keys or Use Existing API Keys.

3. Complete the form. To learn more, see Create Credentials for the Kubernetes Operator.

4. Click Generate Key and YAML.

Alternatively, you can create the ConfigMap and Secret manually in the following steps.

Create and save the ConfigMap.

If you generated the ConfigMap from the Ops Manager UI, copy and save the generated config-map.yaml file. Otherwise, create and save the following file. Set data.baseUrl to the URL of your Ops Manager instance from status.opsManager.url.

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-project
  namespace: mongodb
data:
  baseUrl: http://ops-manager-svc.mongodb.svc.cluster.local:8080
  projectName: my-project
  orgId: <your-org-id>

Replace <your-org-id> with your Ops Manager Organization ID. You can find this value in the Ops Manager UI URL: http://<ops-manager-url>/v2#/org/<orgId>/projects.

To learn more, see the parameter descriptions.

Create and save the Secret.

If you generated the Secret from the Ops Manager UI, copy and save the generated secret.yaml file. Otherwise, create a secret that contains the API keys for your Ops Manager Organization.

Example:

apiVersion: v1
kind: Secret
metadata:
  name: organization-secret
  namespace: mongodb
stringData:
  publicKey: <public_key>
  privateKey: <private_key>

To create Programmatic API Keys, see Create Credentials for the Kubernetes Operator.

Apply the ConfigMap and Secret.

Run the following command:

kubectl apply -f secret.yaml -f config-map.yaml

Deploy the MongoDB replica set resource.

1. Copy and save the following YAML file:

   apiVersion: mongodb.com/v1
   kind: MongoDB
   metadata:
     name: demo-mongodb-cluster-1
     namespace: mongodb
   spec:
     members: 3
     version: 8.0.0
     type: ReplicaSet
     security:
       authentication:
         enabled: true
         modes: ["SCRAM"]
     opsManager:
       configMapRef:
         name: my-project
     credentials: organization-secret
     persistent: true
     podSpec:
       podTemplate:
         spec:
          containers:
           - name: mongodb-enterprise-database
             resources:
               limits:
                 cpu: 2
                 memory: 1.5G
               requests:
                 cpu: 1
                 memory: 1G
               persistence:
                 single:
                   storage: 10Gi

2. Run the following command:

   kubectl apply -f <replica-set-conf>.yaml

Create a secret with your database user password.

Choose a password for your MongoDB database user and store it in a secret. This password can be any value you choose. You reference this secret when you create the database user in the next step.

You can store the password as cleartext (using stringData) or as a Base64-encoded value (using data).

For a cleartext password, create and save the following YAML file:

apiVersion: v1
kind: Secret
metadata:
  name: mms-user-1-password
  # corresponds to user.spec.passwordSecretKeyRef.name
type: Opaque
stringData:
  password: <my-plain-text-password>
  # corresponds to user.spec.passwordSecretKeyRef.key

For a Base64-encoded password, create and save the following YAML file:

apiVersion: v1
kind: Secret
metadata:
  name: mms-user-1-password
  # corresponds to user.spec.passwordSecretKeyRef.name
type: Opaque
data:
  password: <base-64-encoded-password>
  # corresponds to user.spec.passwordSecretKeyRef.key

Replace the placeholder with your chosen password. To learn more, see Manage Database Users Using SCRAM Authentication.

Create a database user.

1. Copy and save the following MongoDB User Resource Specification file:

   apiVersion: mongodb.com/v1
   kind: MongoDBUser
   metadata:
     name: mms-scram-user-1
   spec:
     passwordSecretKeyRef:
       name: mms-user-1-password
       # Match to metadata.name of the User Secret
       key: password
     username: "mms-scram-user-1"
     db: "admin" #
     mongodbResourceRef:
       name: "demo-mongodb-cluster-1"
       # Match to MongoDB resource using authentication
     roles:
     - db: "admin"
       name: "clusterAdmin"
     - db: "admin"
       name: "userAdminAnyDatabase"
     - db: "admin"
       name: "readWrite"

2. Run the following command:

   kubectl apply -f <database-user-conf>.yaml

Optional: View the newly created user in Cloud Manager or Ops Manager.

You can view the newly-created user in Cloud Manager or Ops Manager:

1. From the Project's Deployment view, click the Security tab.

2. Click the MongoDB Users nested tab.

Connect to the MongoDB replica set.

Perform the following steps in the Ops Manager application:

1. Click Deployment in the left navigation.

2. Click for the deployment to which you want to connect.

3. Click Connect to this instance.

4. Run the connection command in a terminal to connect to the deployment.