Navigation

Install MongoDB Enterprise Kubernetes Operator

Added in Ops Manager 4.0

You can use Kubernetes to deploy MongoDB instances with Ops Manager version 4.0 or later.

MongoDB Enterprise Kubernetes Operator allows you to deploy MongoDB deployment items with Kubernetes and Ops Manager from a macOS or Linux host. This Operator uses Kubernetes and Ops Manager API methods to deploy standalone, replica set, and sharded cluster deployments that Ops Manager manages.

Note

This tutorial presumes some knowledge of Kubernetes, but does link to relevant Kubernetes documentation where possible. If you are unfamiliar with Kubernetes, please review that documentation first.

Prerequisites

Ops Manager Prerequisites

To install the MongoDB Enterprise Kubernetes Operator, you must:

  1. Have or create an Ops Manager Organization.

    Note

    Unlike earlier Kubernetes Operator versions, use the Operator to create your Ops Manager project. The Operator adds additional metadata to Projects that it creates to help manage the deployments.

  2. Have or generate a Public API Key.

  3. Add the IP or CIDR block of any hosts that serve the Kubernetes Operator to the API Whitelist.

Kubernetes Prerequisites

  1. Have a Kubernetes solution available to use.

    If you need a Kubernetes solution, see the Kubernetes documentation on picking the right solution.

  2. Clone the MongoDB Enterprise Kubernetes Operator repository.

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

    Note

    You can use Helm to install the Kubernetes Operator. To learn how to install Helm, see its documentation on GitHub

  3. Create a namespace for your Kubernetes deployment. By default, The Kubernetes Operator uses the mongodb namespace. To simplify your installation, consider creating a namespace labeled mongodb using the following kubectl command:

    kubectl create namespace mongodb
    

    If you do not want to use the mongodb namespace, you can label your namespace anything you like:

    kubectl create namespace <namespaceName>
    

Considerations

Kubernetes Compatibility

MongoDB Enterprise Kubernetes Operator is compatible with Kubernetes v1.9 or later.

Install the MongoDB Enterprise Kubernetes Operator

Use the same namespace throughout

The following examples assume that you created a namespace using the default Kubernetes Operator namespace of mongodb. If you specified a different label for your namespace when you created it, change all values for metadata.namespace to that namespace.

To change the label for the namespace for the following deployment to production, edit all values for metadata.namespace in mongodb-enterprise.yaml:

##---
# Source: mongodb-enterprise-operator/templates/serviceaccount.yaml
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: mongodb-enterprise-operator
  namespace: production
##---
# Source: mongodb-enterprise-operator/templates/operator.yaml
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mongodb-enterprise-operator
  namespace: production

---
# Example truncated
---
...
  1. Change to the directory in which you cloned the repository.

  2. Install the CustomResourceDefinitions for MongoDB deployments using the following kubectl command:

    kubectl apply -f crds.yaml
    
  3. If you use OpenShift as your Kubernetes orchestrator, you need to allow OpenShift to manage the Security Context for the Kubernetes Operator.

    1. Open your mongodb-enterprise.yaml in your preferred text editor.

    2. Set two variables in the kind: Deployment block:

      spec.template.spec.containers.env.name : MANAGED_SECURITY_CONTEXT
      spec.template.spec.containers.env.name : 'true'
      
  4. Install the Kubernetes Operator using the following kubectl command:

    kubectl apply -f mongodb-enterprise.yaml
    
  1. Install Helm following the instructions on GitHub

  2. Change to the directory in which you cloned the repository.

  3. Install the Kubernetes Operator using the following helm command:

    helm install helm_chart/ \
      --name mongodb-enterprise
    

    You can customize your Chart before installing it by using the --set option. For this Chart, you may need to add one or more of the following options:

    --set option When to Use Example
    namespace helm uses the mongodb namespace by default. To use a different namespace, you need to specify that namespace.
    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set namespace=<namespaceName>
    
    managedSecurityContext If you use OpenShift as your Kubernetes orchestrator, you need to allow OpenShift to manage the Security Context for the Kubernetes Operator.
    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set managedSecurityContext=false
    

