122 lines
4.3 KiB
Plaintext
122 lines
4.3 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[migration-api-deprecation]]
|
|
=== Deprecation info APIs
|
|
++++
|
|
<titleabbrev>Deprecation info</titleabbrev>
|
|
++++
|
|
|
|
IMPORTANT: Use this API to check for deprecated configuration before performing
|
|
a major version upgrade. You should run it on the the last minor version of the
|
|
major version you are upgrading from, as earlier minor versions may not include
|
|
all deprecations.
|
|
|
|
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 the next major version.
|
|
|
|
[[migration-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_migration/deprecations` +
|
|
|
|
`GET /<index_name>/_migration/deprecations`
|
|
|
|
[[migration-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`index_name`::
|
|
(Optional, string) Identifier for the index. It can be an index name or a
|
|
wildcard expression. When you specify this parameter, only index-level
|
|
deprecations for the specified indices are returned.
|
|
|
|
[[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}/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}/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 the next major 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. 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]
|