Skip to content

Commit 0f09355

Browse files
github-actions[bot]sethmlarson
github-actions[bot]
and
sethmlarson
authored
[8.0] Add migration guide from 7.x to 8.0
Co-authored-by: Seth Michael Larson <seth.larson@elastic.co>
1 parent 25d3705 commit 0f09355

File tree

3 files changed

+221
-1
lines changed

3 files changed

+221
-1
lines changed

‎docs/guide/configuration.asciidoc

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,7 @@ es = Elasticsearch(
124124
------------------------------------
125125

126126
HTTP compression is recommended to be enabled when requests are traversing the network.
127+
Compression is automatically enabled when connecting to Elastic Cloud.
127128

128129

129130
[discrete]
@@ -270,7 +271,51 @@ To avoid needlessly sniffing too often there is a delay between attempts to disc
270271
[discrete]
271272
==== Filtering nodes which are sniffed
272273

273-
By default nodes which are marked with only a `master` role will not be used. To change the behavior the parameter `sniff_node_filter`
274+
By default nodes which are marked with only a `master` role will not be used. To change the behavior the parameter `sniffed_node_callback` can be used. To mark a sniffed node not to be added to the node pool
275+
return `None` from the `sniffed_node_callback`, otherwise return a `NodeConfig` instance.
276+
277+
[source,python]
278+
------------------------------------
279+
from typing import Optional, Dict, Any
280+
from elastic_transport import NodeConfig
281+
from elasticsearch import Elasticsearch
282+
283+
def filter_master_eligible_nodes(
284+
node_info: Dict[str, Any],
285+
node_config: NodeConfig
286+
) -> Optional[NodeConfig]:
287+
# This callback ignores all nodes that are master eligible
288+
# instead of master-only nodes (default behavior)
289+
if "master" in node_info.get("roles", ()):
290+
return None
291+
return node_config
292+
293+
client = Elasticsearch(
294+
"https://localhost:9200",
295+
sniffed_node_callback=filter_master_eligible_nodes
296+
)
297+
------------------------------------
298+
299+
The `node_info` parameter is part of the response from the `nodes.info()` API, below is an example
300+
of what that object looks like:
301+
302+
[source,json]
303+
------------------------------------
304+
{
305+
"name": "SRZpKFZ",
306+
"transport_address": "127.0.0.1:9300",
307+
"host": "127.0.0.1",
308+
"ip": "127.0.0.1",
309+
"version": "5.0.0",
310+
"build_hash": "253032b",
311+
"roles": ["master", "data", "ingest"],
312+
"http": {
313+
"bound_address": ["[fe80::1]:9200", "[::1]:9200", "127.0.0.1:9200"],
314+
"publish_address": "1.1.1.1:123",
315+
"max_content_length_in_bytes": 104857600
316+
}
317+
}
318+
------------------------------------
274319

275320

276321
[discrete]

‎docs/guide/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ include::connecting.asciidoc[]
1212

1313
include::configuration.asciidoc[]
1414

15+
include::migration.asciidoc[]
16+
1517
include::integrations.asciidoc[]
1618

1719
include::examples.asciidoc[]

‎docs/guide/migration.asciidoc

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
[[migration]]
2+
== Migrating to 8.0
3+
4+
The client has major changes that require changes to how you use the client.
5+
Below outlines all the changes you'll have to take into account when upgrading
6+
from 7.x to 8.0.
7+
8+
* <<migration-compat-mode>>
9+
* <<migration-upgrade-client>>
10+
* <<migration-remove-deprecations>>
11+
** <<migration-strict-client-config>>
12+
** <<migration-keyword-only-args>>
13+
** <<migration-options>>
14+
15+
[discrete]
16+
[[migration-compat-mode]]
17+
=== Enable compatibility mode and upgrade Elasticsearch
18+
19+
Upgrade your Elasticsearch client to 7.16:
20+
21+
[source,bash]
22+
------------------------------------
23+
$ python -m pip install 'elasticsearch>=7.16,<8'
24+
------------------------------------
25+
26+
If you have an existing application enable the compatibility mode
27+
by setting `ELASTIC_CLIENT_APIVERSIONING=1` environment variable.
28+
This will instruct the Elasticsearch server to accept and respond
29+
with 7.x-compatibile requests and responses.
30+
31+
After you've done this you can upgrade Elasticsearch to 8.0.
32+
33+
[discrete]
34+
[[migration-upgrade-client]]
35+
=== Upgrading the client
36+
37+
After you've deployed your application with the 7.16 client and
38+
using an 8.0 Elasticsearch server you can upgrade your client to
39+
be 8.0.
40+
41+
[source,bash]
42+
------------------------------------
43+
$ python -m pip install 'elasticsearch>=8,<9'
44+
------------------------------------
45+
46+
[discrete]
47+
[[migration-remove-deprecations]]
48+
=== Removing deprecation warnings
49+
50+
You'll likely notice after upgrading the client to 8.0 your code is
51+
either raising errors or `DeprecationWarning` to signal where you need
52+
to change your code before using the 8.0 client.
53+
54+
[discrete]
55+
[[migration-strict-client-config]]
56+
==== Strict client configuration
57+
58+
Previously the client would use `scheme="http"`, `host="localhost"`, and `port=9200` defaults
59+
when specifying which node(s) to connect to. Starting in 8.0 these defaults have been removed
60+
and instead require explicit configuration of scheme, host, and port.
61+
62+
This choice was made because in Elasticsearch 8.0 HTTPS is enabled by default, so it's no
63+
longer a good assumption that `http://localhost:9200` is a locally running cluster.
64+
65+
See documentation on <<connecting, connecting to Elasticsearch>> and <<tls-and-ssl, configuring HTTPS>>.
66+
67+
68+
[discrete]
69+
[[migration-keyword-only-args]]
70+
==== Keyword-only arguments for APIs
71+
72+
APIs used to support both positional and keyword arguments, however
73+
using **keyword-only arguments was always recommended** in the documentation.
74+
Starting in 7.14 using positional arguments would raise a `DeprecationWarning` but would still work.
75+
76+
Now starting in 8.0 keyword-only arguments are now required for APIs for better forwards-compatibility
77+
with new API options. When attempting to use positional arguments a `TypeError` will be raised.
78+
79+
[source,python]
80+
------------------------------------
81+
# 8.0+ SUPPORTED USAGE:
82+
client.indices.get(index="*")
83+
84+
# 7.x UNSUPPORTED USAGE (Don't do this!):
85+
client.indices.get("*")
86+
------------------------------------
87+
88+
89+
[discrete]
90+
[[migration-options]]
91+
==== Start using .options()
92+
93+
Previously some per-request options like `api_key` and `ignore` were allowed within
94+
client API methods. Starting in 8.0 this is deprecated for all APIs and for a small
95+
number of APIs may break in unexpected ways if not changed.
96+
97+
The parameters `headers`, `params`, `api_key`, `http_auth`, `opaque_id`, `request_timeout`, and `ignore`
98+
are effected:
99+
100+
[source,python]
101+
------------------------------------
102+
from elasticsearch import Elasticsearch
103+
104+
client = Elasticsearch("http://localhost:9200")
105+
106+
# 8.0+ SUPPORTED USAGE:
107+
client.options(api_key=("id", "api_key")).search(index="blogs")
108+
109+
# 7.x DEPRECATED USAGE (Don't do this!):
110+
client.search(index="blogs", api_key=("id", "api_key"))
111+
------------------------------------
112+
113+
Some of these parameters have been renamed to be more readable and to fit other APIs.
114+
`ignore` should be `ignore_status` and `http_auth` should be `basic_auth`:
115+
116+
[source,python]
117+
------------------------------------
118+
# 8.0+ SUPPORTED USAGES:
119+
client.options(basic_auth=("username", "password")).search(...)
120+
client.options(ignore_status=404).indices.delete(index=...)
121+
122+
# 7.x DEPRECATED USAGES (Don't do this!):
123+
client.search(http_auth=("username", "password"), ...)
124+
client.indices.delete(index=..., ignore=404)
125+
------------------------------------
126+
127+
APIs where this change is breaking and doesn't have a deprecation period due to conflicts
128+
between the client API and Elasticsearch's API:
129+
130+
- `sql.query` using `request_timeout`
131+
- `security.grant_api_key` using `api_key`
132+
- `render_search_template` using `params`
133+
- `search_template` using `params`
134+
135+
You should immediately evaluate the usage of these parameters and start using `.options(...)`
136+
to avoid unexpected behavior. Below is an example of migrating away from using per-request `api_key`
137+
with the `security.grant_api_key` API:
138+
139+
[source,python]
140+
------------------------------------
141+
# 8.0+ SUPPORTED USAGES:
142+
resp = (
143+
client.options(
144+
# This is the API key being used for the request
145+
api_key=("request-id", "request-api-key")
146+
).security.grant_api_key(
147+
# This is the API key being granted
148+
api_key={
149+
"name": "granted-api-key"
150+
},
151+
grant_type="password",
152+
username="elastic",
153+
password="changeme"
154+
)
155+
)
156+
157+
# 7.x DEPRECATED USAGES (Don't do this!):
158+
resp = (
159+
# This is the API key being used for the request
160+
client.security.grant_api_key(
161+
api_key=("request-id", "request-api-key"),
162+
# This is the API key being granted
163+
body={
164+
"api_key": {
165+
"name": "granted-api-key"
166+
},
167+
"grant_type": "password",
168+
"username": "elastic",
169+
"password": "changeme"
170+
}
171+
)
172+
)
173+
------------------------------------

0 commit comments

Comments
 (0)