This is an automated email from the ASF dual-hosted git repository.
dmagda pushed a commit to branch IGNITE-7595
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push:
new b5c116f IGNITE-12968 Snapshot documentation pages (#8128)
b5c116f is described below
commit b5c116f844bf02ed5ac992bd5919fbe9151cbd89
Author: Maxim Muzafarov <[email protected]>
AuthorDate: Thu Sep 17 19:22:01 2020 +0300
IGNITE-12968 Snapshot documentation pages (#8128)
* IGNITE-12968: Adding Ignite Snapshots documentation
---
.../java/org/apache/ignite/snippets/Snapshots.java | 38 ++++
docs/_docs/code-snippets/xml/snapshots.xml | 36 ++++
docs/_docs/persistence/snapshot.adoc | 198 +++++++++++++++++++++
3 files changed, 272 insertions(+)
diff --git
a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Snapshots.java
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Snapshots.java
new file mode 100644
index 0000000..bea5a27
--- /dev/null
+++
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/Snapshots.java
@@ -0,0 +1,38 @@
+package org.apache.ignite.snippets;
+
+import org.apache.ignite.Ignite;
+import org.apache.ignite.Ignition;
+import org.apache.ignite.configuration.CacheConfiguration;
+import org.apache.ignite.configuration.IgniteConfiguration;
+import org.apache.ignite.spi.encryption.keystore.KeystoreEncryptionSpi;
+
+public class Snapshots {
+
+ void configuration() {
+ //tag::config[]
+ IgniteConfiguration cfg = new IgniteConfiguration();
+
+ File exSnpDir = U.resolveWorkDirectory(U.defaultWorkDirectory(),
"ex_snapshots", true);
+
+ cfg.setSnapshotPath(exSnpDir.getAbsolutePath());
+ //end::config[]
+
+ Ignite ignite = Ignition.start(cfg);
+
+ //tag::create[]
+ CacheConfiguration<Long, String> ccfg = new CacheConfiguration<Long,
String>("snapshot-cache");
+
+ try (IgniteCache<Long, String> cache = ignite.getOrCreateCache(ccfg)) {
+ cache.put(1, "Maxim");
+
+ // Start snapshot operation.
+ ignite.snapshot().createSnapshot("snapshot_02092020").get();
+ }
+ finally {
+ ignite.destroyCache(ccfg);
+ }
+ //end::create[]
+
+ ignite.close();
+ }
+}
diff --git a/docs/_docs/code-snippets/xml/snapshots.xml
b/docs/_docs/code-snippets/xml/snapshots.xml
new file mode 100644
index 0000000..beeea0c
--- /dev/null
+++ b/docs/_docs/code-snippets/xml/snapshots.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans";
xmlns:util="http://www.springframework.org/schema/util";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/util
http://www.springframework.org/schema/util/spring-util.xsd";>
+ <!-- tag::ignite-config[] -->
+ <bean class="org.apache.ignite.configuration.IgniteConfiguration">
+ <!--
+ Sets a path to the root directory where snapshot files will be
persisted.
+ By default, the relative `snapshots` directory is used in the
IGNITE_HOME/db
+ -->
+ <property name="snapshotPath" value="/snapshots"/>
+
+ <!-- tag::cache[] -->
+ <property name="cacheConfiguration">
+ <bean class="org.apache.ignite.configuration.CacheConfiguration">
+ <property name="name" value="snapshot-cache"/>
+ </bean>
+ </property>
+ <!-- end::cache[] -->
+
+ <!-- tag::discovery[] -->
+ <property name="discoverySpi">
+ <bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi">
+ <property name="ipFinder">
+ <bean
class="org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder">
+ <property name="addresses">
+ <list>
+ <value>127.0.0.1:47500..47509</value>
+ </list>
+ </property>
+ </bean>
+ </property>
+ </bean>
+ </property>
+ <!-- end::discovery[] -->
+ </bean>
+ <!-- end::ignite-config[] -->
+</beans>
diff --git a/docs/_docs/persistence/snapshot.adoc
b/docs/_docs/persistence/snapshot.adoc
new file mode 100644
index 0000000..49fc0f1
--- /dev/null
+++ b/docs/_docs/persistence/snapshot.adoc
@@ -0,0 +1,198 @@
+= 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]. At
runtime, you can create multiple snapshots of all
+data stored in your cluster. The snapshot is a consistent copy of all cache
data files (except
+structures used for crash recovery) for each node in a cluster. Since data of
caches are stored
+on disk in files for each node (cache group partition files, configuration
files, binary metadata) in a cluster,
+the snapshot will contain a copy of the same files with keeping Ignite cluster
node data directory structure and node consistent IDs.
+
+=== Snapshot Consistency
+
+All snapshots you've 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
also be fully consistent in created
+snapshots.
+
+The cluster-wide snapshot consistency is 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 are
+finished on primary and backups, and new ones are hold until a new snapshot
operation is initiated.
+
+The local system files (e.g. cache group partition files, binary metadata
files, configuration files) consistency is 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 might require additional
space in the Ignite work 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 the
snapshot directory. The `wal` and `checkpoint`
+directories will be excluded from the snapshot since recovery procedures are
not necessary for cache group data files.
+
+The created snapshot contains:
+
+- cache group partition files;
+- cache configuration files related to cache groups;
+- binary metadata files;
+- marshaller 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
+----
+
+=== Limitations
+
+The snapshot procedure has some limitations that you should be aware of before
using it within your production environment:
+
+* taking a snapshot of a particular cache or cache group is not supported;
+* in-memory caches will not be included into a snapshot;
+* encrypted caches are not supported and will be ignored;
+* only one snapshot operation at a time can be initiated;
+* snapshot procedure will be interrupted if any node leaves the cluster;
+* snapshot may be restored only at the same baseline topology with the same
node consistent IDs;
+* the automatic snapshot restore is not available yet, you must copy files
manually;
+
+== Configuration
+
+A configured Ignite native persistence directory requires additional disk
space (up to the current size of this directory).
+This space will be used for storing intermediate snapshot results and cleaned
up after the snapshot operation is completed.
+
+The destination snapshot directory can be configured 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 act like a tool to
+start or cancel snapshot operation from the command line. The following
commands can be used with `control.(sh|bat)`:
+
+[source,shell]
+----
+#Create cluster snapshot:
+control.(sh|bat) --snapshot create snapshot_name
+
+#Cancel running snapshot:
+control.(sh|bat) --snapshot cancel snapshot_name
+
+#Kill running snapshot:
+control.(sh|bat) --kill SNAPSHOT snapshot_name
+----
+
+=== JMX
+
+You can start snapshot operation or cancel currently running one via the
`SnapshotMXBean` interface:
+
+[cols="1,1",opts="header"]
+|===
+|Method | Description
+|createSnapshot(String snpName) | Create cluster-wide snapshot.
+|cancelSnapshot(String snpName) | Cancel started cluster-wide snapshot on the
node initiator.
+|===
+
+=== Java API
+
+The snapshot operation can be started using Java API:
+
+[tabs]
+--
+tab:Java[]
+
+[source, java]
+----
+include::{javaCodeDir}/Snapshots.java[tags=create, indent=0]
+----
+--
+
+== Restoring from a snapshot (manual)
+
+[NOTE]
+Removing data from the $IGNITE_HOME/work directory performed at your own risk.
+
+Currently, the data restore procedure is fully manual. Since the snapshot is a
consistent copy of all data files for each node,
+in order to recover from the particular snapshot, you need to stop the cluster
and start every cluster node swapping its
+current data from the `{IGNITE_WORK_DIR}/db` directory with the data from the
snapshot
+(see link:#snapshot-structure[Snapshot Structure] for details). Also, you
should take into account if the `storagePath`
+has been overridden by your DataStorageConfiguration object
+(see
link:persistence/native-persistence#configuring-persistent-storage-directory[Configuring
Persistent Storage Directory]).
+
+To restore a cluster from a snapshot, the steps below should be performed.
+
+- Stop the cluster you are intending to restore;
+- Remove files related to cluster-recovery procedure: `wal` and `cp`
directories;
+- Locate the snapshot you've created by name;
+
+After the cluster has been stopped for each node id in the cluster you should
do the following:
+
+- Remove all the data from `$IGNITE_HOME/work/{node_id}` where `{node_id}` is
a consistent id of a node you work with;
+- Copy all snapshot files from the snapshot related to `{node_id}` to the
$IGNITE_HOME/work/{node_id} directory;
+
+*Restore on different baseline*
+
+Some use cases at production deployments may require taking a snapshot at the
m-node cluster and applying it to the
+n-node cluster. Here are some options:
+
+[cols="1,1",opts="header"]
+|===
+|Condition | Description
+|m == n | The *recommended* case. Use the same baseline and configuration.
+|m < n | Start the m-node cluster from the snapshot and add additional nodes
to the started baseline. The process
+will require the cluster to be rebalanced and SQL indexes to be rebuilt. These
operations may take a long time.
+|m > n | Currently, it is not supported.
+|===
