From ecd4e3361057db57ee4ee2e45b672e592074153b Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 16 Sep 2019 13:24:23 -0400 Subject: [PATCH 1/6] [DOCS] Reformat clone index API docs --- docs/reference/indices/clone-index.asciidoc | 114 ++++++++++++------ docs/reference/indices/create-index.asciidoc | 2 + docs/reference/rest-api/common-parms.asciidoc | 31 ++++- 3 files changed, 107 insertions(+), 40 deletions(-) diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc index d7eb2d209134..013806d2f18b 100644 --- a/docs/reference/indices/clone-index.asciidoc +++ b/docs/reference/indices/clone-index.asciidoc @@ -1,42 +1,32 @@ [[indices-clone-index]] -=== Clone Index +=== Clone index API +++++ +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. +Clones an existing index. -[float] -==== How does cloning work? - -Cloning works as follows: +[source,console] +-------------------------------------------------- +POST /twitter/_clone/cloned-twitter-index +-------------------------------------------------- +// TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards" : 5,"blocks.write":true}}\n/] -* 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.) +[[clone-index-api-request]] +==== {api-request-title} -* Finally, it recovers the target index as though it were a closed index which - had just been re-opened. +`POST //_clone/` -[float] -==== Preparing an index for cloning +`PUT //_clone/` -Create a new index: -[source,console] --------------------------------------------------- -PUT my_source_index -{ - "settings": { - "index.number_of_shards" : 5 - } -} --------------------------------------------------- +[[clone-index-api-prereqs]] +==== {api-prereq-title} -In order to clone an index, the index must be marked as read-only, -and have <> `green`. +To clone an index, +the index must be marked as read-only +and have a <> status of `green`. This can be achieved with the following request: @@ -54,8 +44,32 @@ PUT /my_source_index/_settings <1> Prevents write operations to this index while still allowing metadata changes like deleting the index. -[float] -==== Cloning an index + +[[clone-index-api-desc]] +==== {api-description-title} + +Use the clone index API +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. + +[[cloning-works]] +===== How cloning works + +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. + +[[clone-index]] +===== Clone an index To clone `my_source_index` into a new index called `my_target_index`, issue the following request: @@ -72,9 +86,9 @@ 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: +Indices can only be cloned if they meet the following requirements: -* the target index must not exist +* The target index must not exist. * The source index must have the same number of primary shards as the target index. @@ -107,8 +121,8 @@ POST my_source_index/_clone/my_target_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 +[[monitor-cloning]] +===== Monitor the cloning process The clone process can be monitored with the <>, or the <> can be used to wait @@ -126,9 +140,35 @@ 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 +[[clone-wait-active-shards]] +===== Wait For active shards Because the clone operation creates a new index to clone the shards to, the <> setting on index creation applies to the clone index action as well. + + +[[clone-index-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Name of the source index to clone. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index] + + +[[clone-index-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + + +[[clone-index-api-request-body]] +==== {api-request-body-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-aliases] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-settings] \ No newline at end of file diff --git a/docs/reference/indices/create-index.asciidoc b/docs/reference/indices/create-index.asciidoc index fef6ff96a523..afb7ab91232b 100644 --- a/docs/reference/indices/create-index.asciidoc +++ b/docs/reference/indices/create-index.asciidoc @@ -35,6 +35,7 @@ creating an index, you can specify the following: -- (Optional, string) Name of the index you wish to create. +// tag::index-name-reqs[] Index names must meet the following criteria: - Lowercase only @@ -43,6 +44,7 @@ Index names must meet the following criteria: - Cannot start with `-`, `_`, `+` - Cannot be `.` or `..` - Cannot be longer than 255 bytes (note it is bytes, so multi-byte characters will count towards the 255 limit faster) +// end::index-name-reqs[] -- diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 3e860e58557c..1decf35e1d97 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -10,6 +10,13 @@ tag::aliases[] index. See <>. end::aliases[] +tag::target-index-aliases[] +`aliases`:: +(Optional, <>) +Index aliases which include the target index. +See <>. +end::target-index-aliases[] + tag::allow-no-indices[] `allow_no_indices`:: (Optional, boolean) If `true`, @@ -461,15 +468,22 @@ the segment has most likely been written to disk but needs a <> to be searchable. end::segment-search[] +tag::segment-size[] +Disk space used by the segment, such as `50kb`. +end::segment-size[] + tag::settings[] `settings`:: (Optional, <>) Configuration options for the index. See <>. end::settings[] -tag::segment-size[] -Disk space used by the segment, such as `50kb`. -end::segment-size[] +tag::target-index-settings[] +`settings`:: +(Optional, <>) +Configuration options for the target index. +See <>. +end::target-index-settings[] tag::slices[] `slices`:: @@ -506,6 +520,17 @@ tag::stats[] purposes. end::stats[] +tag::target-index[] +``:: ++ +-- +(Required, string) +Name of the target index to create. + +include::{docdir}/indices/create-index.asciidoc[tag=index-name-reqs] +-- +end::target-index[] + tag::terminate_after[] `terminate_after`:: (Optional, integer) The maximum number of documents to collect for each shard, From 185035eb667ee29a1887202e27de49cb6c858f3d Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 16 Sep 2019 14:20:18 -0400 Subject: [PATCH 2/6] Fix snippet examples --- docs/reference/indices/clone-index.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc index 013806d2f18b..a011e062c6f4 100644 --- a/docs/reference/indices/clone-index.asciidoc +++ b/docs/reference/indices/clone-index.asciidoc @@ -39,7 +39,7 @@ PUT /my_source_index/_settings } } -------------------------------------------------- -// TEST[continued] +// TEST[s/^/PUT my_source_index\n/] <1> Prevents write operations to this index while still allowing metadata changes like deleting the index. @@ -76,7 +76,7 @@ the following request: [source,console] -------------------------------------------------- -POST my_source_index/_clone/my_target_index +POST /my_source_index/_clone/my_target_index -------------------------------------------------- // TEST[continued] @@ -102,7 +102,7 @@ and accepts `settings` and `aliases` parameters for the target index: [source,console] -------------------------------------------------- -POST my_source_index/_clone/my_target_index +POST /my_source_index/_clone/my_target_index { "settings": { "index.number_of_shards": 5 <1> From eed4bb9e256823062ae432baaf2bdc0ccb9a0a7e Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 25 Sep 2019 09:41:15 -0400 Subject: [PATCH 3/6] Update docs/reference/indices/clone-index.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: István Zoltán Szabó --- docs/reference/indices/clone-index.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc index a011e062c6f4..3b6a1bd78961 100644 --- a/docs/reference/indices/clone-index.asciidoc +++ b/docs/reference/indices/clone-index.asciidoc @@ -141,7 +141,7 @@ become `active`. At that point, Elasticsearch will try to allocate any replicas and may decide to relocate the primary shard to another node. [[clone-wait-active-shards]] -===== Wait For active shards +===== Wait for active shards Because the clone operation creates a new index to clone the shards to, the <> setting @@ -171,4 +171,4 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-aliases] -include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-settings] \ No newline at end of file +include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-settings] From 080a2a84e942e872030f95441ab8742824babe53 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 25 Sep 2019 09:41:31 -0400 Subject: [PATCH 4/6] Update docs/reference/indices/clone-index.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: István Zoltán Szabó --- docs/reference/indices/clone-index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc index 3b6a1bd78961..03e466e07ff3 100644 --- a/docs/reference/indices/clone-index.asciidoc +++ b/docs/reference/indices/clone-index.asciidoc @@ -137,7 +137,7 @@ 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 +become `active`. At that point, {es} will try to allocate any replicas and may decide to relocate the primary shard to another node. [[clone-wait-active-shards]] From fd375043719872796b172f5257c7064201c6baee Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 25 Sep 2019 09:41:39 -0400 Subject: [PATCH 5/6] Update docs/reference/indices/clone-index.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: István Zoltán Szabó --- docs/reference/indices/clone-index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc index 03e466e07ff3..4fde8bcc94fb 100644 --- a/docs/reference/indices/clone-index.asciidoc +++ b/docs/reference/indices/clone-index.asciidoc @@ -124,7 +124,7 @@ the source index will be used for the target index. [[monitor-cloning]] ===== Monitor the cloning process -The clone process can be monitored with the <>, or the <> can be used to wait until all primary shards have been allocated by setting the `wait_for_status` parameter to `yellow`. From 6b2b25d501ab1bb4fbadc6500acdb2c02fb22bdd Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 25 Sep 2019 09:43:41 -0400 Subject: [PATCH 6/6] Remove callout --- docs/reference/indices/clone-index.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/indices/clone-index.asciidoc b/docs/reference/indices/clone-index.asciidoc index 4fde8bcc94fb..e9c9dd2796a9 100644 --- a/docs/reference/indices/clone-index.asciidoc +++ b/docs/reference/indices/clone-index.asciidoc @@ -28,22 +28,22 @@ To clone an index, the index must be marked as read-only and have a <> status of `green`. -This can be achieved with the following request: +For example, +the following request prevents write operations on `my_source_index` +so it can be cloned. +Metadata changes like deleting the index are still allowed. [source,console] -------------------------------------------------- PUT /my_source_index/_settings { "settings": { - "index.blocks.write": true <1> + "index.blocks.write": true } } -------------------------------------------------- // TEST[s/^/PUT my_source_index\n/] -<1> Prevents write operations to this index while still allowing metadata - changes like deleting the index. - [[clone-index-api-desc]] ==== {api-description-title}