mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-20 03:45:02 +00:00
0ce841915c
Adds an API to clone an index. This is similar to the index split and shrink APIs, just with the difference that the number of primary shards is kept the same. In case where the filesystem provides hard-linking capabilities, this is a very cheap operation. Indexing cloning can be done by running `POST my_source_index/_clone/my_target_index` and it supports the same options as the split and shrink APIs. Closes #44128
139 lines
4.2 KiB
Plaintext
139 lines
4.2 KiB
Plaintext
[[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.
|