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. 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 generate a Public API Key.

  2. Grant the user with this new Public API Key the Project Owner role.

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

  4. (Optional). 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.

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.11 or later.

Only One Operator per Namespace

The MongoDB Enterprise Kubernetes Operator can only exist in one namespace. Your deployment can have:

  • One cluster-wide Kubernetes Operator or
  • Multiple Kubernetes Operators in their own namespaces

Do not try to deploy more than one Kubernetes Operator in the same namespace as another Operator. Multiple Operators cannot coordinate with one another within the same namespace.

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.

    Change the MANAGED_SECURITY_CONTEXT value as described in the next step.

  4. You can edit the Operator YAML file to further customize your Operator before installing it.

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

    2. You may need to add one or more of the following options:

      Environment Variable When to Use
      OPERATOR_ENV

      Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

      If OPERATOR_ENV is Log Level is set to Log Format is set to
      dev debug text
      prod info json

      Accepted values are: dev, prod.

      Default value is: prod.

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: OPERATOR_ENV
      spec.template.spec.containers.name.env.value: prod
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: OPERATOR_ENV
                value: prod
      
      WATCH_NAMESPACE

      Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

      * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

      Default value is: <metadata.namespace>.

      One Namespace or All Namespaces

      If you need to watch more than one namespace, set the value of WATCH_NAMESPACE to * (all). This environment variable can watch one namespace or all namespaces.

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: WATCH_NAMESPACE
      spec.template.spec.containers.name.env.value: "<testNamespace>"
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: WATCH_NAMESPACE
                value: "<testNamespace>"
      
      MANAGED_SECURITY_CONTEXT

      If you use OpenShift as your Kubernetes orchestrator, set this to 'true' to allow OpenShift to manage the Security Context for the Kubernetes Operator.

      Accepted values are: 'true', 'false'.

      Default value is: 'false'.

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: MANAGED_SECURITY_CONTEXT
      spec.template.spec.containers.name.env.value: 'true'
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: MANAGED_SECURITY_CONTEXT
                value: 'true'
      
      POD_WAIT_SEC

      Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

      Default values depend upon OPERATOR_ENV:

      If OPERATOR_ENV is POD_WAIT_SEC is set to
      dev 3
      prod 5

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: POD_WAIT_SEC
      spec.template.spec.containers.name.env.value: 4
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: POD_WAIT_SEC
                value: 4
              - name: POD_WAIT_RETRIES
                value: 30
      
      POD_WAIT_RETRIES

      Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

      Default values depend upon OPERATOR_ENV:

      If OPERATOR_ENV is POD_WAIT_RETRIES is set to
      dev 60
      prod 180

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: POD_WAIT_RETRIES
      spec.template.spec.containers.name.env.value: 30
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: POD_WAIT_SEC
                value: 4
              - name: POD_WAIT_RETRIES
                value: 30
      
  5. Install the Kubernetes Operator using the following kubectl command:

    kubectl apply -f mongodb-enterprise.yaml
    

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.

