673 lines
18 KiB
Plaintext
673 lines
18 KiB
Plaintext
[[client-connecting]]
|
||
== Connecting
|
||
|
||
This page contains the information you need to connect and use the Client with
|
||
{es}.
|
||
|
||
**On this page**
|
||
|
||
* <<authentication, Authentication options>>
|
||
* <<client-usage, Using the client>>
|
||
* <<client-faas-env, Using the Client in a Function-as-a-Service Environment>>
|
||
* <<client-connect-proxy, Connecting through a proxy>>
|
||
* <<client-error-handling, Handling errors>>
|
||
* <<product-check, Automatic product check>>
|
||
|
||
[[authentication]]
|
||
[discrete]
|
||
=== Authentication
|
||
|
||
This document contains code snippets to show you how to connect to various {es}
|
||
providers.
|
||
|
||
|
||
[discrete]
|
||
[[auth-ec]]
|
||
==== Elastic Cloud
|
||
|
||
If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers
|
||
an easy way to connect to it via the `cloud` option. You must pass the Cloud ID
|
||
that you can find in the cloud console, then your username and password inside
|
||
the `auth` option.
|
||
|
||
NOTE: When connecting to Elastic Cloud, the client will automatically enable
|
||
both request and response compression by default, since it yields significant
|
||
throughput improvements. Moreover, the client will also set the tls option
|
||
`secureProtocol` to `TLSv1_2_method` unless specified otherwise. You can still
|
||
override this option by configuring them.
|
||
|
||
IMPORTANT: Do not enable sniffing when using Elastic Cloud, since the nodes are
|
||
behind a load balancer, Elastic Cloud will take care of everything for you.
|
||
Take a look https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[here]
|
||
to know more.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
cloud: {
|
||
id: '<cloud-id>'
|
||
},
|
||
auth: {
|
||
username: 'elastic',
|
||
password: 'changeme'
|
||
}
|
||
})
|
||
----
|
||
|
||
[discrete]
|
||
[[connect-self-managed-new]]
|
||
=== Connecting to a self-managed cluster
|
||
|
||
By default {es} will start with security features like authentication and TLS
|
||
enabled. To connect to the {es} cluster you'll need to configure the Node.js {es}
|
||
client to use HTTPS with the generated CA certificate in order to make requests
|
||
successfully.
|
||
|
||
If you're just getting started with {es} we recommend reading the documentation
|
||
on https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html[configuring]
|
||
and
|
||
https://www.elastic.co/guide/en/elasticsearch/reference/current/starting-elasticsearch.html[starting {es}]
|
||
to ensure your cluster is running as expected.
|
||
|
||
When you start {es} for the first time you'll see a distinct block like the one
|
||
below in the output from {es} (you may have to scroll up if it's been a while):
|
||
|
||
[source,sh]
|
||
----
|
||
|
||
-> Elasticsearch security features have been automatically configured!
|
||
-> Authentication is enabled and cluster connections are encrypted.
|
||
|
||
-> Password for the elastic user (reset with `bin/elasticsearch-reset-password -u elastic`):
|
||
lhQpLELkjkrawaBoaz0Q
|
||
|
||
-> HTTP CA certificate SHA-256 fingerprint:
|
||
a52dd93511e8c6045e21f16654b77c9ee0f34aea26d9f40320b531c474676228
|
||
...
|
||
|
||
----
|
||
|
||
Depending on the circumstances there are two options for verifying the HTTPS
|
||
connection, either verifying with the CA certificate itself or via the HTTP CA
|
||
certificate fingerprint.
|
||
|
||
[discrete]
|
||
[[auth-tls]]
|
||
==== TLS configuration
|
||
|
||
The generated root CA certificate can be found in the `certs` directory in your
|
||
{es} config location (`$ES_CONF_PATH/certs/http_ca.crt`). If you're running {es}
|
||
in Docker there is
|
||
https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html[additional documentation for retrieving the CA certificate].
|
||
|
||
Without any additional configuration you can specify `https://` node urls, and
|
||
the certificates used to sign these requests will be verified. To turn off
|
||
certificate verification, you must specify an `tls` object in the top level
|
||
config and set `rejectUnauthorized: false`. The default `tls` values are the
|
||
same that Node.js's https://nodejs.org/api/tls.html#tls_tls_connect_options_callback[`tls.connect()`]
|
||
uses.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
username: 'elastic',
|
||
password: 'changeme'
|
||
},
|
||
tls: {
|
||
ca: fs.readFileSync('./http_ca.crt'),
|
||
rejectUnauthorized: false
|
||
}
|
||
})
|
||
----
|
||
|
||
[discrete]
|
||
[[auth-ca-fingerprint]]
|
||
==== CA fingerprint
|
||
|
||
You can configure the client to only trust certificates that are signed by a specific CA certificate
|
||
(CA certificate pinning) by providing a `caFingerprint` option.
|
||
This will verify that the fingerprint of the CA certificate that has signed
|
||
the certificate of the server matches the supplied value.
|
||
You must configure a SHA256 digest.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://example.com'
|
||
auth: { ... },
|
||
// the fingerprint (SHA256) of the CA certificate that is used to sign
|
||
// the certificate that the Elasticsearch node presents for TLS.
|
||
caFingerprint: '20:0D:CA:FA:76:...',
|
||
tls: {
|
||
// might be required if it's a self-signed certificate
|
||
rejectUnauthorized: false
|
||
}
|
||
})
|
||
----
|
||
|
||
The certificate fingerprint can be calculated using `openssl x509` with the
|
||
certificate file:
|
||
|
||
[source,sh]
|
||
----
|
||
openssl x509 -fingerprint -sha256 -noout -in /path/to/http_ca.crt
|
||
----
|
||
|
||
If you don't have access to the generated CA file from {es} you can use the
|
||
following script to output the root CA fingerprint of the {es} instance with
|
||
`openssl s_client`:
|
||
|
||
[source,sh]
|
||
----
|
||
# Replace the values of 'localhost' and '9200' to the
|
||
# corresponding host and port values for the cluster.
|
||
openssl s_client -connect localhost:9200 -servername localhost -showcerts </dev/null 2>/dev/null \
|
||
| openssl x509 -fingerprint -sha256 -noout -in /dev/stdin
|
||
----
|
||
|
||
The output of `openssl x509` will look something like this:
|
||
|
||
[source,sh]
|
||
----
|
||
SHA256 Fingerprint=A5:2D:D9:35:11:E8:C6:04:5E:21:F1:66:54:B7:7C:9E:E0:F3:4A:EA:26:D9:F4:03:20:B5:31:C4:74:67:62:28
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[connect-no-security]]
|
||
=== Connecting without security enabled
|
||
|
||
WARNING: Running {es} without security enabled is not recommended.
|
||
|
||
If your cluster is configured with
|
||
https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html[security explicitly disabled]
|
||
then you can connect via HTTP:
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'http://example.com'
|
||
})
|
||
----
|
||
|
||
[discrete]
|
||
[[auth-strategies]]
|
||
=== Authentication strategies
|
||
|
||
Following you can find all the supported authentication strategies.
|
||
|
||
[discrete]
|
||
[[auth-apikey]]
|
||
==== ApiKey authentication
|
||
|
||
You can use the
|
||
{ref-7x}/security-api-create-api-key.html[ApiKey]
|
||
authentication by passing the `apiKey` parameter via the `auth` option. The
|
||
`apiKey` parameter can be either a base64 encoded string or an object with the
|
||
values that you can obtain from the
|
||
{ref-7x}/security-api-create-api-key.html[create api key endpoint].
|
||
|
||
NOTE: If you provide both basic authentication credentials and the ApiKey
|
||
configuration, the ApiKey takes precedence.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
apiKey: 'base64EncodedKey'
|
||
}
|
||
})
|
||
----
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
apiKey: {
|
||
id: 'foo',
|
||
api_key: 'bar'
|
||
}
|
||
}
|
||
})
|
||
----
|
||
|
||
[discrete]
|
||
[[auth-bearer]]
|
||
==== Bearer authentication
|
||
|
||
You can provide your credentials by passing the `bearer` token
|
||
parameter via the `auth` option.
|
||
Useful for https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-service-token.html[service account tokens].
|
||
Be aware that it does not handle automatic token refresh.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
bearer: 'token'
|
||
}
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[auth-basic]]
|
||
==== Basic authentication
|
||
|
||
You can provide your credentials by passing the `username` and `password`
|
||
parameters via the `auth` option.
|
||
|
||
NOTE: If you provide both basic authentication credentials and the Api Key
|
||
configuration, the Api Key will take precedence.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://localhost:9200',
|
||
auth: {
|
||
username: 'elastic',
|
||
password: 'changeme'
|
||
}
|
||
})
|
||
----
|
||
|
||
|
||
Otherwise, you can provide your credentials in the node(s) URL.
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
node: 'https://username:password@localhost:9200'
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[client-usage]]
|
||
=== Usage
|
||
|
||
Using the client is straightforward, it supports all the public APIs of {es},
|
||
and every method exposes the same signature.
|
||
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
cloud: { id: '<cloud-id>' },
|
||
auth: { apiKey: 'base64EncodedKey' }
|
||
})
|
||
|
||
const result = await client.search({
|
||
index: 'my-index',
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
})
|
||
----
|
||
|
||
The returned value of every API call is the response body from {es}.
|
||
If you need to access additonal metadata, such as the status code or headers,
|
||
you must specify `meta: true` in the request options:
|
||
|
||
[source,js]
|
||
----
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
cloud: { id: '<cloud-id>' },
|
||
auth: { apiKey: 'base64EncodedKey' }
|
||
})
|
||
|
||
const result = await client.search({
|
||
index: 'my-index',
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}, { meta: true })
|
||
----
|
||
|
||
In this case, the result will be:
|
||
[source,ts]
|
||
----
|
||
{
|
||
body: object | boolean
|
||
statusCode: number
|
||
headers: object
|
||
warnings: [string],
|
||
meta: object
|
||
}
|
||
----
|
||
|
||
NOTE: The body is a boolean value when you use `HEAD` APIs.
|
||
|
||
[discrete]
|
||
==== Aborting a request
|
||
|
||
If needed, you can abort a running request by using the `AbortController` standard.
|
||
|
||
CAUTION: If you abort a request, the request will fail with a
|
||
`RequestAbortedError`.
|
||
|
||
|
||
[source,js]
|
||
----
|
||
const AbortController = require('node-abort-controller')
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
const client = new Client({
|
||
cloud: { id: '<cloud-id>' },
|
||
auth: { apiKey: 'base64EncodedKey' }
|
||
})
|
||
|
||
const abortController = new AbortController()
|
||
setImmediate(() => abortController.abort())
|
||
|
||
const result = await client.search({
|
||
index: 'my-index',
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}, { signal: abortController.signal })
|
||
----
|
||
|
||
[discrete]
|
||
==== Request specific options
|
||
|
||
If needed you can pass request specific options in a second object:
|
||
|
||
[source,js]
|
||
----
|
||
const result = await client.search({
|
||
index: 'my-index',
|
||
body: {
|
||
query: {
|
||
match: { hello: 'world' }
|
||
}
|
||
}
|
||
}, {
|
||
ignore: [404],
|
||
maxRetries: 3
|
||
})
|
||
----
|
||
|
||
|
||
The supported request specific options are:
|
||
[cols=2*]
|
||
|===
|
||
|`ignore`
|
||
|`[number]` - HTTP status codes which should not be considered errors for this request. +
|
||
_Default:_ `null`
|
||
|
||
|`requestTimeout`
|
||
|`number` - Max request timeout for the request in milliseconds, it overrides the client default. +
|
||
_Default:_ `30000`
|
||
|
||
|`maxRetries`
|
||
|`number` - Max number of retries for the request, it overrides the client default. +
|
||
_Default:_ `3`
|
||
|
||
|`compression`
|
||
|`string, boolean` - Enables body compression for the request. +
|
||
_Options:_ `false`, `'gzip'` +
|
||
_Default:_ `false`
|
||
|
||
|`asStream`
|
||
|`boolean` - Instead of getting the parsed body back, you get the raw Node.js stream of data. +
|
||
_Default:_ `false`
|
||
|
||
|`headers`
|
||
|`object` - Custom headers for the request. +
|
||
_Default:_ `null`
|
||
|
||
|`querystring`
|
||
|`object` - Custom querystring for the request. +
|
||
_Default:_ `null`
|
||
|
||
|`id`
|
||
|`any` - Custom request id. _(overrides the top level request id generator)_ +
|
||
_Default:_ `null`
|
||
|
||
|`context`
|
||
|`any` - Custom object per request. _(you can use it to pass data to the clients events)_ +
|
||
_Default:_ `null`
|
||
|
||
|`maxResponseSize`
|
||
|`number` - When configured, it verifies that the uncompressed response size is lower than the configured number, if it's higher it will abort the request. It cannot be higher than buffer.constants.MAX_STRING_LENTGH +
|
||
_Default:_ `null`
|
||
|
||
|`maxCompressedResponseSize`
|
||
|`number` - When configured, it verifies that the compressed response size is lower than the configured number, if it's higher it will abort the request. It cannot be higher than buffer.constants.MAX_LENTGH +
|
||
_Default:_ `null`
|
||
|
||
|`signal`
|
||
|`AbortSignal` - The AbortSignal instance to allow request abortion. +
|
||
_Default:_ `null`
|
||
|
||
|===
|
||
|
||
[discrete]
|
||
[[client-faas-env]]
|
||
=== Using the Client in a Function-as-a-Service Environment
|
||
|
||
This section illustrates the best practices for leveraging the {es} client in a Function-as-a-Service (FaaS) environment.
|
||
The most influential optimization is to initialize the client outside of the function, the global scope.
|
||
This practice does not only improve performance but also enables background functionality as – for example – https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[sniffing].
|
||
The following examples provide a skeleton for the best practices.
|
||
|
||
[discrete]
|
||
==== GCP Cloud Functions
|
||
|
||
[source,js]
|
||
----
|
||
'use strict'
|
||
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
|
||
const client = new Client({
|
||
// client initialisation
|
||
})
|
||
|
||
exports.testFunction = async function (req, res) {
|
||
// use the client
|
||
}
|
||
----
|
||
|
||
[discrete]
|
||
==== AWS Lambda
|
||
|
||
[source,js]
|
||
----
|
||
'use strict'
|
||
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
|
||
const client = new Client({
|
||
// client initialisation
|
||
})
|
||
|
||
exports.handler = async function (event, context) {
|
||
// use the client
|
||
}
|
||
----
|
||
|
||
[discrete]
|
||
==== Azure Functions
|
||
|
||
[source,js]
|
||
----
|
||
'use strict'
|
||
|
||
const { Client } = require('@elastic/elasticsearch')
|
||
|
||
const client = new Client({
|
||
// client initialisation
|
||
})
|
||
|
||
module.exports = async function (context, req) {
|
||
// use the client
|
||
}
|
||
----
|
||
|
||
Resources used to assess these recommendations:
|
||
|
||
- https://cloud.google.com/functions/docs/bestpractices/tips#use_global_variables_to_reuse_objects_in_future_invocations[GCP Cloud Functions: Tips & Tricks]
|
||
- https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html[Best practices for working with AWS Lambda functions]
|
||
- https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-python?tabs=azurecli-linux%2Capplication-level#global-variables[Azure Functions Python developer guide]
|
||
- https://docs.aws.amazon.com/lambda/latest/operatorguide/global-scope.html[AWS Lambda: Comparing the effect of global scope]
|
||
|
||
|
||
[discrete]
|
||
[[client-connect-proxy]]
|
||
=== Connecting through a proxy
|
||
|
||
~Added~ ~in~ ~`v7.10.0`~
|
||
|
||
If you need to pass through an http(s) proxy for connecting to {es}, the client
|
||
out of the box offers a handy configuration for helping you with it. Under the
|
||
hood, it uses the https://github.com/delvedor/hpagent[`hpagent`] module.
|
||
|
||
In versions 8.0+ of the client, the default `Connection` type is set to `UndiciConnection`, which does not support proxy configurations.
|
||
To use a proxy, you will need to use the `HttpConnection` class from `@elastic/transport` instead.
|
||
|
||
[source,js]
|
||
----
|
||
import { HttpConnection } from '@elastic/transport'
|
||
|
||
const client = new Client({
|
||
node: 'http://localhost:9200',
|
||
proxy: 'http://localhost:8080',
|
||
Connection: HttpConnection,
|
||
})
|
||
----
|
||
|
||
Basic authentication is supported as well:
|
||
|
||
[source,js]
|
||
----
|
||
const client = new Client({
|
||
node: 'http://localhost:9200',
|
||
proxy: 'http:user:pwd@//localhost:8080',
|
||
Connection: HttpConnection,
|
||
})
|
||
----
|
||
|
||
If you are connecting through a non-http(s) proxy, such as a `socks5` or `pac`,
|
||
you can use the `agent` option to configure it.
|
||
|
||
[source,js]
|
||
----
|
||
const SocksProxyAgent = require('socks-proxy-agent')
|
||
const client = new Client({
|
||
node: 'http://localhost:9200',
|
||
agent () {
|
||
return new SocksProxyAgent('socks://127.0.0.1:1080')
|
||
},
|
||
Connection: HttpConnection,
|
||
})
|
||
----
|
||
|
||
|
||
[discrete]
|
||
[[client-error-handling]]
|
||
=== Error handling
|
||
|
||
The client exposes a variety of error objects that you can use to enhance your
|
||
error handling. You can find all the error objects inside the `errors` key in
|
||
the client.
|
||
|
||
[source,js]
|
||
----
|
||
const { errors } = require('@elastic/elasticsearch')
|
||
console.log(errors)
|
||
----
|
||
|
||
|
||
You can find the errors exported by the client in the table below.
|
||
|
||
[cols=3*]
|
||
|===
|
||
|*Error*
|
||
|*Description*
|
||
|*Properties*
|
||
|
||
|`ElasticsearchClientError`
|
||
|Every error inherits from this class, it is the basic error generated by the client.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
|
||
|`TimeoutError`
|
||
|Generated when a request exceeds the `requestTimeout` option.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`ConnectionError`
|
||
|Generated when an error occurs during the request, it can be a connection error or a malformed stream of data.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`RequestAbortedError`
|
||
|Generated if the user calls the `request.abort()` method.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`NoLivingConnectionsError`
|
||
|Given the configuration, the ConnectionPool was not able to find a usable Connection for this request.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
|
||
|`SerializationError`
|
||
|Generated if the serialization fails.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `data` - `object`, the object to serialize
|
||
|
||
|`DeserializationError`
|
||
|Generated if the deserialization fails.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `data` - `string`, the string to deserialize
|
||
|
||
|`ConfigurationError`
|
||
|Generated if there is a malformed configuration or parameter.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
|
||
|`ResponseError`
|
||
|Generated when in case of a `4xx` or `5xx` response.
|
||
a|* `name` - `string`
|
||
* `message` - `string`
|
||
* `meta` - `object`, contains all the information about the request
|
||
* `body` - `object`, the response body
|
||
* `statusCode` - `object`, the response headers
|
||
* `headers` - `object`, the response status code
|
||
|===
|
||
|
||
[discrete]
|
||
[[product-check]]
|
||
=== Automatic product check
|
||
|
||
Since v7.14.0, the client performs a required product check before the first call.
|
||
This pre-flight product check allows the client to establish the version of Elasticsearch
|
||
that it is communicating with. The product check requires one additional HTTP request to
|
||
be sent to the server as part of the request pipeline before the main API call is sent.
|
||
In most cases, this will succeed during the very first API call that the client sends.
|
||
Once the product check completes, no further product check HTTP requests are sent for
|
||
subsequent API calls.
|