Adds a warning about manually mounting snapshots managed by ILM #111883
Conversation
|
Documentation preview: |
elasticsearchmachine
added
v8.16.0
needs:triage
gbanasiak
added
the
:Data Management/ILM+SLM
elasticsearchmachine
added
the
Team:Data Management
|
Pinging @elastic/es-data-management (Team:Data Management) |
elasticsearchmachine
removed
the
needs:triage
There was a problem hiding this comment.
I'd rather we didn't add warnings like this to the top of a page. They tend to accumulate, and it makes the docs very hostile to users who are looking for information about how to use the system rather than how not to do so.
Would it make sense to add this information to the other warnings on the page about searchable snapshots: https://www.elastic.co/guide/en/elasticsearch/reference/current/searchable-snapshots.html#searchable-snapshots-reliability
|
Pinging @elastic/es-docs (Team:Docs) |
| WARNING: Manual Snapshot Mounting | ||
| ==== | ||
| When manually mounting a snapshot that was captured by an Index Lifecycle Management (ILM) policy, be aware of the following: |
There was a problem hiding this comment.
I don't think you can set the title this way. it ends up just putting this sentence in the note block:
I think what you want is this
| WARNING: Manual Snapshot Mounting | |
| ==== | |
| When manually mounting a snapshot that was captured by an Index Lifecycle Management (ILM) policy, be aware of the following: | |
| [WARNING] | |
| ==== | |
| **Manual snapshot mounting** |
| * **ILM Managed Snapshots:** Snapshots taken by ILM policies are handled automatically by ILM. If you manually mount these snapshots, it can interfere with ILM's automated processes, such as managing or deleting snapshots. | ||
|
|
||
| * **Potential Issues:** Manually mounting a snapshot can disrupt ILM actions, like deletions or phase transitions. This can lead to data loss or complications in managing your snapshots. | ||
|
|
||
| * **Best Practice:** It's best to let ILM manage your snapshots. If you must manually mount a snapshot, make sure you understand how this affects ILM and manage the snapshot lifecycle separately. | ||
|
|
||
| Always review the documentation and consider the impact on your data management before manually handling snapshots managed by ILM. |
There was a problem hiding this comment.
I'd like to see this formatted as prose rather than broken down like this. there also seems to be overlap between all of the paragraph content so you could slim this down. it will have an added benefit of making the warning much less scary looking.
consider also shrinking this to "don't use this for snapshots taken by ILM policies. [Learn more]" and linking out to the docs around how ILM snapshots are managed (and maybe adding these considerations there).
finally, we prefer sentence case headings over title case headings. see style guide :)
There was a problem hiding this comment.
Thank you for the feedback!
I’ve shortened the warning to make it clearer and fixed the formatting issues. I encountered some difficulties with the local build but have resolved those issues now thanks to @szabosteve :)
Based on Dave's feedback, I’ve moved the warning to the section about Searchable Snapshots, where it complements the existing information. In the Mount API description, I’ve added a brief note that links to the warning for further details.
|
@DaveCTurner Thank you for the feedback! I’ve moved the warning to the section about Searchable Snapshots, where it complements the existing information. In the Mount API description, I’ve added a brief note that links to the warning for further details. |
| @@ -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>>. | |||
There was a problem hiding this comment.
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.
| 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>>. |
| ==== | ||
| 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>>. | ||
| ==== |
There was a problem hiding this comment.
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.
| ==== | |
| 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>>. | |
| ==== |
* upstream/main: (91 commits) Mute org.elasticsearch.xpack.test.rest.XPackRestIT org.elasticsearch.xpack.test.rest.XPackRestIT elastic#111944 Add audit_unenrolled_* attributes to fleet-agents template (elastic#111909) Fix windows memory locking (elastic#111866) Update OAuth2 OIDC SDK (elastic#108799) Adds a warning about manually mounting snapshots managed by ILM (elastic#111883) Update geoip fixture files and utility methods (elastic#111913) Updated Function Score Query Test with Explain Fixes for 8.15.1 (elastic#111929) Mute org.elasticsearch.xpack.sql.qa.security.JdbcCsvSpecIT org.elasticsearch.xpack.sql.qa.security.JdbcCsvSpecIT elastic#111923 [ESQL] date nanos binary comparisons (elastic#111908) [DOCS] Documents output_field behavior after multiple inference runs (elastic#111875) Add additional BlobCacheMetrics, expose BlobCacheMetrics via SharedBlobCacheService (elastic#111730) Mute org.elasticsearch.xpack.sql.qa.multi_cluster_with_security.JdbcCsvSpecIT org.elasticsearch.xpack.sql.qa.multi_cluster_with_security.JdbcCsvSpecIT elastic#111923 Mute org.elasticsearch.xpack.sql.qa.multi_cluster_with_security.JdbcCsvSpecIT test {agg-ordering.testHistogramDateTimeWithCountAndOrder_2} elastic#111919 Mute org.elasticsearch.xpack.sql.qa.multi_cluster_with_security.JdbcCsvSpecIT test {date.testDateParseHaving} elastic#111921 Mute org.elasticsearch.xpack.sql.qa.multi_cluster_with_security.JdbcCsvSpecIT test {agg-ordering.testHistogramDateTimeWithCountAndOrder_1} elastic#111918 Mute org.elasticsearch.xpack.sql.qa.multi_cluster_with_security.JdbcCsvSpecIT test {datetime.testDateTimeParseHaving} elastic#111922 Mute org.elasticsearch.xpack.sql.qa.single_node.JdbcCsvSpecIT org.elasticsearch.xpack.sql.qa.single_node.JdbcCsvSpecIT elastic#111923 Mute org.elasticsearch.xpack.sql.qa.single_node.JdbcCsvSpecIT test {agg-ordering.testHistogramDateTimeWithCountAndOrder_1} elastic#111918 Mute org.elasticsearch.xpack.sql.qa.single_node.JdbcCsvSpecIT test {datetime.testDateTimeParseHaving} elastic#111922 Mute org.elasticsearch.xpack.sql.qa.single_node.JdbcCsvSpecIT test {date.testDateParseHaving} elastic#111921 ... # Conflicts: # server/src/main/java/org/elasticsearch/TransportVersions.java
…tic#111883) * Adds a warning about manually mounting snapshots managed by ILM * Shortens text and moves the warning to Searchable snapshots chapter
…tic#111883) * Adds a warning about manually mounting snapshots managed by ILM * Shortens text and moves the warning to Searchable snapshots chapter
Overview
This PR introduces a warning to the documentation for the Mount Snapshot API.
Related issue: #105816
Preview
Searchable snapshots
Mount snapshot API