From 8abc3fb796bd7f50ff132b665182b50fe7e240e5 Mon Sep 17 00:00:00 2001
From: David Turner <david.turner@elastic.co>
Date: Wed, 17 Feb 2021 13:26:48 +0000
Subject: [PATCH] Fix docs for behaviour of CCR after lease expiry (#69114)

Today we imply that CCR will automatically fall back to a full index
copy if it cannot replay any missing history. This was true for earlier
versions of the design but we ultimately decided not to do this without
adjusting the docs to match. This commit fixes the docs.
---
 docs/reference/ccr/index.asciidoc | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/reference/ccr/index.asciidoc b/docs/reference/ccr/index.asciidoc
index 5adf860e9d0d..c8830baa78be 100644
--- a/docs/reference/ccr/index.asciidoc
+++ b/docs/reference/ccr/index.asciidoc
@@ -266,12 +266,17 @@ retaining these soft deletes up to configurable limits, the history of
 operations can be retained on the leader shards and made available to the
 follower shard tasks as it replays the history of operations.
 
-The <<ccr-index-soft-deletes-retention-period,`index.soft_deletes.retention_lease.period`>> setting defines the
-maximum time to retain a shard history retention lease before it is
-considered expired. This setting determines how long the cluster containing
-your leader index can be offline, which is 12 hours by default. If a shard copy
-recovers after its retention lease expires, then {es} will fall back to copying
-the entire index, because it can no longer replay the missing history.
+The <<ccr-index-soft-deletes-retention-period,`index.soft_deletes.retention_lease.period`>>
+setting defines the maximum time to retain a shard history retention lease
+before it is considered expired. This setting determines how long the cluster
+containing your follower index can be offline, which is 12 hours by default. If
+a shard copy recovers after its retention lease expires, but the missing
+operations are still available on the leader index, then {es} will establish a
+new lease and copy the missing operations. However {es} does not guarantee to
+retain unleased operations, so it is also possible that some of the missing
+operations have been discarded by the leader and are now completely
+unavailable. If this happens then the follower cannot recover automatically so
+you must <<ccr-recreate-follower-index,recreate it>>.
 
 Soft deletes must be enabled for indices that you want to use as leader
 indices. Soft deletes are enabled by default on new indices created on