From cef79c8a5a4ab0a1a24020b50adbbb64bfa34e17 Mon Sep 17 00:00:00 2001 From: Armin Braun Date: Thu, 28 Feb 2019 12:47:17 +0100 Subject: [PATCH] Add Package Level JavaDoc on Snapshots (#38108) * Add Package Level JavaDoc on Snapshots --- .../elasticsearch/snapshots/package-info.java | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 server/src/main/java/org/elasticsearch/snapshots/package-info.java diff --git a/server/src/main/java/org/elasticsearch/snapshots/package-info.java b/server/src/main/java/org/elasticsearch/snapshots/package-info.java new file mode 100644 index 0000000000000..d5149c9bd3592 --- /dev/null +++ b/server/src/main/java/org/elasticsearch/snapshots/package-info.java @@ -0,0 +1,107 @@ +/* + * Licensed to Elasticsearch under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +/** + *

This package exposes the Elasticsearch Snapshot functionality.

+ * + *

Preliminaries

+ * + *

There are two communication channels between all nodes and master in the snapshot functionality:

+ * + * + *

Snapshot Creation

+ *

Snapshots are created by the following sequence of events:

+ *
    + *
  1. An invocation of {@link org.elasticsearch.snapshots.SnapshotsService#createSnapshot} enqueues a cluster state update to create + * a {@link org.elasticsearch.cluster.SnapshotsInProgress.Entry} in the cluster state's {@code SnapshotsInProgress}. This initial snapshot + * entry has its state set to {@code INIT} and an empty map set for the state of the individual shard's snapshots.
    2. + * + *
  2. After the snapshot's entry with state {@code INIT} is in the cluster state, {@link org.elasticsearch.snapshots.SnapshotsService} + * determines the primary shards' assignments for all indices that are being snapshotted and updates the existing + * {@code SnapshotsInProgress.Entry} with state {@code STARTED} and adds the map of {@link org.elasticsearch.index.shard.ShardId} to + * {@link org.elasticsearch.cluster.SnapshotsInProgress.ShardSnapshotStatus} that 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 {@code INIT} in this map. If the primary for a shard is unassigned, it is marked + * as {@code MISSING} in this map. In case the primary is initializing at this point, it is marked as in state {@code WAITING}. In case a + * shard's primary is relocated at any point after its {@code SnapshotsInProgress.Entry} has moved to state {@code STARTED} and thus been + * assigned to a specific cluster node, that shard's snapshot will fail and move to state {@code FAILED}.
    3. + * + *
  3. The new {@code SnapshotsInProgress.Entry} is then observed by + * {@link org.elasticsearch.snapshots.SnapshotShardsService#clusterChanged} on all nodes and since the entry is in state {@code STARTED} + * the {@code SnapshotShardsService} will check if any local primary shards are to be snapshotted (signaled by the shard's snapshot state + * being {@code INIT}). For those local primary shards found in state {@code INIT}) the snapshot process of writing the shard's data files + * to the snapshot's {@link org.elasticsearch.repositories.Repository} is executed. Once the snapshot execution finishes for a shard an + * {@code UpdateIndexShardSnapshotStatusRequest} is sent to the master node signaling either status {@code SUCCESS} or {@code FAILED}. + * The master node will then update a shard's state in the snapshots {@code SnapshotsInProgress.Entry} whenever it receives such a + * {@code UpdateIndexShardSnapshotStatusRequest}.
    4. + * + *
  4. 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 + * either {@code SUCCESS}, {@code FAILED} or {@code MISSING}, the {@code SnapshotShardsService} will update the state of the {@code Entry} + * itself and mark it as {@code SUCCESS}. At the same time {@link org.elasticsearch.snapshots.SnapshotsService#endSnapshot} is executed, + * writing the metadata necessary to finalize the snapshot in the repository to the repository.
    5. + * + *
  5. 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 {@code SnapshotsInProgress.Entry} from the cluster state completes the snapshot process. + *
    6. + *
+ * + *

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

+ * + *
    + *
  1. Aborting a snapshot starts by updating the state of the snapshot's {@code SnapshotsInProgress.Entry} to {@code ABORTED}.
    2. + * + *
  2. The snapshot's state change to {@code ABORTED} in cluster state is then picked up by the {@code SnapshotShardsService} on 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 {@code FINALIZE} when the abort was registered by + * the {@code SnapshotShardsService}, then the shard's state will be reported to master as {@code SUCCESS}. + * Otherwise, it will be reported as {@code FAILED}.
    3. + * + *
  3. Once all the shards are reported to master as either {@code SUCCESS} or {@code FAILED} the {@code SnapshotsService} on 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.
    4. + *
+ * + *

Deleting a Snapshot from a Repository

+ * + *
    + *
  1. Assuming there are no entries in the cluster state's {@code SnapshotsInProgress}, deleting a snapshot starts by the + * {@code SnapshotsService} creating an entry for deleting the snapshot in the cluster state's + * {@link org.elasticsearch.cluster.SnapshotDeletionsInProgress}.
    2. + * + *
  2. Once the cluster state contains the deletion entry in {@code SnapshotDeletionsInProgress} the {@code SnapshotsService} will invoke + * {@link org.elasticsearch.repositories.Repository#deleteSnapshot} 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.
    3. + * + *
  3. After the deletion of the snapshot's data from the repository finishes, the {@code SnapshotsService} will submit a cluster state + * update to remove the deletion's entry in {@code SnapshotDeletionsInProgress} which concludes the process of deleting a snapshot.
    4. + *
+ */ +package org.elasticsearch.snapshots;