OpenSearch/docs/reference/migration/migrate_7_8.asciidoc

[[breaking-changes-7.8]]
== Breaking changes in 7.8
++++
<titleabbrev>7.8</titleabbrev>
++++

This section discusses the changes that you need to be aware of when migrating
your application to {es} 7.8.

See also <<release-highlights>> and <<es-release-notes>>.

coming[7.8.0]

* <<breaking_78_mappings_changes>>
* <<breaking_78_settings_changes>>

//NOTE: The notable-breaking-changes tagged regions are re-used in the
//Installation and Upgrade Guide

//tag::notable-breaking-changes[]

[discrete]
[[breaking_78_mappings_changes]]
=== Mappings changes

[[prevent-enabled-setting-change]]
.The `enabled` mapping parameter cannot be changed for a root mapping.
[%collapsible]
====
*Details* +
Mapping requests that attempt to change the {ref}/enabled.html[`enabled`]
mapping parameter for a root mapping will fail and return an error.

Previously, {es} accepted mapping requests that attempted to change the
`enabled` parameter of the root mapping. Theses changes were not applied, but
such requests didn't return an error.

*Impact* +
To avoid errors, do not submit mapping requests that change the
{ref}/enabled.html[`enabled`] mapping parameter.
====

[[prevent-include-in-root-change]]
.The `include_in_parent` and `include_in_root` mapping parameters cannot be changed for `nested` fields.
[%collapsible]
====
*Details* +
Mapping requests that attempt to change the
{ref}/nested.html#nested-include-in-parent-parm[`include_in_parent`] or
{ref}/nested.html#nested-include-in-root-parm[`include_in_root`] mapping
parameter for a `nested` field will fail and return an error.

Previously, {es} accepted mapping requests that attempted to change the
`include_in_parent` or `include_in_root` parameter. Theses changes were not
applied, but such requests didn't return an error.

*Impact* +
To avoid errors, do not submit mapping requests that change the
{ref}/nested.html#nested-include-in-parent-parm[`include_in_parent`] or
{ref}/nested.html#nested-include-in-root-parm[`include_in_root`] mapping
parameter.
====

.The get field mapping API's `local` query parameter is deprecated.
[%collapsible]
====
*Details* +
The {ref}/indices-get-field-mapping.html[get field mapping API]'s `local` query
parameter is deprecated and will be removed in {es} 8.0.0.

The `local` parameter is a no-op. The API always retrieves field mappings
locally.

*Impact* +
To avoid deprecation warnings, discontinue use of the `local` parameter.
====

[discrete]
[[breaking_78_settings_changes]]
=== Settings changes

[[deprecate-node-local-storage]]
.The `node.local_storage` setting is deprecated.
[%collapsible]
====
*Details* +
The `node.local_storage` setting is deprecated. In {es} 8.0.0, all nodes require
local storage.

*Impact* +
To avoid deprecation warnings, discontinue use of the `node.local_storage`
setting.
====

[[deprecate-basic-license-feature-enabled]]

.Several {xpack} settings no longer have any effect and are deprecated.

[%collapsible]
====
*Details* +
Basic {xpack} license features are always enabled for the {default-dist}
and the following settings no longer have any effect:

* `xpack.enrich.enabled`
* `xpack.flattened.enabled`
* `xpack.monitoring.enabled`
* `xpack.rollup.enabled`
* `xpack.sql.enabled`
* `xpack.transform.enabled`
* `xpack.vectors.enabled`

Previously, they could be set to `false` to disable the feature's APIs in a cluster.

The ILM and SLM settings have been deprecated, but still have the effect of disabling
their respective APIs:

* `xpack.ilm.enabled`
* `xpack.slm.enabled`

*Impact* +
To avoid deprecation warnings, discontinue use of these settings.
If you have disabled ILM so that you can use another tool to manage Watcher
indices, the newly introduced `xpack.watcher.use_ilm_index_management` setting
may be set to false.
====

[discrete]
[[builtin-users-changes]]
==== Changes to built-in users

.The `kibana` user has been deprecated in favor of the `kibana_system` user.
[%collapsible]
====
*Details* +
The `kibana` user was historically used to authenticate {kib} to {es}.
The name of this user was confusing, and was often mistakenly used to login to {kib}.
This has been renamed to `kibana_system` in order to reduce confusion, and to better
align with other built-in system accounts.

*Impact* +
If your `kibana.yml` used to contain:
[source,yaml]
--------------------------------------------------
elasticsearch.username: kibana
--------------------------------------------------

then you should update to use the new `kibana_system` user instead:
[source,yaml]
--------------------------------------------------
elasticsearch.username: kibana_system
--------------------------------------------------
====


[discrete]
[[builtin-roles-changes]]
==== Changes to built-in roles

.The `kibana_user` role has been deprecated in favor of the `kibana_admin` role.
[%collapsible]
====
*Details* +
Users who were previously assigned the `kibana_user` role should instead be assigned
the `kibana_admin` role. This role grants the same set of privileges as `kibana_user`, but has been
renamed to better reflect its intended use.

*Impact* +
Assign users with the `kibana_user` role to the `kibana_admin` role.
Discontinue use of the `kibana_user` role.
====

//end::notable-breaking-changes[]