- Install and Configure the Kubernetes Operator >
- Upgrade the Kubernetes Operator from Prior Versions >
- Upgrade from Operator Version 0.9 and Earlier
Upgrade from Operator Version 0.9 and Earlier¶
On this page
Warning
Version 0.10 of the MongoDB Enterprise Kubernetes Operator included breaking changes and requires some additional preparation before upgrading. The following procedure outlines the upgrade process for Kubernetes Operator versions 0.9 and earlier. If you are already running version 0.10 or later, see Upgrade from Operator Version 0.10 and Later for upgrade instructions.
Version 0.10 of the Kubernetes Operator consolidated the
MongoDbStandalone
, MongoDbShardedCluster
, and
MongoDbReplicaSet
CustomResourceDefinitions into a
single CustomResourceDefinition
called MongoDB
.
Important
The following upgrade procedure allows you to keep data stored in persistent volumes from previous deployments that the Kubernetes Operator managed. If you do not wish to retain data from previous deployments and plan on deploying new resources, skip to the Upgrade section.
Prerequisites¶
Verify you have the
.yaml
configuration file for each MongoDB resource you have deployed.Standalone ResourcesIf you have standalone resources but do not have the
.yaml
configuration file for them, run the following command to generate the configuration file:Replica Set ResourcesIf you have replica set resources but do not have the
.yaml
configuration file for them, run the following command to generate the configuration file:Sharded Cluster ResourcesIf you have sharded cluster resources but do not have the
.yaml
configuration file for them, run the following command to generate the configuration file:Edit each
.yaml
configuration file match the new CustomResourceDefinition:Change the
kind
toMongoDB
Add the
spec.type
field and set it toStandalone
,ReplicaSet
, orShardedCluster
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
toReplicaSet
and setspec.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:- Standalone
- Replica Set
- Sharded Cluster
Warning
If you change the
metadata.name
field you will lose your resource’s data.
Upgrade the Kubernetes Operator¶
To upgrade to the latest version of the Kubernetes Operator from version v0.9 or earlier:
- Change to the directory in which you cloned the Kubernetes Operator repository. The following steps depend on how your environment is configured:
- Online using kubectl
- Online using Helm
- Offline using Helm and Docker
Upgrade 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 upgrading 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
Note
Any values enclosed in single or double quotes require those quotes. Include the quotes when setting these values.
Upgrade 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.
Upgrade the latest version of 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.
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:
- The Internet
- Another Host
Upgrade the latest version of 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.
Upgrade the latest version of 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
Recreate MongoDB Resources and Delete the Version 0.9 CRDs¶
After you upgrade the Kubernetes Operator, verify you have four CRDs by running the following command:
The following output contains the new
mongodb.mongodb.com
CRD and the version 0.9 CRDs: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:
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.Create the MongoDB resources again.
Use the
.yaml
resource configuration file to recreate each resource:Note
If the old resources had
persistent: true
set and themetadata.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 theRunning
status:For an example of this command’s output, see Get Status of MongoDB Resource.
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:
Run the following command to verify the old CRDs were removed:
The output of the command above should look similar to the following:
Once the version 0.9 CustomResourceDefinitions 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.