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

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-ccr[Cross-cluster replication APIs].
--

Creates a {ccr} <<ccr-auto-follow,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. Indices on the remote cluster that were created before the auto-follow
pattern is created won't be auto-followed even if they match the pattern.

This API can also 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-query-params]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]

[[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, the `follow_index_pattern` will be used for renaming not only the leader index, but also
  the data stream containing the leader index. For example, a data stream called
  `logs-mysql-default` with a backing index of `.ds-logs-mysql-default-2022-01-01-000001` and a
  `follow_index_pattern` of `{{leader_index}}_copy` will replicate the data stream as
  `logs-mysql-default_copy` and the backing index as
  `.ds-logs-mysql-default_copy-2022-01-01-000001`.

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]

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