OpenSearch/docs/reference/ccr/apis/follow/post-forget-follower.asciidoc

[role="xpack"]
[testenv="platinum"]
[[ccr-post-forget-follower]]
=== Forget follower API
++++
<titleabbrev>Forget follower</titleabbrev>
++++

Removes the follower retention leases from the leader.

[[ccr-post-forget-follower-request]]
==== {api-request-title}

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

[source,console]
--------------------------------------------------
PUT /follower_index/_ccr/follow?wait_for_active_shards=1
{
  "remote_cluster" : "remote_cluster",
  "leader_index" : "leader_index"
}
--------------------------------------------------
// TESTSETUP
// TEST[setup:remote_cluster_and_leader_index]

[source,console]
--------------------------------------------------
POST /follower_index/_ccr/pause_follow
--------------------------------------------------
// TEARDOWN

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

[source,console]
--------------------------------------------------
POST /<leader_index>/_ccr/forget_follower
{
  "follower_cluster" : "<follower_cluster>",
  "follower_index" : "<follower_index>",
  "follower_index_uuid" : "<follower_index_uuid>",
  "leader_remote_cluster" : "<leader_remote_cluster>"
}
--------------------------------------------------
// TEST[s/<leader_index>/leader_index/]
// TEST[s/<follower_cluster>/follower_cluster/]
// TEST[s/<follower_index>/follower_index/]
// TEST[s/<follower_index_uuid>/follower_index_uuid/]
// TEST[s/<leader_remote_cluster>/leader_remote_cluster/]
// TEST[skip_shard_failures]

[source,console-result]
--------------------------------------------------
{
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0,
    "failures" : [ ]
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"total" : 1/"total" : $body._shards.total/]
// TESTRESPONSE[s/"successful" : 1/"successful" : $body._shards.successful/]
// TESTRESPONSE[s/"failed" : 0/"failed" : $body._shards.failed/]
// TESTRESPONSE[s/"failures" : \[ \]/"failures" : $body._shards.failures/]

[[ccr-post-forget-follower-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have `manage_leader_index`
index privileges for the leader index. For more information, see
<<security-privileges>>.

[[ccr-post-forget-follower-desc]]
==== {api-description-title}

A following index takes out retention leases on its leader index. These
retention leases are used to increase the likelihood that the shards of the
leader index retain the history of operations that the shards of the following
index need to execute replication. When a follower index is converted to a
regular index via the <<ccr-post-unfollow,unfollow API>> (either via explicit
execution of this API, or implicitly via {ilm}), these retention leases are
removed. However, removing these retention leases can fail (e.g., if the remote
cluster containing the leader index is unavailable). While these retention
leases will eventually expire on their own, their extended existence can cause
the leader index to hold more history than necessary, and prevent {ilm} from
performing some operations on the leader index. This API exists to enable
manually removing these retention leases when the unfollow API was unable to do
so.

NOTE: This API does not stop replication by a following index. If you use this
API targeting a follower index that is still actively following, the following
index will add back retention leases on the leader. The only purpose of this API
is to handle the case of failure to remove the following retention leases after
the <<ccr-post-unfollow,unfollow API>> is invoked.

[[ccr-post-forget-follower-path-parms]]
==== {api-path-parms-title}

`<leader_index>`::
  (Required, string) The name of the leader index.

[[ccr-post-forget-follower-request-body]]
==== {api-request-body-title}

`follower_cluster`::
  (Required, string) The name of the cluster containing the follower index.

`follower_index`::
  (Required, string) The name of the follower index.

`follower_index_uuid`::
  (Required, string) The UUID of the follower index.

`leader_remote_cluster`::
  (Required, string) The alias (from the perspective of the cluster containing
  the follower index) of the <<modules-remote-clusters,remote cluster>>
  containing the leader index.

[[ccr-post-forget-follower-examples]]
==== {api-examples-title}

This example removes the follower retention leases for `follower_index` from
`leader_index`.

[source,console]
--------------------------------------------------
POST /leader_index/_ccr/forget_follower
{
  "follower_cluster" : "follower_cluster",
  "follower_index" : "follower_index",
  "follower_index_uuid" : "vYpnaWPRQB6mNspmoCeYyA",
  "leader_remote_cluster" : "leader_cluster"
}
--------------------------------------------------
// TEST[skip_shard_failures]

The API returns the following result:

[source,console-result]
--------------------------------------------------
{
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0,
    "failures" : [ ]
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"total" : 1/"total" : $body._shards.total/]
// TESTRESPONSE[s/"successful" : 1/"successful" : $body._shards.successful/]
// TESTRESPONSE[s/"failed" : 0/"failed" : $body._shards.failed/]
// TESTRESPONSE[s/"failures" : \[ \]/"failures" : $body._shards.failures/]