[role="xpack"] [testenv="basic"] [[migration-api-deprecation]] === Deprecation info APIs ++++ <titleabbrev>Deprecation info</titleabbrev> ++++ 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. [float] ==== Request `GET /_migration/deprecations` + `GET /<index_name>/_migration/deprecations` //=== Description [float] ==== Path Parameters `index_name`:: (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. //=== Query Parameters //=== Authorization [float] ==== Examples To see the list of offenders in your cluster, submit a GET request to the `_migration/deprecations` endpoint: [source,js] -------------------------------------------------- GET /_migration/deprecations -------------------------------------------------- // CONSOLE // 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,js] -------------------------------------------------- GET /logstash-*/_migration/deprecations -------------------------------------------------- // CONSOLE // TEST[skip:cannot assert tests have certain deprecations]