PSMDB-1091 Updated the upgrade docs (#784)

Split PSMDB upgrdae into 2 docs Reworked Verify the config step for Upgrade from Community doc modified: docs/css/percona.css modified: docs/install/upgrade-from-mongodb.md'
percona · Oct 24, 2023 · de4dc5e · de4dc5e
1 parent 5ae3adf
commit de4dc5e
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 69 deletions.
diff --git a/docs/css/percona.css b/docs/css/percona.css
@@ -143,6 +143,36 @@ section {
     margin: 0.5em 0.25em 0 0;
 }
 
+<<<<<<< HEAD
 /*.git-revision-date-localized-plugin:before {
   content: url('https://api.iconify.design/mdi/clock-edit-outline.svg');
 }*/
+=======
+/* Custom highlights */
+i[info],
+i[warning] {
+    font-style: normal;
+    font-weight: bold;
+    display: inline-block;
+    padding: 0 0.25em;
+    border-radius: 0.2em;
+}
+i[info] {
+    background-color: #00b8d41a;
+    border-width: 0.05rem;
+    border-style: solid;
+    border-color: #00b8d41a;
+}
+i[info] [class*="moji"] {
+    color: #00b8d4;
+}
+i[warning] {
+    background-color: #ff91001a;
+    border-width: 0.05rem;
+    border-style: solid;
+    border-color: #ff91001a;
+}
+i[warning] [class*="moji"] {
+    color: #ff9100;
+}
+>>>>>>> 791e1f2e... PSMDB-1091 Extended the step about using custom db data and log paths
diff --git a/docs/install/minor-upgrade.md b/docs/install/minor-upgrade.md
@@ -0,0 +1,20 @@
+# Minor upgrade of Percona Server for MongoDB
+
+To upgrade Percona Server for MongoDB to the latest version, follow these steps:
+
+
+1. Stop the `mongod` service:
+
+    ```{.bash data-prompt="$"}
+    $ sudo systemctl stop mongod
+    ```
+
+2. [Install the latest version packages](index.md). Use the command relevant to your operating system.
+
+3. Start the `mongod` service:
+
+    ```{.bash data-prompt="$"}
+    $ sudo systemctl start mongod
+    ```
+
+To upgrade a replica set or a sharded cluster, use the [rolling restart](../glossary.md#term-Rolling-restart) method. It allows you to perform the upgrade with minimum downtime. You upgrade the nodes one by one, while the whole cluster / replica set remains operational.
diff --git a/docs/install/upgrade-from-mongodb.md b/docs/install/upgrade-from-mongodb.md
@@ -1,54 +1,39 @@
-# Upgrade Percona Server for MongoDB
+# Upgrade from MongoDB Community Edition to Percona Server for MongoDB 
 
-An in-place upgrade is done by keeping the existing data in the server. It involves changing out the MongoDB binaries. Generally speaking, the upgrade steps include:
+This document provides instructions for an in-place upgrade from MongoDB Community Edition to Percona Server for MongoDB.
 
-1. Stopping the `mongod` service
-2. Removing the old binaries
-3. Installing the new server version binaries
-4. Restarting the `mongod` service with the same `dbpath` data directory.
+An in-place upgrade is done by keeping the existing data in the server and replacing the MongoDB binaries. Afterwards, you restart the `mongod` service with the same `dbpath` data directory.
 
 An in-place upgrade is suitable for most environments except the ones that use ephemeral storage and/or host addresses.
 
-This document provides upgrade instructions for the following use cases:
+## Procedure
 
-* [Upgrading from MongoDB 7.0 Community Edition](#upgrading-from-mongodb-70-community-edition)
+!!! note
 
-* [Minor upgrade of Percona Server for MongoDB](#minor-upgrade-of-percona-server-for-mongodb)
+    MongoDB creates a user that belongs to two groups, which is a potential security risk. This is fixed in Percona Server for MongoDB: the user is included only in the `mongod` group. To avoid problems with current MongoDB setups, existing user group membership is not changed when you migrate to Percona Server for MongoDB.  Instead, a new `mongod` user is created during installation, and it belongs to the `mongod` group.
 
-## Upgrading from MongoDB 7.0 Community Edition
+This procedure describes an in-place upgrade of a `mongod` instance. If you are using data at rest encryption, refer to the [Upgrading to Percona Server for MongoDB with data at rest encryption enabled](upgrading-to-percona-server-for-mongodb-with-data-at-rest-encryption-enabled) section.
 
-!!! note 
+!!! important 
 
-    MongoDB creates a user that belongs to two groups, which is a potential security risk.  This is fixed in Percona Server for MongoDB: the user is included only in the `mongod` group.  To avoid problems with current MongoDB setups, existing user group membership is not changed when you migrate to Percona Server for MongoDB.  Instead, a new `mongod` user is created during installation, and it belongs to the `mongod` group.
-
-This section describes an in-place upgrade of a `mongod` instance. If you are using data at rest encryption, refer to the [Upgrading to Percona Server for MongoDB with data at rest encryption enabled](#upgrading-to-percona-server-for-mongodb-with-data-at-rest-encryption-enabled) section.
-
-### Prerequisites
-
-Before you start the upgrade, update the MongoDB configuration file
-(`/etc/mongod.conf`) to contain the following settings.
-
-```yaml
-processManagement:
-   fork: true
-   pidFilePath: /var/run/mongod.pid
-```
+    Before starting the upgrade, we recommend to perform a full backup of your data.
 
-**Troubleshooting tip**: The `pidFilePath` setting in `mongod.conf` must  match the `PIDFile` option in the `systemd mongod` service unit. Otherwise, the service will kill the `mongod` process after a timeout.
 
-!!! warning
+=== "Upgrade on Debian and Ubuntu"
 
-    Before starting the upgrade, we recommend to perform a full backup of your data.
+     1. Save the current configuration file as the backup:
 
-=== "Upgrade on Debian and Ubuntu"
+         ```{.bash data-prompt="$"}
+         $ sudo mv /etc/mongod.conf /etc/mongod.conf.bkp
+         ```
 
-     1. Stop the `mongod` service:
+     2. Stop the `mongod` service:
 
          ```{.bash data-prompt="$"}
          $ sudo systemctl stop mongod
          ```
 
-     2. Check for installed packages:
+     3. Check for installed packages:
 
          ```{.bash data-prompt="$"}
          $ sudo dpkg -l | grep mongod
@@ -66,7 +51,7 @@ processManagement:
          ii  mongodb-org-tools                7.0.2                       amd64        MongoDB tools
          ```
 
-     3. Remove the installed packages:
+     4. Remove the installed packages:
 
          ```{.bash data-prompt="$"}
          $ sudo apt remove \
@@ -77,16 +62,29 @@ processManagement:
            mongodb-org-tools
          ```
 
-     4. Remove log files:
-
-         ```{.bash data-prompt="$"}
-         $ sudo rm -r /var/log/mongodb
-         ```
      5. [Install Percona Server for MongoDB](apt.md)
 
-     6. Verify that the configuration file includes the correct options. For example, Percona Server for MongoDB stores data files in /var/lib/mongodb by default. If you used another dbPath data directory, edit the configuration file accordingly
+     6. Verify that the configuration file includes correct options:
+
+         * Copy the required configuration options like custom dbPath/system log path, additional security/replication or sharding options from the backup configuration file (`/etc/mongod.conf`) to the current one `/etc/mongodb.conf`. 
+         * Make sure that the `mongod` user has access to your custom paths. If not, provide it as follows:
 
-     7. Start the `mongod` service:
+            ```{.bash data-prompt="$"}
+            $ sudo chown -R mongod:mongod <custom-dbPath>
+            $ sudo chown -R mongod:mongod <custom-systemLog.path>
+            ```
+
+         * Make sure the configuration file includes the following configuration:
+
+            ```yaml
+            processManagement:
+               fork: true
+               pidFilePath: /var/run/mongod.pid
+            ```
+
+            **Troubleshooting tip**: The `pidFilePath` setting in `mongod.conf` must match the `PIDFile` option in the `systemd mongod` service unit. Otherwise, the service will kill the `mongod` process after a timeout.
+
+     7. Restart the `mongod` service:
 
          ```{.bash data-prompt="$"}
          $ sudo systemctl start mongod
@@ -131,19 +129,29 @@ processManagement:
          mongodb-org-tools-7.0.2-1.el8.x86_64
          ```
      
-     4. Remove log files:
+     4. [Install Percona Server for MongoDB](yum.md)
 
-         ```{.bash data-prompt="$"}
-         $ sudo rm -r /var/log/mongodb
-         ```
+    5. Verify that the configuration file includes correct options:
+
+         * When you remove old packages, your existing configuration file is saved as `/etc/mongod.conf.rpmsave`. Copy the required configuration options like custom dbPath/system log path, additional security/replication or sharding options from the backup configuration file (`/etc/mongod.conf.rpmsave`) to the current one `/etc/mongodb.conf`.
+         * Make sure that the `mongod` user has access to your custom paths. If not, provide it as follows:
 
-     5. [Install Percona Server for MongoDB](yum.md)
+            ```{.bash data-prompt="$"}
+            $ sudo chown -R mongod:mongod <custom-dbPath>
+            $ sudo chown -R mongod:mongod <custom-systemLog.path>
+            ```
 
-        !!! note
+         * Make sure the configuration file includes the following configuration:
 
-            When you remove old packages, your existing configuration file is saved as `/etc/mongod.conf.rpmsave`. If you want to use this configuration with the new version, replace the default `/etc/mongod.conf` file. For example, existing data may not be compatible with the default WiredTiger storage engine.
+            ```yaml
+            processManagement:
+               fork: true
+               pidFilePath: /var/run/mongod.pid
+            ```
 
-    6. Start the `mongod` service:
+            **Troubleshooting tip**: The `pidFilePath` setting in `mongod.conf` must match the `PIDFile` option in the `systemd mongod` service unit. Otherwise, the service will kill the `mongod` process after a timeout.
+
+    6. Restart the `mongod` service:
 
         ```{.bash data-prompt="$"}
         $ sudo systemctl start mongod
@@ -158,27 +166,6 @@ To upgrade a replica set or a sharded cluster, use the [rolling restart](../glos
     * [Upgrade a Replica Set](https://docs.mongodb.com/manual/release-notes/7.0-upgrade-replica-set/)
     * [Upgrade a Sharded Cluster](https://docs.mongodb.com/manual/release-notes/7.0-upgrade-sharded-cluster/)
 
-## Minor upgrade of Percona Server for MongoDB
-
-To upgrade Percona Server for MongoDB to the latest version, follow these steps:
-
-
-1. Stop the `mongod` service:
-
-    ```{.bash data-prompt="$"}
-    $ sudo systemctl stop mongod
-    ```
-
-2. [Install the latest version packages](index.md). Use the command relevant to your operating system.
-
-3. Start the `mongod` service:
-
-    ```{.bash data-prompt="$"}
-    $ sudo systemctl start mongod
-    ```
-
-To upgrade a replica set or a sharded cluster, use the [rolling restart](../glossary.md#term-Rolling-restart) method. It allows you to perform the upgrade with minimum downtime. You upgrade the nodes one by one, while the whole cluster / replica set remains operational.
-
 ## Upgrading to Percona Server for MongoDB with data at rest encryption enabled
 
 Steps to upgrade from MongoDB 6.0 Community Edition with data encryption enabled to Percona Server for MongoDB are different. `mongod` requires an empty `dbPath` data directory because it cannot encrypt data files in place. It must receive data from other replica set members during the initial sync. Please refer to the [Switching storage engines](../inmemory.md#switching-storage-engines) for more information on migration of encrypted data. [Contact us](https://www.percona.com/about-percona/contact#us) for working at the detailed migration steps, if further assistance is needed.

diff --git a/mkdocs-base.yml b/mkdocs-base.yml
@@ -181,7 +181,8 @@ nav:
       - "Tune parameters": "set-parameter.md"
       - Upgrade:
         - "Upgrade from 6.0 to 7.0": "install/upgrade-from-60.md"
-        - install/upgrade-from-mongodb.md
+        - "Upgrade from MongoDB Community": "install/upgrade-from-mongodb.md"
+        - install/minor-upgrade.md
       - install/uninstall.md
   - Release notes:
       - "Release notes index": "release_notes/index.md"