Add docs for leader-leaseholder splits #19755
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
Files changed:
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
|
hi @miraradeva i hope PR this captures the gist of our convo (which i copied to the linked docs ticket) but please let me know if i'm missing some important information, or if anything is incorrect |
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
thanks @miraradeva ! I have made updates based on your feedback in 7c1d5cf, thank you for the review! i will move this along for docs team review to get it published ASAP |
taroface
approved these changes
Jun 17, 2025
| @@ -160,6 +160,15 @@ Unlike table data, system ranges use expiration-based leases; expiration-based l | |||
|
|
|||
| Expiration-based leases are also used temporarily during operations like lease transfers, until the new Raft leader can be fortified based on store liveness, as described in [Leader leases](#leader-leases). | |||
|
|
|||
| #### Leader‑leaseholder splits | |||
|
|
|||
| [Epoch-based leases](#epoch-based-leases) are vulnerable to _leader-leaseholder splits_. These can occur when a leaseholder’s Raft log has fallen behind and cannot acquire Raft leadership. Coupled with a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition), this split can cause permanent unavailability of the range if (1) the stale leaseholder continues heartbeating the [liveness range](#liveness-range) to hold its lease but (2) cannot reach the leader to propose writes. | |||
There was a problem hiding this comment.
Replace all smart quotes
Suggested change
| [Epoch-based leases](#epoch-based-leases) are vulnerable to _leader-leaseholder splits_. These can occur when a leaseholder’s Raft log has fallen behind and cannot acquire Raft leadership. Coupled with a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition), this split can cause permanent unavailability of the range if (1) the stale leaseholder continues heartbeating the [liveness range](#liveness-range) to hold its lease but (2) cannot reach the leader to propose writes. | |
| [Epoch-based leases](#epoch-based-leases) are vulnerable to _leader-leaseholder splits_. These can occur when a leaseholder's Raft log has fallen behind and cannot acquire Raft leadership. Coupled with a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition), this split can cause permanent unavailability of the range if (1) the stale leaseholder continues heartbeating the [liveness range](#liveness-range) to hold its lease but (2) cannot reach the leader to propose writes. |
There was a problem hiding this comment.
I might just be tired at the moment, but "Raft log has fallen behind" might be unclear as to "what" the Raft log has fallen behind.
| @@ -320,7 +320,7 @@ Send an alert when the number of ranges with replication below the replication f | |||
|
|
|||
| ### Requests stuck in raft | |||
There was a problem hiding this comment.
Suggested change
| ### Requests stuck in raft | |
| ### Requests stuck in Raft |
| @@ -160,6 +160,15 @@ Unlike table data, system ranges use expiration-based leases; expiration-based l | |||
|
|
|||
| Expiration-based leases are also used temporarily during operations like lease transfers, until the new Raft leader can be fortified based on store liveness, as described in [Leader leases](#leader-leases). | |||
|
|
|||
| #### Leader‑leaseholder splits | |||
|
|
|||
| [Epoch-based leases](#epoch-based-leases) are vulnerable to _leader-leaseholder splits_. These can occur when a leaseholder’s Raft log has fallen behind and cannot acquire Raft leadership. Coupled with a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition), this split can cause permanent unavailability of the range if (1) the stale leaseholder continues heartbeating the [liveness range](#liveness-range) to hold its lease but (2) cannot reach the leader to propose writes. | |||
There was a problem hiding this comment.
Is this correct / worth adding?
Suggested change
| [Epoch-based leases](#epoch-based-leases) are vulnerable to _leader-leaseholder splits_. These can occur when a leaseholder’s Raft log has fallen behind and cannot acquire Raft leadership. Coupled with a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition), this split can cause permanent unavailability of the range if (1) the stale leaseholder continues heartbeating the [liveness range](#liveness-range) to hold its lease but (2) cannot reach the leader to propose writes. | |
| [Epoch-based leases](#epoch-based-leases) (unlike [Leader leases](#leader-leases)) are vulnerable to _leader-leaseholder splits_. These can occur when a leaseholder’s Raft log has fallen behind and cannot acquire Raft leadership. Coupled with a [network partition]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition), this split can cause permanent unavailability of the range if (1) the stale leaseholder continues heartbeating the [liveness range](#liveness-range) to hold its lease but (2) cannot reach the leader to propose writes. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes DOC-13920