Skip to content

Commit 91cacb5

Browse files
stevejgordonstevejgordon
authored
[DOCS] WIP - Connection to v8 (#6153)
* Initial outline for new documentation page * Updating connecting to v8 docs * Update geo queries * Update documentation
1 parent 7ba90be commit 91cacb5

File tree

9 files changed

+238
-8
lines changed

9 files changed

+238
-8
lines changed

‎docs/client-concepts/certificates/working-with-certificates.asciidoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,3 +120,9 @@ If you go for a vendor generated SSL certificate, it's common practice for the c
120120
in the certificate chain. When using such a certificate, use `CertificateValidations.AuthorityPartOfChain` which validates that
121121
the local CA certificate is part of the chain that was used to generate the servers key.
122122

123+
==== Applying a CA Fingerprint
124+
125+
During development against a newly created v8 cluster, you may also configure the client to authenticate using the CA fingerprint logged by the
126+
server at initial startup. The fingerprint can be set by calling the `CertificateFingerprint` method on a ConnectionSettings instance.
127+
See <<connecting-to-elasticsearch-v8, Connecting to Elasticsearch v8.x using the v7.x client>> for further details.
128+

‎docs/client-concepts/connection/connecting-to-elasticsearch-v8.asciidoc

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/7.17
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
////
8+
IMPORTANT NOTE
9+
==============
10+
This file has been generated from https://github.com/elastic/elasticsearch-net/tree/7.x/src/Tests/Tests/ClientConcepts/Connection/ConnectingToElasticsearchV8.doc.cs.
11+
If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
12+
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
13+
////
14+
15+
[[connecting-to-elasticsearch-v8]]
16+
=== Connecting to Elasticsearch v8.x using the v7.17.x client
17+
18+
We recommend using the latest client with a corresponding major version when connecting to Elasticsearch. Until the v7 .NET client is
19+
generally available, you may use the v7.17.x client to communicate with a 8.x Elasticsearch cluster. There are several important considerations
20+
regarding configuration. Failure to correctly configure the client to connect using the security features enabled on the server will result in
21+
an exception being thrown during the initial client communication that will prevent further use of the client.
22+
23+
:security: https://www.elastic.co/guide/en/elasticsearch/reference/8.1/configuring-stack-security.html
24+
25+
:security-clients: https://www.elastic.co/guide/en/elasticsearch/reference/8.1/configuring-stack-security.html#_connect_clients_to_elasticsearch_5
26+
27+
==== Security and Certificates
28+
29+
Newly installed Elasticsearch v8 clusters start with security configuration {security}[enabled automatically by default]. As a result,
30+
a certificate authority and certificate is created for secure HTTPS communication. Additionally, an `elastic` user is created with a
31+
unique, secure password. Elasticsearch logs details of the security configuration when it first starts, enabling the collection of a
32+
certificate fingerprint, along with the password configured for the `elastic` user. In a development environment, you will need to collect
33+
these pieces of information, required to configure the client to securely communicate with the server. The
34+
{security-clients}[Elasticsearch documentation] provides commands which may also be used to retrieve this information after the cluster has started.
35+
36+
[[ca-fingerprint]]
37+
===== Applying the CA Fingerprint
38+
39+
The simplest configuration option during development is to connect to the server using the CA fingerprint logged by the server at initial startup.
40+
The fingerprint can be set by calling the `CertificateFingerprint` method on a `ConnectionSettings` instance.
41+
42+
[source,csharp]
43+
----
44+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
45+
46+
var settings = new ConnectionSettings(pool)
47+
.CertificateFingerprint("94:75:CE:4F:EB:05:32:83:40:B8:18:BB:79:01:7B:E0:F0:B6:C3:01:57:DB:4D:F5:D8:B8:A6:BA:BD:6D:C5:C4");
48+
49+
var client = new ElasticClient(settings);
50+
----
51+
52+
If preferred, you may also configure the client to work with the certificate in the usual way.
53+
See <<working-with-certificates, Working with certificates>> for further details.
54+
55+
[[basic-authentication]]
56+
===== Basic Authentication
57+
58+
Additionally, you will need to provide the basic authentication credentials for a user account configured on the server. During development,
59+
you may begin by using the `elastic` user and the automatically generated password captured from the server logs.
60+
61+
[source,csharp]
62+
----
63+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
64+
65+
var settings = new ConnectionSettings(pool)
66+
.CertificateFingerprint("94:75:CE:4F:EB:05:32:83:40:B8:18:BB:79:01:7B:E0:F0:B6:C3:01:57:DB:4D:F5:D8:B8:A6:BA:BD:6D:C5:C4")
67+
.BasicAuthentication("elastic", "password");
68+
69+
var client = new ElasticClient(settings);
70+
----
71+
72+
==== Enabling Compatibility Mode
73+
74+
The Elasticsearch server version 8.0 is introducing a new compatibility mode that allows you a smoother upgrade
75+
experience from 7 to 8. In a nutshell, you can use the latest 7.x Elasticsearch client with an 8.x Elasticsearch
76+
server, giving more room to coordinate the upgrade of your codebase to the next major version.
77+
78+
If you want to leverage this functionality, please make sure that you are using the latest 7.x client and set
79+
the environment variable `ELASTIC_CLIENT_APIVERSIONING` to `true`. The client is handling the rest internally.
80+
81+
Compatibility mode may also be enabled directly on `ConnectionSettings` by calling `EnableApiVersioningHeader`.
82+
83+
[source,csharp]
84+
----
85+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
86+
87+
var settings = new ConnectionSettings(pool)
88+
.CertificateFingerprint("94:75:CE:4F:EB:05:32:83:40:B8:18:BB:79:01:7B:E0:F0:B6:C3:01:57:DB:4D:F5:D8:B8:A6:BA:BD:6D:C5:C4")
89+
.BasicAuthentication("elastic", "password")
90+
.EnableApiVersioningHeader();
91+
92+
var client = new ElasticClient(settings);
93+
----
94+

‎docs/high-level.asciidoc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,8 @@ configuration options and components to change this behaviour
6767

6868
* <<function-as-a-service-environments, Using the Client in a Function-as-a-Service Environment>>
6969

70+
* <<connecting-to-elasticsearch-v8, Connecting to Elasticsearch v8.x using the v7.x client>>
71+
7072
include::client-concepts/connection/configuration-options.asciidoc[]
7173

7274
include::client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc[]
@@ -77,6 +79,8 @@ include::client-concepts/certificates/working-with-certificates.asciidoc[]
7779

7880
include::client-concepts/connection/function-as-a-service-environments.asciidoc[]
7981

82+
include::client-concepts/connection/connecting-to-elasticsearch-v8.asciidoc[]
83+
8084
[[serialization]]
8185
== Serialization
8286

‎docs/query-dsl/geo/bounding-box/geo-bounding-box-query-usage.asciidoc

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ q
3030
)
3131
.ValidationMethod(GeoValidationMethod.Strict)
3232
.Type(GeoExecution.Indexed)
33+
.IgnoreUnmapped(true)
3334
)
3435
----
3536