If you have not already installed Helm, follow the instructions on GitHub to install it.

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

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

    helm template helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

    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
    namespace

    To use a different namespace, you need to specify that namespace.

    Default value is: mongodb.

    Example

    helm template \
      --set namespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.env

    Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

    If operator.env is Log Level is set to Log Format is set to
    dev debug text
    prod info json

    Accepted values are: dev, prod.

    Default value is: prod.

    Example

    helm template \
      --set operator.env=dev \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.watchNamespace

    Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

    * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

    Default value is: <metadata.namespace>.

    Example

    helm template \
      --set operator.watchNamespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    managedSecurityContext

    If you use OpenShift as your Kubernetes orchestrator, set this to true to allow OpenShift to manage the Security Context for the Kubernetes Operator.

    Accepted values are: true, false.

    Default value is: false.

    Example

    helm template \
      --set managedSecurityContext=false \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podWaitSeconds

    Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

    Default values depend upon operator.env:

    If operator.env is operator.podWaitSeconds is set to
    dev 3
    prod 5

    Example

    helm template \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podSetWaitRetries

    Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

    Default values depend upon operator.env:

    If operator.env is operator.podSetWaitRetries is set to
    dev 60
    prod 180

    Example

    helm template
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      --set operator.podSetWaitRetries=20 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.

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 template --set registry.pullPolicy=IfNotPresent \
      helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

    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
    namespace

    To use a different namespace, you need to specify that namespace.

    Default value is: mongodb.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set namespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.env

    Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

    If operator.env is Log Level is set to Log Format is set to
    dev debug text
    prod info json

    Accepted values are: dev, prod.

    Default value is: prod.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.watchNamespace

    Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

    * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

    Default value is: <metadata.namespace>.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.watchNamespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    managedSecurityContext

    If you use OpenShift as your Kubernetes orchestrator, set this to true to allow OpenShift to manage the Security Context for the Kubernetes Operator.

    Accepted values are: true, false.

    Default value is: false.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set managedSecurityContext=false \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podWaitSeconds

    Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

    Default values depend upon operator.env:

    If operator.env is operator.podWaitSeconds is set to
    dev 3
    prod 5

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podSetWaitRetries

    Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

    Default values depend upon operator.env:

    If operator.env is operator.podSetWaitRetries is set to
    dev 60
    prod 180

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      --set operator.podSetWaitRetries=20 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.

  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 template --set registry.pullPolicy=IfNotPresent \
      helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

    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
    namespace

    To use a different namespace, you need to specify that namespace.

    Default value is: mongodb.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set namespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.env

    Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

    If operator.env is Log Level is set to Log Format is set to
    dev debug text
    prod info json

    Accepted values are: dev, prod.

    Default value is: prod.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.watchNamespace

    Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

    * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

    Default value is: <metadata.namespace>.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.watchNamespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    managedSecurityContext

    If you use OpenShift as your Kubernetes orchestrator, set this to true to allow OpenShift to manage the Security Context for the Kubernetes Operator.

    Accepted values are: true, false.

    Default value is: false.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set managedSecurityContext=false \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podWaitSeconds

    Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

    Default values depend upon operator.env:

    If operator.env is operator.podWaitSeconds is set to
    dev 3
    prod 5

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podSetWaitRetries

    Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

    Default values depend upon operator.env:

    If operator.env is operator.podSetWaitRetries is set to
    dev 60
    prod 180

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      --set operator.podSetWaitRetries=20 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.

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>
      orgId: <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

    • metadata.name
    • Kubernetes documentation on names. This name must follow RFC1123 naming conventions, using only lowercase alphanumeric characters, ‘-‘ or ‘.’, and must start and end with an alphanumeric character.
    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:8443/
    v2#/org/<orgId>/projects
    data.baseUrl string

    URL to your Ops Manager Application including the FQDN and port number.

    Note

    You may use Cloud Manager for the data.baseUrl value.

    https://ops.example.com:8443
  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
    

Upgrade the MongoDB Enterprise Kubernetes Operator

Version 0.10 of the Kubernetes Operator consolidates the MongoDbStandalone, MongoDbShardedCluster, and MongoDbReplicaSet CustomResourceDefinitions into a single CustomResourceDefinition called MongoDB.

Prerequisites

Important

The following prerequisite steps are necessary if you already have resources managed by the Kubernetes Operator that you want to keep. If the resources had data persisted, then the persistent volumes are reused in the new resources created.

