Clone Snapshot API (#61839) (#63291)

Snapshot clone API. Complete except for some TODOs around documentation (and adding HLRC support).

backport of #61839, #63217, #63037

Author: original-brownbear

docs/reference/snapshot-restore/apis/clone-snapshot-api.asciidoc

@@ -0,0 +1,52 @@
+[[clone-snapshot-api]]
+=== Clone snapshot API
+++++
+<titleabbrev>Clone snapshot</titleabbrev>
+++++
+
+Clones part or all of a snapshot into a new snapshot.
+
+[source,console]
+----
+PUT /_snapshot/my_repository/source_snapshot/_clone/target_snapshot
+{
+  "indices": "index_a,index_b"
+}
+----
+// TEST[skip:TODO]
+
+[[clone-snapshot-api-request]]
+==== {api-request-title}
+
+`PUT /_snapshot/<repository>/<source_snapshot>/_clone/<target_snapshot>`
+
+[[clone-snapshot-api-desc]]
+==== {api-description-title}
+
+The clone snapshot API allows creating a copy of all or part of an existing snapshot
+within the same repository.
+
+[[clone-snapshot-api-params]]
+==== {api-path-parms-title}
+
+`<repository>`::
+(Required, string)
+Name of the snapshot repository that both source and target snapshot belong to.
+
+[[clone-snapshot-api-query-params]]
+==== {api-query-parms-title}
+
+`master_timeout`::
+(Optional, <<time-units, time units>>) Specifies the period of time to wait for
+a connection to the master node. If no response is received before the timeout
+expires, the request fails and returns an error. Defaults to `30s`.
+
+`timeout`::
+(Optional, <<time-units, time units>>) Specifies the period of time to wait for
+a response. If no response is received before the timeout expires, the request
+fails and returns an error. Defaults to `30s`.
+
+`indices`::
+(Required, string)
+A comma-separated list of indices to include in the snapshot.
+<<multi-index,Multi-index syntax>> is supported.

docs/reference/snapshot-restore/index.asciidoc

@@ -107,6 +107,7 @@ understand the time requirements before proceeding.
 --
 
 include::register-repository.asciidoc[]
+include::apis/clone-snapshot-api.asciidoc[]
 include::take-snapshot.asciidoc[]
 include::restore-snapshot.asciidoc[]
 include::monitor-snapshot-restore.asciidoc[]

docs/reference/snapshot-restore/take-snapshot.asciidoc

@@ -124,3 +124,5 @@ PUT /_snapshot/my_backup/<snapshot-{now/d}>
 PUT /_snapshot/my_backup/%3Csnapshot-%7Bnow%2Fd%7D%3E
 -----------------------------------
 // TEST[continued]
+
+NOTE: You can also create snapshots that are copies of part of an existing snapshot using the <<clone-snapshot-api,clone snapshot API>>.

server/src/internalClusterTest/java/org/elasticsearch/snapshots/CloneSnapshotIT.java

@@ -64,6 +64,8 @@
 import org.elasticsearch.action.admin.cluster.settings.TransportClusterUpdateSettingsAction;
 import org.elasticsearch.action.admin.cluster.shards.ClusterSearchShardsAction;
 import org.elasticsearch.action.admin.cluster.shards.TransportClusterSearchShardsAction;
+import org.elasticsearch.action.admin.cluster.snapshots.clone.CloneSnapshotAction;
+import org.elasticsearch.action.admin.cluster.snapshots.clone.TransportCloneSnapshotAction;
 import org.elasticsearch.action.admin.cluster.snapshots.create.CreateSnapshotAction;
 import org.elasticsearch.action.admin.cluster.snapshots.create.TransportCreateSnapshotAction;
 import org.elasticsearch.action.admin.cluster.snapshots.delete.DeleteSnapshotAction;
@@ -267,6 +269,7 @@
 import org.elasticsearch.rest.action.admin.cluster.RestCancelTasksAction;
 import org.elasticsearch.rest.action.admin.cluster.RestCleanupRepositoryAction;
 import org.elasticsearch.rest.action.admin.cluster.RestClearVotingConfigExclusionsAction;
+import org.elasticsearch.rest.action.admin.cluster.RestCloneSnapshotAction;
 import org.elasticsearch.rest.action.admin.cluster.RestClusterAllocationExplainAction;
 import org.elasticsearch.rest.action.admin.cluster.RestClusterGetSettingsAction;
 import org.elasticsearch.rest.action.admin.cluster.RestClusterHealthAction;
@@ -522,6 +525,7 @@ public <Request extends ActionRequest, Response extends ActionResponse> void reg
         actions.register(GetSnapshotsAction.INSTANCE, TransportGetSnapshotsAction.class);
         actions.register(DeleteSnapshotAction.INSTANCE, TransportDeleteSnapshotAction.class);
         actions.register(CreateSnapshotAction.INSTANCE, TransportCreateSnapshotAction.class);
+        actions.register(CloneSnapshotAction.INSTANCE, TransportCloneSnapshotAction.class);
         actions.register(RestoreSnapshotAction.INSTANCE, TransportRestoreSnapshotAction.class);
         actions.register(SnapshotsStatusAction.INSTANCE, TransportSnapshotsStatusAction.class);
 
@@ -665,6 +669,7 @@ public void initRestHandlers(Supplier<DiscoveryNodes> nodesInCluster) {
         registerHandler.accept(new RestCleanupRepositoryAction());
         registerHandler.accept(new RestGetSnapshotsAction());
         registerHandler.accept(new RestCreateSnapshotAction());
+        registerHandler.accept(new RestCloneSnapshotAction());
         registerHandler.accept(new RestRestoreSnapshotAction());
         registerHandler.accept(new RestDeleteSnapshotAction());
         registerHandler.accept(new RestSnapshotsStatusAction());

server/src/main/java/org/elasticsearch/action/ActionModule.java

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+package org.elasticsearch.action.admin.cluster.snapshots.clone;
+
+import org.elasticsearch.action.ActionType;
+import org.elasticsearch.action.support.master.AcknowledgedResponse;
+
+public final class CloneSnapshotAction extends ActionType<AcknowledgedResponse> {
+
+    public static final CloneSnapshotAction INSTANCE = new CloneSnapshotAction();
+    public static final String NAME = "cluster:admin/snapshot/clone";
+
+    private CloneSnapshotAction() {
+        super(NAME, AcknowledgedResponse::new);
+    }
+}

server/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/clone/CloneSnapshotAction.java

@@ -0,0 +1,142 @@
+/*
+ * 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.
+ */
+
+package org.elasticsearch.action.admin.cluster.snapshots.clone;
+
+import org.elasticsearch.action.ActionRequestValidationException;
+import org.elasticsearch.action.IndicesRequest;
+import org.elasticsearch.action.support.IndicesOptions;
+import org.elasticsearch.action.support.master.MasterNodeRequest;
+import org.elasticsearch.common.io.stream.StreamInput;
+import org.elasticsearch.common.io.stream.StreamOutput;
+
+import java.io.IOException;
+
+import static org.elasticsearch.action.ValidateActions.addValidationError;
+
+public class CloneSnapshotRequest extends MasterNodeRequest<CloneSnapshotRequest> implements IndicesRequest.Replaceable{
+
+    private final String repository;
+
+    private final String source;
+
+    private final String target;
+
+    private String[] indices;
+
+    private IndicesOptions indicesOptions = IndicesOptions.strictExpandHidden();
+
+    public CloneSnapshotRequest(StreamInput in) throws IOException {
+        super(in);
+        repository = in.readString();
+        source = in.readString();
+        target = in.readString();
+        indices = in.readStringArray();
+        indicesOptions = IndicesOptions.readIndicesOptions(in);
+    }
+
+    /**
+     * Creates a clone snapshot request for cloning the given source snapshot's indices into the given target snapshot on the given
+     * repository.
+     *
+     * @param repository repository that source snapshot belongs to and that the target snapshot will be created in
+     * @param source     source snapshot name
+     * @param target     target snapshot name
+     * @param indices    indices to clone from source to target
+     */
+    public CloneSnapshotRequest(String repository, String source, String target, String[] indices) {
+        this.repository = repository;
+        this.source = source;
+        this.target = target;
+        this.indices = indices;
+    }
+
+    @Override
+    public void writeTo(StreamOutput out) throws IOException {
+        super.writeTo(out);
+        out.writeString(repository);
+        out.writeString(source);
+        out.writeString(target);
+        out.writeStringArray(indices);
+        indicesOptions.writeIndicesOptions(out);
+    }
+
+    @Override
+    public ActionRequestValidationException validate() {
+        ActionRequestValidationException validationException = null;
+        if (source == null) {
+            validationException = addValidationError("source snapshot name is missing", null);
+        }
+        if (target == null) {
+            validationException = addValidationError("target snapshot name is missing", null);
+        }
+        if (repository == null) {
+            validationException = addValidationError("repository is missing", validationException);
+        }
+        if (indices == null) {
+            validationException = addValidationError("indices is null", validationException);
+        } else if (indices.length == 0) {
+            validationException = addValidationError("indices patterns are empty", validationException);
+        } else {
+            for (String index : indices) {
+                if (index == null) {
+                    validationException = addValidationError("index is null", validationException);
+                    break;
+                }
+            }
+        }
+        return validationException;
+    }
+
+    @Override
+    public String[] indices() {
+        return this.indices;
+    }
+
+    @Override
+    public IndicesOptions indicesOptions() {
+        return indicesOptions;
+    }
+
+    @Override
+    public CloneSnapshotRequest indices(String... indices) {
+        this.indices = indices;
+        return this;
+    }
+
+    /**
+     * @see CloneSnapshotRequestBuilder#setIndicesOptions
+     */
+    public CloneSnapshotRequest indicesOptions(IndicesOptions indicesOptions) {
+        this.indicesOptions = indicesOptions;
+        return this;
+    }
+
+    public String repository() {
+        return this.repository;
+    }
+
+    public String target() {
+        return this.target;
+    }
+
+    public String source() {
+        return this.source;
+    }
+}

server/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/clone/CloneSnapshotRequest.java

@@ -0,0 +1,65 @@
+/*
+ * 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.
+ */
+
+package org.elasticsearch.action.admin.cluster.snapshots.clone;
+
+import org.elasticsearch.action.ActionType;
+import org.elasticsearch.action.support.IndicesOptions;
+import org.elasticsearch.action.support.master.AcknowledgedResponse;
+import org.elasticsearch.action.support.master.MasterNodeOperationRequestBuilder;
+import org.elasticsearch.client.ElasticsearchClient;
+import org.elasticsearch.common.Strings;
+
+public class CloneSnapshotRequestBuilder extends MasterNodeOperationRequestBuilder<CloneSnapshotRequest, AcknowledgedResponse,
+                                                                                   CloneSnapshotRequestBuilder> {
+
+    protected CloneSnapshotRequestBuilder(ElasticsearchClient client, ActionType<AcknowledgedResponse> action,
+                                          CloneSnapshotRequest request) {
+        super(client, action, request);
+    }
+
+    public CloneSnapshotRequestBuilder(ElasticsearchClient client, ActionType<AcknowledgedResponse> action,
+                                       String repository, String source, String target) {
+        this(client, action, new CloneSnapshotRequest(repository, source, target, Strings.EMPTY_ARRAY));
+    }
+
+    /**
+     * Sets a list of indices that should be cloned from the source to the target snapshot
+     * <p>
+     * The list of indices supports multi-index syntax. For example: "+test*" ,"-test42" will clone all indices with
+     * prefix "test" except index "test42".
+     *
+     * @return this builder
+     */
+    public CloneSnapshotRequestBuilder setIndices(String... indices) {
+        request.indices(indices);
+        return this;
+    }
+
+    /**
+     * Specifies the indices options. Like what type of requested indices to ignore. For example indices that don't exist.
+     *
+     * @param indicesOptions the desired behaviour regarding indices options
+     * @return this request
+     */
+    public CloneSnapshotRequestBuilder setIndicesOptions(IndicesOptions indicesOptions) {
+        request.indicesOptions(indicesOptions);
+        return this;
+    }
+}