From 4f8532ce1da89b2e28dd3ffe8bdc9ba77dbe4a7b Mon Sep 17 00:00:00 2001 From: Lauren Tran Date: Wed, 13 Nov 2024 15:30:55 -0500 Subject: [PATCH 1/6] DOCSP-44528-cutover-failure-warnings' --- source/reference/cutover-process.txt | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index 0c5394014..3db75171d 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -20,11 +20,22 @@ workload from the source to the destination cluster using the :ref:`COMMITTED ` state. This allows ``mongosync`` to sync any additional writes that occur during the migration. -.. note:: - - Before you switch your application workload to the - destination cluster, you should always verify a successful sync. - For more information, see :ref:`c2c-verification`. +.. warning:: + + Failing to properly cutover from your source cluster to your + destination may result in the following application issues: + + - Garbage data on the destination cluster + - Commit failures with no option to rollback the sync + - Unrecoverable and undiagnosable ``mongosync`` errors + - Reduced application availibility, especially if there is + application-side enforcement of document schema or other + characteristics + - Missing transactions on the destination cluster + - Other unexpected cluster behavior + + You must use the following steps to safely finalize your cutover process and achieve + expected ``mongosync`` behavior. Steps ----- From a550c750737f04760bc30891e2e133179d660d90 Mon Sep 17 00:00:00 2001 From: Lauren Tran Date: Wed, 13 Nov 2024 15:39:53 -0500 Subject: [PATCH 2/6] DOCSP-44528-cutover-failure-warnings' --- source/reference/cutover-process.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index 3db75171d..e2922df2d 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -16,14 +16,20 @@ You can finalize a migration and transfer your application workload from the source to the destination cluster using the :ref:`mongosync ` cutover process. +.. note:: + + Before you switch your application workload to the + destination cluster, you should always verify a successful sync. + For more information, see :ref:`c2c-verification`. + ``mongosync`` should remain active until it reaches the :ref:`COMMITTED ` state. This allows ``mongosync`` to sync any additional writes that occur during the migration. .. warning:: - Failing to properly cutover from your source cluster to your - destination may result in the following application issues: + If you do not properly cutover from your source to your + destination, you may face the following issues: - Garbage data on the destination cluster - Commit failures with no option to rollback the sync From 594fc7c0458729072012317b7585675836a959f2 Mon Sep 17 00:00:00 2001 From: Lauren Tran Date: Wed, 13 Nov 2024 15:47:31 -0500 Subject: [PATCH 3/6] DOCSP-44528 adding disaster warning --- source/reference/cutover-process.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index e2922df2d..1bef18b81 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -132,11 +132,16 @@ Steps :language: json :copyable: false - .. note:: + After you submit a ``commit`` request, call the ``progress`` endpoint + to ensure that the ``mongosync`` state is ``COMMITTING`` or + ``COMMITTED``. - After you submit a ``commit`` request, call the ``progress`` endpoint - to ensure that the ``mongosync`` state is ``COMMITTING`` or - ``COMMITTED``. + .. warning:: + + If the source cluster shuts down before mongosync can commit, such + as in a disaster scenario, the destination cluster might not have + a consistent snapshot of the source data. To learn more, see + Consistency. .. step:: Wait until you can perform writes on the destination cluster. From 0620ac4becc7247af938d4d0d8422801ae56bffd Mon Sep 17 00:00:00 2001 From: Lauren Tran Date: Wed, 13 Nov 2024 15:53:00 -0500 Subject: [PATCH 4/6] DOCSP-44528 adding disaster warning --- source/reference/cutover-process.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index 1bef18b81..463d19364 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -141,7 +141,7 @@ Steps If the source cluster shuts down before mongosync can commit, such as in a disaster scenario, the destination cluster might not have a consistent snapshot of the source data. To learn more, see - Consistency. + :ref:`c2c-behavior-consistency`. .. step:: Wait until you can perform writes on the destination cluster. From eead8ef125177d65bde41b7d8211a0049f04cd4a Mon Sep 17 00:00:00 2001 From: Lauren Tran Date: Thu, 14 Nov 2024 10:28:17 -0500 Subject: [PATCH 5/6] DOCSP-44528 copy edit --- source/reference/cutover-process.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index 463d19364..b1d4819f3 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -31,10 +31,10 @@ any additional writes that occur during the migration. If you do not properly cutover from your source to your destination, you may face the following issues: - - Garbage data on the destination cluster + - Unstructured or unneeded data on the destination cluster - Commit failures with no option to rollback the sync - Unrecoverable and undiagnosable ``mongosync`` errors - - Reduced application availibility, especially if there is + - Reduced application availability, especially if there is application-side enforcement of document schema or other characteristics - Missing transactions on the destination cluster From e74bdbc5cb962db516af445e1d53260da08da35b Mon Sep 17 00:00:00 2001 From: Lauren Tran Date: Mon, 18 Nov 2024 10:14:52 -0500 Subject: [PATCH 6/6] DOCSP-44528 Maria comments --- source/includes/cluster-shutdown-warning.rst | 3 +++ source/reference/cutover-process.txt | 12 ++++-------- source/reference/mongosync/mongosync-behavior.txt | 4 +--- 3 files changed, 8 insertions(+), 11 deletions(-) create mode 100644 source/includes/cluster-shutdown-warning.rst diff --git a/source/includes/cluster-shutdown-warning.rst b/source/includes/cluster-shutdown-warning.rst new file mode 100644 index 000000000..a8a3e5edd --- /dev/null +++ b/source/includes/cluster-shutdown-warning.rst @@ -0,0 +1,3 @@ +If the source cluster shuts down before ``mongosync`` can commit, such as in +a disaster scenario, the destination cluster might not have a consistent +snapshot of the source data. To learn more, see :ref:`c2c-behavior-consistency`. \ No newline at end of file diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index b1d4819f3..b63a9e46f 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -31,16 +31,15 @@ any additional writes that occur during the migration. If you do not properly cutover from your source to your destination, you may face the following issues: - - Unstructured or unneeded data on the destination cluster - - Commit failures with no option to rollback the sync + - Inaccurate data on the destination cluster - Unrecoverable and undiagnosable ``mongosync`` errors - Reduced application availability, especially if there is application-side enforcement of document schema or other characteristics - - Missing transactions on the destination cluster + - Incomplete transactions on the destination cluster - Other unexpected cluster behavior - You must use the following steps to safely finalize your cutover process and achieve + Use the following steps to safely finalize your cutover process and achieve expected ``mongosync`` behavior. Steps @@ -138,10 +137,7 @@ Steps .. warning:: - If the source cluster shuts down before mongosync can commit, such - as in a disaster scenario, the destination cluster might not have - a consistent snapshot of the source data. To learn more, see - :ref:`c2c-behavior-consistency`. + .. include:: /includes/cluster-shutdown-warning .. step:: Wait until you can perform writes on the destination cluster. diff --git a/source/reference/mongosync/mongosync-behavior.txt b/source/reference/mongosync/mongosync-behavior.txt index e83a776dc..259b0c2b8 100644 --- a/source/reference/mongosync/mongosync-behavior.txt +++ b/source/reference/mongosync/mongosync-behavior.txt @@ -203,9 +203,7 @@ For any continuous synchronization use cases with ``mongosync``, ensure that ``mongosync`` commits before cutting over from the source to the destination. -If the source cluster shuts down before ``mongosync`` can commit, such as in -a disaster scenario, the destination cluster might not have a consistent -snapshot of the source data. To learn more, see :ref:`c2c-behavior-consistency`. +.. include:: /includes/cluster-shutdown-warning .. note::