[role="xpack"]
[testenv="platinum"]
[[ccr-put-auto-follow-pattern]]
=== Create auto-follow pattern API
++++
<titleabbrev>Create auto-follow pattern</titleabbrev>
++++

Creates an auto-follow pattern.

[[ccr-put-auto-follow-pattern-request]]
==== {api-request-title}

[source,console]
--------------------------------------------------
PUT /_ccr/auto_follow/<auto_follow_pattern_name>
{
  "remote_cluster" : "<remote_cluster>",
  "leader_index_patterns" :
  [
    "<leader_index_pattern>"
  ],
  "leader_index_exclusion_patterns":
  [
    "<leader_index_exclusion_pattern>"
  ],
  "follow_index_pattern" : "<follow_index_pattern>"
}
--------------------------------------------------
// TEST[setup:remote_cluster]
// TEST[s/<auto_follow_pattern_name>/auto_follow_pattern_name/]
// TEST[s/<remote_cluster>/remote_cluster/]
// TEST[s/<leader_index_patterns>/leader_index*/]
// TEST[s/<leader_index_exclusion_pattern>//]
// TEST[s/<follow_index_pattern>/{{leader_index}}-follower/]

//////////////////////////

[source,console]
--------------------------------------------------
DELETE /_ccr/auto_follow/auto_follow_pattern_name
--------------------------------------------------
// TEST[continued]

//////////////////////////

[[ccr-put-auto-follow-pattern-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have `read` and `monitor`
index privileges for the leader index patterns. You must also have `manage_ccr`
cluster privileges on the cluster that contains the follower index. For more
information, see <<security-privileges>>.

[[ccr-put-auto-follow-pattern-desc]]
==== {api-description-title}

This API creates a new named collection of
<<ccr-auto-follow,auto-follow patterns>> against the remote cluster
specified in the request body. Newly created indices on the remote cluster
matching any of the specified patterns will be automatically configured as follower
indices. Additionally, this API can be used to update existing
<<ccr-auto-follow,auto-follow patterns>>. Note that follower indices that were configured automatically
before updating an auto-follow pattern will remain unchanged even if they don't match against
the new patterns.

[[ccr-put-auto-follow-pattern-path-parms]]
==== {api-path-parms-title}
`<auto_follow_pattern_name>`::
  (Required, string) The name of the collection of auto-follow patterns.

[[ccr-put-auto-follow-pattern-request-body]]
==== {api-request-body-title}

`remote_cluster`::
  (Required, string) The <<remote-clusters,remote cluster>> containing
  the leader indices to match against.

`leader_index_patterns`::
  (Optional, array) An array of simple index patterns to match against indices
  in the remote cluster specified by the `remote_cluster` field.

`leader_index_exclusion_patterns`::
  (Optional, array) An array of simple index patterns that can be used to exclude indices
  from being auto-followed. Indices in the remote cluster whose names are matching one or
  more `leader_index_patterns` and one or more `leader_index_exclusion_patterns` won't be followed.

`follow_index_pattern`::
  (Optional, string) The name of follower index. The template `{{leader_index}}`
  can be used to derive the name of the follower index from the name of the
  leader index. When following a data stream, use `{{leader_index}}`; {ccr-init}
  does not support changes to the names of a follower data stream's backing
  indices.

include::../follow-request-body.asciidoc[]

[[ccr-put-auto-follow-pattern-examples]]
==== {api-examples-title}

This example creates an auto-follow pattern named `my_auto_follow_pattern`:

[source,console]
--------------------------------------------------
PUT /_ccr/auto_follow/my_auto_follow_pattern
{
  "remote_cluster" : "remote_cluster",
  "leader_index_patterns" :
  [
    "leader_index*"
  ],
  "follow_index_pattern" : "{{leader_index}}-follower",
  "settings": {
    "index.number_of_replicas": 0
  },
  "max_read_request_operation_count" : 1024,
  "max_outstanding_read_requests" : 16,
  "max_read_request_size" : "1024k",
  "max_write_request_operation_count" : 32768,
  "max_write_request_size" : "16k",
  "max_outstanding_write_requests" : 8,
  "max_write_buffer_count" : 512,
  "max_write_buffer_size" : "512k",
  "max_retry_delay" : "10s",
  "read_poll_timeout" : "30s"
}
--------------------------------------------------
// TEST[setup:remote_cluster]

The API returns the following result:

[source,console-result]
--------------------------------------------------
{
  "acknowledged" : true
}
--------------------------------------------------

//////////////////////////

[source,console]
--------------------------------------------------
DELETE /_ccr/auto_follow/my_auto_follow_pattern
--------------------------------------------------
// TEST[continued]

//////////////////////////