- Install and Configure the Kubernetes Operator >
- Install the MongoDB Enterprise Kubernetes Operator
Install the MongoDB Enterprise Kubernetes Operator¶
On this page
Supported with Cloud Manager and Ops Manager 4.0
You can use Kubernetes Operator to deploy MongoDB instances with Ops Manager version 4.0 or later and Cloud Manager. At any place in this guide that says Ops Manager, you can substitute Cloud Manager.
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:
Have or generate a Programmatic API Key.
Grant this new Programmatic API Key the
Project Owner
role.Add the IP or CIDR block of any hosts that serve the Kubernetes Operator to the API Whitelist.
(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¶
Have a Kubernetes solution available to use.
If you need a Kubernetes solution, see the Kubernetes documentation on picking the right solution.
Clone the MongoDB Enterprise Kubernetes Operator repository.
Note
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 labeledmongodb
using the followingkubectl
command:If you do not want to use the
mongodb
namespace, you can label your namespace anything you like:
Considerations¶
Kubernetes Compatibility¶
MongoDB Enterprise Kubernetes Operator is compatible with Kubernetes v1.11 or later.
Docker Container Details¶
MongoDB builds the container images from the latest builds of the following operating systems:
If you get your Kubernetes Operator from… | …the Container uses |
---|---|
quay.io or GitHub | Ubuntu 16.04 |
OpenShift | Red Hat Enterprise Linux 7 |
MongoDB, Inc. updates all packages on these images before releasing them every three weeks.
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¶
- Online using kubectl
- Online using Helm
- Offline using Helm and Docker
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
:
Change to the directory in which you cloned the repository.
Install the CustomResourceDefinitions for MongoDB deployments using the following
kubectl
command: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.You can edit the Operator YAML file to further customize your Operator before installing it.
Open your
mongodb-enterprise.yaml
in your preferred text editor.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
isLog 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:
Example
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 themongodb-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:
Example
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:
Example
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
isPOD_WAIT_SEC
is set todev
3 prod
5 You can set the following pair of values:
Example
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
isPOD_WAIT_RETRIES
is set todev
60 prod
180 You can set the following pair of values:
Example
Install the Kubernetes Operator using the following
kubectl
command:
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.
Change to the directory in which you cloned the repository.
Install the Kubernetes Operator using the following
helm
command: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
optionWhen to Use namespace
To use a different namespace, you need to specify that
namespace
.Default value is:
mongodb
.Example
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
isLog 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
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 themongodb-enterprise-operator
ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.Default value is:
<metadata.namespace>
.Example
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
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
isoperator.podWaitSeconds
is set todev
3 prod
5 Example
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
isoperator.podSetWaitRetries
is set todev
60 prod
180 Example
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:
- The Internet
- Another Host
Connect to the Internet.
Use
docker
to request the files.Disconnect from the Internet.
Install the Kubernetes Operator with modified pull policy values using the following
helm
command: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
optionWhen to Use namespace
To use a different namespace, you need to specify that
namespace
.Default value is:
mongodb
.Example
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
isLog 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
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 themongodb-enterprise-operator
ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.Default value is:
<metadata.namespace>
.Example
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
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
isoperator.podWaitSeconds
is set todev
3 prod
5 Example
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
isoperator.podSetWaitRetries
is set todev
60 prod
180 Example
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.
Use
docker
to request the files on a host connected to the Internet.Save the Operator files to transferrable files.
Copy these
.tar
files to the host running the Kubernetesdocker
daemon.Import the
.tar
files intodocker
.Install the Kubernetes Operator with modified pull policy values using the following
helm
command: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
optionWhen to Use namespace
To use a different namespace, you need to specify that
namespace
.Default value is:
mongodb
.Example
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
isLog 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
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 themongodb-enterprise-operator
ServiceAccount which is the ServiceAccount used to run the Kubernetes Operator.Default value is:
<metadata.namespace>
.Example
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
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
isoperator.podWaitSeconds
is set todev
3 prod
5 Example
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
isoperator.podSetWaitRetries
is set todev
60 prod
180 Example
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.
Verify the Installation¶
To verify that the Kubernetes Operator installed correctly, run the following command and verify the output:
By default, deployments exist in the mongodb
namespace. If the
following error message appears, ensure you use the correct
namespace:
Next Steps¶
After installing the MongoDB Enterprise Kubernetes Operator, you need to:
- Create your Cloud or Ops Manager project and Kubernetes ConfigMap
- Create credentials so the Kubernetes Operator can update your Cloud Manager or Ops Manager project