Skip to content

Commit f35cebd

Browse files
szabostevestevejgordon
szabosteve
and
stevejgordon
authored
[DOCS] Adds Connecting section to docs (#6183) (#6193)
* [DOCS] Adds Connecting section to docs. * [DOCS] Amends ID. * [DOCS] Changes section ID. * Apply suggestions from code review Co-authored-by: Steve Gordon <sgordon@hotmail.co.uk> * [DOCS] Addresses feedback. Co-authored-by: Steve Gordon <sgordon@hotmail.co.uk> Co-authored-by: Steve Gordon <sgordon@hotmail.co.uk>
1 parent 24d1495 commit f35cebd

File tree

3 files changed

+149
-1
lines changed

3 files changed

+149
-1
lines changed

‎docs/connecting.asciidoc‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
[[connecting]]
2+
== Connecting
3+
4+
This page contains the information you need to create an instance of the .NET
5+
Client for {es} that connects to your {es} cluster.
6+
7+
It’s possible to connect to your {es} cluster via a single node, or by
8+
specifying multiple nodes using a node pool. Using a node pool has a few
9+
advantages over a single node, such as load balancing and cluster failover
10+
support. The client provides convenient configuration options to connect to an
11+
Elastic Cloud deployment.
12+
13+
IMPORTANT: Client applications should create a single instance of
14+
`ElasticsearchClient` that is used throughout your application for its entire
15+
lifetime. Internally the client manages and maintains HTTP connections to nodes,
16+
reusing them to optimize performance. If you use a dependency injection
17+
container for your application, the client instance should be registered with a
18+
singleton lifetime.
19+
20+
[discrete]
21+
[[cloud-deployment]]
22+
=== Connecting to a cloud deployment
23+
24+
Connecting to an Elasticsearch Service deployment is achieved by providing the
25+
unique Cloud ID for your deployment when configuring the `ElasticsearchClient`
26+
instance. You can retrieve the Cloud ID from the homepage of the deployment in
27+
Elasticsearch Service. You also require suitable credentials that your
28+
application uses to authenticate with your deployment.
29+
30+
As a security best practice, it is recommended to create a dedicated API key per
31+
application, with permissions limited to only those required for any API calls
32+
the application is authorized to make.
33+
34+
The following snippet shows you how to create a client instance that connects to
35+
an {es} deployment in the cloud.
36+
37+
[source,csharp]
38+
----
39+
using Elastic.Clients.Elasticsearch;
40+
using Elastic.Transport;
41+
42+
var client = new ElasticsearchClient("<CLOUD_ID>", new ApiKey("<API_KEY>")); <1>
43+
----
44+
<1> Replace the placeholder string values above with your cloud ID and the API key
45+
configured for your application to access your deployment.
46+
47+
48+
[discrete]
49+
[[single-node]]
50+
=== Connecting to a single node
51+
52+
Single node configuration is best suited to connections to a multi-node cluster
53+
running behind a load balancer or reverse proxy, which is exposed via a single
54+
URL. It may also be convenient to use a single node during local application
55+
development. If the URL represents a single {es} node, be aware that this offers
56+
no resiliency should the server be unreachable or unresponsive.
57+
58+
By default, security features such as authentication and TLS are enabled on {es}
59+
clusters. When you start {es} for the first time, TLS is configured
60+
automatically for the HTTP layer. A CA certificate is generated and stored on
61+
disk which is used to sign the certificates for the HTTP layer of the {es}
62+
cluster.
63+
64+
In order for the client to establish a connection with the cluster over HTTPS,
65+
the CA certificate must be trusted by the client application. There are several
66+
mechanisms for <<working-with-certificates, working with certificates>>, but the
67+
simplest choice is to use the hex-encoded SHA-256 fingerprint of the CA
68+
certificate. The CA fingerprint is output to the terminal when you start {es}
69+
for the first time. It can also be retrieved from you cluster by running the
70+
following command:
71+
72+
[source,shell]
73+
----
74+
openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt
75+
----
76+
77+
The command returns the security certificate, including the fingerprint. The
78+
`issuer` should be `Elasticsearch security auto-configuration HTTP CA`.
79+
80+
[source,shell]
81+
----
82+
issuer= /CN=Elasticsearch security auto-configuration HTTP CA
83+
SHA256 Fingerprint=<FINGERPRINT>
84+
----
85+
86+
Visit the
87+
https://www.elastic.co/guide/en/elasticsearch/reference/master/configuring-stack-security.html[Connect clients to {es}] documentation for more information.
88+
89+
The following snippet shows you how to create a client instance that connects to
90+
your {es} cluster via a single node, using the CA fingerprint:
91+
92+
[source,csharp]
93+
----
94+
using Elastic.Clients.Elasticsearch;
95+
using Elastic.Transport;
96+
97+
var settings = new ElasticsearchClientSettings(new Uri("https://localhost:9200"))
98+
.CertificateFingerprint("<FINGERPRINT>")
99+
.Authentication(new BasicAuthentication("<USERNAME>", "<PASSWORD>"));
100+
101+
var client = new ElasticsearchClient(settings);
102+
----
103+
104+
The preceding snippet demonstrates configuring the client to authenticate by
105+
providing a username and password with basic authentication. If preferred, you
106+
may also use `ApiKey` authentication as shown in the cloud connection example.
107+
108+
[discrete]
109+
[[multiple-nodes]]
110+
=== Connecting to multiple nodes using a node pool
111+
112+
To provide resiliency, you should configure multiple nodes for your cluster to
113+
which the client attempts to communicate. By default, the client cycles through
114+
nodes for each request in a round robin fashion. The client also tracks
115+
unhealthy nodes and avoids sending requests to them until they become healthy.
116+
117+
This configuration is best suited to connect to a known small sized cluster,
118+
where you do not require sniffing to detect the cluster topology. Refer to the
119+
<<connection-pooling,node pool documentation>> for more information about the
120+
types of node pool available in the {es} .NET client.
121+
122+
The following snippet shows you how to connect to multiple nodes by using a
123+
static node pool:
124+
125+
[source,csharp]
126+
----
127+
using Elastic.Clients.Elasticsearch;
128+
using Elastic.Transport;
129+
130+
var nodes = new Uri[]
131+
{
132+
new Uri("https://myserver1:9200"),
133+
new Uri("https://myserver2:9200"),
134+
new Uri("https://myserver3:9200")
135+
};
136+
137+
var pool = new StaticNodePool(nodes);
138+
139+
var settings = new ElasticsearchClientSettings(pool)
140+
.CertificateFingerprint("<FINGERPRINT>")
141+
.Authentication(new ApiKey("<API_KEY>"));
142+
143+
var client = new ElasticsearchClient(settings);
144+
----
145+
146+

‎docs/high-level.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ And features such as
5050

5151
include::{output-dir}/getting-started.asciidoc[]
5252

53-
[[connecting]]
53+
[[connecting-nest-hl]]
5454
== Connecting
5555

5656
NEST uses sensible defaults for connecting to and interacting with an Elasticsearch cluster but provides numerous

‎docs/index.asciidoc‎

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

1818
include::install.asciidoc[]
1919

20+
include::connecting.asciidoc[]
21+
2022
include::breaking-changes.asciidoc[]
2123

2224
include::conventions.asciidoc[]

0 commit comments

Comments
 (0)