If you do not wish to retain data from previous deployments, skip this section and start from the Procedure section.

  1. Verify you have the .yaml configuration file for each MongoDB resource you have deployed.

    Standalone Resources

    If you have standalone resources but do not have the .yaml configuration file for them, run the following command to generate the configuration file:

    kubectl mst <standalone-name> -n <namespace> -o yaml > <standalone-conf-name>.yaml
    
    Replica Set Resources

    If you have replica set resources but do not have the .yaml configuration file for them, run the following command to generate the configuration file:

    kubectl get mrs <replicaset-name> -n <namespace> -o yaml > <replicaset-conf-name>.yaml
    
    Sharded Cluster Resources

    If you have sharded cluster resources but do not have the .yaml configuration file for them, run the following command to generate the configuration file:

    kubectl get msc <shardedcluster-name> -n <namespace> -o yaml > <shardedcluster-conf-name>.yaml
    
  2. Edit each .yaml configuration file match the new CustomResourceDefinition:

    • Change the kind to MongoDB

    • Add the spec.type field and set it to Standalone, ReplicaSet, or ShardedCluster depending on your resource.

      Note

      The Kubernetes Operator does not support changing the type of an existing configuration even though it will accept a valid configuration for a different type.

      For example, if your MongoDB resource is a standalone, you cannot set the value of spec.type to ReplicaSet and set spec.members. If you do, the Kubernetes Operator throws an error and requires you to revert to the previously working configuration.

    After you edit each .yaml file, it should look like the following example:

    ---
    apiVersion: mongodb.com/v1
    kind: MongoDB
    metadata:
      name: <mystandalone>
      namespace: <metadata.namespace> # Should match metadata.namespace in
                                      # your configmap file.
    spec:
      version: 4.0.6
      project: <myconfigmap> # Should match metadata.name in your
                             # configmap file.
      credentials: <mycredentials>
      type: Standalone
      persistent: true
    ...
    
    ---
    apiVersion: mongodb.com/v1
    kind: MongoDB
    metadata:
      name: <myreplicaset>
      namespace: <metadata.namespace> # Should match metadata.namespace in
                                      # your configmap file.
    spec:
      members: 3
      version: 4.0.6
      project: <myconfigmap> # Should match metadata.name in your
                             # configmap file.
      credentials: <mycredentials>
      type: ReplicaSet
      persistent: true
    ...
    
    ---
    apiVersion: mongodb.com/v1
    kind: MongoDB
    metadata:
      name: <myshardedcluster>
      namespace: <metadata.namespace> # Should match metadata.namespace in
                                      # your configmap file.
    spec:
      shardCount: 2
      mongodsPerShardCount: 3
      mongosCount: 2
      configServerCount: 3
      version: 4.0.6
      project: <myconfigmap> # Should match metadata.name in your
                             # configmap file.
      credentials: <mycredentials>
      type: ShardedCluster
      persistent: true
    ...
    

    Warning

    If you change the metadata.name field you will lose your resource’s data.

Procedure