@@ -48,7 +49,8 @@ new GeoBoundingBoxQuery
4849
BottomRight = new GeoLocation(-34, 34),
4950
},
5051
Type = GeoExecution.Indexed,
51-
ValidationMethod = GeoValidationMethod.Strict
52+
ValidationMethod = GeoValidationMethod.Strict,
53+
IgnoreUnmapped = true
5254
}
5355
----
5456

@@ -70,7 +72,8 @@ new GeoBoundingBoxQuery
7072
"lat": -34.0,
7173
"lon": 34.0
7274
}
73-
}
75+
},
76+
"ignore_unmapped": true
7477
}
7578
}
7679
----
@@ -89,6 +92,7 @@ q
8992
)
9093
.ValidationMethod(GeoValidationMethod.Strict)
9194
.Type(GeoExecution.Indexed)
95+
.IgnoreUnmapped(true)
9296
)
9397
----
9498

@@ -106,7 +110,8 @@ new GeoBoundingBoxQuery
106110
WellKnownText = "BBOX (-34, 34, 34, -34)"
107111
},
108112
Type = GeoExecution.Indexed,
109-
ValidationMethod = GeoValidationMethod.Strict
113+
ValidationMethod = GeoValidationMethod.Strict,
114+
IgnoreUnmapped = true
110115
}
111116
----
112117

@@ -121,7 +126,8 @@ new GeoBoundingBoxQuery
121126
"boost": 1.1,
122127
"locationPoint": {
123128
"wkt": "BBOX (-34, 34, 34, -34)"
124-
}
129+
},
130+
"ignore_unmapped": true
125131
}
126132
}
127133
----

‎docs/query-dsl/geo/distance/geo-distance-query-usage.asciidoc

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ q
2828
.Location(34, -34)
2929
.Distance("200m")
3030
.ValidationMethod(GeoValidationMethod.IgnoreMalformed)
31+
.IgnoreUnmapped(true)
3132
)
3233
----
3334

