From cd2d9d83c1d56161a3e90e7f4fdfe3c0cfc6369a Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Sat, 10 Nov 2018 15:45:15 -0500 Subject: [PATCH 1/9] Introduce CCR getting started guide This commit introduces a basic getting started guide for cross-cluster replication to the docs. Co-authored-by: "lcawl " --- docs/reference/ccr/getting-started.asciidoc | 260 +++++++++++++++++++- docs/reference/ccr/index.asciidoc | 2 +- 2 files changed, 258 insertions(+), 4 deletions(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index a0f97a659f279..d1e6b7c5dbd0f 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -1,7 +1,261 @@ [role="xpack"] [testenv="platinum"] -[[ccr-getting-started]] -== Getting Started +[[ccr-gs]] +== Getting Started with Cross-Cluster Replication beta[] -This is the getting started section of the {ccr} docs. \ No newline at end of file + +This getting-started guide for {ccr} shows you how to: + +* <> +* <> in a remote cluster that can be + replicated to a follower index in a local cluster +* <> that replicates a leader + index in a remote cluster + +[float] +[[ccr-gs-before-you-begin]] +=== Before you begin +. Install {es} on local and remote clusters. + +. Obtain a license that includes the {ccr} features. See +{stack-ov}/license-management.html[License Management]. + +. If {security} is enabled in your local and remote cluster, you need a user +that has appropriate authority to perform the steps in this tutorial. ++ +-- +[[ccr-gs-security]] +The {ccr} features use cluster privileges and built-in roles to make it easier +to control which users have authority to manage {ccr}. + +By default, you can perform all of the steps in this getting-started guide by +using the built-in `elastic` user. However, a password must be set for this user +before the user can do anything. For information about how to set that password, +see {stack-ov}/security-getting-started.html[Getting started with security]. + +If you are performing these steps in a production environment, take extra care +because the `elastic` user has the `superuser` role and you could inadvertently +make significant changes. You can alternately assign the appropriate privileges +to a user ID of your choice. + +On the remote cluster containing the leader index, a user will need the +`read_ccr` cluster privilege, and `monitor` and `read` privileges on the leader +index. + +[source,yml] +-------------------------------------------------- +ccr_user: + cluster: + - read_ccr + indices: + - names: [ 'leader-index' ] + privileges: + - monitor + - read +-------------------------------------------------- + +On the local cluster containing the follower index, the same user will need the +`manage_ccr` cluster privilege, and `monitor`, `read`, `write` and +`manage_follow_index` privileges on the follower index. + +[source,yml] +-------------------------------------------------- +ccr_user: + cluster: + - manage_ccr + indices: + - names: [ 'follower-index' ] + privileges: + - monitor + - read + - write + - manage_follow_index +-------------------------------------------------- +-- + +[float] +[[ccr-gs-remote-cluster]] +=== Connecting to a remote cluster + +The {ccr} features require +<>. +In the example for this getting-started guide, we will connect our local cluster +to a remote cluster with the cluster alias `leader`. + +[source,js] +-------------------------------------------------- +PUT /_cluster/settings +{ + "persistent" : { + "cluster" : { + "remote" : { + "leader" : { + "seeds" : [ + "127.0.0.1:9300" <1> + ] + } + } + } + } +} +-------------------------------------------------- +// CONSOLE +// TEST[setup:host] +// TEST[s/127.0.0.1:9300/\${transport_host}/] +<1> Specifies the hostname and transport port of a seed node in the remote + cluster. + +You can verify that the local cluster is successfully connected to the remote +cluster. + +[source,js] +-------------------------------------------------- +GET /_remote/info +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +The API will respond by showing that the local cluster is connected to the +remote cluster. + +[source,js] +-------------------------------------------------- +{ + "leader" : { + "seeds" : [ + "127.0.0.1:9300" + ], + "connected" : true, <1> + "num_nodes_connected" : 1, <2> + "max_connections_per_cluster" : 3, + "initial_connect_timeout" : "30s", + "skip_unavailable" : false + } +} +-------------------------------------------------- +// TESTRESPONSE +// TEST[s/127.0.0.1:9300/$body.leader.seeds.0/] +// TEST[s/"connected" : true/"connected" : $body.leader.connected/] +// TEST[s/"num_nodes_connected" : 1/"num_nodes_connected" : $body.leader.num_nodes_connected/] +<1> This shows the local cluster is connected to the remote cluster with cluster + alias `leader` +<2> This shows the number of nodes in the remote cluster the local cluster is + connected to. + +[float] +[[ccr-gs-leader-index]] +=== Creating a leader index + +Leader indices require special index settings to ensure that the operations that +need to replicated by the follower from the leader are available when the +follower requests them from the leader. These settings are used to enable soft +deletes on the leader index, and control how many soft deletes are retained. A +soft delete occurs whenever a document is deleted or updated. Soft deletes can +only be enabled on new indices created on or after {es} 6.5.0. In the following +example, we will create a leader index in the remote cluster. + +[source,js] +-------------------------------------------------- +PUT /server-metrics +{ + "settings" : { + "index" : { + "number_of_shards" : 1, + "number_of_replicas" : 0, + "soft_deletes" : { + "enabled" : true, <1> + "retention" : { + "operations" : 1024 <2> + } + } + } + }, + "mappings" : { + "metric" : { + "properties" : { + "@timestamp" : { + "type" : "date" + }, + "accept" : { + "type" : "long" + }, + "deny" : { + "type" : "long" + }, + "host" : { + "type" : "keyword" + }, + "response" : { + "type" : "float" + }, + "service" : { + "type" : "keyword" + }, + "total" : { + "type" : "long" + } + } + } + } +} +-------------------------------------------------- +// CONSOLE +// TEST[continued] +<1> Enables soft deletes on the leader index. +<2> Sets that up to 1024 soft deletes will be retained. + +[float] +[[ccr-gs-follower-index]] +=== Creating a follower index + +Follower indices are created with the <>. +When creating a follower index, you will reference the +<> that you connected your +local cluster to and the <> that +you created in the remote cluster. + +[source,js] +-------------------------------------------------- +PUT /server-metrics-copy/_ccr/follow +{ + "remote_cluster" : "leader", + "leader_index" : "server-metrics" +} +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +////////////////////////// + +[source,js] +-------------------------------------------------- +{ + "follow_index_created" : true, + "follow_index_shards_acked" : true, + "index_following_started" : true +} +-------------------------------------------------- +// TESTRESPONSE + +////////////////////////// + +Now when you index documents into your leader index, you will see these +documents are replicated by the follower index from the leader index. You can +inspect the status of replication using the +<>. + +////////////////////////// + +[source,js] +-------------------------------------------------- +POST /server-metrics-copy/_ccr/pause_follow + +POST /server-metrics-copy/_close + +POST /server-metrics-copy/_ccr/unfollow +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +////////////////////////// diff --git a/docs/reference/ccr/index.asciidoc b/docs/reference/ccr/index.asciidoc index e802286af7cd5..921b19e8b0094 100644 --- a/docs/reference/ccr/index.asciidoc +++ b/docs/reference/ccr/index.asciidoc @@ -9,7 +9,7 @@ beta[] * <> -* <> +* <> -- From 61373e9c830eaaa7137917174d057d248bf3abdb Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Sun, 11 Nov 2018 12:43:16 -0500 Subject: [PATCH 2/9] Add auto-follow patterns --- docs/reference/ccr/getting-started.asciidoc | 60 ++++++++++++++++++++- docs/reference/index.asciidoc | 2 + 2 files changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index d1e6b7c5dbd0f..b6c632ccb34e1 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -12,6 +12,8 @@ This getting-started guide for {ccr} shows you how to: replicated to a follower index in a local cluster * <> that replicates a leader index in a remote cluster +* <> that replicate + new indices in a remote cluster [float] [[ccr-gs-before-you-begin]] @@ -212,7 +214,7 @@ PUT /server-metrics Follower indices are created with the <>. When creating a follower index, you will reference the <> that you connected your -local cluster to and the <> that +local cluster to, and the <> that you created in the remote cluster. [source,js] @@ -259,3 +261,59 @@ POST /server-metrics-copy/_ccr/unfollow // TEST[continued] ////////////////////////// + +[float] +[[ccr-gs-auto-follow]] +=== Automatically create follower indices + +The auto-follow feature in {ccr} helps for time-series use-cases where new +indices that you want to follow are periodically created in the remote cluster +(e.g., daily Beats indices). Auto-following is configured using the +<>. With an +auto-follow pattern, you reference the <> +that you connected your local cluster to, and a collection of patterns that +match the indices that you want to be automatically followed when they are +created in the remote cluster. + +[source,js] +-------------------------------------------------- +PUT /_ccr/auto_follow/beats +{ + "remote_cluster" : "leader", + "leader_index_patterns" : + [ + "metricbeat-*", <1> + "packetbeat-*" <2> + ], + "follow_index_pattern" : "{{leader_index}}-copy" <3> +} +-------------------------------------------------- +// CONSOLE +// TEST[continued] +<1> Automatically follow newly-created Metricbeat indices. +<2> Automatically follow newly-created Packetbeat indices. +<3> The name of the follower index is derived from the name of the leader index + by adding the suffix `-copy` to the name of the leader index. + +////////////////////////// + +[source,js] +-------------------------------------------------- +{ + "acknowledged" : true +} +-------------------------------------------------- +// TESTRESPONSE + +////////////////////////// + +////////////////////////// + +[source,js] +-------------------------------------------------- +DELETE /_ccr/auto_follow/beats +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +////////////////////////// diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index 48cb7700a52ea..9f481efd6dd52 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -57,6 +57,8 @@ include::ingest.asciidoc[] include::ilm/index.asciidoc[] +include::ccr/index.asciidoc[] + include::sql/index.asciidoc[] include::monitoring/index.asciidoc[] From 296ae8986e55143079fb47f301da195cec307f32 Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Sun, 11 Nov 2018 12:44:26 -0500 Subject: [PATCH 3/9] Remove adding CCR to reference guide --- docs/reference/index.asciidoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index 9f481efd6dd52..48cb7700a52ea 100644 --- a/docs/reference/index.asciidoc +++ b/docs/reference/index.asciidoc @@ -57,8 +57,6 @@ include::ingest.asciidoc[] include::ilm/index.asciidoc[] -include::ccr/index.asciidoc[] - include::sql/index.asciidoc[] include::monitoring/index.asciidoc[] From 83f020e58ce3ddd6020ed72717c972f954039389 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 12 Nov 2018 00:37:58 -0800 Subject: [PATCH 4/9] [DOCS] Fixes broken links --- docs/reference/ccr/getting-started.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index b6c632ccb34e1..7983d1c2cd2c0 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -81,7 +81,7 @@ ccr_user: === Connecting to a remote cluster The {ccr} features require -<>. +{ref}/modules-remote-clusters.html[connecting your local cluster to a remote cluster]. In the example for this getting-started guide, we will connect our local cluster to a remote cluster with the cluster alias `leader`. @@ -211,7 +211,7 @@ PUT /server-metrics [[ccr-gs-follower-index]] === Creating a follower index -Follower indices are created with the <>. +Follower indices are created with the {ref}/ccr-put-follow.html[create follower API]. When creating a follower index, you will reference the <> that you connected your local cluster to, and the <> that @@ -245,7 +245,7 @@ PUT /server-metrics-copy/_ccr/follow Now when you index documents into your leader index, you will see these documents are replicated by the follower index from the leader index. You can inspect the status of replication using the -<>. +{ref}/ccr-get-follow-stats[get follower stats API]. ////////////////////////// @@ -269,7 +269,7 @@ POST /server-metrics-copy/_ccr/unfollow The auto-follow feature in {ccr} helps for time-series use-cases where new indices that you want to follow are periodically created in the remote cluster (e.g., daily Beats indices). Auto-following is configured using the -<>. With an +{ref}/ccr-put-auto-follow-pattern.html[create auto-follow pattern API]. With an auto-follow pattern, you reference the <> that you connected your local cluster to, and a collection of patterns that match the indices that you want to be automatically followed when they are From d6b8a4ae7e4a149f3a783e1f57c83b1837c998a7 Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Mon, 12 Nov 2018 10:31:04 -0500 Subject: [PATCH 5/9] Fix typo --- docs/reference/ccr/getting-started.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index 7983d1c2cd2c0..04563cec40cdc 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -150,7 +150,7 @@ remote cluster. === Creating a leader index Leader indices require special index settings to ensure that the operations that -need to replicated by the follower from the leader are available when the +need to be replicated by the follower from the leader are available when the follower requests them from the leader. These settings are used to enable soft deletes on the leader index, and control how many soft deletes are retained. A soft delete occurs whenever a document is deleted or updated. Soft deletes can From 0244e9c839e8e29b6d74857320c2ce1f71fd34de Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Mon, 12 Nov 2018 10:31:28 -0500 Subject: [PATCH 6/9] Fix another typo --- docs/reference/ccr/getting-started.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index 04563cec40cdc..e8b7ecfc132c7 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -18,7 +18,7 @@ This getting-started guide for {ccr} shows you how to: [float] [[ccr-gs-before-you-begin]] === Before you begin -. Install {es} on local and remote clusters. +. Install {es} your on local and remote clusters. . Obtain a license that includes the {ccr} features. See {stack-ov}/license-management.html[License Management]. From c8512dab3545eb09ae1d397c292ab5393ef58c47 Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Mon, 12 Nov 2018 12:15:48 -0500 Subject: [PATCH 7/9] Add link to installing ES --- docs/reference/ccr/getting-started.asciidoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index e8b7ecfc132c7..ddb7571a30337 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -18,13 +18,14 @@ This getting-started guide for {ccr} shows you how to: [float] [[ccr-gs-before-you-begin]] === Before you begin -. Install {es} your on local and remote clusters. +. {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Install {es}] + your on local and remote clusters. . Obtain a license that includes the {ccr} features. See -{stack-ov}/license-management.html[License Management]. + {stack-ov}/license-management.html[License Management]. . If {security} is enabled in your local and remote cluster, you need a user -that has appropriate authority to perform the steps in this tutorial. + that has appropriate authority to perform the steps in this tutorial. + -- [[ccr-gs-security]] From a26580699ce9cd86cc97080767e72a1b2acc2843 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 12 Nov 2018 16:03:06 -0800 Subject: [PATCH 8/9] [DOCS] Minor edits to CCR getting started --- docs/reference/ccr/getting-started.asciidoc | 81 +++++++++++---------- 1 file changed, 41 insertions(+), 40 deletions(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index ddb7571a30337..a2ad84d45e2f6 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -8,42 +8,42 @@ beta[] This getting-started guide for {ccr} shows you how to: * <> -* <> in a remote cluster that can be - replicated to a follower index in a local cluster +* <> in a remote cluster * <> that replicates a leader - index in a remote cluster -* <> that replicate - new indices in a remote cluster + index +* <> [float] [[ccr-gs-before-you-begin]] === Before you begin . {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Install {es}] - your on local and remote clusters. + on your local and remote clusters. -. Obtain a license that includes the {ccr} features. See - {stack-ov}/license-management.html[License Management]. +. Obtain a license that includes the {ccr} features. See https://www.elastic.co/subscriptions + and <>. -. If {security} is enabled in your local and remote cluster, you need a user - that has appropriate authority to perform the steps in this tutorial. +. If the Elastic {security-features} are enabled in your local and remote +clusters, you need a user that has appropriate authority to perform the steps in +this tutorial. + -- [[ccr-gs-security]] The {ccr} features use cluster privileges and built-in roles to make it easier to control which users have authority to manage {ccr}. -By default, you can perform all of the steps in this getting-started guide by +By default, you can perform all of the steps in this tutorial by using the built-in `elastic` user. However, a password must be set for this user before the user can do anything. For information about how to set that password, -see {stack-ov}/security-getting-started.html[Getting started with security]. +see <>. If you are performing these steps in a production environment, take extra care because the `elastic` user has the `superuser` role and you could inadvertently -make significant changes. You can alternately assign the appropriate privileges -to a user ID of your choice. +make significant changes. -On the remote cluster containing the leader index, a user will need the -`read_ccr` cluster privilege, and `monitor` and `read` privileges on the leader +Alternatively, you can assign the appropriate privileges +to a user ID of your choice. On the remote cluster that contains the leader index, +a user will need the +`read_ccr` cluster privilege and `monitor` and `read` privileges on the leader index. [source,yml] @@ -58,8 +58,8 @@ ccr_user: - read -------------------------------------------------- -On the local cluster containing the follower index, the same user will need the -`manage_ccr` cluster privilege, and `monitor`, `read`, `write` and +On the local cluster that contains the follower index, the same user will need the +`manage_ccr` cluster privilege and `monitor`, `read`, `write` and `manage_follow_index` privileges on the follower index. [source,yml] @@ -81,9 +81,9 @@ ccr_user: [[ccr-gs-remote-cluster]] === Connecting to a remote cluster -The {ccr} features require -{ref}/modules-remote-clusters.html[connecting your local cluster to a remote cluster]. -In the example for this getting-started guide, we will connect our local cluster +The {ccr} features require that you +{ref}/modules-remote-clusters.html[connect your local cluster to a remote cluster]. +In this tutorial, we will connect our local cluster to a remote cluster with the cluster alias `leader`. [source,js] @@ -107,7 +107,7 @@ PUT /_cluster/settings // TEST[setup:host] // TEST[s/127.0.0.1:9300/\${transport_host}/] <1> Specifies the hostname and transport port of a seed node in the remote - cluster. + cluster. You can verify that the local cluster is successfully connected to the remote cluster. @@ -151,12 +151,13 @@ remote cluster. === Creating a leader index Leader indices require special index settings to ensure that the operations that -need to be replicated by the follower from the leader are available when the +need to be replicated are available when the follower requests them from the leader. These settings are used to enable soft -deletes on the leader index, and control how many soft deletes are retained. A -soft delete occurs whenever a document is deleted or updated. Soft deletes can -only be enabled on new indices created on or after {es} 6.5.0. In the following -example, we will create a leader index in the remote cluster. +deletes on the leader index and to control how many soft deletes are retained. A +_soft delete_ occurs whenever a document is deleted or updated. Soft deletes can +be enabled only on new indices created on or after {es} 6.5.0. + +In the following example, we will create a leader index in the remote cluster: [source,js] -------------------------------------------------- @@ -213,10 +214,9 @@ PUT /server-metrics === Creating a follower index Follower indices are created with the {ref}/ccr-put-follow.html[create follower API]. -When creating a follower index, you will reference the -<> that you connected your -local cluster to, and the <> that -you created in the remote cluster. +When you create a follower index, you must reference the +<> and the +<> that you created in the remote cluster. [source,js] -------------------------------------------------- @@ -244,7 +244,7 @@ PUT /server-metrics-copy/_ccr/follow ////////////////////////// Now when you index documents into your leader index, you will see these -documents are replicated by the follower index from the leader index. You can +documents replicated in the follower index. You can inspect the status of replication using the {ref}/ccr-get-follow-stats[get follower stats API]. @@ -267,14 +267,15 @@ POST /server-metrics-copy/_ccr/unfollow [[ccr-gs-auto-follow]] === Automatically create follower indices -The auto-follow feature in {ccr} helps for time-series use-cases where new -indices that you want to follow are periodically created in the remote cluster -(e.g., daily Beats indices). Auto-following is configured using the +The auto-follow feature in {ccr} helps for time series use cases where you want +to follow new indices that are periodically created in the remote cluster +(such as daily Beats indices). Auto-following is configured using the {ref}/ccr-put-auto-follow-pattern.html[create auto-follow pattern API]. With an auto-follow pattern, you reference the <> -that you connected your local cluster to, and a collection of patterns that -match the indices that you want to be automatically followed when they are -created in the remote cluster. +that you connected your local cluster to. You must also specify a collection of +patterns that match the indices you want to automatically follow. + +For example: [source,js] -------------------------------------------------- @@ -291,8 +292,8 @@ PUT /_ccr/auto_follow/beats -------------------------------------------------- // CONSOLE // TEST[continued] -<1> Automatically follow newly-created Metricbeat indices. -<2> Automatically follow newly-created Packetbeat indices. +<1> Automatically follow new {metricbeat} indices. +<2> Automatically follow new {packetbeat} indices. <3> The name of the follower index is derived from the name of the leader index by adding the suffix `-copy` to the name of the leader index. From 39720b2c329b777bbf62a4d9be219e1b2a9a1d2b Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Tue, 13 Nov 2018 06:40:13 -0500 Subject: [PATCH 9/9] Minor edits --- docs/reference/ccr/getting-started.asciidoc | 76 ++++++++++++--------- docs/reference/ccr/index.asciidoc | 2 +- 2 files changed, 43 insertions(+), 35 deletions(-) diff --git a/docs/reference/ccr/getting-started.asciidoc b/docs/reference/ccr/getting-started.asciidoc index a2ad84d45e2f6..a0721e7f989e9 100644 --- a/docs/reference/ccr/getting-started.asciidoc +++ b/docs/reference/ccr/getting-started.asciidoc @@ -1,33 +1,35 @@ [role="xpack"] [testenv="platinum"] -[[ccr-gs]] -== Getting Started with Cross-Cluster Replication +[[ccr-getting-started]] +== Getting Started with {ccr} beta[] This getting-started guide for {ccr} shows you how to: -* <> -* <> in a remote cluster -* <> that replicates a leader - index -* <> +* <> +* <> in a remote cluster +* <> that replicates + a leader index +* <> [float] -[[ccr-gs-before-you-begin]] +[[ccr-getting-started-before-you-begin]] === Before you begin . {stack-gs}/get-started-elastic-stack.html#install-elasticsearch[Install {es}] on your local and remote clusters. -. Obtain a license that includes the {ccr} features. See https://www.elastic.co/subscriptions - and <>. +. Obtain a license that includes the {ccr} features. See + https://www.elastic.co/subscriptions[subscriptions] and + <>. . If the Elastic {security-features} are enabled in your local and remote -clusters, you need a user that has appropriate authority to perform the steps in -this tutorial. + clusters, you need a user that has appropriate authority to perform the steps + in this tutorial. + -- -[[ccr-gs-security]] +[[ccr-getting-started-security]] The {ccr} features use cluster privileges and built-in roles to make it easier to control which users have authority to manage {ccr}. @@ -40,11 +42,10 @@ If you are performing these steps in a production environment, take extra care because the `elastic` user has the `superuser` role and you could inadvertently make significant changes. -Alternatively, you can assign the appropriate privileges -to a user ID of your choice. On the remote cluster that contains the leader index, -a user will need the -`read_ccr` cluster privilege and `monitor` and `read` privileges on the leader -index. +Alternatively, you can assign the appropriate privileges to a user ID of your +choice. On the remote cluster that contains the leader index, a user will need +the `read_ccr` cluster privilege and `monitor` and `read` privileges on the +leader index. [source,yml] -------------------------------------------------- @@ -58,8 +59,8 @@ ccr_user: - read -------------------------------------------------- -On the local cluster that contains the follower index, the same user will need the -`manage_ccr` cluster privilege and `monitor`, `read`, `write` and +On the local cluster that contains the follower index, the same user will need +the `manage_ccr` cluster privilege and `monitor`, `read`, `write` and `manage_follow_index` privileges on the follower index. [source,yml] @@ -75,16 +76,21 @@ ccr_user: - write - manage_follow_index -------------------------------------------------- + +If you are managing +<> via the +cluster update settings API, you will also need a user with the `all` cluster +privilege. -- [float] -[[ccr-gs-remote-cluster]] +[[ccr-getting-started-remote-cluster]] === Connecting to a remote cluster The {ccr} features require that you -{ref}/modules-remote-clusters.html[connect your local cluster to a remote cluster]. -In this tutorial, we will connect our local cluster -to a remote cluster with the cluster alias `leader`. +{ref}/modules-remote-clusters.html[connect your local cluster to a remote +cluster]. In this tutorial, we will connect our local cluster to a remote +cluster with the cluster alias `leader`. [source,js] -------------------------------------------------- @@ -147,7 +153,7 @@ remote cluster. connected to. [float] -[[ccr-gs-leader-index]] +[[ccr-getting-started-leader-index]] === Creating a leader index Leader indices require special index settings to ensure that the operations that @@ -210,13 +216,14 @@ PUT /server-metrics <2> Sets that up to 1024 soft deletes will be retained. [float] -[[ccr-gs-follower-index]] +[[ccr-getting-started-follower-index]] === Creating a follower index -Follower indices are created with the {ref}/ccr-put-follow.html[create follower API]. -When you create a follower index, you must reference the -<> and the -<> that you created in the remote cluster. +Follower indices are created with the {ref}/ccr-put-follow.html[create follower +API]. When you create a follower index, you must reference the +<> and the +<> that you created in the remote +cluster. [source,js] -------------------------------------------------- @@ -264,16 +271,17 @@ POST /server-metrics-copy/_ccr/unfollow ////////////////////////// [float] -[[ccr-gs-auto-follow]] +[[ccr-getting-started-auto-follow]] === Automatically create follower indices The auto-follow feature in {ccr} helps for time series use cases where you want to follow new indices that are periodically created in the remote cluster (such as daily Beats indices). Auto-following is configured using the {ref}/ccr-put-auto-follow-pattern.html[create auto-follow pattern API]. With an -auto-follow pattern, you reference the <> -that you connected your local cluster to. You must also specify a collection of -patterns that match the indices you want to automatically follow. +auto-follow pattern, you reference the +<> that you connected your +local cluster to. You must also specify a collection of patterns that match the +indices you want to automatically follow. For example: diff --git a/docs/reference/ccr/index.asciidoc b/docs/reference/ccr/index.asciidoc index 921b19e8b0094..e802286af7cd5 100644 --- a/docs/reference/ccr/index.asciidoc +++ b/docs/reference/ccr/index.asciidoc @@ -9,7 +9,7 @@ beta[] * <> -* <> +* <> --