[[migrating-7.13]]
== Migrating to 7.13
++++
<titleabbrev>7.13</titleabbrev>
++++

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

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

// * <<breaking_713_blah_changes>>
// * <<breaking_713_blah_changes>>

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

[discrete]
[[breaking-changes-7.13]]
=== Breaking changes

The following changes in {es} 7.13 might affect your applications
and prevent them from operating normally.
Before upgrading to 7.13, review these changes and take the described steps
to mitigate the impact.

NOTE: Breaking changes introduced in minor versions are
normally limited to security and bug fixes.
Significant changes in behavior are deprecated in a minor release and
the old behavior is supported until the next major release.
To find out if you are using any deprecated functionality,
enable <<deprecation-logging, deprecation logging>>.

// tag::notable-breaking-changes[]
[discrete]
[[breaking_713_mapping_changes]]
==== Mapping changes

[[geo-mappers-external-values]]
.Geo mappers no longer accept external values from multifields.
[%collapsible]
====
*Details* +
In earlier versions, geo fields could theoretically be used as a subfield
if their parent field set a geometry object as an external value during
parsing. This functionality was unused within the {es} codebase and
blocked required changes to allow index-time scripts on `geo_point` fields,
so it has been removed.
====

[[geo-point-geohash-subfields]]
.Geopoint mappers pass geohashes to subfields one-by-one.
[%collapsible]
====
*Details* +
In earlier versions, a multiply-valued geopoint field would pass
its values as geohashes to subfields by combining them in to a single
comma-delimited string. These are now passed one-by-one as single
geohash strings.
====

[discrete]
[[breaking_713_ssl_changes]]
==== SSL/TLS changes

[[breaking_713_bundled_jdk_tls_versions]]
.TLSv1.1 and TLSv1.0 are disabled in the bundled JDK
[%collapsible]
====
*Details* +
When using the bundled JDK, TLSv1.1 and TLSv1.0 are disabled by default.
This may affect SSL connections to the Rest API for some older clients.
It also has the potential to affect outgoing connections such as {watcher} webhooks,
LDAP authentication or access to snapshot repositories.

Most {es} deployments will not be affected by this change, as these older
TLS versions have known vulnerabilities and are no longer heavily used.

For instructions on how to enable these older TLS versions in your {es} cluster, see
{ref}/jdk-tls-versions.html#jdk-enable-tls-protocol[Enabling additional SSL/TLS versions on your JDK]

====

[discrete]
[[breaking_713_settings_changes]]
==== Settings changes

[[breaking_713_frozen_multiple_data_paths_changes]]
.Changes to the frozen tier and multiple data paths
[%collapsible]
====
*Details* +
{es} 7.12 included a technical preview of the frozen tier, being able to use
partially mounted indices (searchable snapshots mounted with the shared cache
option). Trying out this feature required configuring a shared cache using the
`xpack.searchable.snapshot.shared_cache.size` setting.

In {es} 7.13+, having a non-zero `xpack.searchable.snapshot.shared_cache.size`
on nodes utilizing multiple data paths (`path.data` points to multiple
locations) is no longer supported and will prevent the node from starting. If
you do not utilize multiple data paths this will not affect you. Likewise, if
you have not set `xpack.searchable.snapshot.shared_cache.size` and have not
configured dedicated frozen nodes (nodes with the `data_frozen` role and no
other data roles) this will not affect you.
====
// end::notable-breaking-changes[]

[discrete]
[[deprecated-7.13]]
=== Deprecations

The following functionality has been deprecated in {es} 7.13
and will be removed in 8.0.
While this won't have an immediate impact on your applications,
we strongly encourage you take the described steps to update your code
after upgrading to 7.13.

NOTE: Significant changes in behavior are deprecated in a minor release and
the old behavior is supported until the next major release.
To find out if you are using any deprecated functionality,
enable <<deprecation-logging, deprecation logging>>.

// tag::notable-breaking-changes[]
[discrete]
[[breaking_713_agg_deprecations]]
==== Aggregation deprecations

[discrete]
[[breaking_713_boolean-field-support-deprecated-date-aggs]]
.Date aggregations on `boolean` fields are deprecated.
[%collapsible]
====
*Details* +
Support for auto-interval date histogram, date histogram, and date range
aggregations on `boolean` fields is now deprecated. On `boolean` fields, these
aggregations are rarely useful and often unintended.
====

[discrete]
[[breaking_713_infra_core_deprecations]]
==== Core deprecations

[[multiple-data-path-support-deprecated]]
.Multiple data path support is deprecated.
[%collapsible]
====
*Details* +
The `path.data` setting accepts a list of data paths, but if you specify
multiple paths then the behaviour is unintuitive and usually does not give the
desired outcomes. Support for multiple data paths is now deprecated and will be
removed in 8.0.0.

*Impact* +
Specify a single path in `path.data`. If needed, you can create a filesystem
which spans multiple disks with a hardware virtualisation layer such as RAID,
or a software virtualisation layer such as Logical Volume Manager (LVM) on
Linux or Storage Spaces on Windows. If you wish to use multiple data paths on a
single machine then you must run one node for each data path.

If you currently use multiple data paths in a
{ref}/high-availability-cluster-design.html[highly available cluster] then you 
can migrate to a setup that uses a single path for each node without downtime 
using a process similar to a 
{ref}/restart-cluster.html#restart-cluster-rolling[rolling restart]: shut each
node down in turn and replace it with one or more nodes each configured to use
a single data path. In more detail, for each node that currently has multiple
data paths you should follow the following process.

1. Take a snapshot to protect your data in case of disaster.

2. Optionally, migrate the data away from the target node by using an
{ref}/modules-cluster.html#cluster-shard-allocation-filtering[allocation filter]:
+
[source,console]
--------------------------------------------------
PUT _cluster/settings
{
  "transient": {
    "cluster.routing.allocation.exclude._name": "target-node-name"
  }
}
--------------------------------------------------
+
You can use the {ref}/cat-allocation.html[cat allocation API] to track progress 
of this data migration. If some shards do not migrate then the
{ref}/cluster-allocation-explain.html[cluster allocation explain API] will help 
you to determine why.

3. Follow the steps in the 
{ref}/restart-cluster.html#restart-cluster-rolling[rolling restart process]
up to and including shutting the target node down.

4. Ensure your cluster health is `yellow` or `green`, so that there is a copy
of every shard assigned to at least one of the other nodes in your cluster.

5. If applicable, remove the allocation filter applied in the earlier step.
+
[source,console]
--------------------------------------------------
PUT _cluster/settings
{
  "transient": {
    "cluster.routing.allocation.exclude._name": null
  }
}
--------------------------------------------------

6. Discard the data held by the stopped node by deleting the contents of its
data paths.

7. Reconfigure your storage. For instance, combine your disks into a single
filesystem using LVM or Storage Spaces. Ensure that your reconfigured storage
has sufficient space for the data that it will hold.

8. Reconfigure your node by adjusting the `path.data` setting in its
`elasticsearch.yml` file. If needed, install more nodes each with their own
`path.data` setting pointing at a separate data path.

9. Start the new nodes and follow the rest of the
{ref}/restart-cluster.html#restart-cluster-rolling[rolling restart process] for 
them.

10. Ensure your cluster health is `green`, so that every shard has been
assigned.

You can alternatively add some number of single-data-path nodes to your
cluster, migrate all your data over to these new nodes using
{ref}/modules-cluster.html#cluster-shard-allocation-filtering[allocation filters], 
and then remove the old nodes from the cluster. This approach will temporarily 
double the size of your cluster so it will only work if you have the capacity to 
expand your cluster like this.

If you currently use multiple data paths but your cluster is not highly
available then the you can migrate to a non-deprecated configuration by taking
a snapshot, creating a new cluster with the desired configuration and restoring
the snapshot into it.
====

[[action-destructive-defaults-to-true]]
.The `action.destructive_requires_name` setting will default to `true` in 8.0.0.
[%collapsible]
====
*Details* +
In 8.0.0, the `action.destructive_requires_name` setting will default to `true`.
Currently, the setting defaults to `false`.

*Impact* +
If you use a wildcard (`*`) or `_all` to delete indices or perform other
destructive actions, use the {ref}/cluster-update-settings.html[update cluster
settings API] to set `action.destructive_requires_name` to `false` to avoid
errors in 8.0.0.
====

[discrete]
[[breaking_713_eql_deprecations]]
==== EQL deprecations

[[wildcard-function-deprecated]]
.The `wildcard` function is deprecated.
[%collapsible]
====
*Impact* +
Use the {ref}/eql-syntax.html#eql-syntax-pattern-comparison-keywords[`like`] or
{ref}/eql-syntax.html#eql-syntax-pattern-comparison-keywords[`regex`] keyword
instead.
====

[discrete]
[[breaking_713_security_changes]]
==== Security deprecations

[[implicitly-disabled-basic-realms]]
.Implicit enablement of the file and native realms is deprecated.
[%collapsible]
====
*Details* +
Currently, the file and native realms have the following implicit behaviors:

* If file and native realms are not configured, they are implicitly disabled
if there are other explicitly configured realms.
* If no realm is available because realms are unconfigured, explicitly
disabled, or not allowed by your license, the file and native realms are always
enabled, even if explicitly disabled.

*Impact* +
Both of the above behaviors are deprecated. In 8.0.0, the file and
native realms will always be enabled unless explicitly disabled. If they are
explicitly disabled, they remain disabled at all times.
====

[[system-call-filter-setting]]
.System call filter setting deprecated
[%collapsible]
====
*Details* +
Elasticsearch uses system call filters to remove its ability to fork another
process. This is useful to mitigate remote code exploits. These system call
filters are enabled by default, and controlled via the setting
`bootstrap.system_call_filter`. Starting in Elasticsearch 8.0, system call
filters will be required. As such, the setting `bootstrap.system_call_filter` is
deprecated and will be removed in Elasticsearch 8.0.

*Impact* +
Discontinue use of the removed setting. Specifying this setting in Elasticsearch
configuration will result in an error on startup.
====
// end::notable-breaking-changes[]
