DOCSP-4997 - One CRD upgrade procedure. (#19)

jdestefano-mongo · jwilliams-mongo · commit 8ea7c9198cd9 · 2025-04-14T17:11:13.000-05:00
* DOCSP-4997 - One CRD update documentation. * DOCSP-4997 - One CRD upgrade procedure. * DOCSP-4997 - Tech review feedback. * DOCSP-4997 - Copy and tech review feedback.
diff --git a/source/includes/fact-cannot-change-type.rst b/source/includes/fact-cannot-change-type.rst
@@ -0,0 +1,11 @@
+.. note::
+
+   The |k8s-op-short| 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
+   |k8s-op-short| throws an error and requires you to revert to the
+   previously working configuration.
diff --git a/source/includes/upgrade-one-crd-prereqs.rst b/source/includes/upgrade-one-crd-prereqs.rst
@@ -0,0 +1,81 @@
+1. Verify you have the ``.yaml`` configuration file for each MongoDB
+   resource you have deployed.
+
+   .. Formating hack, need whitespace below too
+
+   | \ 
+   | **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:
+
+   .. code-block:: sh
+
+      kubectl mst <standalone-name> -n <namespace> -o yaml > <standalone-conf-name>.yaml
+
+   .. Formating hack, need whitespace below too
+
+   | \ 
+   | **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:
+
+   .. code-block:: sh
+
+      kubectl get mrs <replicaset-name> -n <namespace> -o yaml > <replicaset-conf-name>.yaml
+
+   .. Formating hack, need whitespace below too
+
+   | \ 
+   | **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:
+
+   .. code-block:: sh
+
+      kubectl get msc <shardedcluster-name> -n <namespace> -o yaml > <shardedcluster-conf-name>.yaml
+
+#. Edit each ``.yaml`` configuration file match the new |k8s-crd|:
+
+   - Change the ``kind`` to ``MongoDB``
+   - Add the ``spec.type`` field and set it to ``Standalone``,
+     ``ReplicaSet``, or ``ShardedCluster`` depending on your resource.
+
+     .. include:: /includes/fact-cannot-change-type.rst
+
+   After you edit each ``.yaml`` file, it should look like the following
+   example:
+
+   .. tabs-deployments::
+
+      tabs:
+        - id: standalone
+          content: |
+            .. literalinclude:: /reference/k8s/example-standalone-minimal.yaml
+               :language: yaml
+               :emphasize-lines: 3,13
+
+        - id: repl
+          content: |
+            .. literalinclude:: /reference/k8s/example-replica-set-minimal.yaml
+               :language: yaml
+               :emphasize-lines: 3,14
+
+        - id: shard
+          content: |
+            .. literalinclude:: /reference/k8s/example-sharded-cluster-minimal.yaml
+               :language: yaml
+               :emphasize-lines: 3,17
+
+   .. warning::
+
+      If you change the ``metadata.name`` field you will lose your
+      resource's data.
diff --git a/source/includes/upgrade-one-crd.rst b/source/includes/upgrade-one-crd.rst
@@ -0,0 +1,108 @@
+1. After you upgrade the |k8s-op-short|, verify you have four CRDs by
+   running the following command:
+   
+   .. code-block:: sh
+
+      kubectl get crds
+
+   The following output contains the new ``mongodb.mongodb.com`` CRD and
+   the version 0.9 CRDs:
+
+   .. code-block:: sh
+      :copyable: false
+
+      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
+
+#. 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:
+      
+   .. code-block:: sh
+
+      kubectl delete mst --all
+
+   .. code-block:: sh
+
+      kubectl delete mrs --all
+
+   .. code-block:: sh
+
+      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.
+
+#. Create the MongoDB resources again.
+
+   Use the ``.yaml`` resource configuration file to recreate each
+   resource:
+
+   .. code-block:: sh
+
+      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:
+
+   .. code-block:: sh
+
+      kubectl get mdb <resource-name> -n <namespace> -o yaml -w
+
+   For an example of this command's output, see
+   :ref:`get-resource-status`.
+
+| \ 
+
+4. Delete the old CRDs.
+
+   Once all the resources are up and running, delete all of the v0.9
+   CRDs as the |k8s-op-short| no longer watches them:
+
+   .. code-block:: sh
+
+      kubectl delete crd mongodbreplicasets.mongodb.com
+
+   .. code-block:: sh
+
+      kubectl delete crd mongodbshardedclusters.mongodb.com
+
+   .. code-block:: sh
+
+      kubectl delete crd mongodbstandalones.mongodb.com
+      
+   Run the following command to verify the old CRDs were removed:
+   
+   .. code-block:: sh
+
+      kubectl get crds
+  
+   The output of the command above should look similar to the following:
+
+   .. code-block:: sh
+      :copyable: false
+
+      NAME                  CREATED AT
+      mongodb.mongodb.com   2019-03-27T19:30:09Z
diff --git a/source/reference/troubleshooting.txt b/source/reference/troubleshooting.txt
@@ -12,6 +12,8 @@
    :depth: 1
    :class: singlecol
 
+.. _get-resource-status:
+
 Get Status of MongoDB Resource
 ------------------------------
 
diff --git a/source/tutorial/install-k8s-operator.txt b/source/tutorial/install-k8s-operator.txt
@@ -561,7 +561,37 @@ To create your |k8s| secret:
 Upgrade the |k8s-op-full|
 -------------------------
 
-To upgrade to the latest version of the |k8s-op-full|:
+Version 0.10 of the |k8s-op-short| consolidates the 
+``MongoDbStandalone``, ``MongoDbShardedCluster``, and
+``MongoDbReplicaSet`` |k8s-crds| into a
+single ``CustomResourceDefinition`` called ``MongoDB``.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+.. important::
+
+   The following prerequisite steps are necessary if you already have
+   resources managed by the |k8s-op-short| 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 :ref:`upgrade-k8s-operator-procedure`
+   section.
+
+.. include:: /includes/upgrade-one-crd-prereqs.rst
+
+.. _upgrade-k8s-operator-procedure:
+
+Procedure
+~~~~~~~~~
+
+To upgrade to the latest version of the |k8s-op-short|:
+
+1. Change to the directory in which you cloned the |k8s-op-short|
+   repository. The following steps depend on how your environment is
+   configured:
 
 .. tabs::
 
@@ -572,10 +602,7 @@ To upgrade to the latest version of the |k8s-op-full|:
 
          .. _upgrade-k8s-operator-kubectl:
 
-         1. Change to the directory in which you cloned the  
-            |k8s-op-short| repository.
-
-         #. Upgrade the |k8s-crds| for MongoDB deployments using the
+         2. Upgrade the |k8s-crds| for MongoDB deployments using the
             following kubectl_ command:
 
             .. code-block:: sh
@@ -624,10 +651,7 @@ To upgrade to the latest version of the |k8s-op-full|:
 
          .. _upgrade-k8s-operator-helm:
 
-         1. Change to the directory in which you cloned the  
-            |k8s-op-short| repository.
-
-         #. Upgrade the latest version of the |k8s-op-short| using the
+         2. Upgrade the latest version of the |k8s-op-short| using the
             following ``helm`` command:
 
             .. code-block:: sh
@@ -661,10 +685,7 @@ To upgrade to the latest version of the |k8s-op-full|:
                 name: The Internet
                 content: |
 
-                  1. Change to the directory in which you cloned the  
-                     |k8s-op-short| repository.
-
-                  #. Upgrade the latest version of the |k8s-op-short|
+                  2. Upgrade the latest version of the |k8s-op-short|
                      with modified pull policy values using the
                      following ``helm`` command:
 
@@ -690,10 +711,7 @@ To upgrade to the latest version of the |k8s-op-full|:
                 name: Another Host
                 content: |
 
-                  1. Change to the directory in which you installed 
-                     the |k8s-op-short|.
-
-                  #. Upgrade the latest version of the |k8s-op-short|
+                  2. Upgrade the latest version of the |k8s-op-short|
                      with modified pull policy values using the
                      following ``helm`` command:
 
@@ -710,3 +728,17 @@ To upgrade to the latest version of the |k8s-op-full|:
 
                      .. include:: /includes/list-table-k8s-helm-install-options-offline.rst
 
+Recreate MongoDB Resources and Delete the Version 0.9 CRDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/upgrade-one-crd.rst
+
+Once the version 0.9 CRDs are deleted, the |k8s-op-full| upgrade is
+complete.
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+To troubleshoot your |k8s-op-short|, see :ref:`review-k8s-op-logs`.
+
+.. include:: /includes/fact-remove-k8s-resources-first.rst
