Default Values¶
Client Configuration¶
The Builder
class expects either a dict
(configdict) or a YAML file
(configfile) of configuration settings. Whichever is used, both must contain the top level key:
elasticsearch
. The top level key logging
is also acceptable as outlined.
This is an example of what the structure looks like with many keys present (some contradictory, but shown for reference):
{
'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': ...
}
},
},
'logging': {
'loglevel': 'INFO',
'logfile': ...,
'logformat': 'default',
'blacklist': ['elastic_transport', 'urllib3']
},
}
The next level keys are further described below.
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:
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:
bool
: (Optional)es_client
should only connect to versions covered. If set toTrue
, this will ignore those limitations and attempt to connect regardless.- username:
int
: (Optional) If bothusername
andpassword
are provided, they will be used to create the necessarytuple
forbasic_auth
. An exception will be thrown if only one is provided.- password:
int
: (Optional) If bothusername
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:
dict
: (Optional) Can only contain the sub-keystoken
,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:
int
: (Optional) Cloud ID as provided by Elastic Cloud or ECE. This is mutually exclusive ofhosts
, 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 adict
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: valueN- connections_per_node:
int
: (Optional) Number of connections allowed per node. Replaces formermaxsize
parameter.- http_compress:
bool
: (Optional) Whether to compress http traffic or not.- verify_certs:
bool
: (Optional) Whether to verify certificates or not.- ca_certs:
int
: (Optional) optional path to CA bundle. If using https scheme andca_certs
is not configured,es_client
will automatically usecertifi
provided certificates.- client_cert:
int
: (Optional) path to the file containing the private key and the certificate, or cert only if usingclient_key
- client_key:
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:
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 inhost
. 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:
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:
int
: Minimum acceptable TLS/SSL version- ssl_context:
ssl.SSLContext
: Pre-configuredssl.SSLContext
OBJECT. If this valueis given then no other TLS options (besidesssl_assert_fingerprint
) can be set on theNodeConfig
.- ssl_show_warn:
bool
: (Optional)- request_timeout:
float
: (Optional) If unset, the default value fromElasticsearch
is used, which is 10.0 seconds.
Constants and Settings¶
Default values and constants shown here are used throughought the code.
- es_client.defaults.KEYS_TO_REDACT: Sequence[str] = ['password', 'basic_auth', 'bearer_auth', 'api_key', 'id', 'opaque_id']¶
When doing configuration Schema validation, redact the value from any listed dictionary key. This only happens if logging is at DEBUG level.
- es_client.defaults.CLIENT_SETTINGS¶
Valid argument/option names for
Elasticsearch
. Too large to show
- es_client.defaults.OTHER_SETTINGS: Sequence[str] = ['master_only', 'skip_version_test', 'username', 'password', 'api_key']¶
Valid option names for
Builder
’s other settings
- es_client.defaults.CLICK_SETTINGS¶
Default settings used for building
click.Option
. Too large to show.
- es_client.defaults.ES_DEFAULT: Dict = {'elasticsearch': {'client': {'hosts': ['http://127.0.0.1:9200']}}}¶
Default settings for
Builder
- es_client.defaults.LOGDEFAULTS: Dict = {'blacklist': None, 'logfile': None, 'logformat': None, 'loglevel': None}¶
All logging defaults in a single combined dictionary
- es_client.defaults.LOGGING_SETTINGS¶
Default logging settings used for building
click.Option
. Too large to show.
- es_client.defaults.SHOW_OPTION: Dict[str, bool] = {'hidden': False}¶
Override value to “unhide” a
click.Option
- es_client.defaults.SHOW_ENVVAR: Dict[str, bool] = {'show_envvar': True}¶
Override value to make Click’s help output show the associated environment variable
- es_client.defaults.config_logging() Schema ¶
- Returns:
A validation schema of all acceptable logging configuration parameter names and values with defaults for unset parameters.
- Return type:
Logging schema with defaults:
logging: loglevel: INFO logfile: None logformat: default blacklist: ['elastic_transport', 'urllib3']