Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds a warning about manually mounting snapshots managed by ILM #111883

Merged
merged 2 commits into from
Aug 15, 2024
Merged

Adds a warning about manually mounting snapshots managed by ILM #111883

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b2f0bf6
Adds a warning about manually mounting snapshots managed by ILM
kosabogi Aug 14, 2024
d752f9e
Shortens text and moves the warning to Searchable snapshots chapter
kosabogi Aug 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/reference/searchable-snapshots/apis/mount-snapshot.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ For more information, see <<security-privileges>>.
[[searchable-snapshots-api-mount-desc]]
==== {api-description-title}

This API mounts a snapshot as a searchable snapshot index.
Note that manually mounting {ilm-init}-managed snapshots can <<manually-mounting-snapshots,interfere>> with <<index-lifecycle-management,{ilm-init} processes>>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd drop this in as a separate paragraph so it's more visible. Also, avoid "note that" - either it should be a callout, or it's just a sentence. technically all documentation is just noting things.

I think that because this can cause problems, and we want to discourage people from using this API in the context of ILM-managed snapshots, I'd say that a little more clearly as well.

Suggested change
Note that manually mounting {ilm-init}-managed snapshots can <<manually-mounting-snapshots,interfere>> with <<index-lifecycle-management,{ilm-init} processes>>.
Don't use this API for snapshots managed by {ilm-init}. Manually mounting {ilm-init}-managed snapshots can <<manually-mounting-snapshots,interfere>> with <<index-lifecycle-management,{ilm-init} processes>>.


[[searchable-snapshots-api-mount-path-params]]
==== {api-path-parms-title}
Expand Down
11 changes: 11 additions & 0 deletions docs/reference/searchable-snapshots/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,17 @@ do not have a dedicated frozen tier, you must configure the
cache on one or more nodes. Partially mounted indices are only allocated to
nodes that have a shared cache.

[[manually-mounting-snapshots]]
[WARNING]
.Manual snapshot mounting
====
Manually mounting snapshots captured by an Index Lifecycle Management ({ilm-init}) policy can
interfere with {ilm-init}'s automatic management. This may lead to issues such as data loss
or complications with snapshot handling. For optimal results, allow {ilm-init} to manage
snapshots automatically. If manual mounting is necessary, be aware of its potential
impact on {ilm-init} processes. For more information, learn about <<index-lifecycle-management,{ilm-init} snapshot management>>.
====
Comment on lines +176 to +182
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider breaking this into a couple of paragraphs. I'm also unclear on whether the complications you mentioned in your last draft ("can disrupt ILM actions, like deletions or phase transitions") is totally covered by this statement.

I'd avoid restating the problem, as you do in the "if you need to mount manually" sentence. it seems to imply that there are impacts not listed here. if it is meant to imply that, we should probably list the additional impacts as I don't think they're captured elsewhere.

finally, I don't think your link is ideal - there's no snapshot info on that top level ILM page. Consider a different link, or changing your link text to refer to just ILM.

Suggested change
====
Manually mounting snapshots captured by an Index Lifecycle Management ({ilm-init}) policy can
interfere with {ilm-init}'s automatic management. This may lead to issues such as data loss
or complications with snapshot handling. For optimal results, allow {ilm-init} to manage
snapshots automatically. If manual mounting is necessary, be aware of its potential
impact on {ilm-init} processes. For more information, learn about <<index-lifecycle-management,{ilm-init} snapshot management>>.
====
====
Manually mounting snapshots captured by an Index Lifecycle Management ({ilm-init}) policy can
interfere with {ilm-init}'s automatic snapshot management. This may lead to issues such as data loss
or complications with snapshot handling.
For optimal results, allow {ilm-init} to manage
snapshots automatically.
<<index-lifecycle-management,Learn more about {ilm-init} snapshot management>>.
====


[[searchable-snapshots-shared-cache]]
`xpack.searchable.snapshot.shared_cache.size`::
(<<static-cluster-setting,Static>>)
Expand Down