[DOCS] Reformat rollover index API docs (#46778)

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[]
 --
 
 

docs/reference/indices/rollover-index.asciidoc

@@ -1,5 +1,37 @@
 [[indices-rollover-index]]
-=== Rollover Index
+=== Rollover index API
+++++
+<titleabbrev>Rollover index</titleabbrev>
+++++
+
+Assigns an <<indices-aliases, index alias>> to a new index
+when the alias's existing index meets a condition you provide.
+
+[source,console]
+----
+POST /alias1/_rollover/twitter
+{
+  "conditions": {
+    "max_age":   "7d",
+    "max_docs":  1000,
+    "max_size": "5gb"
+  }
+}
+----
+// TEST[s/^/PUT my_old_index_name\nPUT my_old_index_name\/_alias\/alias1\n/]
+
+
+[[rollover-index-api-request]]
+==== {api-request-title}
+
+
+`POST /<alias>/_rollover/<target-index>`
+
+`POST /<alias>/_rollover/`
+
+
+[[rollover-index-api-desc]]
+==== {api-description-title}
 
 The rollover index API rolls an <<indices-aliases, alias>> to a new index when
 the existing index meets a condition you provide. You can use this API to retire
@@ -24,17 +56,102 @@ from the original (rolled-over) index.
 In this scenario, the write index will have its rollover alias' `is_write_index` set to `false`, while the newly created index
 will now have the rollover alias pointing to it as the write index with `is_write_index` as `true`.
 
-The available conditions are:
 
-[[index-rollover-conditions]]
-.`conditions` parameters
-[options="header"]
-|===
-| Name     | Description
-| max_age  | The maximum age of the index
-| max_docs | The maximum number of documents the index should contain. This does not add documents multiple times for replicas
-| max_size | The maximum estimated size of the primary shard of the index
-|===
+[[rollover-wait-active-shards]]
+===== Wait for active shards
+
+Because the rollover operation creates a new index to rollover to, the
+<<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting on
+index creation applies to the rollover action.
+
+
+[[rollover-index-api-path-params]]
+==== {api-path-parms-title}
+
+`<alias>`::
+(Required, string)
+Name of the existing index alias
+to assign to the target index.
+
+
+`<target-index>`::
++
+--
+(Optional*, string)
+Name of the target index to create and assign the index alias.
+
+include::{docdir}/indices/create-index.asciidoc[tag=index-name-reqs]
+
+*This parameter is not required
+if the alias is assigned to an index name that ends with `-` and a number,
+such as `logs-000001`.
+In this case,
+the name of the new index follows the same pattern,
+incrementing the number.
+For example,
+`logs-000001` increments to `logs-000002`.
+This number is zero-padded with a length of 6,
+regardless of the prior index name.
+
+If the existing index for the alias does not match this pattern,
+this parameter is required.
+--
+
+
+[[rollover-index-api-query-params]]
+==== {api-query-parms-title}
+
+`dry_run`::
+(Optional, boolean)
+If `true`,
+the request checks whether the index matches provided conditions
+but does not perform a rollover.
+Defaults to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+
+[[rollover-index-api-request-body]]
+==== {api-request-body-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=aliases]
+
+`conditions`::
++
+--
+(Required, object)
+Set of conditions the index alias's existing index must met to roll over.
+
+Parameters include:
+
+`max_age`::
+(Optional, <<time-units, time units>>)
+Maximum age of the index.
+
+`max_docs`::
+(Optional, integer)
+Maximum number of documents in the index.
+This number does *not* include documents in replica shards.
+
+`max_size`::
+(Optional, <<byte-units, byte units>>)
+Maximum estimated size of the primary shard of the index.
+--
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=settings]
+
+
+[[rollover-index-api-example]]
+==== {api-examples-title}
+
+[[rollover-index-basic-ex]]
+===== Basic example
 
 [source,console]
 --------------------------------------------------
@@ -63,7 +180,7 @@ POST /logs_write/_rollover <2>
     contains 1,000 or more documents, or has an index size at least around 5GB, then the `logs-000002` index is created
     and the `logs_write` alias is updated to point to `logs-000002`.
 
-The above request might return the following response:
+The API returns the following response:
 
 [source,console-result]
 --------------------------------------------------
