diff --git a/docs/reference/data-management.asciidoc b/docs/reference/data-management.asciidoc index 10f9f155f2deb..dc5ca9bd7f29d 100644 --- a/docs/reference/data-management.asciidoc +++ b/docs/reference/data-management.asciidoc @@ -31,3 +31,5 @@ for your older indices while reducing operating costs and maintaining search per -- include::datatiers.asciidoc[] + +include::indices/index-mgmt.asciidoc[] diff --git a/docs/reference/images/index-mgmt/management-index-templates-mappings.png b/docs/reference/images/index-mgmt/management-index-templates-mappings.png new file mode 100644 index 0000000000000..beb964b348171 Binary files /dev/null and b/docs/reference/images/index-mgmt/management-index-templates-mappings.png differ diff --git a/docs/reference/images/index-mgmt/management-index-templates.png b/docs/reference/images/index-mgmt/management-index-templates.png new file mode 100644 index 0000000000000..07f1fb9a7add1 Binary files /dev/null and b/docs/reference/images/index-mgmt/management-index-templates.png differ diff --git a/docs/reference/images/index-mgmt/management_index_component_template.png b/docs/reference/images/index-mgmt/management_index_component_template.png new file mode 100644 index 0000000000000..c03029fd172f0 Binary files /dev/null and b/docs/reference/images/index-mgmt/management_index_component_template.png differ diff --git a/docs/reference/images/index-mgmt/management_index_create_wizard.png b/docs/reference/images/index-mgmt/management_index_create_wizard.png new file mode 100644 index 0000000000000..bff1dd4cd0e7a Binary files /dev/null and b/docs/reference/images/index-mgmt/management_index_create_wizard.png differ diff --git a/docs/reference/images/index-mgmt/management_index_data_stream_backing_index.png b/docs/reference/images/index-mgmt/management_index_data_stream_backing_index.png new file mode 100644 index 0000000000000..a5c577affbbb2 Binary files /dev/null and b/docs/reference/images/index-mgmt/management_index_data_stream_backing_index.png differ diff --git a/docs/reference/images/index-mgmt/management_index_data_stream_stats.png b/docs/reference/images/index-mgmt/management_index_data_stream_stats.png new file mode 100644 index 0000000000000..a67ab4a7deb32 Binary files /dev/null and b/docs/reference/images/index-mgmt/management_index_data_stream_stats.png differ diff --git a/docs/reference/images/index-mgmt/management_index_details.png b/docs/reference/images/index-mgmt/management_index_details.png new file mode 100644 index 0000000000000..b199d13218f5a Binary files /dev/null and b/docs/reference/images/index-mgmt/management_index_details.png differ diff --git a/docs/reference/images/index-mgmt/management_index_labels.png b/docs/reference/images/index-mgmt/management_index_labels.png new file mode 100644 index 0000000000000..a89c32e08beff Binary files /dev/null and b/docs/reference/images/index-mgmt/management_index_labels.png differ diff --git a/docs/reference/indices/index-mgmt.asciidoc b/docs/reference/indices/index-mgmt.asciidoc new file mode 100644 index 0000000000000..0dcfbe0455607 --- /dev/null +++ b/docs/reference/indices/index-mgmt.asciidoc @@ -0,0 +1,236 @@ +[role="xpack"] +[[index-mgmt]] +== Index management + +{kib}'s *Index Management* features are an easy, convenient way to manage your +cluster's indices, <>, and <>. Practicing good index management ensures your data is stored +correctly and in the most cost-effective way possible. + +[discrete] +[[index-mgmt-wyl]] +=== What you'll learn + +You'll learn how to: + +* View and edit index settings. +* View mappings and statistics for an index. +* Perform index-level operations, such as refreshes and freezes. +* View and manage data streams. +* Create index templates to automatically configure new data streams and indices. + +[discrete] +[[index-mgm-req-permissions]] +=== Required permissions + +If you use {es} {security-features}, the following +<> are required: + +* The `monitor` cluster privilege to access {kib}'s *Index Management* features. +* The `view_index_metadata` and `manage` index privileges to view a data stream +or index's data. +* The `manage_index_templates` cluster privilege to manage index templates. + +To add these privileges in {kib}, go to *Stack Management > Security > Roles*. + +[discrete] +[[view-edit-indices]] +=== View and edit indices + +Open {kib}'s main menu and click *Stack Management > Index Management*. + +[role="screenshot"] +image::images/index-mgmt/management_index_labels.png[Index Management UI] + +The *Index Management* page contains an overview of your indices. +Badges indicate if an index is <>, a +<>, or a +<>. + +Clicking a badge narrows the list to only indices of that type. +You can also filter indices using the search bar. + +You can drill down into each index to investigate the index +<>, <>, and statistics. +From this view, you can also edit the index settings. + +[role="screenshot"] +image::images/index-mgmt/management_index_details.png[Index Management UI] + +[float] +=== Perform index-level operations + +Use the *Manage* menu to perform index-level operations. This menu +is available in the index details view, or when you select the checkbox of one or more +indices on the overview page. The menu includes the following actions: + +* <> +* <> +* <> +* <> +* <> +* <> +* *Add* <> + +[float] +[[manage-data-streams]] +=== Manage data streams + +The *Data Streams* view lists your data streams and lets you examine or delete +them. + +To view more information about a data stream, such as its generation or its +current index lifecycle policy, click the stream's name. + +[role="screenshot"] +image::images/index-mgmt/management_index_data_stream_stats.png[Data stream details] + +To view information about the stream's backing indices, click the number in the +*Indices* column. + +[role="screenshot"] +image::images/index-mgmt/management_index_data_stream_backing_index.png[Backing index] + +[float] +[[manage-index-templates]] +=== Manage index templates + +The *Index Templates* view lists your templates and lets you examine, +edit, clone, and delete them. Changes made to an index template do not +affect existing indices. + +[role="screenshot"] +image::images/index-mgmt/management-index-templates.png[Index templates] + +If you don't have any templates, you can create one using the *Create template* +wizard. + +[float] +==== Try it: Create an index template + +In this tutorial, you’ll create an index template and use it to configure two +new indices. + +*Step 1. Add a name and index pattern* + +. In the *Index Templates* view, open the *Create template* wizard. ++ +[role="screenshot"] +image::images/index-mgmt/management_index_create_wizard.png[Create wizard] + +. In the *Name* field, enter `my-index-template`. + +. Set *Index pattern* to `my-index-*` so the template matches any index +with that index pattern. + +. Leave *Data Stream*, *Priority*, *Version*, and *_meta field* blank or as-is. + +*Step 2. Add settings, mappings, and index aliases* + +. Add <> to your index template. ++ +Component templates are pre-configured sets of mappings, index settings, and +index aliases you can reuse across multiple index templates. Badges indicate +whether a component template contains mappings (*M*), index settings (*S*), +index aliases (*A*), or a combination of the three. ++ +Component templates are optional. For this tutorial, do not add any component +templates. ++ +[role="screenshot"] +image::images/index-mgmt/management_index_component_template.png[Component templates page] + +. Define index settings. These are optional. For this tutorial, leave this +section blank. + +. Define a mapping that contains an <> field named `geo` with a +child <> field named `coordinates`: ++ +[role="screenshot"] +image::images/index-mgmt/management-index-templates-mappings.png[Mapped fields page] ++ +Alternatively, you can click the *Load JSON* link and define the mapping as JSON: ++ +[source,js] +---- +{ + "properties": { + "geo": { + "properties": { + "coordinates": { + "type": "geo_point" + } + } + } + } +} +---- +// NOTCONSOLE ++ +You can create additional mapping configurations in the *Dynamic templates* and +*Advanced options* tabs. For this tutorial, do not create any additional +mappings. + +. Define an index alias named `my-index`: ++ +[source,js] +---- +{ + "my-index": {} +} +---- +// NOTCONSOLE + +. On the review page, check the summary. If everything looks right, click +*Create template*. + +*Step 3. Create new indices* + +You’re now ready to create new indices using your index template. + +. Index the following documents to create two indices: +`my-index-000001` and `my-index-000002`. ++ +[source,console] +---- +POST /my-index-000001/_doc +{ + "@timestamp": "2019-05-18T15:57:27.541Z", + "ip": "225.44.217.191", + "extension": "jpg", + "response": "200", + "geo": { + "coordinates": { + "lat": 38.53146222, + "lon": -121.7864906 + } + }, + "url": "https://media-for-the-masses.theacademyofperformingartsandscience.org/uploads/charles-fullerton.jpg" +} + +POST /my-index-000002/_doc +{ + "@timestamp": "2019-05-20T03:44:20.844Z", + "ip": "198.247.165.49", + "extension": "php", + "response": "200", + "geo": { + "coordinates": { + "lat": 37.13189556, + "lon": -76.4929875 + } + }, + "memory": 241720, + "url": "https://theacademyofperformingartsandscience.org/people/type:astronauts/name:laurel-b-clark/profile" +} +---- + +. Use the <> to view the configurations for the +new indices. The indices were configured using the index template you created +earlier. ++ +[source,console] +-------------------------------------------------- +GET /my-index-000001,my-index-000002 +-------------------------------------------------- +// TEST[continued]