diff --git a/docs/connecting.asciidoc b/docs/connecting.asciidoc new file mode 100644 index 00000000000..782a79c3b78 --- /dev/null +++ b/docs/connecting.asciidoc @@ -0,0 +1,146 @@ +[[connecting]] +== Connecting + +This page contains the information you need to create an instance of the .NET +Client for {es} that connects to your {es} cluster. + +It’s possible to connect to your {es} cluster via a single node, or by +specifying multiple nodes using a node pool. Using a node pool has a few +advantages over a single node, such as load balancing and cluster failover +support. The client provides convenient configuration options to connect to an +Elastic Cloud deployment. + +IMPORTANT: Client applications should create a single instance of +`ElasticsearchClient` that is used throughout your application for its entire +lifetime. Internally the client manages and maintains HTTP connections to nodes, +reusing them to optimize performance. If you use a dependency injection +container for your application, the client instance should be registered with a +singleton lifetime. + +[discrete] +[[cloud-deployment]] +=== Connecting to a cloud deployment + +Connecting to an Elasticsearch Service deployment is achieved by providing the +unique Cloud ID for your deployment when configuring the `ElasticsearchClient` +instance. You can retrieve the Cloud ID from the homepage of the deployment in +Elasticsearch Service. You also require suitable credentials that your +application uses to authenticate with your deployment. + +As a security best practice, it is recommended to create a dedicated API key per +application, with permissions limited to only those required for any API calls +the application is authorized to make. + +The following snippet shows you how to create a client instance that connects to +an {es} deployment in the cloud. + +[source,csharp] +---- +using Elastic.Clients.Elasticsearch; +using Elastic.Transport; + +var client = new ElasticsearchClient("", new ApiKey("")); <1> +---- +<1> Replace the placeholder string values above with your cloud ID and the API key +configured for your application to access your deployment. + + +[discrete] +[[single-node]] +=== Connecting to a single node + +Single node configuration is best suited to connections to a multi-node cluster +running behind a load balancer or reverse proxy, which is exposed via a single +URL. It may also be convenient to use a single node during local application +development. If the URL represents a single {es} node, be aware that this offers +no resiliency should the server be unreachable or unresponsive. + +By default, security features such as authentication and TLS are enabled on {es} +clusters. When you start {es} for the first time, TLS is configured +automatically for the HTTP layer. A CA certificate is generated and stored on +disk which is used to sign the certificates for the HTTP layer of the {es} +cluster. + +In order for the client to establish a connection with the cluster over HTTPS, +the CA certificate must be trusted by the client application. There are several +mechanisms for <>, but the +simplest choice is to use the hex-encoded SHA-256 fingerprint of the CA +certificate. The CA fingerprint is output to the terminal when you start {es} +for the first time. It can also be retrieved from you cluster by running the +following command: + +[source,shell] +---- +openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt +---- + +The command returns the security certificate, including the fingerprint. The +`issuer` should be `Elasticsearch security auto-configuration HTTP CA`. + +[source,shell] +---- +issuer= /CN=Elasticsearch security auto-configuration HTTP CA +SHA256 Fingerprint= +---- + +Visit the +https://www.elastic.co/guide/en/elasticsearch/reference/master/configuring-stack-security.html[Connect clients to {es}] documentation for more information. + +The following snippet shows you how to create a client instance that connects to +your {es} cluster via a single node, using the CA fingerprint: + +[source,csharp] +---- +using Elastic.Clients.Elasticsearch; +using Elastic.Transport; + +var settings = new ElasticsearchClientSettings(new Uri("https://localhost:9200")) + .CertificateFingerprint("") + .Authentication(new BasicAuthentication("", "")); + +var client = new ElasticsearchClient(settings); +---- + +The preceding snippet demonstrates configuring the client to authenticate by +providing a username and password with basic authentication. If preferred, you +may also use `ApiKey` authentication as shown in the cloud connection example. + +[discrete] +[[multiple-nodes]] +=== Connecting to multiple nodes using a node pool + +To provide resiliency, you should configure multiple nodes for your cluster to +which the client attempts to communicate. By default, the client cycles through +nodes for each request in a round robin fashion. The client also tracks +unhealthy nodes and avoids sending requests to them until they become healthy. + +This configuration is best suited to connect to a known small sized cluster, +where you do not require sniffing to detect the cluster topology. Refer to the +<> for more information about the +types of node pool available in the {es} .NET client. + +The following snippet shows you how to connect to multiple nodes by using a +static node pool: + +[source,csharp] +---- +using Elastic.Clients.Elasticsearch; +using Elastic.Transport; + +var nodes = new Uri[] +{ + new Uri("https://myserver1:9200"), + new Uri("https://myserver2:9200"), + new Uri("https://myserver3:9200") +}; + +var pool = new StaticNodePool(nodes); + +var settings = new ElasticsearchClientSettings(pool) + .CertificateFingerprint("") + .Authentication(new ApiKey("")); + +var client = new ElasticsearchClient(settings); +---- + + diff --git a/docs/high-level.asciidoc b/docs/high-level.asciidoc index 916b04ab1d9..a230d8903d0 100644 --- a/docs/high-level.asciidoc +++ b/docs/high-level.asciidoc @@ -50,7 +50,7 @@ And features such as include::{output-dir}/getting-started.asciidoc[] -[[connecting]] +[[connecting-nest-hl]] == Connecting NEST uses sensible defaults for connecting to and interacting with an Elasticsearch cluster but provides numerous diff --git a/docs/index.asciidoc b/docs/index.asciidoc index e22fa8065bf..949f9d105cd 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -17,6 +17,8 @@ include::intro.asciidoc[] include::install.asciidoc[] +include::connecting.asciidoc[] + include::breaking-changes.asciidoc[] include::conventions.asciidoc[]