- Install and Configure the Kubernetes Operator >
- Upgrade the Kubernetes Operator from Prior Versions >
- Upgrade from Operator Version 0.9 or Earlier
Upgrade from Operator Version 0.9 or 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 or 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¶
If you have not already, run the following command to execute all
kubectl
commands in the namespace you created: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, they 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:
The following steps depend on how your environment is configured:
- Kubernetes
- OpenShift
- Online using kubectl
- Online using Helm
- Offline using Helm and Docker
Change to the directory in which you cloned the repository.¶
Upgrade the CustomResourceDefinitions for MongoDB deployments using the following kubectl
command:¶
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>
.Important
To watch Ops Manager and MongoDB Kubernetes resources in a different namespace to which you deploy the Kubernetes Operator, see Kubernetes Operator Deployment Scopes for values you must use and additional steps you might have to perform.
You can set the following pair of values:
Example
MONGODB_ENTERPRISE_DATABASE_IMAGE
URL of the MongoDB Enterprise Database image the Kubernetes Operator deploys.
Default value is
quay.io/mongodb/mongodb-enterprise-database
.Example
IMAGE_PULL_POLICY
Pull policy for the MongoDB Enterprise database image the Kubernetes Operator deploys.
Accepted values are
Always
,IfNotPresent
,Never
.Default value is
Always
.Example
OPS_MANAGER_IMAGE_REPOSITORY
URL of the repository from which the image for an Ops Manager resource is downloaded.
Default value is
quay.io/mongodb/mongodb-enterprise-ops-manager
.Example
OPS_MANAGER_IMAGE_PULL_POLICY
Pull policy for the Ops Manager images the Kubernetes Operator deploys.
Accepted values are:
Always
,IfNotPresent
,Never
.Default value is
Always
.Example
INIT_OPS_MANAGER_IMAGE_REPOSITORY
URL of the repository from which the initContainer image that contains Ops Manager start-up scripts and the readiness probe is downloaded.
Default value is
quay.io/mongodb/mongodb-enterprise-ops-manager-init
.Example
INIT_OPS_MANAGER_VERSION
Version of the initContainer image that contains Ops Manager start-up scripts and the readiness probe.
Default value is 1.0.1.
Example
APPDB_IMAGE_REPOSITORY
URL of the repository from which the Application Database image is downloaded.
Default value is
quay.io/mongodb/mongodb-enterprise-appdb
.Example
INIT_APPDB_IMAGE_REPOSITORY
URL of the repository from which the initContainer image that contains Application Database start-up scripts and the readiness probe is downloaded.
Default value is
quay.io/mongodb/mongodb-enterprise-appdb-init
.Example
INIT_APPDB_VERSION
Version of the initContainer image that contains Ops Manager start-up scripts and the readiness probe.
Default value is 1.0.2.
Example
MANAGED_SECURITY_CONTEXT
Flag that determines if the Kubernetes Operator inherits the
securityContext
settings that your Kubernetes cluster manages.Set this field to
true
if you want to run the Kubernetes Operator in OpenShift or in a restrictive environment.Default value is
false
.Example
Upgrade the Kubernetes Operator using the following kubectl
and helm
commands:¶
You can customize your Helm Chart before installing it. To modify it,
add one or more of the following options to the values.yaml
file:
Setting | Purpose | Default | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
namespace |
To use a different namespace, specify that |
mongodb |
|||||||||
managedSecurityContext |
Flag that determines if the Kubernetes Operator inherits the
Set this field to Example |
false |
|||||||||
operator .env |
Label for the Operator’s deployment environment. The
Accepted values are: |
prod |
|||||||||
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.
Important To watch Ops Manager and MongoDB Kubernetes resources in a different namespace to which you deploy the Kubernetes Operator, see Kubernetes Operator Deployment Scopes for values you must use and additional steps you might have to perform. |
<metadata.namespace> |
|||||||||
operator .watchedResources |
Custom resources that the Kubernetes Operator watches. The Kubernetes Operator installs the CustomResourceDefinitions for and watches only the resources you specify. Accepted values are:
|
|
|||||||||
registry .appDb |
Repository from which the Application Database image is pulled. Specify this value if you want to pull the Ops Manager image from a private repository. |
||||||||||
registry .initAppDb |
Repository from which the Application Database initContainer image is pulled. This image contains the start-up scripts and readiness probe for the Application Database. Specify this value if you want to pull the Application Database initContainer image from a private repository. Example |
||||||||||
registry .initOpsManager |
Repository from which the Ops Manager initContainer image is pulled. This image contains the start-up scripts and readiness probe for Ops Manager. Specify this value if you want to pull the Ops Manager
Example |
||||||||||
registry .operator |
Repository from which the Kubernetes Operator image is pulled. Specify this value if you want to pull the Kubernetes Operator image from a private repository. Example |
||||||||||
registry .opsManager |
Repository from which the Ops Manager image is pulled. Specify this value if you want to pull the Ops Manager image from a private repository. Example |
Note
Alternatively, you can pass these values as options when you apply the Helm Chart:
To upgrade the Kubernetes Operator on a host not connected to the Internet:
Upgrade the latest version of the Kubernetes Operator with modified pull policy values using the following helm
command:¶
Invoke the following kubectl
and helm
commands:
You can customize your Helm Chart before installing it. To modify it,
add one or more of the following options to the values.yaml
file:
Setting | Purpose | Default | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
namespace |
To use a different namespace, specify that |
mongodb |
|||||||||
managedSecurityContext |
Flag that determines if the Kubernetes Operator inherits the
Set this field to Example |
false |
|||||||||
operator .env |
Label for the Operator’s deployment environment. The
Accepted values are: |
prod |
|||||||||
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.
Important To watch Ops Manager and MongoDB Kubernetes resources in a different namespace to which you deploy the Kubernetes Operator, see Kubernetes Operator Deployment Scopes for values you must use and additional steps you might have to perform. |
<metadata.namespace> |
|||||||||
operator .watchedResources |
Custom resources that the Kubernetes Operator watches. The Kubernetes Operator installs the CustomResourceDefinitions for and watches only the resources you specify. Accepted values are:
|
|
|||||||||
registry .appDb |
Repository from which the Application Database image is pulled. Specify this value if you want to pull the Ops Manager image from a private repository. |
||||||||||
registry .initAppDb |
Repository from which the Application Database initContainer image is pulled. This image contains the start-up scripts and readiness probe for the Application Database. Specify this value if you want to pull the Application Database initContainer image from a private repository. Example |
||||||||||
registry .initOpsManager |
Repository from which the Ops Manager initContainer image is pulled. This image contains the start-up scripts and readiness probe for Ops Manager. Specify this value if you want to pull the Ops Manager
Example |
||||||||||
registry .operator |
Repository from which the Kubernetes Operator image is pulled. Specify this value if you want to pull the Kubernetes Operator image from a private repository. Example |
||||||||||
registry .opsManager |
Repository from which the Ops Manager image is pulled. Specify this value if you want to pull the Ops Manager image from a private repository. Example |
Note
Alternatively, you can pass these values as options when you apply the Helm Chart:
- Online using oc
- Online using Helm
- Offline using Helm and Docker
Change to the directory in which you cloned the repository.¶
Upgrade the CustomResourceDefinitions for MongoDB deployments.¶
OpenShift 3.11 or earlier
If you run OpenShift 3.11 or earlier, you must first manually edit the CustomResourceDefinitions to remove subresources. In each CustomResourceDefinition, remove the following option:
Invoke the following oc
command:
You can edit the Operator YAML file to further customize your Operator before upgrading it.¶
Open your
mongodb-enterprise-openshift.yaml
in your preferred text editor.You must add your
<openshift-pull-secret>
to theServiceAccount
definitions:You may need to add one or more of the following options:
Environment Variable | Purpose | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
OPERATOR_ENV |
Label for the Operator’s deployment environment. The
Accepted values are: Default value is: 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.
Default value is: Important To watch Ops Manager and MongoDB Kubernetes resources in a different namespace to which you deploy the Kubernetes Operator, see Kubernetes Operator Deployment Scopes for values you must use and additional steps you might have to perform. You can set the following pair of values: Example |
|||||||||
MONGODB_ENTERPRISE_DATABASE_IMAGE |
URL of the MongoDB Enterprise Database image the Kubernetes Operator deploys. Default value is
Example |
|||||||||
IMAGE_PULL_POLICY |
Pull policy for the MongoDB Enterprise database image the Kubernetes Operator deploys. Accepted values are Default value is Example |
|||||||||
OPS_MANAGER_IMAGE_REPOSITORY |
URL of the repository from which the image for an Ops Manager resource is downloaded. Default value is
Example |
|||||||||
OPS_MANAGER_IMAGE_PULL_POLICY |
Pull policy for the image deployed to an Ops Manager resource. Accepted values are Default value is Example |
|||||||||
INIT_OPS_MANAGER_IMAGE_REPOSITORY |
URL of the repository from which the initContainer image that contains Ops Manager start-up scripts and the readiness probe is downloaded. Default value is
Example |
|||||||||
INIT_OPS_MANAGER_VERSION |
Version of the initContainer image that contains Ops Manager start-up scripts and the readiness probe. Default value is 1.0.1. Example |
|||||||||
APPDB_IMAGE_REPOSITORY |
URL of the repository from which the Application Database image is downloaded. Default value is
Example |
|||||||||
INIT_APPDB_IMAGE_REPOSITORY |
URL of the repository from which the Default value is
Example |
|||||||||
INIT_APPDB_VERSION |
Version of the Default value is 1.0.2. Example |
|||||||||
MANAGED_SECURITY_CONTEXT |
Flag that determines if the Kubernetes Operator inherits the
For OpenShift, Default value is Example |
Upgrade the Kubernetes Operator.¶
OpenShift 3.11 or earlier
If you run OpenShift 3.11 or earlier, you must first manually edit the CustomResourceDefinitions to remove subresources. In each CustomResourceDefinition, remove the following option:
Invoke the following oc
and helm
commands:
You can customize your Helm Chart before installing it. To modify it,
add one or more of the following options to the
values-openshift.yaml
file:
Setting | Purpose | Default | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
namespace |
To use a different namespace, specify that Example |
mongodb |
|||||||||
managedSecurityContext |
Flag that determines if the Kubernetes Operator inherits the
For OpenShift, Example |
true |
|||||||||
operator .env |
Label for the Operator’s deployment environment. The
Accepted values are: Example |
prod |
|||||||||
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.
Example Important To watch Ops Manager and MongoDB Kubernetes resources in a different namespace to which you deploy the Kubernetes Operator, see Kubernetes Operator Deployment Scopes for values you must use and additional steps you might have to perform. |
<metadata.namespace> |
|||||||||
operator .watchedResources |
Custom resources that the Kubernetes Operator watches. The Kubernetes Operator installs the CustomResourceDefinitions for and watches only the resources you specify. Accepted values are:
Example |
|
|||||||||
registry .appDb |
Repository from which the Application Database image is pulled. Specify this value if you want to pull the Ops Manager image from a private repository. Example |
||||||||||
registry .imagePullSecrets |
secret that contains the credentials required to pull imagePullSecrets from the repository. Important OpenShift requires this setting. Define it in this file or pass it when you install the Kubernetes Operator using Helm. Example |
||||||||||
registry .operator |
Repository from which the Kubernetes Operator image is pulled. Specify this value if you want to pull the Kubernetes Operator image from a private repository. Example |
||||||||||
registry .opsManager |
Repository from which OpenShift pulls the Ops Manager image. Specify this value if you want to pull the Ops Manager image from a private repository. Example |
||||||||||
registry .initAppDb |
Repository from which the Application Database Specify this value if you want to pull the Application Database
Example |
||||||||||
registry .initOpsManager |
Repository from which the Ops Manager Specify this value if you want to pull the Ops Manager
Example |
Note
Alternatively, you can pass these values as options when you apply the Helm Chart:
To upgrade the Kubernetes Operator on a host not connected to the Internet:
Upgrade the latest version of the Kubernetes Operator with modified pull policy values.¶
OpenShift 3.11 or earlier
If you run OpenShift 3.11 or earlier, you must first manually edit the CustomResourceDefinitions to remove subresources. In each CustomResourceDefinition, remove the following option:
Invoke the following oc
and helm
commands:
You can customize your Helm Chart before installing it. To modify it,
add one or more of the following options to the
values-openshift.yaml
file:
Setting | Purpose | Default | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
namespace |
To use a different namespace, specify that Example |
mongodb |
|||||||||
managedSecurityContext |
Flag that determines if the Kubernetes Operator inherits the
For OpenShift, Example |
true |
|||||||||
operator .env |
Label for the Operator’s deployment environment. The
Accepted values are: Example |
prod |
|||||||||
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.
Example Important To watch Ops Manager and MongoDB Kubernetes resources in a different namespace to which you deploy the Kubernetes Operator, see Kubernetes Operator Deployment Scopes for values you must use and additional steps you might have to perform. |
<metadata.namespace> |
|||||||||
operator .watchedResources |
Custom resources that the Kubernetes Operator watches. The Kubernetes Operator installs the CustomResourceDefinitions for and watches only the resources you specify. Accepted values are:
Example |
|
|||||||||
registry .appDb |
Repository from which the Application Database image is pulled. Specify this value if you want to pull the Ops Manager image from a private repository. Example |
||||||||||
registry .imagePullSecrets |
secret that contains the credentials required to pull imagePullSecrets from the repository. Important OpenShift requires this setting. Define it in this file or pass it when you install the Kubernetes Operator using Helm. Example |
||||||||||
registry .operator |
Repository from which the Kubernetes Operator image is pulled. Specify this value if you want to pull the Kubernetes Operator image from a private repository. Example |
||||||||||
registry .opsManager |
Repository from which OpenShift pulls the Ops Manager image. Specify this value if you want to pull the Ops Manager image from a private repository. Example |
||||||||||
registry .initAppDb |
Repository from which the Application Database Specify this value if you want to pull the Application Database
Example |
||||||||||
registry .initOpsManager |
Repository from which the Ops Manager Specify this value if you want to pull the Ops Manager
Example |
Note
Alternatively, you can pass these values as options when you apply the Helm Chart:
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.
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 a Deployed 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.