To upgrade to the latest version of the Kubernetes Operator:

  1. Change to the directory in which you cloned the Kubernetes Operator repository. The following steps depend on how your environment is configured:
  1. Upgrade the CustomResourceDefinitions for MongoDB deployments using the following kubectl command:

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

    Change the MANAGED_SECURITY_CONTEXT value as described in the next step.

  3. You can edit the Operator YAML file to further customize your Operator before upgrading it.

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

    2. You may need to add one or more of the following options:

      Environment Variable When to Use
      OPERATOR_ENV

      Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

      If OPERATOR_ENV is Log Level is set to Log Format is set to
      dev debug text
      prod info json

      Accepted values are: dev, prod.

      Default value is: prod.

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: OPERATOR_ENV
      spec.template.spec.containers.name.env.value: prod
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: OPERATOR_ENV
                value: prod
      
      WATCH_NAMESPACE

      Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

      * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

      Default value is: <metadata.namespace>.

      One Namespace or All Namespaces

      If you need to watch more than one namespace, set the value of WATCH_NAMESPACE to * (all). This environment variable can watch one namespace or all namespaces.

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: WATCH_NAMESPACE
      spec.template.spec.containers.name.env.value: "<testNamespace>"
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: WATCH_NAMESPACE
                value: "<testNamespace>"
      
      MANAGED_SECURITY_CONTEXT

      If you use OpenShift as your Kubernetes orchestrator, set this to 'true' to allow OpenShift to manage the Security Context for the Kubernetes Operator.

      Accepted values are: 'true', 'false'.

      Default value is: 'false'.

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: MANAGED_SECURITY_CONTEXT
      spec.template.spec.containers.name.env.value: 'true'
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: MANAGED_SECURITY_CONTEXT
                value: 'true'
      
      POD_WAIT_SEC

      Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

      Default values depend upon OPERATOR_ENV:

      If OPERATOR_ENV is POD_WAIT_SEC is set to
      dev 3
      prod 5

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: POD_WAIT_SEC
      spec.template.spec.containers.name.env.value: 4
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: POD_WAIT_SEC
                value: 4
              - name: POD_WAIT_RETRIES
                value: 30
      
      POD_WAIT_RETRIES

      Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

      Default values depend upon OPERATOR_ENV:

      If OPERATOR_ENV is POD_WAIT_RETRIES is set to
      dev 60
      prod 180

      You can set the following pair of values:

      spec.template.spec.containers.name.env.name: POD_WAIT_RETRIES
      spec.template.spec.containers.name.env.value: 30
      

      Example

      spec:
        template:
          spec:
            serviceAccountName: mongodb-enterprise-operator
            containers:
            - name: mongodb-enterprise-operator
              image: <operatorVersionUrl>
              imagePullPolicy: <policyChoice>
              env:
              - name: POD_WAIT_SEC
                value: 4
              - name: POD_WAIT_RETRIES
                value: 30
      

      Note

      Any values enclosed in single or double quotes require those quotes. Include the quotes when setting these values.

  4. Upgrade the Kubernetes Operator using the following kubectl command:

    kubectl apply -f mongodb-enterprise.yaml
    

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.

  1. Upgrade the latest version of the Kubernetes Operator using the following helm command:

    helm template public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

    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
    namespace

    To use a different namespace, you need to specify that namespace.

    Default value is: mongodb.

    Example

    helm template \
      --set namespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.env

    Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

    If operator.env is Log Level is set to Log Format is set to
    dev debug text
    prod info json

    Accepted values are: dev, prod.

    Default value is: prod.

    Example

    helm template \
      --set operator.env=dev \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.watchNamespace

    Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

    * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

    Default value is: <metadata.namespace>.

    Example

    helm template \
      --set operator.watchNamespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    managedSecurityContext

    If you use OpenShift as your Kubernetes orchestrator, set this to true to allow OpenShift to manage the Security Context for the Kubernetes Operator.

    Accepted values are: true, false.

    Default value is: false.

    Example

    helm template \
      --set managedSecurityContext=false \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podWaitSeconds

    Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

    Default values depend upon operator.env:

    If operator.env is operator.podWaitSeconds is set to
    dev 3
    prod 5

    Example

    helm template \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podSetWaitRetries

    Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

    Default values depend upon operator.env:

    If operator.env is operator.podSetWaitRetries is set to
    dev 60
    prod 180

    Example

    helm template
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      --set operator.podSetWaitRetries=20 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.

To upgrade 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. Upgrade the latest version of the Kubernetes Operator with modified pull policy values using the following helm command:

    helm template --set registry.pullPolicy=IfNotPresent \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

    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
    namespace

    To use a different namespace, you need to specify that namespace.

    Default value is: mongodb.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set namespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.env

    Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

    If operator.env is Log Level is set to Log Format is set to
    dev debug text
    prod info json

    Accepted values are: dev, prod.

    Default value is: prod.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.watchNamespace

    Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

    * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

    Default value is: <metadata.namespace>.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.watchNamespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    managedSecurityContext

    If you use OpenShift as your Kubernetes orchestrator, set this to true to allow OpenShift to manage the Security Context for the Kubernetes Operator.

    Accepted values are: true, false.

    Default value is: false.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set managedSecurityContext=false \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podWaitSeconds

    Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

    Default values depend upon operator.env:

    If operator.env is operator.podWaitSeconds is set to
    dev 3
    prod 5

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podSetWaitRetries

    Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

    Default values depend upon operator.env:

    If operator.env is operator.podSetWaitRetries is set to
    dev 60
    prod 180

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      --set operator.podSetWaitRetries=20 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.

  1. Upgrade the latest version of the Kubernetes Operator with modified pull policy values using the following helm command:

    helm template --set registry.pullPolicy=IfNotPresent \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

    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
    namespace

    To use a different namespace, you need to specify that namespace.

    Default value is: mongodb.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set namespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.env

    Label for the Operator’s deployment environment. The env value affects default timeouts and the format and level of logging.

    If operator.env is Log Level is set to Log Format is set to
    dev debug text
    prod info json

    Accepted values are: dev, prod.

    Default value is: prod.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.watchNamespace

    Namespace that the Operator watches for MongoDB Kubernetes resource changes. If this namespace differs from the default, ensure that the Operator’s ServiceAccount can access that different namespace.

    * means all namespaces and requires the ClusterRole assigned to the mongodb-enterprise-operator ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.

    Default value is: <metadata.namespace>.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.watchNamespace=<testNamespace> \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    managedSecurityContext

    If you use OpenShift as your Kubernetes orchestrator, set this to true to allow OpenShift to manage the Security Context for the Kubernetes Operator.

    Accepted values are: true, false.

    Default value is: false.

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set managedSecurityContext=false \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podWaitSeconds

    Time in seconds that the Operator waits for StatefulSets to start when MongoDB Kubernetes resources are being created or updated before retrying.

    Default values depend upon operator.env:

    If operator.env is operator.podWaitSeconds is set to
    dev 3
    prod 5

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    
    operator.podSetWaitRetries

    Maximum number of retries that the Operator attempts when waiting for StatefulSets to start after MongoDB Kubernetes resources are created or updated.

    Default values depend upon operator.env:

    If operator.env is operator.podSetWaitRetries is set to
    dev 60
    prod 180

    Example

    helm template \
      --set registry.pullPolicy=IfNotPresent \
      --set operator.env=dev \
      --set operator.podWaitSeconds=10 \
      --set operator.podSetWaitRetries=20 \
      public/helm_chart > operator.yaml
    kubectl apply -f operator.yaml
    

