From e04e40d45513221937e3d9577961547430406a74 Mon Sep 17 00:00:00 2001 From: Tomas Della Vedova Date: Mon, 28 Mar 2022 12:22:47 +0200 Subject: [PATCH] Update connecting documentation (#1666) --- README.md | 15 +- docs/advanced-config.asciidoc | 12 +- docs/basic-config.asciidoc | 5 +- docs/child.asciidoc | 5 +- docs/connecting.asciidoc | 214 +++++++++++++++++------ docs/examples/asStream.asciidoc | 10 +- docs/examples/bulk.asciidoc | 3 +- docs/examples/exists.asciidoc | 5 +- docs/examples/get.asciidoc | 5 +- docs/examples/ignore.asciidoc | 5 +- docs/examples/msearch.asciidoc | 5 +- docs/examples/reindex.asciidoc | 5 +- docs/examples/scroll.asciidoc | 10 +- docs/examples/search.asciidoc | 5 +- docs/examples/sql.query.asciidoc | 5 +- docs/examples/suggest.asciidoc | 5 +- docs/examples/transport.request.asciidoc | 5 +- docs/examples/update.asciidoc | 10 +- docs/examples/update_by_query.asciidoc | 5 +- docs/helpers.asciidoc | 25 ++- docs/introduction.asciidoc | 15 +- docs/observability.asciidoc | 30 +++- docs/testing.asciidoc | 3 +- docs/transport.asciidoc | 3 +- docs/typescript.asciidoc | 5 +- 25 files changed, 315 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index 69c410c12..9fb9abc44 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,10 @@ We recommend that you write a lightweight proxy that uses this client instead, y 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { // Let's start by indexing some data @@ -165,8 +168,14 @@ You will require the packages from your code by using the alias you have defined const { Client: Client6 } = require('es6') const { Client: Client7 } = require('es7') -const client6 = new Client6({ node: 'http://localhost:9200' }) -const client7 = new Client7({ node: 'http://localhost:9201' }) +const client6 = new Client6({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) +const client7 = new Client7({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) client6.info().then(console.log, console.log) client7.info().then(console.log, console.log) diff --git a/docs/advanced-config.asciidoc b/docs/advanced-config.asciidoc index 34eb3d750..3dcbb5692 100644 --- a/docs/advanced-config.asciidoc +++ b/docs/advanced-config.asciidoc @@ -30,7 +30,9 @@ class MyConnectionPool extends ConnectionPool { } const client = new Client({ - ConnectionPool: MyConnectionPool + ConnectionPool: MyConnectionPool, + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } }) ---- @@ -54,7 +56,9 @@ class MyConnection extends BaseConnection { } const client = new Client({ - Connection: MyConnection + Connection: MyConnection, + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } }) ---- @@ -81,7 +85,9 @@ class MySerializer extends Serializer { } const client = new Client({ - Serializer: MySerializer + Serializer: MySerializer, + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } }) ---- diff --git a/docs/basic-config.asciidoc b/docs/basic-config.asciidoc index 536dfead4..04ca7b1ee 100644 --- a/docs/basic-config.asciidoc +++ b/docs/basic-config.asciidoc @@ -10,7 +10,8 @@ offers. const { Client } = require('@elastic/elasticsearch') const client = new Client({ - node: 'http://localhost:9200', + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } maxRetries: 5, requestTimeout: 60000, sniffOnStart: true @@ -241,7 +242,7 @@ _Cloud configuration example:_ ---- const client = new Client({ cloud: { - id: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA==' + id: '' }, auth: { username: 'elastic', diff --git a/docs/child.asciidoc b/docs/child.asciidoc index 5e1abdee7..0bd7ace21 100644 --- a/docs/child.asciidoc +++ b/docs/child.asciidoc @@ -22,7 +22,10 @@ will be closed. [source,js] ---- const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const child = client.child({ headers: { 'x-foo': 'bar' }, requestTimeout: 1000 diff --git a/docs/connecting.asciidoc b/docs/connecting.asciidoc index 282e12512..239eea79e 100644 --- a/docs/connecting.asciidoc +++ b/docs/connecting.asciidoc @@ -46,7 +46,7 @@ to know more. const { Client } = require('@elastic/elasticsearch') const client = new Client({ cloud: { - id: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA==', + id: '' }, auth: { username: 'elastic', @@ -55,6 +55,152 @@ const client = new Client({ }) ---- +[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 \ + | 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]] @@ -150,57 +296,6 @@ const client = new Client({ ---- -[discrete] -[[auth-tls]] -==== TLS configuration - -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('./cacert.pem'), - 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. -a `caFingerprint` option, which will verify the supplied certificate authority fingerprint. -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 - } -}) ----- - - [discrete] [[client-usage]] === Usage @@ -212,7 +307,10 @@ and every method exposes the same signature. [source,js] ---- const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const result = await client.search({ index: 'my-index', @@ -229,7 +327,10 @@ you must specify `meta: true` in the request options: [source,js] ---- const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const result = await client.search({ index: 'my-index', @@ -266,7 +367,10 @@ CAUTION: If you abort a request, the request will fail with a ---- const AbortController = require('node-abort-controller') const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const abortController = new AbortController() setImmediate(() => abortController.abort()) diff --git a/docs/examples/asStream.asciidoc b/docs/examples/asStream.asciidoc index dd7f9f21a..e77025fcf 100644 --- a/docs/examples/asStream.asciidoc +++ b/docs/examples/asStream.asciidoc @@ -9,7 +9,10 @@ data. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { const bulkResponse = await client.bulk({ @@ -83,7 +86,10 @@ send it directly to another source. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const fastify = require('fastify')() fastify.post('/search/:index', async (req, reply) => { diff --git a/docs/examples/bulk.asciidoc b/docs/examples/bulk.asciidoc index e7d9261be..c6117c249 100644 --- a/docs/examples/bulk.asciidoc +++ b/docs/examples/bulk.asciidoc @@ -13,7 +13,8 @@ NOTE: Did you know that we provide an helper for sending bulk request? You can f require('array.prototype.flatmap').shim() const { Client } = require('@elastic/elasticsearch') const client = new Client({ - node: 'http://localhost:9200' + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } }) async function run () { diff --git a/docs/examples/exists.asciidoc b/docs/examples/exists.asciidoc index 368f4ae2b..29a39a196 100644 --- a/docs/examples/exists.asciidoc +++ b/docs/examples/exists.asciidoc @@ -10,7 +10,10 @@ NOTE: Since this API uses the `HEAD` method, the body value will be boolean. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { await client.index({ diff --git a/docs/examples/get.asciidoc b/docs/examples/get.asciidoc index 9302c7607..f6dd94ddf 100644 --- a/docs/examples/get.asciidoc +++ b/docs/examples/get.asciidoc @@ -10,7 +10,10 @@ The following example gets a JSON document from an index called 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { await client.index({ diff --git a/docs/examples/ignore.asciidoc b/docs/examples/ignore.asciidoc index 40b570726..de5577dcd 100644 --- a/docs/examples/ignore.asciidoc +++ b/docs/examples/ignore.asciidoc @@ -8,7 +8,10 @@ HTTP status codes which should not be considered errors for this request. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { const bulkResponse = await client.bulk({ diff --git a/docs/examples/msearch.asciidoc b/docs/examples/msearch.asciidoc index 445bf866c..66222a34e 100644 --- a/docs/examples/msearch.asciidoc +++ b/docs/examples/msearch.asciidoc @@ -9,7 +9,10 @@ API. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { const bulkResponse = await client.bulk({ diff --git a/docs/examples/reindex.asciidoc b/docs/examples/reindex.asciidoc index 984e21c99..9d917dbd6 100644 --- a/docs/examples/reindex.asciidoc +++ b/docs/examples/reindex.asciidoc @@ -15,7 +15,10 @@ the house Stark and remove the `house` field from the document source. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { await client.index({ diff --git a/docs/examples/scroll.asciidoc b/docs/examples/scroll.asciidoc index 90e6e6524..5cc76d8a6 100644 --- a/docs/examples/scroll.asciidoc +++ b/docs/examples/scroll.asciidoc @@ -26,7 +26,10 @@ NOTE: Did you know that we provide an helper for sending scroll requests? You ca 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { const allQuotes = [] @@ -118,7 +121,10 @@ async iteration! 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) // Scroll utility async function * scrollSearch (params) { diff --git a/docs/examples/search.asciidoc b/docs/examples/search.asciidoc index 2cf5b3c50..229d1b09b 100644 --- a/docs/examples/search.asciidoc +++ b/docs/examples/search.asciidoc @@ -12,7 +12,10 @@ https://www.elastic.co/guide/en/elasticsearch/reference/6.6/search-request-body. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { // Let's start by indexing some data diff --git a/docs/examples/sql.query.asciidoc b/docs/examples/sql.query.asciidoc index 00505d2fd..cdf61147c 100644 --- a/docs/examples/sql.query.asciidoc +++ b/docs/examples/sql.query.asciidoc @@ -17,7 +17,10 @@ manipulate the result to obtain an object easy to navigate. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { await client.index({ diff --git a/docs/examples/suggest.asciidoc b/docs/examples/suggest.asciidoc index d4448a1a4..6096bc753 100644 --- a/docs/examples/suggest.asciidoc +++ b/docs/examples/suggest.asciidoc @@ -12,7 +12,10 @@ request. If the query part is left out, only suggestions are returned. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { const bulkResponse = await client.bulk({ diff --git a/docs/examples/transport.request.asciidoc b/docs/examples/transport.request.asciidoc index 86482046f..7c325e07e 100644 --- a/docs/examples/transport.request.asciidoc +++ b/docs/examples/transport.request.asciidoc @@ -20,7 +20,10 @@ maintain. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { const bulkResponse = await client.bulk({ diff --git a/docs/examples/update.asciidoc b/docs/examples/update.asciidoc index 784a7d6d8..3c83acd25 100644 --- a/docs/examples/update.asciidoc +++ b/docs/examples/update.asciidoc @@ -10,7 +10,10 @@ a character has said the given quote, and then we will update the `times` field. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { await client.index({ @@ -54,7 +57,10 @@ With the update API, you can also run a partial update of a document. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { await client.index({ diff --git a/docs/examples/update_by_query.asciidoc b/docs/examples/update_by_query.asciidoc index fdb198aec..d17b5c455 100644 --- a/docs/examples/update_by_query.asciidoc +++ b/docs/examples/update_by_query.asciidoc @@ -10,7 +10,10 @@ property or some other online mapping change. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { await client.index({ diff --git a/docs/helpers.asciidoc b/docs/helpers.asciidoc index f83d29144..b78f79399 100644 --- a/docs/helpers.asciidoc +++ b/docs/helpers.asciidoc @@ -27,7 +27,10 @@ const { createReadStream } = require('fs') const split = require('split2') const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const result = await client.helpers.bulk({ datasource: createReadStream('./dataset.ndjson').pipe(split()), onDocument (doc) { @@ -248,7 +251,10 @@ const { createReadStream } = require('fs') const split = require('split2') const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const b = client.helpers.bulk({ datasource: createReadStream('./dataset.ndjson').pipe(split()), onDocument (doc) { @@ -304,7 +310,10 @@ async function * generator () { } } -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const result = await client.helpers.bulk({ datasource: generator(), onDocument (doc) { @@ -338,7 +347,10 @@ sources. ---- const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const m = client.helpers.msearch() m.search( @@ -427,7 +439,10 @@ running will not be stopped. ---- const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) const m = client.helpers.msearch() m.search( diff --git a/docs/introduction.asciidoc b/docs/introduction.asciidoc index 5d8ba3cbe..83885d09e 100644 --- a/docs/introduction.asciidoc +++ b/docs/introduction.asciidoc @@ -25,7 +25,10 @@ about the features of the client. 'use strict' const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) async function run () { // Let's start by indexing some data @@ -116,8 +119,14 @@ Require the packages from your code by using the alias you have defined. const { Client: Client6 } = require('es6') const { Client: Client7 } = require('es7') -const client6 = new Client6({ node: 'http://localhost:9200' }) -const client7 = new Client7({ node: 'http://localhost:9201' }) +const client6 = new Client6({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) +const client7 = new Client7({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) client6.info().then(console.log, console.log) client7.info().then(console.log, console.log) diff --git a/docs/observability.asciidoc b/docs/observability.asciidoc index 44307f68b..c5e4d380c 100644 --- a/docs/observability.asciidoc +++ b/docs/observability.asciidoc @@ -34,7 +34,10 @@ response and error that is happening during the use of the client. ---- const logger = require('my-logger')() const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) client.diagnostic.on('response', (err, result) => { if (err) { @@ -183,7 +186,10 @@ handle this problem. [source,js] ---- const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) client.diagnostic.on('request', (err, result) => { const { id } = result.meta.request @@ -213,7 +219,8 @@ By default the id is an incremental integer, but you can configure it with the ---- const { Client } = require('@elastic/elasticsearch') const client = new Client({ - node: 'http://localhost:9200', + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' }, // it takes two parameters, the request parameters and options generateRequestId: function (params, options) { // your id generation logic @@ -246,7 +253,10 @@ can do that via the `context` option of a request: [source,js] ---- const { Client } = require('@elastic/elasticsearch') -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) client.diagnostic.on('request', (err, result) => { const { id } = result.meta.request @@ -280,7 +290,8 @@ merged, and the API level object will take precedence. ---- const { Client } = require('@elastic/elasticsearch') const client = new Client({ - node: 'http://localhost:9200', + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' }, context: { winter: 'is coming' } }) @@ -321,7 +332,8 @@ options help you in this regard. ---- const { Client } = require('@elastic/elasticsearch') const client = new Client({ - node: 'http://localhost:9200', + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' }, name: 'parent-client' // default to 'elasticsearch-js' }) @@ -377,7 +389,8 @@ resulting header will be `{ 'X-Opaque-Id': 'my-search' }`. ---- const { Client } = require('@elastic/elasticsearch') const client = new Client({ - node: 'http://localhost:9200' + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } }) client.search({ @@ -398,7 +411,8 @@ doing this, the client offers a top-level configuration option: ---- const { Client } = require('@elastic/elasticsearch') const client = new Client({ - node: 'http://localhost:9200', + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' }, opaqueIdPrefix: 'proxy-client::' }) diff --git a/docs/testing.asciidoc b/docs/testing.asciidoc index 34778ba06..35b937474 100644 --- a/docs/testing.asciidoc +++ b/docs/testing.asciidoc @@ -61,7 +61,8 @@ const Mock = require('@elastic/elasticsearch-mock') const mock = new Mock() const client = new Client({ - node: 'http://localhost:9200', + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' }, Connection: mock.getConnection() }) diff --git a/docs/transport.asciidoc b/docs/transport.asciidoc index 308e7098e..5096616ea 100644 --- a/docs/transport.asciidoc +++ b/docs/transport.asciidoc @@ -6,7 +6,8 @@ errors, it also handles sniffing. [source,js] ---- -const { Client, Transport } = require('@elastic/elasticsearch') +const { Client } = require('@elastic/elasticsearch') +const { Transport } = require('@elastic/transport') class MyTransport extends Transport { request (params, options, callback) { diff --git a/docs/typescript.asciidoc b/docs/typescript.asciidoc index eace26e63..ec4cfe288 100644 --- a/docs/typescript.asciidoc +++ b/docs/typescript.asciidoc @@ -14,7 +14,10 @@ and others may contain some errors, but we are continuously pushing fixes & impr ---- import { Client } from '@elastic/elasticsearch' -const client = new Client({ node: 'http://localhost:9200' }) +const client = new Client({ + cloud: { id: '' }, + auth: { apiKey: 'base64EncodedKey' } +}) interface Document { character: string