@@ -86,8 +203,41 @@ The above request might return the following response:
 <2> Whether the rollover was dry run.
 <3> The result of each condition.
 
-[float]
-==== Naming the new index
+[[rollover-index-settings-ex]]
+===== Specify settings for the target index
+
+The settings, mappings, and aliases for the new index are taken from any
+matching <<indices-templates,index templates>>. Additionally, you can specify
+`settings`, `mappings`, and `aliases` in the body of the request, just like the
+<<indices-create-index,create index>> API. Values specified in the request
+override any values set in matching index templates. For example, the following
+`rollover` request overrides the `index.number_of_shards` setting:
+
+[source,console]
+--------------------------------------------------
+PUT /logs-000001
+{
+  "aliases": {
+    "logs_write": {}
+  }
+}
+
+POST /logs_write/_rollover
+{
+  "conditions" : {
+    "max_age": "7d",
+    "max_docs": 1000,
+    "max_size": "5gb"
+  },
+  "settings": {
+    "index.number_of_shards": 2
+  }
+}
+--------------------------------------------------
+
+
+[[rollover-index-specify-index-ex]]
+===== Specify a target index name
 
 If the name of the existing index ends with `-` and a number -- e.g.
 `logs-000001` -- then the name of the new index will follow the same pattern,
@@ -110,8 +260,9 @@ POST /my_alias/_rollover/my_new_index_name
 --------------------------------------------------
 // TEST[s/^/PUT my_old_index_name\nPUT my_old_index_name\/_alias\/my_alias\n/]
 
-[float]
-==== Using date math with the rollover API
+
+[[_using_date_math_with_the_rollover_api]]
+===== Use date math with a rollover
 
 It can be useful to use <<date-math-index-names,date math>> to name the
 rollover index according to the date that the index rolled over, e.g.
@@ -187,53 +338,15 @@ GET /%3Clogs-%7Bnow%2Fd%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-1d%7D-*%3E%2C%3Clogs-%7Bnow
 // TEST[continued]
 // TEST[s/now/2016.10.31||/]
 
-[float]
-==== Defining the new index
 
-The settings, mappings, and aliases for the new index are taken from any
-matching <<indices-templates,index templates>>. Additionally, you can specify
-`settings`, `mappings`, and `aliases` in the body of the request, just like the
-<<indices-create-index,create index>> API. Values specified in the request
-override any values set in matching index templates. For example, the following
-`rollover` request overrides the `index.number_of_shards` setting:
-
-[source,console]
---------------------------------------------------
-PUT /logs-000001
-{
-  "aliases": {
-    "logs_write": {}
-  }
-}
-
-POST /logs_write/_rollover
-{
-  "conditions" : {
-    "max_age": "7d",
-    "max_docs": 1000,
-    "max_size": "5gb"
-  },
-  "settings": {
-    "index.number_of_shards": 2
-  }
-}
---------------------------------------------------
-
-[float]
-==== Dry run
+[[rollover-index-api-dry-run-ex]]
+===== Dry run
 
 The rollover API supports `dry_run` mode, where request conditions can be
-checked without performing the actual rollover:
+checked without performing the actual rollover.
 
 [source,console]
 --------------------------------------------------
-PUT /logs-000001
-{
-  "aliases": {
-    "logs_write": {}
-  }
-}
-
 POST /logs_write/_rollover?dry_run
 {
   "conditions" : {
@@ -243,17 +356,11 @@ POST /logs_write/_rollover?dry_run
   }
 }
 --------------------------------------------------
+// TEST[s/^/PUT logs-000001\nPUT logs-000001\/_alias\/logs_write\n/]
 
-[float]
-==== Wait For Active Shards
-
-Because the rollover operation creates a new index to rollover to, the
-<<create-index-wait-for-active-shards,`wait_for_active_shards`>> setting on
-index creation applies to the rollover action as well.
 
 [[indices-rollover-is-write-index]]
-[float]
-==== Write Index Alias Behavior
+===== Roll over a write index
 
 The rollover alias when rolling over a write index that has `is_write_index` explicitly set to `true` is not
 swapped during rollover actions. Since having an alias point to multiple indices is ambiguous in distinguishing