This package exposes the Elasticsearch Snapshot functionality.
There are two communication channels between all nodes and master in the snapshot functionality:
- The master updates the cluster state by adding, removing or altering the contents of its custom entry
SnapshotsInProgress. All nodes consume the state of the
SnapshotsInProgressand will start or abort relevant shard snapshot tasks accordingly.
- Nodes that are executing shard snapshot tasks report either success or failure of their snapshot task by submitting a
SnapshotShardsService.UpdateIndexShardSnapshotStatusRequestto the master node that will update the snapshot's entry in the cluster state accordingly.
Snapshots are created by the following sequence of events:
- An invocation of
SnapshotsService.createSnapshot(org.elasticsearch.action.admin.cluster.snapshots.create.CreateSnapshotRequest, org.elasticsearch.action.ActionListener<org.elasticsearch.snapshots.Snapshot>)enqueues a cluster state update to create a
SnapshotsInProgress.Entryin the cluster state's
SnapshotsInProgress. This initial snapshot entry has its state set to
INITand an empty map set for the state of the individual shard's snapshots.
- After the snapshot's entry with state
INITis in the cluster state,
SnapshotsServicedetermines the primary shards' assignments for all indices that are being snapshotted and updates the existing
STARTEDand adds the map of
SnapshotsInProgress.ShardSnapshotStatusthat tracks the assignment of which node is to snapshot which shard. All shard snapshots are executed on the shard's primary node. Thus all shards for which the primary node was found to have a healthy copy of the shard are marked as being in state
INITin this map. If the primary for a shard is unassigned, it is marked as
MISSINGin this map. In case the primary is initializing at this point, it is marked as in state
WAITING. In case a shard's primary is relocated at any point after its
SnapshotsInProgress.Entryhas moved to state
STARTEDand thus been assigned to a specific cluster node, that shard's snapshot will fail and move to state
- The new
SnapshotsInProgress.Entryis then observed by
SnapshotShardsService.clusterChanged(org.elasticsearch.cluster.ClusterChangedEvent)on all nodes and since the entry is in state
SnapshotShardsServicewill check if any local primary shards are to be snapshotted (signaled by the shard's snapshot state being
INIT). For those local primary shards found in state
INIT) the snapshot process of writing the shard's data files to the snapshot's
Repositoryis executed. Once the snapshot execution finishes for a shard an
UpdateIndexShardSnapshotStatusRequestis sent to the master node signaling either status
FAILED. The master node will then update a shard's state in the snapshots
SnapshotsInProgress.Entrywhenever it receives such a
- If as a result of the received status update requests, all shards in the cluster state are in a completed state, i.e are marked as
SnapshotShardsServicewill update the state of the
Entryitself and mark it as
SUCCESS. At the same time
SnapshotsService.endSnapshot(org.elasticsearch.cluster.SnapshotsInProgress.Entry, org.elasticsearch.cluster.metadata.MetaData)is executed, writing the metadata necessary to finalize the snapshot in the repository to the repository.
- After writing the final metadata to the repository, a cluster state update to remove the snapshot from the cluster state is
submitted and the removal of the snapshot's
SnapshotsInProgress.Entryfrom the cluster state completes the snapshot process.
Deleting a Snapshot
Deleting a snapshot can take the form of either simply deleting it from the repository or (if it has not completed yet) aborting it and subsequently deleting it from the repository.
Aborting a Snapshot
- Aborting a snapshot starts by updating the state of the snapshot's
- The snapshot's state change to
ABORTEDin cluster state is then picked up by the
SnapshotShardsServiceon all nodes. Those nodes that have shard snapshot actions for the snapshot assigned to them, will abort them and notify master about the shards snapshot status accordingly. If the shard snapshot action completed or was in state
FINALIZEwhen the abort was registered by the
SnapshotShardsService, then the shard's state will be reported to master as
SUCCESS. Otherwise, it will be reported as
- Once all the shards are reported to master as either
SnapshotsServiceon the master will finish the snapshot process as all shard's states are now completed and hence the snapshot can be completed as explained in point 4 of the snapshot creation section above.
Deleting a Snapshot from a Repository
- Assuming there are no entries in the cluster state's
SnapshotsInProgress, deleting a snapshot starts by the
SnapshotsServicecreating an entry for deleting the snapshot in the cluster state's
- Once the cluster state contains the deletion entry in
Repository.deleteSnapshot(org.elasticsearch.snapshots.SnapshotId, long, org.elasticsearch.action.ActionListener<java.lang.Void>)for the given snapshot, which will remove files associated with the snapshot from the repository as well as update its meta-data to reflect the deletion of the snapshot.
- After the deletion of the snapshot's data from the repository finishes, the
SnapshotsServicewill submit a cluster state update to remove the deletion's entry in
SnapshotDeletionsInProgresswhich concludes the process of deleting a snapshot.
Class Summary Class Description RestoreInfoInformation about successfully completed restore operation. RestoreServiceService responsible for restoring snapshots RestoreService.RestoreCompletionResponse RestoreService.RestoreInProgressUpdater SnapshotBasic information about a snapshot - a SnapshotId and the repository that the snapshot belongs to. SnapshotIdSnapshotId - snapshot name + snapshot UUID SnapshotInfoInformation about a snapshot SnapshotInfo.SnapshotInfoBuilder SnapshotShardFailureStores information about failures that occurred during shard snapshotting process SnapshotShardsServiceThis service runs on data and master nodes and controls currently snapshotted shards on these nodes. SnapshotShardsService.UpdateIndexShardSnapshotStatusRequestInternal request that is used to send changes in snapshot status to master SnapshotsServiceService responsible for creating snapshots SnapshotUtilsSnapshot utilities
Enum Summary Enum Description SnapshotStateRepresents the state that a snapshot can be in
Exception Summary Exception Description ConcurrentSnapshotExecutionExceptionThrown when a user tries to multiple conflicting snapshot/restore operations at the same time. InvalidSnapshotNameExceptionThrown on the attempt to create a snapshot with invalid name SnapshotCreationExceptionThrown when snapshot creation fails completely SnapshotExceptionGeneric snapshot exception SnapshotInProgressExceptionThrown on the attempt to execute an action that requires that no snapshot is in progress. SnapshotMissingExceptionThrown if requested snapshot doesn't exist SnapshotRestoreExceptionSnapshot restore exception