OpenSearch/docs/reference/indices/clone-index.asciidoc

[[indices-clone-index]]
=== Clone Index

The clone index API allows you to clone an existing index into a new index,
where each original primary shard is cloned into a new primary shard in
the new index.

[float]
==== How does cloning work?

Cloning works as follows:

* First, it creates a new target index with the same definition as the source
  index.

* Then it hard-links segments from the source index into the target index. (If
  the file system doesn't support hard-linking, then all segments are copied
  into the new index, which is a much more time consuming process.)

* Finally, it recovers the target index as though it were a closed index which
  had just been re-opened.

[float]
==== Preparing an index for cloning

Create a new index:

[source,js]
--------------------------------------------------
PUT my_source_index
{
  "settings": {
    "index.number_of_shards" : 5
  }
}
--------------------------------------------------
// CONSOLE

In order to clone an index, the index must be marked as read-only,
and have <<cluster-health,health>> `green`.

This can be achieved with the following request:

[source,js]
--------------------------------------------------
PUT /my_source_index/_settings
{
  "settings": {
    "index.blocks.write": true <1>
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<1> Prevents write operations to this index while still allowing metadata
    changes like deleting the index.

[float]
==== Cloning an index

To clone `my_source_index` into a new index called `my_target_index`, issue
the following request:

[source,js]
--------------------------------------------------
POST my_source_index/_clone/my_target_index
--------------------------------------------------
// CONSOLE
// TEST[continued]

The above request returns immediately once the target index has been added to
the cluster state -- it doesn't wait for the clone operation to start.

[IMPORTANT]
=====================================

Indices can only be cloned if they satisfy the following requirements:

* the target index must not exist

* The source index must have the same number of primary shards as the target index.

* The node handling the clone process must have sufficient free disk space to
  accommodate a second copy of the existing index.

=====================================

The `_clone` API is similar to the <<indices-create-index, `create index` API>>
and accepts `settings` and `aliases` parameters for the target index:

[source,js]
--------------------------------------------------
POST my_source_index/_clone/my_target_index
{
  "settings": {
    "index.number_of_shards": 5 <1>
  },
  "aliases": {
    "my_search_indices": {}
  }
}
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT my_source_index\n{"settings": {"index.blocks.write": true, "index.number_of_shards": "5"}}\n/]

<1> The number of shards in the target index. This must be equal to the
    number of shards in the source index.


NOTE: Mappings may not be specified in the `_clone` request. The mappings of
the source index will be used for the target index.

[float]
==== Monitoring the clone process

The clone process can be monitored with the <<cat-recovery,`_cat recovery`
API>>, or the <<cluster-health, `cluster health` API>> can be used to wait
until all primary shards have been allocated by setting the  `wait_for_status`
parameter to `yellow`.

The `_clone` API returns as soon as the target index has been added to the
cluster state, before any shards have been allocated. At this point, all
shards are in the state `unassigned`. If, for any reason, the target index
can't be allocated, its primary shard will remain `unassigned` until it
can be allocated on that node.

Once the primary shard is allocated, it moves to state `initializing`, and the
clone process begins. When the clone operation completes, the shard will
become `active`. At that  point, Elasticsearch will try to allocate any
replicas and may decide to relocate the primary shard to another node.

[float]
==== Wait For Active Shards

Because the clone operation creates a new index to clone the shards to,
the <<create-index-wait-for-active-shards,wait for active shards>> setting
on index creation applies to the clone index action as well.