Before continuing, install Helm following the instructions on GitHub

To install the Kubernetes Operator on a host not connected to the Internet, you have two options, you can download the Kubernetes Operator files from either:

  1. Connect to the Internet.

  2. Use docker to request the files.

    docker pull quay.io/mongodb/mongodb-enterprise-operator:0.1; \
    docker pull quay.io/mongodb/mongodb-enterprise-database:0.1
    
  3. Disconnect from the Internet.

  4. Install the Kubernetes Operator with modified pull policy values using the following helm command:

    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set database.pullPolicy=IfNotPresent \
      --set operator.pullPolicy=IfNotPresent
    

    You can further customize your Chart before installing it by using the --set option. For this Chart, you may need to add one or more of the following options:

    --set option When to Use Example
    namespace helm uses the mongodb namespace by default. To use a different namespace, you need to specify that namespace.
    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set database.pullPolicy=IfNotPresent \
      --set operator.pullPolicy=IfNotPresent \
      --set namespace=<namespaceName>
    
    managedSecurityContext If you use OpenShift as your Kubernetes orchestrator, you need to allow OpenShift to manage the Security Context for the Kubernetes Operator.
    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set database.pullPolicy=IfNotPresent \
      --set operator.pullPolicy=IfNotPresent \
      --set managedSecurityContext=false
    
  1. Use docker to request the files on a host connected to the Internet.

    docker pull quay.io/mongodb/mongodb-enterprise-operator:0.1; \
    docker pull quay.io/mongodb/mongodb-enterprise-database:0.1
    
  2. Save the Operator files to transferrable files.

    docker save quay.io/mongodb/mongodb-enterprise-operator:0.1 -o mongodb-enterprise-operator.tar; \
    docker save quay.io/mongodb/mongodb-enterprise-database:0.1 -o mongodb-enterprise-database.tar
    
  3. Copy these .tar files to the host running the Kubernetes docker daemon.

  4. Import the .tar files into docker.

    docker import mongodb-enterprise-operator.tar quay.io/mongodb/mongodb-enterprise-operator:0.1; \
    docker import mongodb-enterprise-database.tar quay.io/mongodb/mongodb-enterprise-database:0.1
    
  5. Install the Kubernetes Operator with modified pull policy values using the following helm command:

    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set database.pullPolicy=IfNotPresent \
      --set operator.pullPolicy=IfNotPresent
    

    You can further customize your Chart before installing it by using the --set option. For this Chart, you may need to add one or more of the following options:

    --set option When to Use Example
    namespace helm uses the mongodb namespace by default. To use a different namespace, you need to specify that namespace.
    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set database.pullPolicy=IfNotPresent \
      --set operator.pullPolicy=IfNotPresent \
      --set namespace=<namespaceName>
    
    managedSecurityContext If you use OpenShift as your Kubernetes orchestrator, you need to allow OpenShift to manage the Security Context for the Kubernetes Operator.
    helm install helm_chart/ \
      --name mongodb-enterprise \
      --set database.pullPolicy=IfNotPresent \
      --set operator.pullPolicy=IfNotPresent \
      --set managedSecurityContext=false
    

To troubleshoot your Kubernetes Operator, see MongoDB Enterprise Kubernetes Operator Troubleshooting.

Create your Ops Manager Project and Kubernetes ConfigMap