@@ -43,7 +44,8 @@ new GeoDistanceQuery
4344
DistanceType = GeoDistanceType.Arc,
4445
Location = new GeoLocation(34, -34),
4546
Distance = "200m",
46-
ValidationMethod = GeoValidationMethod.IgnoreMalformed
47+
ValidationMethod = GeoValidationMethod.IgnoreMalformed,
48+
IgnoreUnmapped = true,
4749
}
4850
----
4951

@@ -60,7 +62,8 @@ new GeoDistanceQuery
6062
"locationPoint": {
6163
"lat": 34.0,
6264
"lon": -34.0
63-
}
65+
},
66+
"ignore_unmapped": true
6467
}
6568
}
6669
----

‎docs/query-dsl/geo/polygon/geo-polygon-query-usage.asciidoc

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ q
2626
.Field(p => p.LocationPoint)
2727
.ValidationMethod(GeoValidationMethod.Strict)
2828
.Points(new GeoLocation(45, -45), new GeoLocation(-34, 34), new GeoLocation(70, -70))
29+
.IgnoreUnmapped(true)
2930
)
3031
----
3132

@@ -39,7 +40,8 @@ new GeoPolygonQuery
3940
Name = "named_query",
4041
ValidationMethod = GeoValidationMethod.Strict,
4142
Points = new[] { new GeoLocation(45, -45), new GeoLocation(-34, 34), new GeoLocation(70, -70) },
42-
Field = Infer.Field<Project>(p => p.LocationPoint)
43+
Field = Infer.Field<Project>(p => p.LocationPoint),
44+
IgnoreUnmapped = true
4345
}
4446
----
4547

@@ -66,7 +68,8 @@ new GeoPolygonQuery
6668
"lon": -70.0
6769
}
6870
]
69-
}
71+
},
72+
"ignore_unmapped": true
7073
}
7174
}
7275
----

‎tests/Tests/ClientConcepts/Certificates/WorkingWithCertificates.doc.cs

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,23 @@ public PkiApiTests(PkiCluster cluster, EndpointUsage usage) : base(cluster, usag
216216
[I] public async Task UsedHttps() => await AssertOnAllResponses(r => r.ApiCall.Uri.Scheme.Should().Be("https"));
217217
}
218218
#endif
219+
220+
/**
221+
* ==== Applying a CA Fingerprint
222+
*
223+
* During development against a newly created v8 cluster, you may also configure the client to authenticate using the CA fingerprint logged by the
224+
* server at initial startup. The fingerprint can be set by calling the `CertificateFingerprint` method on a ConnectionSettings instance.
225+
* See <<connecting-to-elasticsearch-v8, Connecting to Elasticsearch v8.x using the v7.x client>> for further details.
226+
*/
227+
[U] public void CertificateFingerprint()
228+
{
229+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
230+
231+
var settings = new ConnectionSettings(pool)
232+
.CertificateFingerprint("94:75:CE:4F:EB:05:32:83:40:B8:18:BB:79:01:7B:E0:F0:B6:C3:01:57:DB:4D:F5:D8:B8:A6:BA:BD:6D:C5:C4");
233+
234+
var client = new ElasticClient(settings);
235+
}
219236
}
220237

221238
#if !DOTNETCORE

