You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/reference/migration/migrate_8_19.asciidoc
+202-1Lines changed: 202 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,5 +16,206 @@ coming::[8.19.0]
16
16
[[breaking-changes-8.19]]
17
17
=== Breaking changes
18
18
19
-
There are no breaking changes in {es} 8.19.
19
+
The following changes in {es} 8.19 might affect your applications
20
+
and prevent them from operating normally.
21
+
Before upgrading to 8.19, review these changes and take the described steps
22
+
to mitigate the impact.
23
+
24
+
[discrete]
25
+
[[breaking_819_cluster_and_node_setting_changes]]
26
+
==== Cluster and node setting changes
27
+
28
+
[[upgrade_discovery_ec2_to_aws_sdk_v2]]
29
+
.Upgrade `discovery-ec2` to AWS SDK v2
30
+
[%collapsible]
31
+
====
32
+
*Details* +
33
+
In earlier versions of {es} the `discovery-ec2` plugin was based on the AWS SDK v1. AWS will withdraw support for this SDK before the end of the life of {es} {minor-version} so we must migrate to the newer AWS SDK v2.
34
+
Unfortunately there are several differences between the two AWS SDK versions which may require you to adjust your system configuration when upgrading to {es} {minor-version} or later. These differences include, but may not be limited to, the following items.
35
+
* AWS SDK v2 does not support the EC2 IMDSv1 protocol.
36
+
* AWS SDK v2 does not support the `aws.secretKey` or
37
+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system properties.
38
+
39
+
* AWS SDK v2 does not permit specifying a choice between HTTP and HTTPS so
40
+
the `discovery.ec2.protocol` setting is no longer effective.
41
+
42
+
* AWS SDK v2 does not accept an access key without a secret key or vice
43
+
versa.
44
+
45
+
*Impact* +
46
+
If you use the `discovery-ec2` plugin, test your upgrade thoroughly before upgrading any production workloads.
47
+
Adapt your configuration to the new SDK functionality. This includes, but may not be limited to, the following items.
48
+
* If you use IMDS to determine the availability zone of a node or to obtain
49
+
credentials for accessing the EC2 API, ensure that it supports the IMDSv2
50
+
protocol.
51
+
52
+
* If applicable, discontinue use of the `aws.secretKey` and
53
+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system properties.
54
+
55
+
* If applicable, specify that you wish to use the insecure HTTP protocol to
56
+
access the EC2 API by setting `discovery.ec2.endpoint` to a URL which
57
+
starts with `http://`.
58
+
59
+
* Either supply both an access key and a secret key using the keystore
60
+
settings `discovery.ec2.access_key` and `discovery.ec2.secret_key`, or
61
+
configure neither of these settings.
62
+
====
63
+
64
+
[[upgrade_repository_s3_to_aws_sdk_v2]]
65
+
.Upgrade `repository-s3` to AWS SDK v2
66
+
[%collapsible]
67
+
====
68
+
*Details* +
69
+
In earlier versions of {es} the `repository-s3` plugin was based on the AWS SDK v1. AWS will withdraw support for this SDK before the end of the life of {es} {minor-version} so we must migrate to the newer AWS SDK v2.
70
+
Unfortunately there are several differences between the two AWS SDK versions which may require you to adjust your system configuration when upgrading to {es} {minor-version} or later. These differences include, but may not be limited to, the following items.
71
+
* AWS SDK v2 requires users to specify the region to use for signing
72
+
requests, or else to run in an environment in which it can determine the
73
+
correct region automatically. The older SDK would try to determine the
74
+
region based on the endpoint URL as specified with the
75
+
`s3.client.${CLIENT_NAME}.endpoint` setting, together with other data
76
+
drawn from the operating environment, and would ultimately fall back to
77
+
`us-east-1` if no better value could be found.
78
+
79
+
* AWS SDK v2 does not support the EC2 IMDSv1 protocol.
80
+
* AWS SDK v2 does not support the
81
+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system property.
82
+
83
+
* AWS SDK v2 does not permit specifying a choice between HTTP and HTTPS so
84
+
the `s3.client.${CLIENT_NAME}.protocol` setting is deprecated.
85
+
86
+
* AWS SDK v2 does not permit control over throttling for retries, so the
87
+
the `s3.client.${CLIENT_NAME}.use_throttle_retries` setting is deprecated
88
+
and no longer has any effect.
89
+
90
+
* AWS SDK v2 requires the use of the V4 signature algorithm, so the
91
+
`s3.client.${CLIENT_NAME}.signer_override` setting is deprecated and no
92
+
longer has any effect.
93
+
94
+
* AWS SDK v2 does not support the `log-delivery-write` canned ACL.
95
+
* AWS SDK v2 counts 4xx responses differently in its metrics reporting.
could use either a regional endpoint or the global
98
+
`https://sts.amazonaws.com` one.
99
+
100
+
*Impact* +
101
+
If you use the `repository-s3` module, test your upgrade thoroughly before upgrading any production workloads.
102
+
Adapt your configuration to the new SDK functionality. This includes, but may not be limited to, the following items.
103
+
* Specify the correct signing region using the
104
+
`s3.client.${CLIENT_NAME}.region` setting on each node. {es} will try and
105
+
determine the correct region based on the endpoint URL and other data
106
+
drawn from the operating environment but cannot guarantee to do so
107
+
correctly in all cases.
108
+
109
+
* If you use IMDS to determine the availability zone of a node or to obtain
110
+
credentials for accessing the EC2 API, ensure that it supports the IMDSv2
111
+
protocol.
112
+
113
+
* If applicable, discontinue use of the
114
+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system property.
115
+
116
+
* If applicable, specify the protocol to use to access the S3 API by
117
+
setting `s3.client.${CLIENT_NAME}.endpoint` to a URL which starts with
118
+
`http://` or `https://`.
119
+
120
+
* If applicable, discontinue use of the `log-delivery-write` canned ACL.
121
+
====
122
+
123
+
[discrete]
124
+
[[breaking_819_es_ql_changes]]
125
+
==== ES|QL changes
126
+
127
+
[[allow_partial_results_by_default_in_es_ql]]
128
+
.Allow partial results by default in ES|QL
129
+
[%collapsible]
130
+
====
131
+
*Details* +
132
+
In earlier versions of {es}, ES|QL would fail the entire query if it encountered any error. ES|QL now returns partial results instead of failing when encountering errors.
133
+
134
+
*Impact* +
135
+
Callers should check the `is_partial` flag returned in the response to determine if the result is partial or complete. If returning partial results is not desired, this option can be overridden per request via an `allow_partial_results` parameter in the query URL or globally via the cluster setting `esql.query.allow_partial_results`.
.Cluster setting "skip_unavailable" catches all runtime errors
144
+
[%collapsible]
145
+
====
146
+
*Details* +
147
+
If `skip_unavailable` is set to `true`, the runtime errors from this cluster do not lead to a failure of the query. Instead, the cluster is set to `skipped` or `partial` status, and the query execution continues. This is a breaking change from previous versions, where `skip_unavailable` only applied to errors related to a cluster being unavailable.
148
+
149
+
*Impact* +
150
+
The errors on remote clusters, e.g. missing indices, will not lead to a failure of the query. Instead, the cluster is set to `skipped` or `partial` status in the response metadata.
Previously, the ES|QL grammar allowed users to individually quote constituent strings in index patterns such as "remote_cluster":"index_name". This would allow users to write complex malformed index patterns that often slip through grammar and the subsequent validation. This could result in runtime errors that can be misleading. This change simplifies the grammar to early reject such malformed index patterns at the parsing stage, allowing users to write simpler queries and see more relevant and meaningful errors.
159
+
160
+
*Impact* +
161
+
Users can write queries with simpler index patterns and see more meaningful and relevant errors.
.Deprecate ability to connect to nodes of versions 8.18 and earlier
212
+
[%collapsible]
213
+
====
214
+
*Details* +
215
+
Versions 9.1.0 and later of {es} will not support communication with nodes of versions earlier than 8.19.0, so the ability to connect to nodes of earlier versions is deprecated in this version. This applies both to communication within a cluster and communication across clusters (e.g. for <<modules-cross-cluster-search,{ccs}>> or <<xpack-ccr,{ccr}>>).
216
+
{es} will report in its <<deprecation-logging, deprecation logging>> each time it opens a connection to a node that will not be supported from version 9.1.0 onwards. You must upgrade all your clusters to version 8.19.0 or later before upgrading any of your clusters to 9.1.0 or later.
217
+
218
+
*Impact* +
219
+
Upgrade all of your clusters to at least 8.19.0 before upgrading any of them to 9.1.0 or later.
0 commit comments