The MongoDB Enterprise Kubernetes Operator uses a Kubernetes ConfigMap to link to your Ops Manager Project. To create a Kubernetes Operator ConfigMap, you need to edit 4 lines of the example ConfigMap YAML file and apply the ConfigMap:

  1. Copy the following example ConfigMap.

    ---
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: <myConfigMap>
      namespace: <myNamespace>
    data:
      projectName: <myOpsManagerProjectName>
      ordId: <orgId> # Optional
      baseUrl: https://<myOpsManagerURL>
    ...
    
  2. Open your preferred text editor and paste the example ConfigMap into a new text file.

  3. Change the following four lines:

    Key Type Description Example
    metadata.name string

    Label for a Kubernetes object.

    See also

    myConfigMap
    metadata.namespace string

    Scope of object names. Used to limit what can be managed to a subset of all objects. The default value is mongodb.

    Important

    The Kubernetes Operator, secret, and MongoDB Kubernetes resources must be created in the same namespace.

    See also

    mongodb
    data.projectName string

    Label for your Ops Manager Project.

    Let Kubernetes Operator create the Project

    The Kubernetes Operator creates the Ops Manager Project if it does not exist. It is strongly recommended to use the Operator to create a new Project for Kubernetes to manage. The Operator adds additional internal information to Projects that it creates.

    If you need or want to use an existing Project, you can find the projectName by clicking the All Clusters link at the top left of the screen, then either search by name in the Search box or scroll to find the name in the list. Each card in this list represents the combination of one Organization and Project.

    Development
    data.orgId string

    24 character hex string that uniquely identifies your MongoDB Organization. You can find the orgId in your Ops Manager URL:

    1. Click the Context menu.
    2. Select your Organization.
    3. Copy the value from the URL.

    Important

    This field is optional. If you omit the orgId, Ops Manager creates an Organization called projectName that contains a Project also called projectName.

    You must have the Organization Project Creator role to create a new project within an existing organization.

    https://ops.example.com:8080/
    v2#/org/<orgId>/projects
    data.baseUrl string URL to your Ops Manager Application including the FQDN and port number. https://ops.example.com:8080
  4. Save this file with a .yaml file extension.

  5. Invoke the following Kubernetes command to create your ConfigMap:

    kubectl apply -f <myConfigMap.yaml>
    

    Important

    All subsequent kubectl commands you invoke must add the -n option with the metadata.namespace you specified in your ConfigMap.

  6. Invoke the following Kubernetes command to verify your ConfigMap:

    kubectl describe configmaps <myConfigMap> -n <metadata.namespace>
    

    Always include the namespace option with kubectl

    kubectl defaults to an empty namespace if you do not specify the -n option, resulting in deployment failures. You must specify the value of the <metadata.namespace> field. The Kubernetes Operator, secret, and MongoDB Kubernetes resources should run in the same unique namespace.

    This command returns a ConfigMap description in the shell:

    Name:           <myConfigMap>
    Namespace:      <metadata.namespace>
    Labels:         <none>
    Annotations:    <none>
    

Create Credentials

For the Kubernetes Operator to create or update objects in your Ops Manager Project, you need to store your username and Public API Key as a Kubernetes secret. Creating a secret stores authentication credentials so only Kubernetes can access them.

Multiple secrets can exist in the same namespace. Each user should have their own secret.

To create your Kubernetes secret:

  1. Make sure you have your Ops Manager username and Public API Key.

    If you do not have your Public API Key, you need to generate a new Public API Key.

  2. Invoke the following Kubernetes command to create your secret:

    kubectl -n <metadata.namespace> \
      create secret generic <myCredentials> \
      --from-literal="user=<first.last@example.com>" \
      --from-literal="publicApiKey=<my-public-api-key>"
    

    Note

    The -n flag limits the namespace to which this secret applies. All MongoDB Kubernetes resources must be in the same namespace with the secrets and ConfigMaps. The Kubernetes Operator does not use either the secrets or ConfigMaps.

  3. Invoke the following Kubernetes command to verify your secret:

    kubectl describe secrets/<myCredentials> -n <metadata.namespace>
    

    This command returns a secret description in the shell:

    Name:         <myCredentials>
    Namespace:    <metadata.namespace>
    Labels:       <none>
    Annotations:  <none>
    
    Type:  Opaque
    
    Data
    ====
    publicApiKey:  31 bytes
    user:          22 bytes