Skip to content

Commit 8a7ea1f

Browse files
kennethdyerianf-mongodb
kennethdyer
and
ianf-mongodb
authored
DOCSP-33215 Restore from Sharded Backup (#5578) - Backport to v6.0 (#5676)
* DOCSP-33215 Restore from Sharded Backup (#5578) * DOCSP-33219 Restore Sharded Cluster * Restore notice for backup * Vale checks * Fixes admonition * Fixes per Ian Co-authored-by: ianf-mongodb <[email protected]> * Fixes per Ian * Fixes per Ian * Fixes per Ian * fixes per Ian --------- Co-authored-by: ianf-mongodb <[email protected]> * Fixes build issue --------- Co-authored-by: ianf-mongodb <[email protected]>
1 parent 2f06b2a commit 8a7ea1f

5 files changed

+234
-24
lines changed

‎source/includes/extracts-sharded-clusters-backup-restore-limitations.yaml‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,22 @@
11
ref: sharded-clusters-backup-restore-mongodump-mongorestore-restriction
22
content: |
3-
4-
:binary:`~bin.mongodump` and :binary:`~bin.mongorestore`
5-
:red:`cannot` be part of a backup strategy for 4.2+ sharded clusters
6-
that have sharded transactions in progress, as backups created with
7-
:binary:`~bin.mongodump` *do not maintain* the atomicity guarantees
8-
of transactions across shards.
93
10-
For 4.2+ sharded clusters with in-progress sharded transactions, use
11-
one of the following coordinated backup and restore processes which
12-
*do maintain* the atomicity guarantees of transactions across shards:
4+
To use :program:`mongodump` and :program:`mongorestore` as a backup strategy
5+
for sharded clusters, you must stop the
6+
:ref:`sharded cluster balancer <sharding-balancing>` and use the
7+
:dbcommand:`fsync` command or the :method:`db.fsyncLock` method on
8+
:program:`mongos` to block writes on the cluster during backups.
139
14-
- `MongoDB Atlas <https://www.mongodb.com/atlas/database?tck=docs_server>`_,
10+
Sharded clusters can also use one of the following coordinated backup
11+
and restore processes, which maintain the atomicity guarantees of
12+
transactions across shards:
13+
14+
- `MongoDB Atlas <https://www.mongodb.com/atlas/database?tck=docs_server>`_
1515
1616
- `MongoDB Cloud Manager
17-
<https://www.mongodb.com/cloud/cloud-manager?tck=docs_server>`_, or
18-
17+
<https://www.mongodb.com/cloud/cloud-manager?tck=docs_server>`_
18+
1919
- `MongoDB Ops Manager
20-
<https://www.mongodb.com/products/ops-manager?tck=docs_server>`_.
21-
20+
<https://www.mongodb.com/products/ops-manager?tck=docs_server>`_
2221
2322
...

‎source/includes/note-shard-cluster-backup.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. important:: To capture a point-in-time backup from a sharded
2-
cluster you **must** stop *all* writes to the cluster. On a running
3-
production system, you can only capture an *approximation* of
4-
point-in-time snapshot.
1+
.. important::
2+
3+
To capture a consistent backup from a sharded
4+
cluster you **must** stop *all* writes to the cluster.

‎source/includes/sharded-clusters-backup-restore-file-system-snapshot-restriction.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ In MongoDB 4.2+, you cannot use :doc:`file system snapshots
33
transactions across shards because those backups do not maintain
44
atomicity. Instead, use one of the following to perform the backups:
55

6-
- `MongoDB Atlas <https://docs.atlas.mongodb.com/>`_,
6+
- `MongoDB Atlas <https://docs.atlas.mongodb.com/>`_
77

8-
- `MongoDB Cloud Manager <https://docs.cloudmanager.mongodb.com/>`_, or
8+
- `MongoDB Cloud Manager <https://docs.cloudmanager.mongodb.com/>`_
99

10-
- `MongoDB Ops Manager <https://docs.opsmanager.mongodb.com/>`_.
10+
- `MongoDB Ops Manager <https://docs.opsmanager.mongodb.com/>`_

‎source/tutorial/backup-sharded-cluster-with-database-dumps.txt‎

Lines changed: 212 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,219 @@ Back Up a Sharded Cluster with Database Dumps
66

77
.. default-domain:: mongodb
88

9+
To take a consistent backup of a sharded cluster with ``mongodump``, you must
10+
first stop the balancer, stop writes, and stop any schema transformation
11+
operations on the cluster. This ensures that the cluster remains in a
12+
consistent state for the duration of the backup.
913

14+
MongoDB provides backup and restore operations that can run with the balancer
15+
and running transactions through the following services:
1016

17+
- `MongoDB Atlas <https://www.mongodb.com/atlas/database?tck=docs_server>`_
1118

12-
.. note::
19+
- `MongoDB Cloud Manager <https://www.mongodb.com/cloud/cloud-manager?tck=docs_server>`_
20+
21+
- `MongoDB Ops Manager <https://www.mongodb.com/products/ops-manager?tck=docs_server>`_
22+
23+
Before you Begin
24+
----------------
25+
26+
This task uses :program:`mongodump` to back up a sharded cluster. Ensure
27+
that you have a cluster running that contains data in sharded collections.
28+
29+
Admin Privileges
30+
~~~~~~~~~~~~~~~~
31+
32+
To perform these tasks, your user must have the :authaction:`fsync`
33+
authorization, which allows the user to run the :dbcommand:`fsync` and
34+
:dbcommand:`fsyncUnlock` commands.
35+
36+
Steps
37+
-----
38+
39+
To take a self-managed backup of a sharded cluster, complete the following
40+
steps:
41+
42+
.. procedure::
43+
:style: normal
44+
45+
.. step:: Find a Backup Window
46+
47+
To find a good time to perform a backup, monitor your application
48+
and database usage to find a time when chunk migrations, resharding,
49+
and schema transformation operations are unlikely to occur, as these can cause an
50+
inconsistent backup.
51+
52+
For more information, see :ref:`sharded-schedule-backup`.
53+
54+
.. step:: Stop the Balancer
55+
56+
To prevent chunk migrations from distruping the backup, connect to
57+
:program:`mongos` and use the :method:`sh.stopBalancer` method to stop
58+
the balancer:
59+
60+
.. code-block:: javascript
61+
62+
sh.stopBalancer()
63+
64+
If a balancing round is in progress, the operation waits for balancing to
65+
complete.
66+
67+
To confirm that the balancer is stopped, use the
68+
:method:`sh.getBalancerState` method:
69+
70+
.. io-code-block::
71+
72+
.. input::
73+
:language: javascript
74+
75+
sh.getBalancerState()
76+
77+
.. output::
78+
:language: javascript
79+
80+
false
81+
82+
The command returns ``false`` when the balancer is stopped.
83+
84+
.. step:: Lock the Cluster
85+
86+
The sharded cluster must remain locked during the backup process to protect
87+
the database from writes, which may cause inconsistencies in the backup.
88+
89+
To lock a sharded cluster, connect to :program:`mongos` and use the
90+
:method:`db.fsyncLock` method:
91+
92+
.. code-block:: javascript
93+
94+
db.getSiblingDB("admin").fsyncLock()
95+
96+
To confirm the lock, on :program:`mongos` and the primary
97+
:program:`mongod` of the config servers, run the following
98+
aggregation pipeline and ensure that all the shards are
99+
locked:
100+
101+
.. io-code-block::
102+
103+
.. input::
104+
:language: javascript
105+
106+
db.getSiblingDB("admin").aggregate( [
107+
{ $currentOp: { } },
108+
{ $facet: {
109+
"locked": [
110+
{ $match: { $and: [
111+
{ fsyncLock: { $exists: true } },
112+
{ fsyncLock: true }
113+
] } }],
114+
"unlocked": [
115+
{ $match: { fsyncLock: { $exists: false } } }
116+
]
117+
} },
118+
{ $project: {
119+
"fsyncLocked": { $gt: [ { $size: "$locked" }, 0 ] },
120+
"fsyncUnlocked": { $gt: [ { $size: "$unlocked" }, 0 ] }
121+
} }
122+
] )
123+
124+
.. output::
125+
:language: json
126+
127+
[ { fsyncLocked: true }, { fsyncUnlocked: false } ]
128+
129+
.. step:: Take Backup
130+
131+
To back up the sharded cluster, use ``mongodump`` to connect to
132+
:program:`mongos` and perform the backup:
133+
134+
.. code-block:: bash
135+
136+
mongodump \
137+
--host mongos.example.net \
138+
--port 27017 \
139+
--username user \
140+
--password "passwd" \
141+
--out /opt/backups/example-cluster-1
142+
143+
.. step:: Unlock the Cluster
144+
145+
After the backup completes, you can unlock the cluster to allow writes
146+
to resume.
147+
148+
To unlock the cluster, use the :method:`db.fsyncUnlock` method:
149+
150+
.. code-block:: bash
151+
152+
db.getSibling("admin").fsyncUnlock()
153+
154+
To confirm the unlock, on :program:`mongos` and the primary
155+
:program:`mongod` of the config servers, run the following
156+
aggregation pipeline and ensure that all shards are unlocked:
157+
158+
.. io-code-block::
159+
160+
.. input::
161+
:language: javascript
162+
163+
db.getSiblingDB("admin").aggregate( [
164+
{ $currentOp: { } },
165+
{ $facet: {
166+
"locked": [
167+
{ $match: { $and: [
168+
{ fsyncLock: { $exists: true } },
169+
{ fsyncLock: true }
170+
] } }],
171+
"unlocked": [
172+
{ $match: { fsyncLock: { $exists: false } } }
173+
]
174+
} },
175+
{ $project: {
176+
"fsyncLocked": { $gt: [ { $size: "$locked" }, 0 ] },
177+
"fsyncUnlocked": { $gt: [ { $size: "$unlocked" }, 0 ] }
178+
} }
179+
] )
180+
181+
.. output::
182+
:language: json
183+
184+
[ { fsyncLocked: false }, { fsyncUnlocked: true } ]
185+
186+
.. step:: Restart the Balancer
187+
188+
To restart the balancer, use the :method:`sh.startBalancer` method:
189+
190+
.. code-block:: javascript
191+
192+
sh.startBalancer()
193+
194+
To confirm that the balancer is running, use the
195+
:method:`sh.getBalancerState` method:
196+
197+
.. io-code-block::
198+
199+
.. input::
200+
:language: javascript
201+
202+
sh.getBalancerState()
203+
204+
.. output::
205+
:language: javascript
206+
207+
true
208+
209+
The command returns ``true`` when the balancer is running.
210+
211+
Next Steps
212+
----------
213+
214+
You can restore a database from a :program:`mongodump` backup using
215+
:program:`mongorestore`.
216+
217+
- To restore a sharded cluster, execute ``mongorestore`` against
218+
:program:`mongos`.
219+
220+
- To migrate to a replica set or standalone server, execute ``mongorestore``
221+
against :program:`mongod`.
222+
223+
For more information, see :ref:`manual-tutorial-backup-and-restore`.
13224

14-
.. include:: /includes/extracts/sharded-clusters-backup-restore-mongodump-mongorestore-restriction.rst
15-

‎source/tutorial/schedule-backup-window-for-sharded-clusters.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _sharded-schedule-backup:
2+
13
===========================================
24
Schedule Backup Window for Sharded Clusters
35
===========================================

0 commit comments

Comments
 (0)