Breaking changes in 8.0edit

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

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

Coming in 8.0.0.

Indices created in Elasticsearch 6.x and earlier versions are not supported.

Details
Elasticsearch 8.0 can read indices created in version 7.0 or above. An Elasticsearch 8.0 node will not start in the presence of indices created in a version of Elasticsearch before 7.0.

Impact
Reindex indices created in Elasticsearch 6.x or before with Elasticsearch 7.x if they need to be carried forward to Elasticsearch 8.x.

REST API endpoints containing _xpack have been removed.

Details
In 7.0, we deprecated REST endpoints that contain _xpack in their path. These endpoints are now removed in 8.0. Each endpoint that was deprecated and removed is replaced with a new endpoint that does not contain _xpack. As an example, /{index}/_xpack/graph/_explore is replaced by /{index}/_graph/explore.

Impact
Use the replacement REST API endpoints. Requests submitted to the _xpack API endpoints will return an error.

Aggregations changesedit

The percentiles aggregation’s percents parameter no longer supports duplicate values.

Details
If you specify the percents parameter with the percentiles aggregation, its values must be unique. Otherwise, an exception occurs.

Impact
Use unique values in the percents parameter of the percentiles aggregation. Requests containing duplicate values in the percents parameter will return an error.

Allocation changesedit

The automatic removal of flood-stage blocks is no longer optional.

Details
If a node exceeds the flood-stage disk watermark then we add a block to all of its indices to prevent further writes as a last-ditch attempt to prevent the node completely exhausting its disk space. By default, from 7.4 onwards the block is automatically removed when a node drops below the high watermark again, but this behaviour could be disabled by setting the system property es.disk.auto_release_flood_stage_block to false. This behaviour is no longer optional, and this system property must now not be set.

Impact
Discontinue use of the es.disk.auto_release_flood_stage_block system property. Specifying this property in elasticsearch.yml will result in an error on startup.

Accounting for the disk usage of relocating shards is no longer optional.

Details
By default Elasticsearch will account for the sizes of relocating shards when making allocation decisions based on the disk usage of the nodes in the cluster. In earlier versions the cluster.routing.allocation.disk.include_relocations setting allowed this accounting to be disabled, which would result in poor allocation decisions that might overshoot watermarks and require significant extra work to correct. This behaviour is no longer optional, and this setting has been removed.

Impact
Discontinue use of the cluster.routing.allocation.disk.include_relocations setting. Specifying this setting in elasticsearch.yml will result in an error on startup.

Analysis changesedit

The nGram and edgeNGram token filter names have been removed.

Details
The nGram and edgeNGram token filter names that have been deprecated since version 6.4 have been removed. Both token filters can only be used by their alternative names ngram and edge_ngram since version 7.0.

Impact
Use the equivalent ngram and edge_ngram token filters. Requests containing the nGram and edgeNGram token filter names will return an error.

The nGram and edgeNGram tokenizer names have been removed.

Details
The nGram and edgeNGram tokenizer names haven been deprecated with 7.6 and are no longer supported on new indices. Mappings for indices created after 7.6 will continue to work but emit a deprecation warning. The tokenizer name should be changed to the fully equivalent ngram or edge_ngram names for new indices and in index templates.

Impact
Use the ngram and edge_ngram tokenizers. Requests to create new indices using the nGram and edgeNGram tokenizer names will return an error.

Circuit breaker changesedit

The in_flight_requests stat has been renamed inflight_requests in logs and diagnostic APIs.

Details
The name of the in flight requests circuit breaker in log output and diagnostic APIs (such as the node stats API) changes from in_flight_requests to inflight_requests to align it with the name of the corresponding settings.

Impact
Update your workflow and applications to use the inflight_requests stat in place of in_flight_requests.

Cluster changesedit

The voting configuration exclusions API endpoint has changed.

Details
The POST /_cluster/voting_config_exclusions/{node_filter} API has been removed in favour of POST /_cluster/voting_config_exclusions?node_names=... and POST /_cluster/voting_config_exclusions?node_ids=... which allow you to specify the names or IDs of the nodes to exclude.

Impact
Use POST /_cluster/voting_config_exclusions?node_ids=... and specify the nodes to exclude instead of using a node filter. Requests submitted to the /_cluster/voting_config_exclusions/{node_filter} endpoint will return an error.

The cluster.join.timeout setting has been removed.

