Skip to content

Commit 7ab9719

Browse files
elasticsearchmachineelasticsearchmachine
authored
Add release notes for v8.19.0 release (#131952)
* Update docs for v8.19.0 release
1 parent 36b20d4 commit 7ab9719

File tree

2 files changed

+742
-1
lines changed

2 files changed

+742
-1
lines changed

‎docs/reference/migration/migrate_8_19.asciidoc‎

Lines changed: 206 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,210 @@ coming::[8.19.0]
1616
[[breaking-changes-8.19]]
1717
=== Breaking changes
1818

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+
36+
* AWS SDK v2 does not support the EC2 IMDSv1 protocol.
37+
38+
* AWS SDK v2 does not support the `aws.secretKey` or
39+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system properties.
40+
41+
* AWS SDK v2 does not permit specifying a choice between HTTP and HTTPS so
42+
the `discovery.ec2.protocol` setting is no longer effective.
43+
44+
* AWS SDK v2 does not accept an access key without a secret key or vice
45+
versa.
46+
47+
*Impact* +
48+
If you use the `discovery-ec2` plugin, test your upgrade thoroughly before upgrading any production workloads.
49+
Adapt your configuration to the new SDK functionality. This includes, but may not be limited to, the following items.
50+
51+
* If you use IMDS to determine the availability zone of a node or to obtain
52+
credentials for accessing the EC2 API, ensure that it supports the IMDSv2
53+
protocol.
54+
55+
* If applicable, discontinue use of the `aws.secretKey` and
56+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system properties.
57+
58+
* If applicable, specify that you wish to use the insecure HTTP protocol to
59+
access the EC2 API by setting `discovery.ec2.endpoint` to a URL which
60+
starts with `http://`.
61+
62+
* Either supply both an access key and a secret key using the keystore
63+
settings `discovery.ec2.access_key` and `discovery.ec2.secret_key`, or
64+
configure neither of these settings.
65+
====
66+
67+
[[upgrade_repository_s3_to_aws_sdk]]
68+
.Upgrade `repository-s3` to AWS SDK v2
69+
[%collapsible]
70+
====
71+
*Details* +
72+
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.
73+
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.
74+
75+
* AWS SDK v2 requires users to specify the region to use for signing
76+
requests, or else to run in an environment in which it can determine the
77+
correct region automatically. The older SDK would try to determine the
78+
region based on the endpoint URL as specified with the
79+
`s3.client.${CLIENT_NAME}.endpoint` setting, together with other data
80+
drawn from the operating environment, and would ultimately fall back to
81+
`us-east-1` if no better value could be found.
82+
83+
* AWS SDK v2 does not support the EC2 IMDSv1 protocol.
84+
85+
* AWS SDK v2 does not support the
86+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system property.
87+
88+
* AWS SDK v2 does not permit specifying a choice between HTTP and HTTPS so
89+
the `s3.client.${CLIENT_NAME}.protocol` setting is deprecated.
90+
91+
* AWS SDK v2 does not permit control over throttling for retries, so the
92+
the `s3.client.${CLIENT_NAME}.use_throttle_retries` setting is deprecated
93+
and no longer has any effect.
94+
95+
* AWS SDK v2 requires the use of the V4 signature algorithm, so the
96+
`s3.client.${CLIENT_NAME}.signer_override` setting is deprecated and no
97+
longer has any effect.
98+
99+
* AWS SDK v2 does not support the `log-delivery-write` canned ACL.
100+
101+
* AWS SDK v2 counts 4xx responses differently in its metrics reporting.
102+
103+
* AWS SDK v2 always uses the regional STS endpoint, whereas AWS SDK v2
104+
could use either a regional endpoint or the global
105+
`https://sts.amazonaws.com` one.
106+
107+
*Impact* +
108+
If you use the `repository-s3` module, test your upgrade thoroughly before upgrading any production workloads.
109+
Adapt your configuration to the new SDK functionality. This includes, but may not be limited to, the following items.
110+
111+
* Specify the correct signing region using the
112+
`s3.client.${CLIENT_NAME}.region` setting on each node. {es} will try and
113+
determine the correct region based on the endpoint URL and other data
114+
drawn from the operating environment but cannot guarantee to do so
115+
correctly in all cases.
116+
117+
* If you use IMDS to determine the availability zone of a node or to obtain
118+
credentials for accessing the EC2 API, ensure that it supports the IMDSv2
119+
protocol.
120+
121+
* If applicable, discontinue use of the
122+
`com.amazonaws.sdk.ec2MetadataServiceEndpointOverride` system property.
123+
124+
* If applicable, specify the protocol to use to access the S3 API by
125+
setting `s3.client.${CLIENT_NAME}.endpoint` to a URL which starts with
126+
`http://` or `https://`.
127+
128+
* If applicable, discontinue use of the `log-delivery-write` canned ACL.
129+
====
130+
131+
[discrete]
132+
[[breaking_819_es_ql_changes]]
133+
==== ES|QL changes
134+
135+
[[allow_partial_results_by_default_in_es_ql]]
136+
.Allow partial results by default in ES|QL
137+
[%collapsible]
138+
====
139+
*Details* +
140+
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.
141+
142+
*Impact* +
143+
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`.
144+
====
145+
146+
[[cluster_setting_skip_unavailable_catches_all_runtime_errors]]
147+
.Cluster setting "skip_unavailable" catches all runtime errors
148+
[%collapsible]
149+
====
150+
*Details* +
151+
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.
152+
153+
*Impact* +
154+
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.
155+
====
156+
157+
[[disallow_mixed_quoted_unquoted_patterns_in_from]]
158+
.Disallow mixed quoted/unquoted patterns in FROM
159+
[%collapsible]
160+
====
161+
*Details* +
162+
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.
163+
164+
*Impact* +
165+
Users can write queries with simpler index patterns and see more meaningful and relevant errors.
166+
====
167+
168+
[[unquoted_index_patterns_do_not_allow_characters]]
169+
.Unquoted index patterns do not allow `(` and `)` characters
170+
[%collapsible]
171+
====
172+
*Details* +
173+
Previously, ES|QL accepted unquoted index patterns containing brackets, such as `FROM index(1) | ENRICH policy(2)`.
174+
This query syntax is no longer valid because it could conflict with subquery syntax, where brackets are used as delimiters.
175+
Brackets are now only allowed in quoted index patterns. For example: `FROM "index(1)" | ENRICH "policy(2)"`.
176+
177+
*Impact* +
178+
This affects existing queries containing brackets in index or policy names, i.e. in FROM, ENRICH, and LOOKUP JOIN commands.
179+
====
180+
181+
182+
[discrete]
183+
[[deprecated-8.19]]
184+
=== Deprecations
185+
186+
The following functionality has been deprecated in {es} 8.19
187+
and will be removed in a future version.
188+
While this won't have an immediate impact on your applications,
189+
we strongly encourage you to take the described steps to update your code
190+
after upgrading to 8.19.
191+
192+
To find out if you are using any deprecated functionality,
193+
enable <<deprecation-logging, deprecation logging>>.
194+
195+
[discrete]
196+
[[deprecations_819_ingest]]
197+
==== Ingest deprecations
198+
199+
[[deprecate_indices_merge_scheduler_use_thread_pool_setting]]
200+
.Deprecate `indices.merge.scheduler.use_thread_pool` setting
201+
[%collapsible]
202+
====
203+
*Details* +
204+
This deprecates the `indices.merge.scheduler.use_thread_pool` node setting that was introduced in
205+
206+
*Impact* +
207+
There should be no impact to users since the setting was not released before its deprecation here (and is not documented).
208+
====
209+
210+
[discrete]
211+
[[deprecations_819_rest_api]]
212+
==== REST API deprecations
213+
214+
[[deprecate_ability_to_connect_to_nodes_of_versions_8_18_earlier]]
215+
.Deprecate ability to connect to nodes of versions 8.18 and earlier
216+
[%collapsible]
217+
====
218+
*Details* +
219+
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}>>).
220+
{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.
221+
222+
*Impact* +
223+
Upgrade all of your clusters to at least 8.19.0 before upgrading any of them to 9.1.0 or later.
224+
====
20225

0 commit comments

Comments
 (0)