The :py:class:`~.esclient.Builder` class expects a raw_dict
of
configuration settings. This :py:class:`dict` should only contain one top
level key: elasticsearch
. This is an example of what the structure looks
like with many keys present (some contradictory, but shown for reference):
raw_dict = { 'elasticsearch': { 'client': { 'hosts': ..., 'request_timeout': ..., 'verify_certs': ..., 'ca_certs': ..., 'client_cert': ..., 'client_key': ..., 'ssl_version': ..., 'ssl_assert_hostname': ..., 'ssl_assert_fingerprint': ..., 'headers': { 'key1': ..., }, 'http_compress': ..., }, 'other_settings': { 'master_only': ..., 'skip_version_test': ..., 'username': ..., 'password': ..., 'api_key': { 'id': ..., 'api_key': ... 'token': ... } }, }, }
The top-level keys are further described below.
client: :py:class:`dict`: (Optional) other_settings: :py:class:`dict`: (Optional)
The acceptable sub-keys of other_settings are listed below. Anything listed as (Optional) will effectively be an empty value by default, rather than populated with the default value.
master_only: :py:class:`bool`: (Optional) Whether to execute on the elected master node or not. This has been used in the past to run a script (ostentibly Elasticsearch Curator) on every node in a cluster, but only execute if the node is the elected master. Not otherwise particularly useful, but preserved here due to its past usefulness. skip_version_test: :py:class:`bool`: (Optional) es_client
should only connect to versions covered. If set toTrue
, this will ignore those limitations and attempt to connect regardless.username: :py:class:`int`: (Optional) If both username
andpassword
are provided, they will be used to create the necessarytuple
forbasic_auth
. An exception will be thrown if only one is provided.password: :py:class:`int`: (Optional) If both username
andpassword
are provided, they will be used to create the necessarytuple
forbasic_auth
. An exception will be thrown if only one is provided.api_key: :py:class:`dict`: (Optional) Can only contain the sub-keys token
,id
, andapi_key
.token
is the base64 encoded representation ofid:api_key
. As such, iftoken
is provided, it will override anything provided inid
andapi_key
. Iftoken
is not provided, bothid
andapi_key
must be either empty/None
, or populated with the appropriate values for thehosts
orcloud_id
being connected to.
The acceptable sub-keys of client are described at https://elasticsearch-py.readthedocs.io/en/latest/api.html#module-elasticsearch. Anything listed as (Optional) will effectively be an empty value by default, rather than populated with the default value.
Anything of note regarding other options is mentioned below:
hosts:
list(str)
: (Optional) List of hosts to use for connections. (default:http://127.0.0.1:9200
)cloud_id: :py:class:`int`: (Optional) Cloud ID as provided by Elastic Cloud or ECE. This is mutually exclusive of
hosts
, and if anything but the default value ofhosts
is used in conjunction withcloud_id
it will result in an exception and will not connect.api_key:
Tuple[str, str]
: (Optional) Can be atuple
orNone
. If using thetoken
, orapi_key
subkeys ofid
andapi_key
underother_settings
, this value will be built for you automatically. Regardless, this value must be in(id, api_key)
tuple form and not Base64 form.basic_auth:
Tuple[str, str]
: (Optional) Can be atuple
orNone
. If using the subkeysusername
andpassword
underother_settings
, this value will be built for you automatically. Replaceshttp_auth
in older versions.headers:
Mapping[str, str]
: (Optional) This is a :py:class:`dict` type and should be mapped as multiple key/value pairs. If using YAML files, these should be each on its own line, e.g.:elasticsearch: client: headers: key1: value1 key2: value2 ... keyN: valueNconnections_per_node: :py:class:`int`: (Optional) Number of connections allowed per node. Replaces former
maxsize
parameter.http_compress: :py:class:`bool`: (Optional) Whether to compress http traffic or not.
verify_certs: :py:class:`bool`: (Optional) Whether to verify certificates or not.
ca_certs: :py:class:`int`: (Optional) optional path to CA bundle. If using https scheme and
ca_certs
is not configured,es_client
will automatically usecertifi
provided certificates.client_cert: :py:class:`int`: (Optional) path to the file containing the private key and the certificate, or cert only if using
client_key
client_key: :py:class:`int`: (Optional) path to the file containing the private key if using separate cert and key files (
client_cert
will contain only the cert)ssl_assert_hostname: :py:class:`int`: (Optional) Hostname or IP address to verify on the node's certificate. This is useful if the certificate contains a different value than the one supplied in
host
. An example of this situation is connecting to an IP address instead of a hostname. Set toFalse
to disable certificate hostname verification.ssl_assert_fingerprint: :py:class:`int`: SHA-256 fingerprint of the node's certificate. If this value is given then root-of-trust verification isn't done and only the node's certificate fingerprint is verified.
On CPython 3.10+ this also verifies if any certificate in the chain including the Root CA matches this fingerprint. However because this requires using private APIs support for this is experimental.
ssl_version: :py:class:`int`: Minimum acceptable TLS/SSL version
ssl_context: :py:class:`ssl.SSLContext`: Pre-configured :py:class:`ssl.SSLContext` OBJECT. If this valueis given then no other TLS options (besides
ssl_assert_fingerprint
) can be set on the :py:class:`~.elastic_transport.NodeConfig`.ssl_show_warn: :py:class:`bool`: (Optional)
request_timeout: :py:class:`float`: (Optional) If unset, the default value from :py:class:`~.elasticsearch.Elasticsearch` is used, which is 10.0 seconds.