‎tests/Tests/ClientConcepts/Connection/ConnectingToElasticsearchV8.doc.cs

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// Licensed to Elasticsearch B.V under one or more agreements.
2+
// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
3+
// See the LICENSE file in the project root for more information
4+
5+
using System;
6+
using Elastic.Elasticsearch.Xunit.XunitPlumbing;
7+
using Elasticsearch.Net;
8+
using Nest;
9+
10+
namespace Tests.ClientConcepts.Connection
11+
{
12+
public class ConnectingToElasticsearchV8
13+
{
14+
/**[[connecting-to-elasticsearch-v8]]
15+
* === Connecting to Elasticsearch v8.x using the v7.17.x client
16+
*
17+
* We recommend using the latest client with a corresponding major version when connecting to Elasticsearch. Until the v7 .NET client is
18+
* generally available, you may use the v7.17.x client to communicate with a 8.x Elasticsearch cluster. There are several important considerations
19+
* regarding configuration. Failure to correctly configure the client to connect using the security features enabled on the server will result in
20+
* an exception being thrown during the initial client communication that will prevent further use of the client.
21+
*
22+
* :security: https://www.elastic.co/guide/en/elasticsearch/reference/8.1/configuring-stack-security.html
23+
* :security-clients: https://www.elastic.co/guide/en/elasticsearch/reference/8.1/configuring-stack-security.html#_connect_clients_to_elasticsearch_5
24+
*
25+
* ==== Security and Certificates
26+
* Newly installed Elasticsearch v8 clusters start with security configuration {security}[enabled automatically by default]. As a result,
27+
* a certificate authority and certificate is created for secure HTTPS communication. Additionally, an `elastic` user is created with a
28+
* unique, secure password. Elasticsearch logs details of the security configuration when it first starts, enabling the collection of a
29+
* certificate fingerprint, along with the password configured for the `elastic` user. In a development environment, you will need to collect
30+
* these pieces of information, required to configure the client to securely communicate with the server. The
31+
* {security-clients}[Elasticsearch documentation] provides commands which may also be used to retrieve this information after the cluster has started.
32+
*
33+
* [[ca-fingerprint]]
34+
* ===== Applying the CA Fingerprint
35+
*
36+
* The simplest configuration option during development is to connect to the server using the CA fingerprint logged by the server at initial startup.
37+
* The fingerprint can be set by calling the `CertificateFingerprint` method on a `ConnectionSettings` instance.
38+
*/
39+
[U] public void CertificateFingerprint()
40+
{
41+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
42+
43+
var settings = new ConnectionSettings(pool)
44+
.CertificateFingerprint("94:75:CE:4F:EB:05:32:83:40:B8:18:BB:79:01:7B:E0:F0:B6:C3:01:57:DB:4D:F5:D8:B8:A6:BA:BD:6D:C5:C4");
45+
46+
var client = new ElasticClient(settings);
47+
}
48+
49+
/**
50+
* If preferred, you may also configure the client to work with the certificate in the usual way.
51+
* See <<working-with-certificates, Working with certificates>> for further details.
52+
53+
* [[basic-authentication]]
54+
* ===== Basic Authentication
55+
*
56+
* Additionally, you will need to provide the basic authentication credentials for a user account configured on the server. During development,
57+
* you may begin by using the `elastic` user and the automatically generated password captured from the server logs.
58+
*/
59+
[U] public void BasicAuth()
60+
{
61+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
62+
63+
var settings = new ConnectionSettings(pool)
64+
.CertificateFingerprint("94:75:CE:4F:EB:05:32:83:40:B8:18:BB:79:01:7B:E0:F0:B6:C3:01:57:DB:4D:F5:D8:B8:A6:BA:BD:6D:C5:C4")
65+
.BasicAuthentication("elastic", "password");
66+
67+
var client = new ElasticClient(settings);
68+
}
69+
70+
/**
71+
* ==== Enabling Compatibility Mode
72+
*
73+
* The Elasticsearch server version 8.0 is introducing a new compatibility mode that allows you a smoother upgrade
74+
* experience from 7 to 8. In a nutshell, you can use the latest 7.x Elasticsearch client with an 8.x Elasticsearch
75+
* server, giving more room to coordinate the upgrade of your codebase to the next major version.
76+
77+
* If you want to leverage this functionality, please make sure that you are using the latest 7.x client and set
78+
* the environment variable `ELASTIC_CLIENT_APIVERSIONING` to `true`. The client is handling the rest internally.
79+
*
80+
* Compatibility mode may also be enabled directly on `ConnectionSettings` by calling `EnableApiVersioningHeader`.
81+
*/
82+
83+
[U] public void CompatibilityMode()
84+
{
85+
var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
86+
87+
var settings = new ConnectionSettings(pool)
88+
.CertificateFingerprint("94:75:CE:4F:EB:05:32:83:40:B8:18:BB:79:01:7B:E0:F0:B6:C3:01:57:DB:4D:F5:D8:B8:A6:BA:BD:6D:C5:C4")
89+
.BasicAuthentication("elastic", "password")
90+
.EnableApiVersioningHeader();
91+
92+
var client = new ElasticClient(settings);
93+
}
94+
}
95+
}

‎tests/Tests/high-level.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,14 @@ configuration options and components to change this behaviour
4646
- <<modifying-default-connection, Modifying the default connection>>
4747
- <<working-with-certificates, Working with certificates>>
4848
- <<function-as-a-service-environments, Using the Client in a Function-as-a-Service Environment>>
49+
- <<connecting-to-elasticsearch-v8, Connecting to Elasticsearch v8.x using the v7.x client>>
4950

5051
include::client-concepts/connection/configuration-options.asciidoc[]
5152
include::client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc[]
5253
include::client-concepts/connection/modifying-default-connection.asciidoc[]
5354
include::client-concepts/certificates/working-with-certificates.asciidoc[]
5455
include::client-concepts/connection/function-as-a-service-environments.asciidoc[]
56+
include::client-concepts/connection/connecting-to-elasticsearch-v8.asciidoc[]
5557

5658
[[serialization]]
5759
== Serialization

0 commit comments

Comments
 (0)