Details
The cluster.join.timeout setting has been removed. Join attempts no longer time out.

Impact
Do not set cluster.join.timeout in your elasticsearch.yml file.

Discovery changesedit

discovery.zen settings have been removed.

Details
All settings under the discovery.zen namespace, which existed only for BWC reasons in 7.x, are no longer supported. In particular, this includes:

  • discovery.zen.minimum_master_nodes
  • discovery.zen.no_master_block
  • discovery.zen.hosts_provider
  • discovery.zen.publish_timeout
  • discovery.zen.commit_timeout
  • discovery.zen.publish_diff.enable
  • discovery.zen.ping.unicast.concurrent_connects
  • discovery.zen.ping.unicast.hosts.resolve_timeout
  • discovery.zen.ping.unicast.hosts
  • discovery.zen.ping_timeout
  • discovery.zen.unsafe_rolling_upgrades_enabled
  • discovery.zen.fd.connect_on_network_disconnect
  • discovery.zen.fd.ping_interval
  • discovery.zen.fd.ping_timeout
  • discovery.zen.fd.ping_retries
  • discovery.zen.fd.register_connection_listener
  • discovery.zen.join_retry_attempts
  • discovery.zen.join_retry_delay
  • discovery.zen.join_timeout
  • discovery.zen.max_pings_from_another_master
  • discovery.zen.send_leave_request
  • discovery.zen.master_election.wait_for_joins_timeout
  • discovery.zen.master_election.ignore_non_master_pings
  • discovery.zen.publish.max_pending_cluster_states

Impact
Discontinue use of the discovery.zen settings. Specifying these settings in elasticsearch.yml will result in an error on startup.

HTTP changesedit

The http.content_type.required setting has been removed.

Details
The http.content_type.required setting was deprecated in Elasticsearch 6.0 and has been removed in Elasticsearch 8.0. The setting was introduced in Elasticsearch 5.3 to prepare users for Elasticsearch 6.0, where content type auto detection was removed for HTTP requests.

Impact
Discontinue use of the http.content_type.required system property. Specifying this property in elasticsearch.yml will result in an error on startup.

The http.tcp_no_delay setting has been replaced by http.tcp.no_delay.

Details
The http.tcp_no_delay setting was deprecated in 7.x and has been removed in 8.0. It has been replaced by http.tcp.no_delay.

Impact
Use the http.tcp.no_delay setting. Discontinue use of the http.tcp_no_delay setting. Specifying the http.tcp_no_delay setting in elasticsearch.yml will result in an error on startup.

The es.rest.url_plus_as_space system property has been removed.

Details
Starting in version 7.4, a + in a URL will be encoded as %2B by all REST API functionality. Prior versions handled a + as a single space. In these previous versions, if your application required handling + as a single space, you could return to the old behaviour by setting the system property es.rest.url_plus_as_space to true. Note that this behaviour is deprecated and setting this system property to true will cease to be supported in version 8.

Impact
Update your workflow and applications to assume + in a URL is encoded as %2B. Discontinue use of the es.rest.url_plus_as_space system property. Specifying this property in elasticsearch.yml will result in an error on startup.

Index lifecycle management changesedit

The indices.lifecycle.poll_interval setting must be greater than 1s.

Details
The setting indices.lifecycle.poll_interval, if set too low, can cause excessive load on a cluster. This setting must now be set to 1s (one second) or greater.

Impact
Update the indices.lifecycle.poll_interval setting to a value of 1s or greater using elasticsearch.yml or the cluster update settings API.

Setting indices.lifecycle.poll_interval to less than 1s in elasticsearch.yml will result in an error on startup. Cluster update settings API requests that set indices.lifecycle.poll_interval to less than 1s will return an error.

The indexlifecycle package has been renamed ilm in the Java High Level REST Client.

Details
In the high level REST client, the indexlifecycle package has been renamed to ilm to match the package rename inside the Elasticsearch code.

Impact
Update your workflow and applications to use the ilm package in place of indexlifecycle.

Indices changesedit

The force merge API’s max_num_segments and only_expunge_deletes parameters cannot both be specified in the same request.

Details
Previously, the force merge API allowed the parameters only_expunge_deletes and max_num_segments to be set to a non default value at the same time. But the max_num_segments was silently ignored when only_expunge_deletes is set to true, leaving the false impression that it has been applied.

