Restore feature states requires restricted permissions #3857

stefnestor · 2025-11-07T22:14:35Z

👋 howdy, team!

This

adds in the two most common errors encountered when snapshot restoring feature states / system indices wrong
cross-links how to get the needed restricted permissions to restore system feature states (and removes outdated-since-v8.0 information which no longer works)
adds in an example API outline of reading the feature state to its snapshot appearance to determining which to restore

Related changed pages

Snapshot and restore > Feature states
Restore a snapshot > Restore a feature state and Restore an entire cluster
File-based access recovery

stefnestor · 2025-11-07T22:17:55Z

👋 may I have help on failing check

info ::e.d.i.atedBuildService:: Finished building and exporting exporters Html, LLMText, Configuration, DocumentationState, LinkMetadata, Redirects

	The following errors and warnings were found in the documentation

Error: 'reference/cloud/cloud-hosted/ec-api-console.md' is not a valid link in the 'cloud' cross link index: https://elastic-docs-link-index.s3.us-east-2.amazonaws.com/elastic/cloud/master/links.json
     ┌─[/github/workspace/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md]
     │
 233 │ Restoring the `security` feature state overwrites system indices used for authentication. If you use {{ech}} or {{ece}}, ensure you have access to the [{{es}} API console](cloud://reference/cloud/cloud-hosted/ec-api-console.md) before restoring the `security` feature state. If you run {{es}} on your own hardware or in {{eck}}, [create a temporary user with elevated permissions to edit restricted indices in the file realm](/troubleshoot/elasticsearch/file-based-recovery.md) to ensure you’ll still be able to access your cluster.
     ·                                                                                                                                                       ──────────────────────────────────────────────────────                                                                                                                                                                                                                                                                                                                                        
     ·                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      
     │
     └─



	1 Errors / 0 Warnings / 0 Hints

related documentation doesn't say how to cross-link cloud reference section 🙏

deploy-manage/tools/snapshot-and-restore/restore-snapshot.md

Link fix

github-actions · 2025-11-10T11:21:13Z

🔍 Preview links for changed docs

yetanothertw

Hi @stefnestor -- thank you so much for your contributions! 🌻

I've fixed the link that was causing the check to fail, and the docs build fine now. I've also left a few suggestions for style and clarity for your consideration.

yetanothertw · 2025-11-10T11:29:30Z

deploy-manage/tools/snapshot-and-restore.md

 A feature state typically includes one or more [system indices or system data streams](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). It may also include regular indices and data streams used by the feature. For example, a feature state may include a regular index that contains the feature’s execution history. Storing this history in a regular index lets you more easily search it.

-In {{es}} 8.0 and later versions, feature states are the only way to back up and restore system indices and system data streams.
+In {{es}} 8.0 and later versions, feature states are the only way to back up and restore system indices and system data streams. Attempting to restore a system index or data stream outside its feature state will be blocked by an error. For example index `.example` this error would appear like


Minor tweak for clarity and minimalism:

Suggested change

In {{es}} 8.0 and later versions, feature states are the only way to back up and restore system indices and system data streams. Attempting to restore a system index or data stream outside its feature state will be blocked by an error. For example index `.example` this error would appear like

Starting with {{es}} 8.0 and later versions, feature states are the only way to back up and restore system indices and system data streams. Attempting to restore a system index or data stream outside its feature state is not permitted and will result in the following error:

yetanothertw · 2025-11-10T11:32:54Z

deploy-manage/tools/snapshot-and-restore.md

+requested system indices [.example], but system indices can only be restored as part of a feature state
+```
+
+Restoring system indices and data streams will require temporary elevated permissions to edit restricted indices. For more information see [File-based access recovery](/troubleshoot/elasticsearch/file-based-recovery.md). Attempting to restore a system index or data stream without these temporary elevated permissions will be blocked by an error. For example index `.example` this error would appear like


Suggested change

Restoring system indices and data streams will require temporary elevated permissions to edit restricted indices. For more information see [File-based access recovery](/troubleshoot/elasticsearch/file-based-recovery.md). Attempting to restore a system index or data stream without these temporary elevated permissions will be blocked by an error. For example index `.example` this error would appear like

Restoring system indices and data streams will require temporary elevated permissions to edit restricted indices. For more information, refer to [File-based access recovery](/troubleshoot/elasticsearch/file-based-recovery.md). Attempting to restore a system index or data stream without the required temporary elevated permissions will result in the following error:

yetanothertw · 2025-11-10T11:37:32Z

troubleshoot/elasticsearch/file-based-recovery.md

 ```

-Now that you have regained recovery access to the cluster, you can investigate and recover the {{stack}} {{security-features}} as needed.
+Now that you have regained recovery access to the cluster, you can investigate and recover the {{stack}} {{security-features}} as needed. For more information, see [Restore a feature state](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md#restore-feature-state).


Suggested change

Now that you have regained recovery access to the cluster, you can investigate and recover the {{stack}} {{security-features}} as needed. For more information, see [Restore a feature state](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md#restore-feature-state).

Now that you have regained recovery access to the cluster, you can investigate and recover the {{stack}} {{security-features}} as needed. For more information, refer to [Restore a feature state](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md#restore-feature-state).

This is a tiny style guide-related nitpick. Using refer to instead of see is preferred as a more actionable alternative. I'm relatively newish to the docs team myself, so sharing my learnings as I go 😅

yetanothertw · 2025-11-10T11:44:58Z

deploy-manage/tools/snapshot-and-restore/restore-snapshot.md

 If you restore a snapshot’s cluster state, the operation restores all feature states in the snapshot by default. Similarly, if you don’t restore a snapshot’s cluster state, the operation doesn’t restore any feature states by default. You can also choose to restore only specific feature states from a snapshot, regardless of the cluster state.

-To view a snapshot’s feature states, use the get snapshot API.
+Feature backing indices are version dependent. To see which indices are included within a snapshot's feature state, [list an applicable snapshot](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-get). For example on {{ech}} you might poll its latest snapshot on its built-in SLM policy `cloud-snapshot-policy`.


Suggested change

Feature backing indices are version dependent. To see which indices are included within a snapshot's feature state, [list an applicable snapshot](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-get). For example on {{ech}} you might poll its latest snapshot on its built-in SLM policy `cloud-snapshot-policy`.

Feature backing indices are version dependent. To see which indices are included within a snapshot's feature state, [list an applicable snapshot](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-get). For example, on {{ech}} you might poll its latest snapshot on its built-in `cloud-snapshot-policy` SLM policy:

yetanothertw · 2025-11-10T11:48:20Z

deploy-manage/tools/snapshot-and-restore/restore-snapshot.md

 ```

-The response’s `feature_states` property contains a list of features in the snapshot as well as each feature’s indices.
+The response’s `feature_states` property contains a list of features in the snapshot as well as each feature’s indices. For an example cluster, its output might appear:


Suggested change

The response’s `feature_states` property contains a list of features in the snapshot as well as each feature’s indices. For an example cluster, its output might appear:

The response’s `feature_states` property contains a list of features in the snapshot as well as each feature’s indices. The following is an example of the output that might display for a cluster:

yetanothertw · 2025-11-10T11:55:31Z

deploy-manage/tools/snapshot-and-restore/restore-snapshot.md

-::::
+To restore a specific feature state from the snapshot, specify the `feature_name` from the response in the [restore snapshot API’s](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-restore) `feature_states` parameter.

+Feature state names may line-up to {{kib}} UI sections while not being encompassing to completely reset that UI. For example, the {{fleet}} UI backs against the `fleet` feature state as well as `kibana` and `security`. It is important to ensure you line up desired reset behavior with which backing feature states to include in the `feature_states` parameter when restoring.


Suggested change

Feature state names may line-up to {{kib}} UI sections while not being encompassing to completely reset that UI. For example, the {{fleet}} UI backs against the `fleet` feature state as well as `kibana` and `security`. It is important to ensure you line up desired reset behavior with which backing feature states to include in the `feature_states` parameter when restoring.

Note that feature state names may match {{kib}} UI sections, but restoring a single feature state may not fully reset that UI. For example, the {{fleet}} UI depends on the `fleet` feature state as well as `kibana` and `security`. When restoring, it's important to include all required feature states in the `feature_states` parameter to achieve the desired reset behavior.

yetanothertw · 2025-11-10T11:59:32Z

deploy-manage/tools/snapshot-and-restore/restore-snapshot.md

+Restoring the `security` feature state overwrites system indices used for authentication. If you use {{ech}} or {{ece}}, ensure you have access to the [{{es}} API console](cloud://reference/cloud-hosted/ec-api-console.md) before restoring the `security` feature state. If you run {{es}} on your own hardware or in {{eck}}, [create a temporary user with elevated permissions to edit restricted indices in the file realm](/troubleshoot/elasticsearch/file-based-recovery.md) to ensure you’ll still be able to access your cluster.
 ::::

+When you restore a feature state, {{es}} closes and overwrites the feature’s existing indices and data streams. Therefore to [snapshot restore](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-restore) the `geoip` feature state for example will appear like:


Suggested change

When you restore a feature state, {{es}} closes and overwrites the feature’s existing indices and data streams. Therefore to [snapshot restore](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-restore) the `geoip` feature state for example will appear like:

When you restore a feature state, {{es}} closes and overwrites the feature’s existing indices and data streams. For example, to [snapshot restore](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-restore) the `geoip` feature state, you might use:

Restore feature states requires restricted permissions

4f4485a

stefnestor requested a review from a team as a code owner November 7, 2025 22:14

stefnestor mentioned this pull request Nov 7, 2025

Document restore feature states dependencies #2094

Open

github-actions bot had a problem deploying to docs-preview November 7, 2025 22:15 Failure

Merge branch 'main' into stef_crossLinkSystemIndexRestore

ba1da0c

github-actions bot had a problem deploying to docs-preview November 10, 2025 10:59 Failure

yetanothertw reviewed Nov 10, 2025

View reviewed changes

deploy-manage/tools/snapshot-and-restore/restore-snapshot.md Outdated Show resolved Hide resolved

Apply suggestion from @yetanothertw

5409216

Link fix

github-actions bot deployed to docs-preview November 10, 2025 11:20 View deployment

yetanothertw approved these changes Nov 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Restore feature states requires restricted permissions #3857

Restore feature states requires restricted permissions #3857

stefnestor commented Nov 7, 2025

Uh oh!

stefnestor commented Nov 7, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 10, 2025

Uh oh!

yetanothertw left a comment

Uh oh!

yetanothertw Nov 10, 2025

Uh oh!

yetanothertw Nov 10, 2025

Uh oh!

yetanothertw Nov 10, 2025

Uh oh!

yetanothertw Nov 10, 2025

Uh oh!

yetanothertw Nov 10, 2025

Uh oh!

yetanothertw Nov 10, 2025

Uh oh!

yetanothertw Nov 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	In {{es}} 8.0 and later versions, feature states are the only way to back up and restore system indices and system data streams. Attempting to restore a system index or data stream outside its feature state will be blocked by an error. For example index `.example` this error would appear like
	Starting with {{es}} 8.0 and later versions, feature states are the only way to back up and restore system indices and system data streams. Attempting to restore a system index or data stream outside its feature state is not permitted and will result in the following error:

	Now that you have regained recovery access to the cluster, you can investigate and recover the {{stack}} {{security-features}} as needed. For more information, see [Restore a feature state](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md#restore-feature-state).
	Now that you have regained recovery access to the cluster, you can investigate and recover the {{stack}} {{security-features}} as needed. For more information, refer to [Restore a feature state](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md#restore-feature-state).

	Feature backing indices are version dependent. To see which indices are included within a snapshot's feature state, [list an applicable snapshot](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-get). For example on {{ech}} you might poll its latest snapshot on its built-in SLM policy `cloud-snapshot-policy`.
	Feature backing indices are version dependent. To see which indices are included within a snapshot's feature state, [list an applicable snapshot](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-get). For example, on {{ech}} you might poll its latest snapshot on its built-in `cloud-snapshot-policy` SLM policy:

	The response’s `feature_states` property contains a list of features in the snapshot as well as each feature’s indices. For an example cluster, its output might appear:
	The response’s `feature_states` property contains a list of features in the snapshot as well as each feature’s indices. The following is an example of the output that might display for a cluster:

	Feature state names may line-up to {{kib}} UI sections while not being encompassing to completely reset that UI. For example, the {{fleet}} UI backs against the `fleet` feature state as well as `kibana` and `security`. It is important to ensure you line up desired reset behavior with which backing feature states to include in the `feature_states` parameter when restoring.
	Note that feature state names may match {{kib}} UI sections, but restoring a single feature state may not fully reset that UI. For example, the {{fleet}} UI depends on the `fleet` feature state as well as `kibana` and `security`. When restoring, it's important to include all required feature states in the `feature_states` parameter to achieve the desired reset behavior.

	When you restore a feature state, {{es}} closes and overwrites the feature’s existing indices and data streams. Therefore to [snapshot restore](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-restore) the `geoip` feature state for example will appear like:
	When you restore a feature state, {{es}} closes and overwrites the feature’s existing indices and data streams. For example, to [snapshot restore](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-restore) the `geoip` feature state, you might use:

Restore feature states requires restricted permissions #3857

Are you sure you want to change the base?

Restore feature states requires restricted permissions #3857

Conversation

stefnestor commented Nov 7, 2025

Uh oh!

stefnestor commented Nov 7, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 10, 2025

🔍 Preview links for changed docs

Uh oh!

yetanothertw left a comment

Choose a reason for hiding this comment

Uh oh!

yetanothertw Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

yetanothertw Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

yetanothertw Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

yetanothertw Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

yetanothertw Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

yetanothertw Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

yetanothertw Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants