Note
This tutorial presumes some knowledge of Kubernetes. If you are unfamiliar with Kubernetes, review the Kubernetes documentation on Kubernetes objects and custom resources before you begin. The Kubernetes Operator represents Ops Manager and MongoDB deployments as custom resources. You create and manage them with kubectl in the same way that you manage any other Kubernetes object. To learn how these custom resources relate to each other, see MongoDB Controllers for Kubernetes Operator Architecture Overview.
Prerequisites
Complete the following prerequisites before you install the Kubernetes Operator:
Have a Kubernetes solution available to use, and verify hardware architecture support.
If you need a Kubernetes solution, see the Kubernetes documentation on picking the right solution. Review supported hardware architectures.
Clone the MongoDB Controllers for Kubernetes Operator repository and check out the tag for the current release.
git clone https://github.com/mongodb/mongodb-kubernetes.gitcd mongodb-kubernetesgit checkout 1.15.0Note
You can use Helm to install the Kubernetes Operator. To learn how to install Helm, see its documentation on GitHub.
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 mongodbIf you do not want to use the mongodb namespace, you can label your namespace anything you like:
kubectl create namespace <namespaceName>Optional: Have a running Ops Manager.
If you don't deploy an Ops Manager resource with the Kubernetes Operator, you must have an Ops Manager running outside of your Kubernetes cluster. If you will deploy an Ops Manager resource in Kubernetes with the Kubernetes Operator, skip this prerequisite.
Important
Your Ops Manager installation must run an active NTP service. If the Ops Manager host's clock falls out of sync, that host can't communicate with the Kubernetes Operator.
To learn how to check your NTP service for your Ops Manager host, see the documentation for RHEL.
Considerations
Review the following planning topics. To learn more, see Plan Your Kubernetes Operator Installation.
Decide whether to install on a single Kubernetes cluster or on multiple Kubernetes clusters. See Choose Single- or Multi-Cluster Installation Mode.
Confirm that your versions of Kubernetes, OpenShift, MongoDB, and Ops Manager are compatible. See MongoDB Controllers for Kubernetes Operator Compatibility.
Set the scope of the Kubernetes Operator deployment, which determines the namespaces that the Kubernetes Operator watches. See Set Scope for MongoDB Controllers for Kubernetes Operator Deployment.
Apply the production recommendations for storage, persistence, and CPU and memory bounds. See Best Practices.
Install with Kubernetes
The installation procedure varies based on how you want to configure your environment:
Note
Use the same namespace throughout
By default, the Kubernetes Operator deploys all resources in your Kubernetes cluster to the namespace mongodb. You can deploy Kubernetes Operator resources to a different namespace by editing all values for metadata.namespace in mongodb-kubernetes.yaml. You must also update the subjects[0].namespace value in every RoleBinding and ClusterRoleBinding in the same file. If you omit this value, the bindings look for the ServiceAccount in the default mongodb namespace and can't find it:
apiVersion: v1kind: ServiceAccountmetadata: name: mongodb-kubernetes-operator namespace: production
apiVersion: rbac.authorization.k8s.io/v1kind: RoleBindingmetadata: name: mongodb-kubernetes-operator namespace: productionroleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: mongodb-kubernetes-operatorsubjects: - kind: ServiceAccount name: mongodb-kubernetes-operator namespace: production
apiVersion: apps/v1kind: Deploymentmetadata: name: mongodb-kubernetes-operator namespace: production
# Example truncatedOptional: Customize the Kubernetes Operator YAML before installing it.
To learn about optional Kubernetes Operator installation settings, see Operator kubectl and oc Installation Settings.
Note
To enable the Public Preview of static containers, which improve and simplify security, see Static Containers (Public Preview). We don't recommend using this feature in production while it's in Public Preview. To learn more, see Preview Features.
Use the MongoDB Helm Charts for Kubernetes.
Note
Helm Chart Repository Deprecation
Installing the Kubernetes Operator from the MongoDB Helm Charts for Kubernetes repository is deprecated and will be removed in the MCK version 2.0. To install the Helm chart from the OCI-compliant registry instead, see the "Using Helm (OCI-Compliant Registry)" tab.
Add the MongoDB Helm Charts for Kubernetes.
You can add the Kubernetes Operator Helm Chart locally by running:
helm repo add mongodb https://mongodb.github.io/helm-chartsCustomize your Helm Chart before deploying it.
To learn about optional Kubernetes Operator installation settings, see Operator Helm Installation Settings.
Deploy the Kubernetes Operator.
Run the following helm command to deploy the Kubernetes Operator to the default namespace in your Kubernetes cluster:
helm upgrade --install mongodb-kubernetes-operator mongodb/mongodb-kubernetesYou can pass the --namespace and --create-namespace flags to deploy the Kubernetes Operator to a non-default namespace, like so:
helm upgrade --install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \--namespace mongodb \--create-namespaceInstall a Specific Daily Build with Helm
MongoDB rebuilds Kubernetes Operator images every day to integrate the latest security and OS updates.
By default, helm installs the latest build for the version of the Kubernetes Operator you specify.
To install an earlier build, specify the build ID as a parameter with --set build=<build-id>. Build IDs are always in the format -b<YYYYMMDD>T000000Z, where <YYYYMMDD> is the date that the build you want to use was created.
Example
This example shows how to install the Kubernetes Operator with the latest image:
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetesThis example shows how to install the Kubernetes Operator with the image created at midnight on February 5th, 2021:
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \ --set build=-b20210205T000000ZNote
MongoDB recommends using the default (latest) build.
MongoDB also publishes the Kubernetes Operator Helm chart to an OCI-compliant container registry at quay.io/mongodb/helm-charts. When you install from this registry, you reference the chart directly instead of adding the Helm chart repository.
Customize your Helm chart before deploying it.
To learn about optional Kubernetes Operator installation settings, see Operator Helm Installation Settings.
Deploy the Kubernetes Operator.
Run the following helm command to deploy the Kubernetes Operator to the default namespace in your Kubernetes cluster:
helm upgrade --install mongodb-kubernetes-operator \ oci://quay.io/mongodb/helm-charts/mongodb-kubernetesTo deploy the Kubernetes Operator to a non-default namespace, pass the --namespace and --create-namespace flags:
helm upgrade --install mongodb-kubernetes-operator \ oci://quay.io/mongodb/helm-charts/mongodb-kubernetes \ --namespace mongodb \ --create-namespaceInstall with OpenShift
Before you begin, ensure that the MANAGED_SECURITY_CONTEXT flag is set to true when you deploy the Kubernetes Operator to OpenShift. This value is pre-defined in the values-openshift.yaml file.
The installation procedure varies based on how you want to configure your environment:
Note
Use the same namespace throughout
By default, the Kubernetes Operator deploys all resources in your Kubernetes cluster to the namespace mongodb. You can deploy Kubernetes Operator resources to a different namespace by editing all values for metadata.namespace in mongodb-kubernetes-openshift.yaml. You must also update the subjects[0].namespace value in every RoleBinding and ClusterRoleBinding in the same file. If you omit this value, the bindings look for the ServiceAccount in the default mongodb namespace and can't find it:
apiVersion: v1kind: ServiceAccountmetadata: name: mongodb-kubernetes-operator namespace: production
apiVersion: rbac.authorization.k8s.io/v1kind: RoleBindingmetadata: name: mongodb-kubernetes-operator namespace: productionroleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: mongodb-kubernetes-operatorsubjects: - kind: ServiceAccount name: mongodb-kubernetes-operator namespace: production
apiVersion: apps/v1kind: Deploymentmetadata: name: mongodb-kubernetes-operator namespace: production
# Example truncatedClone the MongoDB Controllers for Kubernetes Operator repository and check out the tag for the current release.
Invoke the following git commands:
git clone https://github.com/mongodb/mongodb-kubernetes.gitcd mongodb-kubernetesgit checkout 1.15.0Navigate to the directory in which you cloned the MongoDB Controllers for Kubernetes Operator repository.
For example, if you cloned the repository in your home directory, run:
cd ~/mongodb-kubernetesInstall the CustomResourceDefinitions for MongoDB deployments.
Invoke the following oc command:
oc apply -f crds.yamlOptional: Customize the Kubernetes Operator YAML before installing it.
To learn about optional Kubernetes Operator installation settings, see Operator kubectl and oc Installation Settings.
Note
To enable the Public Preview of static containers, which improve and simplify security, see Static Containers (Public Preview). We don't recommend using this feature in production while it's in Public Preview. To learn more, see Preview Features.
Add your <openshift-pull-secret> to the ServiceAccount definitions in the Kubernetes Operator YAML before installing it.
apiVersion: v1kind: ServiceAccountmetadata: name: enterprise-operator
namespace: mongodb
imagePullSecrets: - name: <openshift-pull-secret>
apiVersion: v1kind: ServiceAccountmetadata: name: mongodb-kubernetes-appdb
namespace: mongodb
imagePullSecrets: - name: <openshift-pull-secret>
apiVersion: v1kind: ServiceAccountmetadata: name: mongodb-kubernetes-database-pods
namespace: mongodb
imagePullSecrets: - name: <openshift-pull-secret>To learn more, see the registry.imagePullSecrets setting in the Helm installation settings.
Use the MongoDB Helm Charts for Kubernetes.
Note
Helm Chart Repository Deprecation
Installing the Kubernetes Operator from the MongoDB Helm Charts
for Kubernetes repository is deprecated and will be removed in the MCK version 2.0. Install the Helm chart from the OCI-compliant registry at quay.io/mongodb/helm-charts instead.
You can install the Kubernetes Operator with Helm 3.
Add the MongoDB Helm Charts for Kubernetes repository to Helm.
helm repo add mongodb https://mongodb.github.io/helm-chartsInstall the Kubernetes Operator using helm.
Install MongoDB Helm Charts for Kubernetes:
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \ --values https://raw.githubusercontent.com/mongodb/helm-charts/main/charts/mongodb-kubernetes/values-openshift.yamlUse the values-openshift.yaml settings. To learn about optional Kubernetes Operator installation settings, see Operator Helm Installation Settings.
Note
To enable the Public Preview of static containers, which improve and simplify security, see Static Containers (Public Preview). We don't recommend using this feature in production while it's in Public Preview. To learn more, see Preview Features.
Install a Specific Daily Build with Helm
MongoDB rebuilds Kubernetes Operator images every day to integrate the latest security and OS updates.
By default, helm installs the latest build for the version of the Kubernetes Operator you specify.
To install an earlier build, specify the build ID as a parameter with --set build=<build-id>. Build IDs are always in the format -b<YYYYMMDD>T000000Z, where <YYYYMMDD> is the date that the build you want to use was created.
Example
This example shows how to install the Kubernetes Operator with the latest image:
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetesThis example shows how to install the Kubernetes Operator with the image created at midnight on February 5th, 2021:
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \ --set build=-b20210205T000000ZNote
MongoDB recommends using the default (latest) build.
Verify the Installation
To verify that the Kubernetes Operator installed correctly, run the following command and verify the output:
kubectl describe deployments mongodb-kubernetes-operator -n <metadata.namespace>oc describe deployments mongodb-kubernetes-operator -n <metadata.namespace>By default, deployments exist in the mongodb namespace. If the following error message appears, ensure you use the correct namespace:
Error from server (NotFound): deployments.apps "mongodb-kubernetes-operator" not foundTo troubleshoot your Kubernetes Operator, see Review Logs from the Kubernetes Operator and other troubleshooting topics.
Important
If you need to remove the Kubernetes Operator or the namespace, you first must remove MongoDB resources.
Next Steps
After installing the MongoDB Controllers for Kubernetes Operator, you can: