Migrating to 7.15

edit

This section discusses the changes that you need to be aware of when migrating your application to Elasticsearch 7.15.

See also What’s new in 7.15 and Release notes.

Breaking changes

edit

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

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.

Deprecations

edit

The following functionality has been deprecated in Elasticsearch 7.15 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.15.

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.

Security changes

edit
The xpack.security.transport.ssl.enabled setting will be required to configure xpack.security.transport.ssl settings.

Details
Configuring any SSL settings for xpack.security.transport.ssl without also configuring xpack.security.transport.ssl.enabled generates warnings in the deprecation log. In 8.0, this configuration will result in errors.

Impact
To avoid deprecation warnings, either:

  • Explicitly set xpack.security.transport.ssl.enabled as false
  • Discontinue use of other xpack.security.transport.ssl settings

If you want to enable SSL, follow the instructions to encrypt internode communications with TLS. As part of this configuration, explicitly set xpack.security.transport.ssl.enabled as true.

For example:

xpack.security.transport.ssl.enabled: true 
xpack.security.transport.ssl.keystore.path: elastic-certificates.p12
xpack.security.transport.ssl.truststore.path: elastic-certificates.p12

or false.

The xpack.security.http.ssl.enabled setting will be required to configure xpack.security.http.ssl settings.

Details
Configuring any SSL settings for xpack.security.http.ssl without also configuring xpack.security.http.ssl.enabled generates warnings in the deprecation log. In 8.0, this configuration will result in errors.

Impact
To avoid deprecation warnings, either:

  • Explicitly set xpack.security.http.ssl.enabled as false
  • Discontinue use of other xpack.security.http.ssl settings

If you want to enable SSL, follow the instructions to encrypt HTTP client communications for Elasticsearch. As part of this configuration, explicitly set xpack.security.http.ssl.enabled as true.

For example:

xpack.security.http.ssl.enabled: true 
xpack.security.http.ssl.certificate: elasticsearch.crt
xpack.security.http.ssl.key: elasticsearch.key
xpack.security.http.ssl.certificate_authorities: [ "corporate-ca.crt" ]

or false.

A xpack.security.transport.ssl certificate and key will be required to enable SSL for the transport interface.

Details
Enabling SSL for the transport interface without also configuring a certificate and key through use of the xpack.security.transport.ssl.keystore.path setting or the xpack.security.transport.ssl.certificate and xpack.security.transport.ssl.key settings generates warnings in the deprecation log. In 8.0, this configuration will result in errors.

Impact
If xpack.security.transport.ssl.enabled is set to true, provide a certificate and key using the xpack.security.transport.ssl.keystore.path setting or the xpack.security.transport.ssl.certificate and xpack.security.transport.ssl.key settings. If a certificate and key is not provided, Elasticsearch will generate warnings in the deprecation log.

A xpack.security.http.ssl certificate and key will be required to enable SSL for the HTTP layer.

Details
Enabling SSL for the HTTP layer without also configuring a certificate and key through use of the xpack.security.http.ssl.keystore.path setting or the xpack.security.http.ssl.certificate and xpack.security.http.ssl.key settings generates warnings in the deprecation log. In 8.0, this configuration will result in errors. Impact
If xpack.security.http.ssl.enabled is set to true, provide a certificate and key using the xpack.security.http.ssl.keystore.path setting or the xpack.security.http.ssl.certificate and xpack.security.http.ssl.key settings. If a certificate and key is not provided, Elasticsearch will generate warnings in the deprecation log.

Indices deprecations

edit
Indices created in Elasticsearch 6.x and earlier versions are deprecated.

Details
In 8.x, Elasticsearch will only read indices created in version 7.0 or above. An 8.x node will not start in the presence of indices created in 6.x or earlier versions of Elasticsearch.

Impact
Before upgrading to an 8.x version, reindex any index created in 6.x or earlier versions with Elasticsearch 7.x. If you no longer need the index, delete it instead. You can use the get index API to check the Elasticsearch version in which an index was created.

GET *,-.*?human=true&filter_path=**.settings.index.version.created_string
The simpleifs index store type is deprecated.

Details
The simplefs value for the index.store.type index setting is now deprecated. Use the niofs value for superior or equivalent performance instead.

Impact
To avoid deprecation warnings, discontinue use of the simpleifs store type in new indices or index templates. Reindex any index using simplefs into one with another store type.

Security deprecations

edit
The accept_default_password setting is deprecated.

Details
In 6.0, we deprecated the accept_default_password cluster setting. We removed support for default passwords in 6.0 but did not remove the setting for backwards compatibility. In 8.0, we will remove the setting.

Impact
To avoid deprecation warnings, discontinue use of the setting.

Native role cache settings are deprecated.

Details
In 5.2, we deprecated the following cluster settings:

  • xpack.security.authz.store.roles.index.cache.max_size
  • xpack.security.authz.store.roles.index.cache.ttl

These native role cache settings have been unused since 5.2, but we did not remove the settings for backwards compatibility. In 8.0, we will remove the settings.

Impact
To avoid deprecation warnings, discontinue use of the settings.

Settings deprecations

edit
Fractional byte size values are deprecated.

Details
In 6.2, we deprecated support for fractional byte size values, such as 23.5pb, in:

  • Cluster settings
  • Index settings
  • Cluster state metadata, such as an ILM policy, that support byte size values

Impact
To avoid deprecation warnings, discontinue use of fractional byte size values in your configurations. Update any existing configurations to use whole values.