Mmuzaf commented on a change in pull request #8128: URL: https://github.com/apache/ignite/pull/8128#discussion_r484828072
########## File path: docs/_docs/persistence/snapshot.adoc ########## @@ -0,0 +1,181 @@ += Snapshots and recovery + +== Overview + +Apache Ignite 2.9 comes with an ability to create fully consistent cluster-wide snapshots for deployments with +the link:persistence/native-persistence[Ignite Native Persistence]. You can create at runtime any number of snapshots +of all configured persistent cache groups. The snapshot is a consistent copy of all cache group data files (except +structures used for crash recovery) for each baseline node in a cluster. Since data of persistent cache groups stored +on disk in files on each node (cache group partition files, configuration files, binary metadata) the snapshot will +contain a copy of the same files with keeping Ignite cluster node data directory structure and the node consistent ids. + +*Snapshot Consistency.* + +All snapshots you created are fully consistent in terms of concurrent cluster-wide operations and all ongoing changes of +system files on the local node. Primary and backup cache group partitions will be also fully consistent in created +snapshots. + +The cluster-wide snapshot consistency achieved by triggering the +link:https://cwiki.apache.org/confluence/display/IGNITE/%28Partition+Map%29+Exchange+-+under+the+hood[Partition-Map-Exchange] +procedure. Doing this the cluster will eventually get a point in time when all previously started transactions +finished on primary and backups, and new ones are hold until a new snapshot operation will be started. + +The local system files consistency (e.g. cache group partition files, binary metadata files, configuration files) achieved +by copying them to the destination snapshot directory with tracking all concurrent ongoing changes. Tracking concurrent +changes during copying of cache group partition files will require additional space in Ignite system directory. + +*Snapshot Structure.* + +The created snapshot has the same +link:https://cwiki.apache.org/confluence/display/IGNITE/Ignite+Persistent+Store+-+under+the+hood#IgnitePersistentStoreunderthehood-FoldersStructure[Directory Structure] +as the Ignite native persistence does with keeping nodes `consistentId` in snapshot directory. The `wal` directory will +be excluded from snapshot since recovery procedures are not necessary for cache group data files. + +.Example of snapshot directory structure +[source,shell] +---- +work +└── snapshots + └── backup23012020 + ├── binary_meta + │ ├── snapshot_IgniteClusterSnapshotSelfTest0 + │ ├── snapshot_IgniteClusterSnapshotSelfTest1 + │ └── snapshot_IgniteClusterSnapshotSelfTest2 + ├── db + │ ├── snapshot_IgniteClusterSnapshotSelfTest0 + │ │ └── cache-txCache + │ │ ├── cache_data.dat + │ │ ├── part-3.bin + │ │ ├── part-4.bin + │ │ └── part-6.bin + │ ├── snapshot_IgniteClusterSnapshotSelfTest1 + │ │ └── cache-txCache + │ │ ├── cache_data.dat + │ │ ├── part-1.bin + │ │ ├── part-5.bin + │ │ └── part-7.bin + │ └── snapshot_IgniteClusterSnapshotSelfTest2 + │ └── cache-txCache + │ ├── cache_data.dat + │ ├── part-0.bin + │ └── part-2.bin + └── marshaller +---- + +*Requirements.* + +You need an extra space on disk for the configured Ignite native persistence directory up to the current size this directory. +This space will be used for storing intermediate snapshot results and will be freed when the snapshot operation ends. + +*Limitations.* + +The snapshot procedure has some limitations that you should be aware of before using it at your production environment: + +* taking a snapshot of particular cache or cache group not supported; +* in-memory caches will not be included into snapshot; +* encrypted caches not supported and will be ignored; +* only single snapshot operation can be started at once; +* snapshot procedure will be interrupted if any baseline node leave the cluster; +* snapshot recovery at the same baseline topology with the same consistent node id; + +== Configuration + +You may configure the destination snapshot directory via `IgniteConfiguration`. + +[tabs] +-- +tab:XML[] + +[source, xml] +---- +include::code-snippets/xml/snapshots.xml[tags=ignite-config;!discovery, indent=0] + +---- + +tab:Java[] + +[source, java] +---- +include::{javaCodeDir}/Snapshots.java[tags=config, indent=0] + +---- + +tab:C#/.NET[] +tab:C++[] +-- + +== Snapshot creation + +Ignite provides the ability to start a snapshot operation from the following interfaces: + +- link:#command-line[Command line] +- link:#jmx[JMX] +- link:#java-api[Java API] + +=== Command line + +Ignite ships `control.(sh|bat)` scripts, located in the `$IGNITE_HOME/bin` directory, that acts like a tool to Review comment: Fixed. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