Impact
When using the force merge API, do not specify values for both the max_num_segments and only_expunge_deletes parameters. Requests that include values for both parameters will return an error.

The index.force_memory_term_dictionary setting has been removed.

Details
The index.force_memory_term_dictionary setting was introduced in 7.0 as a temporary measure to allow users to opt-out of the optimization that leaves the term dictionary on disk when appropriate. This optimization is now mandatory and the setting is removed.

Impact
Discontinue use of the index.force_memory_term_dictionary index setting. Requests that include this setting will return an error.

The put index template API’s template parameter has been removed.

Details
In 6.0, we deprecated the template parameter in put index template requests in favor of using index_patterns. Support for the template parameter is now removed in 8.0.

Impact
Use the put index template API's index_patterns parameter. Requests that include the template parameter will return an error.

Synced flush has been removed.

Details
Synced flush was deprecated in 7.6 and is removed in 8.0. Use a regular flush instead as it has the same effect as a synced flush in 7.6 and later.

Impact
Use the flush API. Requests to the /<index>/flush/synced or /flush/synced endpoints will return an error.

The index.soft_deletes.enabled setting has been removed.

Details
Creating indices with soft deletes disabled was deprecated in 7.6 and is no longer supported in 8.0. The index.soft_deletes.enabled setting can no longer be set to false.

Impact
Discontinue use of the index.soft_deletes.enabled index setting. Requests that set index.soft_deletes.enabled to false will return an error.

The index.translog.retention.age and index.translog.retention.size settings have been removed.

Details
Translog retention settings index.translog.retention.age and index.translog.retention.size were effectively ignored in 7.4, deprecated in 7.7, and removed in 8.0 in favor of soft deletes.

Impact
Discontinue use of the index.translog.retention.age and index.translog.retention.size index settings. Requests that include these settings will return an error.

Java API changesedit

Changes to Fuzziness.

Details
To create Fuzziness instances, use the fromString and fromEdits method instead of the build method that used to accept both Strings and numeric values. Several fuzziness setters on query builders (e.g. MatchQueryBuilder#fuzziness) now accept only a `Fuzziness`instance instead of an Object.

Fuzziness used to be lenient when it comes to parsing arbitrary numeric values while silently truncating them to one of the three allowed edit distances 0, 1 or 2. This leniency is now removed and the class will throw errors when trying to construct an instance with another value (e.g. floats like 1.3 used to get accepted but truncated to 1).

Impact
Use the available constants (e.g. Fuzziness.ONE, Fuzziness.AUTO) or build your own instance using the above mentioned factory methods. Use only allowed Fuzziness values.

Changes to Repository.

Details
Repository has no dependency on IndexShard anymore. The contract of restoreShard and snapshotShard has been reduced to Store and MappingService in order to improve testability.

Impact
No action needed.

Mapping changesedit

The maximum number of completion contexts per field is now 10.

Details
The number of completion contexts within a single completion field has been limited to 10.

Impact
Use a maximum of 10 completion contexts in a completion field. Specifying more than 10 completion contexts will return an error.

Mapping API endpoints containing mapping types have been removed.

Details
The typed REST endpoints of the Put Mapping, Get Mapping and Get Field mapping APIs have been removed in favour of their typeless REST endpoints, since indexes no longer contain types, these typed endpoints are obsolete.

Impact
Use the typeless REST endpoints to update and retrieve mappings. Requests submitted to the typed mapping API endpoints will return an error.

Multi-fields within multi-fields is no longer supported.

Details
Previously, it was possible to define a multi-field within a multi-field. Defining chained multi-fields was deprecated in 7.3 and is now no longer supported.

Impact
To migrate mappings, all instances of fields that occur within a fields block should be removed, either by flattening the chained fields blocks into a single level, or by switching to copy_to if appropriate.

The _field_names metadata field’s enabled parameter has been removed.

Details
The setting has been deprecated with 7.5 and is no longer supported on new indices. Mappings for older indices will continue to work but emit a deprecation warning.

Impact
The enabled setting for _field_names should be removed from templates and mappings. Disabling _field_names is not necessary because it no longer carries a large index overhead.

Network changesedit

The network.tcp.connect_timeout setting has been removed.

Details
The network.tcp.connect_timeout setting was deprecated in 7.x and has been removed in 8.0. This setting was a fallback setting for transport.connect_timeout.

Impact
Use the transport.connect_timeout setting to change the default connection timeout for client connections. Discontinue use of the network.tcp.connect_timeout setting. Specifying the network.tcp.connect_timeout setting in elasticsearch.yml will result in an error on startup.

Node changesedit

The node.max_local_storage_nodes setting has been removed.

Details
The node.max_local_storage_nodes setting was deprecated in 7.x and has been removed in 8.0. Nodes should be run on separate data paths to ensure that each node is consistently assigned to the same data path.

Impact
Discontinue use of the node.max_local_storage_nodes setting. Specifying this setting in elasticsearch.yml will result in an error on startup.

The layout of the data folder has changed.

Details
Each node’s data is now stored directly in the data directory set by the path.data setting, rather than in ${path.data}/nodes/0, because the removal of the node.max_local_storage_nodes setting means that nodes may no longer share a data path.

Impact
At startup, Elasticsearch will automatically migrate the data path to the new layout. This automatic migration will not proceed if the data path contains data for more than one node. You should move to a configuration in which each node has its own data path before upgrading.

If you try to upgrade a configuration in which there is data for more than one node in a data path then the automatic migration will fail and Elasticsearch will refuse to start. To resolve this you will need to perform the migration manually. The data for the extra nodes are stored in folders named ${path.data}/nodes/1, ${path.data}/nodes/2 and so on, and you should move each of these folders to an appropriate location and then configure the corresponding node to use this location for its data path. If your nodes each have more than one data path in their path.data settings then you should move all the corresponding subfolders in parallel. Each node uses the same subfolder (e.g. nodes/2) across all its data paths.

Closed indices created in Elasticsearch 6.x and earlier versions are not supported.

Details
In earlier versions a node would start up even if it had data from indices created in a version before the previous major version, as long as those indices were closed. Elasticsearch now ensures that it is compatible with every index, open or closed, at startup time.

Impact
Reindex closed indices created in Elasticsearch 6.x or before with Elasticsearch 7.x if they need to be carried forward to Elasticsearch 8.x.

Packaging changesedit

Java 11 is required.

Details
Java 11 or higher is now required to run Elasticsearch and any of its command line tools.

Impact
Use Java 11 or higher. Attempts to run Elasticsearch 8.0 using earlier Java versions will fail.

Reindex changesedit

Reindex from remote now re-encodes URL-encoded index names.

Details
Reindex from remote would previously allow URL-encoded index names and not re-encode them when generating the search request for the remote host. This leniency has been removed such that all index names are correctly encoded when reindex generates remote search requests.

Impact
Specify unencoded index names for reindex from remote requests.

Reindex-related REST API endpoints containing mapping types have been removed.

Details
The /{index}/{type}/_delete_by_query and /{index}/{type}/_update_by_query REST endpoints have been removed in favour of /{index}/_delete_by_query and /{index}/_update_by_query, since indexes no longer contain types, these typed endpoints are obsolete.

Impact
Use the replacement REST API endpoints. Requests submitted to API endpoints that contain a mapping type will return an error.

In the reindex, delete by query, and update by query APIs, the size parameter has been renamed.

Details
Previously, a _reindex request had two different size specifications in the body:

  • Outer level, determining the maximum number of documents to process
  • Inside the source element, determining the scroll/batch size.

The outer level size parameter has now been renamed to max_docs to avoid confusion and clarify its semantics.

Similarly, the size parameter has been renamed to max_docs for _delete_by_query and _update_by_query to keep the 3 interfaces consistent.

Impact
Use the replacement parameters. Requests containing the size parameter will return an error.

REST API changesedit

The cat node API’s local query parameter has been removed.

Details
The ?local parameter to the GET _cat/nodes API was deprecated in 7.x and is rejected in 8.0. This parameter caused the API to use the local cluster state to determine the nodes returned by the API rather than the cluster state from the master, but this API requests information from each selected node regardless of the ?local parameter which means this API does not run in a fully node-local fashion.

Impact
Discontinue use of the ?local query parameter. cat node API requests that include this parameter will return an error.

The get field mapping API’s local query parameter has been removed.

Details
The local parameter for get field mapping API was deprecated in 7.8 and is removed in 8.0. This parameter is a no-op and field mappings are always retrieved locally.

Impact
Discontinue use of the local query parameter. get field mapping API requests that include this parameter will return an error.

Rollup changesedit

The StartRollupJob endpoint now returns a success status if a job has already started.

Details
Previously, attempting to start an already-started rollup job would result in a 500 InternalServerError: Cannot start task for Rollup Job [job] because state was [STARTED] exception.

Now, attempting to start a job that is already started will just return a successful 200 OK: started response.

Impact
Update your workflow and applications to assume that a 200 status in response to attempting to start a rollup job means the job is in an actively started state. The request itself may have started the job, or it was previously running and so the request had no effect.

Search Changesedit

Search-related REST API endpoints containing mapping types have been removed.

Details
The /{index}/{type}/_search, /{index}/{type}/_msearch, /{index}/{type}/_search/template and /{index}/{type}/_msearch/template REST endpoints have been removed in favour of /{index}/_search, /{index}/_msearch, /{index}/_search/template and /{index}/_msearch/template; since indexes no longer contain types, these typed endpoints are obsolete..

The /{index}/{type}/_termvectors, /{index}/{type}/{id}/_termvectors and /{index}/{type}/_mtermvectors REST endpoints have been removed in favour of /{index}/_termvectors, /{index}/{id}/_termvectors and /{index}/_mtermvectors; since indexes no longer contain types, these typed endpoints are obsolete..

The /{index}/{type}/{doc} and /{index}/{type}/_mget REST endpoints have been removed in favour of /{index}/_doc/{doc} and /{index}/_mget; since indexes no longer contain types, these typed endpoints are obsolete.

Impact
Use the replacement REST API endpoints. Requests submitted to API endpoints that contain a mapping type will return an error.

The common query has been removed.

Details
The common query, deprecated in 7.x, has been removed in 8.0. The same functionality can be achieved by the match query if the total number of hits is not tracked.

Impact
Discontinue use of the common query. Search requests containing a common query will return an error.

The cutoff_frequency parameter has been removed from the match and multi_match query.

Details
The cutoff_frequency parameter, deprecated in 7.x, has been removed in 8.0 from match and multi_match queries. The same functionality can be achieved without any configuration provided that the total number of hits is not tracked.

Impact
Discontinue use of the cutoff_frequency parameter. Search requests containing this parameter in a match or multi_match query will return an error.

The nested_filter and nested_path properties have been removed from the search API’s sort request body parameter.

Details
The nested_filter and nested_path options, deprecated in 6.x, have been removed in favor of the nested context.

Impact
Discontinue use of the sort request body parameter’s nested_filter and nested_path properties. Requests containing these properties will return an error.

Search and get requests are now routed to shards using adaptive replica selection by default.

Details
Elasticsearch will no longer prefer using shards in the same location (with the same awareness attribute values) to process _search and _get requests. Adaptive replica selection (activated by default in this version) will route requests more efficiently using the service time of prior inter-node communications.

Impact
No action needed.

The sparse_vector field data type has been removed.

Details
The sparse_vector field type was deprecated in 7.6 and is now removed in 8.0. We have not seen much interest in this experimental field type, and don’t see a clear use case as it’s currently designed. If you have feedback or suggestions around sparse vector functionality, please let us know through GitHub or the discuss forums.

Impact
Discontinue use of the sparse_vector field data type. Requests containing a mapping for this field data type will return an error.

Vector functions using (query, doc['field']) are no longer supported.

Details
The vector functions of the form function(query, doc['field']) were deprecated in 7.6, and are now removed in 8.x. The form function(query, 'field') should be used instead. For example, cosineSimilarity(query, doc['field']) is replaced by cosineSimilarity(query, 'field').

Impact
Use the function(query, 'field') form. Discontinue use of the function(query, doc['field']) form. Requests containing the function(query, doc['field']) form will return an error.

The search API’s indices_boost request body parameter no longer accepts object values.

Details
The indices_boost option in the search request used to accept the boosts both as an object and as an array. The object format has been deprecated since 5.2 and is now removed in 8.0.

Impact
Use only array values in the indices_boost parameter. Requests containing an object value in the indices_boost parameter will return an error.

The search API’s use_field_mapping request body parameter has been removed.

Details
In 7.0, we began formatting docvalue_fields by default using each field’s mapping definition. To ease the transition from 6.x, we added the format option use_field_mapping. This parameter was deprecated in 7.0, and is now removed in 8.0.

Impact
Discontinue use of the use_field_mapping request body parameter. Requests containing this parameter will return an error.

The search API’s from request body and url parameter cannot be negative.

Details
Search request used to accept -1 as a from in the search body and the url, treating it as the default value of 0. Other negative values got rejected with an error already. We now also reject -1 as an invalid value.

Impact
Change any use of -1 as from parameter in request body or url parameters by either setting it to 0 or omitting it entirely. Requests containing negative values will return an error.

Security changesedit

The realm order setting is now required.

Details
The xpack.security.authc.realms.{type}.{name}.order setting is now required and must be specified for each explicitly configured realm. Each value must be unique.

Impact
The cluster will fail to start if the requirements are not met.

For example, the following configuration is invalid:

xpack.security.authc.realms.kerberos.kerb1:
  keytab.path: es.keytab
  remove_realm_name: false

And must be configured as:

xpack.security.authc.realms.kerberos.kerb1:
  order: 0
  keytab.path: es.keytab
  remove_realm_name: false
The accept_default_password setting has been removed.

Details
The xpack.security.authc.accept_default_password setting has not had any affect since the 6.0 release of Elasticsearch. It has been removed and cannot be used.

Impact
Discontinue use of the xpack.security.authc.accept_default_password setting. Specifying this setting in elasticsearch.yml will result in an error on startup.

The roles.index.cache.* settings have been removed.

Details
The xpack.security.authz.store.roles.index.cache.max_size and xpack.security.authz.store.roles.index.cache.ttl settings have been removed. These settings have been redundant and deprecated since the 5.2 release of Elasticsearch.

Impact
Discontinue use of the xpack.security.authz.store.roles.index.cache.max_size and xpack.security.authz.store.roles.index.cache.ttl settings. Specifying these settings in elasticsearch.yml will result in an error on startup.

The elasticsearch-migrate tool has been removed.

Details
The elasticsearch-migrate tool provided a way to convert file realm users and roles into the native realm. It has been deprecated since 7.2.0. Users and roles should now be created in the native realm directly.

Impact
Discontinue use of the elasticsearch-migrate tool. Attempts to use the elasticsearch-migrate tool will result in an error.

The transport.profiles.*.xpack.security.type setting has been removed.

Details
The transport.profiles.*.xpack.security.type setting has been removed since the Transport Client has been removed and therefore all client traffic now uses the HTTP transport. Transport profiles using this setting should be removed.

Impact
Discontinue use of the transport.profiles.*.xpack.security.type setting. Specifying this setting in a transport profile in elasticsearch.yml will result in an error on startup.

SSL/TLS configuration validationedit

The xpack.security.transport.ssl.enabled setting is now required to configure xpack.security.transport.ssl settings.

Details
It is now an error to configure any SSL settings for xpack.security.transport.ssl without also configuring xpack.security.transport.ssl.enabled.

Impact
If using other xpack.security.transport.ssl settings, you must explicitly specify the xpack.security.transport.ssl.enabled setting.

If you do not want to enable SSL and are currently using other xpack.security.transport.ssl settings, do one of the following:

  • Explicitly specify 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 in Encrypting communications between nodes in a cluster. As part of this configuration, explicitly specify xpack.security.transport.ssl.enabled as true.

For example, the following configuration is invalid:

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

And must be configured as:

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 is now required to configure xpack.security.http.ssl settings.

Details
It is now an error to configure any SSL settings for xpack.security.http.ssl without also configuring xpack.security.http.ssl.enabled.

Impact
If using other xpack.security.http.ssl settings, you must explicitly specify the xpack.security.http.ssl.enabled setting.

If you do not want to enable SSL and are currently using other xpack.security.http.ssl settings, do one of the following:

  • Explicitly specify 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 in Encrypting HTTP client communications. As part of this configuration, explicitly specify xpack.security.http.ssl.enabled as true.

For example, the following configuration is invalid:

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

And must be configured as either:

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 are now required to enable SSL for the transport interface.

Details
It is now an error to enable 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.

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 return in an error on startup.

A xpack.security.http.ssl certificate and key are now required to enable SSL for the HTTP server.

Details
It is now an error to enable SSL for the HTTP (Rest) server 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.

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 certificate and key is not provided, Elasticsearch will return in an error on startup.

Changes to built-in usersedit

The kibana user has been replaced by kibana_system.

Details
The kibana user was historically used to authenticate Kibana to Elasticsearch. The name of this user was confusing, and was often mistakenly used to login to Kibana. This has been renamed to kibana_system in order to reduce confusion, and to better align with other built-in system accounts.

Impact
Replace any use of the kibana user with the kibana_system user. Specifying the kibana user in kibana.yml will result in an error on startup.

If your kibana.yml used to contain:

elasticsearch.username: kibana

then you should update to use the new kibana_system user instead:

elasticsearch.username: kibana_system

The new kibana_system user does not preserve the previous kibana user password. You must explicitly set a password for the kibana_system user.

Changes to built-in rolesedit

The kibana_user role has been renamed kibana_admin.

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.

Settings changesedit

The search.remote.* settings have been removed.

Details
In 6.5 these settings were deprecated in favor of cluster.remote. In 7.x we provided automatic upgrading of these settings to their cluster.remote counterparts. In 8.0.0, these settings have been removed. Elasticsearch will refuse to start if you have these settings in your configuration or cluster state.

Impact
Use the replacement cluster.remote settings. Discontinue use of the search.remote.* settings. Specifying these settings in elasticsearch.yml will result in an error on startup.

The pidfile setting has been replaced by node.pidfile.

Details
To ensure that all settings are in a proper namespace, the pidfile setting was previously deprecated in version 7.4.0 of Elasticsearch, and is removed in version 8.0.0. Instead, use node.pidfile.

Impact
Use the node.pidfile setting. Discontinue use of the pidfile setting. Specifying the pidfile setting in elasticsearch.yml will result in an error on startup.

The processors setting has been replaced by node.processors.

Details
To ensure that all settings are in a proper namespace, the processors setting was previously deprecated in version 7.4.0 of Elasticsearch, and is removed in version 8.0.0. Instead, use node.processors.

Impact
Use the node.processors setting. Discontinue use of the processors setting. Specifying the processors setting in elasticsearch.yml will result in an error on startup.

The node.processors setting can no longer exceed the available number of processors.

Details
Previously it was possible to set the number of processors used to set the default sizes for the thread pools to be more than the number of available processors. As this leads to more context switches and more threads but without an increase in the number of physical CPUs on which to schedule these additional threads, the node.processors setting is now bounded by the number of available processors.

Impact
If specified, ensure the value of node.processors setting does not exceed the number of available processors. Setting the node.processors value greater than the number of available processors in elasticsearch.yml will result in an error on startup.

The cluster.remote.connect setting has been removed.

Details
In Elasticsearch 7.7.0, the setting cluster.remote.connect was deprecated in favor of setting node.remote_cluster_client. In Elasticsearch 8.0.0, the setting cluster.remote.connect is removed.

Impact
Use the node.remote_cluster_client setting. Discontinue use of the cluster.remote.connect setting. Specifying the cluster.remote.connect setting in elasticsearch.yml will result in an error on startup.

The node.local_storage setting has been removed.

Details
In Elasticsearch 7.8.0, the setting node.local_storage was deprecated and beginning in Elasticsearch 8.0.0 all nodes will require local storage. Therefore, the node.local_storage setting has been removed.

Impact
Discontinue use of the node.local_storage setting. Specifying this setting in elasticsearch.yml will result in an error on startup.

The auth.password setting for HTTP monitoring has been removed.

Details
In Elasticsearch 7.7.0, the setting xpack.monitoring.exporters.<exporterName>.auth.password was deprecated in favor of setting xpack.monitoring.exporters.<exporterName>.auth.secure_password. In Elasticsearch 8.0.0, the setting xpack.monitoring.exporters.<exporterName>.auth.password is removed.

Impact
Use the xpack.monitoring.exporters.<exporterName>.auth.secure_password setting. Discontinue use of the xpack.monitoring.exporters.<exporterName>.auth.password setting. Specifying the xpack.monitoring.exporters.<exporterName>.auth.password setting in elasticsearch.yml will result in an error on startup.

Settings used to disable basic license features have been removed.

Details
The following settings were deprecated in Elasticsearch 7.8.0 and have been removed in Elasticsearch 8.0.0:

  • xpack.enrich.enabled
  • xpack.flattened.enabled
  • xpack.ilm.enabled
  • xpack.monitoring.enabled
  • xpack.rollup.enabled
  • xpack.slm.enabled
  • xpack.sql.enabled
  • xpack.transform.enabled
  • xpack.vectors.enabled

These basic license features are now always enabled for the default distribution.

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.

Impact
Discontinue use of the removed settings. Specifying these settings in elasticsearch.yml will result in an error on startup.

Snapshot and restore changesedit

The get snapshot API’s response format has changed.

Details
It’s possible to get snapshots from multiple repositories in one go. The response format has changed and now contains separate response for each repository.

For example, requesting one snapshot from particular repository

GET _snapshot/repo1/snap1

produces the following response

{
  "responses": [
    {
      "repository": "repo1",
      "snapshots": [
        {
          "snapshot": "snap1",
          "uuid": "cEzdqUKxQ5G6MyrJAcYwmA",
          "version_id": 8000099,
          "version": "8.0.0",
          "indices": [],
          "include_global_state": true,
          "state": "SUCCESS",
          "start_time": "2019-05-10T17:01:57.868Z",
          "start_time_in_millis": 1557507717868,
          "end_time": "2019-05-10T17:01:57.909Z",
          "end_time_in_millis": 1557507717909,
          "duration_in_millis": 41,
          "failures": [],
          "shards": {
            "total": 0,
            "failed": 0,
            "successful": 0
          }
        }
      ]
    }
  ]
}

See Snapshot module for more information.

Impact
Update your workflow and applications to use the get snapshot API’s new response format.

The repositories.fs.compress node-level setting has been removed.

Details
For shared file system repositories ("type": "fs"), the node level setting repositories.fs.compress could previously be used to enable compression for all shared file system repositories where compress was not specified. The repositories.fs.compress setting has been removed.

Impact
Use the repository specific compress setting to enable compression. See Snapshot module for information on the compress setting.

Discontinue use of the repositories.fs.compress node-level setting.

Metadata files are now compressed by default.

Details
Previously, the default value for compress was false. The default has been changed to true.

This change will affect both newly created repositories and existing repositories where compress=false has not been explicitly specified.

For more information on the compress option, see Snapshot module

Impact
Update your workflow and applications to assume a default value of true for the compress parameter.

The S3 repository plugin now uses a DNS-style access pattern by default.

Details
Starting in version 7.4 the repository-s3 plugin does not use the now-deprecated path-style access pattern by default. In versions 7.0, 7.1, 7.2 and 7.3 the repository-s3 plugin always used the path-style access pattern. This is a breaking change for deployments that only support path-style access but which are recognized as supporting DNS-style access by the AWS SDK. This breaking change was made necessary by AWS’s announcement that the path-style access pattern is deprecated and will be unsupported on buckets created after September 30th 2020.

Impact
If your deployment only supports path-style access and is affected by this change then you must configure the S3 client setting path_style_access to true.

Restore requests no longer accept settings.

Details
In earlier versions, you could pass both settings and index_settings in the body of a restore snapshot request, but the settings value was ignored. The restore snapshot API now rejects requests that include a settings value.

Impact
Discontinue use of the settings parameter in restore snapshot request. Requests that include these parameters will return an error.

Thread pool changesedit

The fixed_auto_queue_size thread pool type has been removed.

Details
The fixed_auto_queue_size thread pool type, previously marked as an experimental feature, was deprecated in 7.x and has been removed in 8.0. The search and search_throttled thread pools have the fixed type now.

Impact
No action needed.

Transport changesedit

Several tranport settings have been replaced.

Details
The following settings have been deprecated in 7.x and removed in 8.0. Each setting has a replacement setting that was introduced in 6.7.

  • transport.tcp.port replaced by transport.port
  • transport.tcp.compress replaced by transport.compress
  • transport.tcp.connect_timeout replaced by transport.connect_timeout
  • transport.tcp_no_delay replaced by transport.tcp.no_delay
  • transport.profiles.profile_name.tcp_no_delay replaced by transport.profiles.profile_name.tcp.no_delay
  • transport.profiles.profile_name.tcp_keep_alive replaced by transport.profiles.profile_name.tcp.keep_alive
  • transport.profiles.profile_name.reuse_address replaced by transport.profiles.profile_name.tcp.reuse_address
  • transport.profiles.profile_name.send_buffer_size replaced by transport.profiles.profile_name.tcp.send_buffer_size
  • transport.profiles.profile_name.receive_buffer_size replaced by transport.profiles.profile_name.tcp.receive_buffer_size

Impact
Use the replacement settings. Discontinue use of the removed settings. Specifying the removed settings in elasticsearch.yml will result in an error on startup.