Recreate MongoDB Resources and Delete the Version 0.9 CRDs

  1. After you upgrade the Kubernetes Operator, verify you have four CRDs by running the following command:

    kubectl get crds
    

    The following output contains the new mongodb.mongodb.com CRD and the version 0.9 CRDs:

    NAME                                 CREATED AT
    mongodb.mongodb.com                  2019-03-27T19:30:09Z
    mongodbreplicasets.mongodb.com       2018-12-07T18:25:42Z
    mongodbshardedclusters.mongodb.com   2018-12-07T18:25:42Z
    mongodbstandalones.mongodb.com       2018-12-07T18:25:42Z
    
  2. Remove the old resources from Kubernetes.

    Important

    Removing MongoDB resources will remove the database server pods and drop any client connections to the database. Connections are reestablished when the new MongoDB resources are created in Kubernetes.

    Run each of the following commands to remove all MongoDB resources:

    kubectl delete mst --all
    
    kubectl delete mrs --all
    
    kubectl delete msc --all
    

    Note

    MongoDB resources that have persistent: true set in their .yaml configuration file will not lose data as it is stored in persistent volumes. The previous command only deletes pods containing MongoDB and not the persistent volumes containing the data. Persistent volume claims referencing persistent volumes stay alive and are reused by the new MongoDB resources.

  3. Create the MongoDB resources again.

    Use the .yaml resource configuration file to recreate each resource:

    kubectl apply -f <resource-conf>.yaml
    

    Note

    If the old resources had persistent: true set and the metadata.name haven’t changed, the new MongoDB pods will reuse the data from the old pods.

    Run the following command to check the status of each resource and verify that the phase reaches the Running status:

    kubectl get mdb <resource-name> -n <namespace> -o yaml -w
    

    For an example of this command’s output, see Get Status of MongoDB Resource.

  1. Delete the old CRDs.

    Once all the resources are up and running, delete all of the v0.9 CRDs as the Kubernetes Operator no longer watches them:

    kubectl delete crd mongodbreplicasets.mongodb.com
    
    kubectl delete crd mongodbshardedclusters.mongodb.com
    
    kubectl delete crd mongodbstandalones.mongodb.com
    

    Run the following command to verify the old CRDs were removed:

    kubectl get crds
    

    The output of the command above should look similar to the following:

    NAME                  CREATED AT
    mongodb.mongodb.com   2019-03-27T19:30:09Z
    

Once the version 0.9 CRDs are deleted, the MongoDB Enterprise Kubernetes Operator upgrade is complete.

Troubleshooting

To troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator.

Important

If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.