mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
33a71e3289
* Remove `es-test-dir` book-scoped variable * Remove `plugins-examples-dir` book-scoped variable * Remove `:dependencies-dir:` and `:xes-repo-dir:` book-scoped variables - In `index.asciidoc`, two variables (`:dependencies-dir:` and `:xes-repo-dir:`) were removed. - In `sql/index.asciidoc`, the `:sql-tests:` path was updated to fuller path - In `esql/index.asciidoc`, the `:esql-tests:` path was updated idem * Replace `es-repo-dir` with `es-ref-dir` * Move `:include-xpack: true` to few files that use it, remove from index.asciidoc
143 lines
5 KiB
Text
143 lines
5 KiB
Text
[role="xpack"]
|
|
[[migration-api-deprecation]]
|
|
=== Deprecation info APIs
|
|
++++
|
|
<titleabbrev>Deprecation info</titleabbrev>
|
|
++++
|
|
|
|
include::{es-ref-dir}/migration/apis/shared-migration-apis-tip.asciidoc[]
|
|
|
|
The deprecation API is to be used to retrieve information about different
|
|
cluster, node, and index level settings that use deprecated features that will
|
|
be removed or changed in a future version.
|
|
|
|
[[migration-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_migration/deprecations` +
|
|
|
|
`GET /<target>/_migration/deprecations`
|
|
|
|
[[migration-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `manage`
|
|
<<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
[[migration-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<target>`::
|
|
(Optional, string)
|
|
Comma-separate list of data streams or indices to check. Wildcard (`*`)
|
|
expressions are supported.
|
|
+
|
|
When you specify this parameter, only deprecations for the specified
|
|
data streams or indices are returned.
|
|
|
|
[[migration-api-settings]]
|
|
==== Settings
|
|
|
|
You can use the following settings to control the behavior of the deprecation info API:
|
|
|
|
[[skip_deprecated_settings]]
|
|
NOTE: This setting is designed for indirect use by {ess-trial}[{ess}], {ece-ref}[{ece}], and {eck-ref}[{eck}].
|
|
Direct use is not supported.
|
|
|
|
// tag::skip_deprecated_settings-tag[]
|
|
`deprecation.skip_deprecated_settings`
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
|
Defaults to an empty list. Set to a list of setting names to be ignored by the deprecation info API. Any
|
|
deprecations related to settings in this list will not be returned by the API. Simple wildcard matching is supported.
|
|
// end::skip_deprecated_settings-tag[]
|
|
|
|
[[migration-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
To see the list of offenders in your cluster, submit a GET request to the
|
|
`_migration/deprecations` endpoint:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_migration/deprecations
|
|
--------------------------------------------------
|
|
// TEST[skip:cannot assert tests have certain deprecations]
|
|
|
|
Example response:
|
|
|
|
|
|
["source","js",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
{
|
|
"cluster_settings" : [
|
|
{
|
|
"level" : "critical",
|
|
"message" : "Cluster name cannot contain ':'",
|
|
"url" : "{ref-70}/breaking-changes-7.0.html#_literal_literal_is_no_longer_allowed_in_cluster_name",
|
|
"details" : "This cluster is named [mycompany:logging], which contains the illegal character ':'."
|
|
}
|
|
],
|
|
"node_settings" : [ ],
|
|
"index_settings" : {
|
|
"logs:apache" : [
|
|
{
|
|
"level" : "warning",
|
|
"message" : "Index name cannot contain ':'",
|
|
"url" : "{ref-70}/breaking-changes-7.0.html#_literal_literal_is_no_longer_allowed_in_index_name",
|
|
"details" : "This index is named [logs:apache], which contains the illegal character ':'."
|
|
}
|
|
]
|
|
},
|
|
"ml_settings" : [ ]
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
The response breaks down all the specific forward-incompatible settings that you
|
|
should resolve before upgrading your cluster. Any offending settings are
|
|
represented as a deprecation warning.
|
|
|
|
The following is an example deprecation warning:
|
|
|
|
["source","js",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
{
|
|
"level" : "warning",
|
|
"message" : "This is the generic descriptive message of the breaking change",
|
|
"url" : "{ref-60}/breaking_60_indices_changes.html",
|
|
"details" : "more information, like which nodes, indices, or settings are to blame"
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
As is shown, there is a `level` property that describes the significance of the
|
|
issue.
|
|
|
|
|=======
|
|
|warning | You can upgrade directly, but you are using deprecated functionality
|
|
which will not be available or behave differently in a future version.
|
|
|critical | You cannot upgrade without fixing this problem.
|
|
|=======
|
|
|
|
The `message` property and the optional `details` property provide descriptive
|
|
information about the deprecation warning. The `url` property provides a link to
|
|
the Breaking Changes Documentation, where you can find more information about
|
|
this change.
|
|
|
|
Any cluster-level deprecation warnings can be found under the `cluster_settings`
|
|
key. Similarly, any node-level warnings are found under `node_settings`. Since
|
|
only a select subset of your nodes might incorporate these settings, it is
|
|
important to read the `details` section for more information about which nodes
|
|
are affected. Index warnings are sectioned off per index and can be filtered
|
|
using an index-pattern in the query. This section includes warnings for the
|
|
backing indices of data streams specified in the request path. Machine Learning
|
|
related deprecation warnings can be found under the `ml_settings` key.
|
|
|
|
The following example request shows only index-level deprecations of all
|
|
`logstash-*` indices:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /logstash-*/_migration/deprecations
|
|
--------------------------------------------------
|
|
// TEST[skip:cannot assert tests have certain deprecations]
|