From e74457866de99975977e8a86ee35086fcf2ed1c7 Mon Sep 17 00:00:00 2001 From: Nick Lang Date: Thu, 28 Dec 2017 12:08:55 -0700 Subject: [PATCH 1/4] updating the docs some more examples --- README | 16 ++++++++++++++++ docs/connection.rst | 8 ++++++++ 2 files changed, 24 insertions(+) diff --git a/README b/README index 199b137f..8a0b360d 100644 --- a/README +++ b/README @@ -88,6 +88,22 @@ Simple use-case:: .. _Full documentation: https://elasticsearch-py.readthedocs.io/ +Elastic Cloud (and SSL) use-case:: + + >>> from elasticsearch import Elasticsearch + >>> es = Elasticsearch("https://elasticsearch.url:port", http_auth=('elastic','yourpassword')) + >>> es.info() + +Using SSL Context with a self-signed cert use-case:: + + >>> from elasticsearch import Elasticsearch + >>> from elasticsearch.connection.http_urllib3 import create_ssl_context + + >>> context = create_ssl_context(cafile="path/to/cafile.pem") + >>> es = Elasticsearch("https://elasticsearch.url:port", ssl_context=context, http_auth=('elastic','yourpassword')) + >>> es.info() + + Features -------- diff --git a/docs/connection.rst b/docs/connection.rst index 7f5743e2..8bccce36 100644 --- a/docs/connection.rst +++ b/docs/connection.rst @@ -54,6 +54,14 @@ If you want to create your own `SSLContext` object you can create one natively u python SSL library with the `create_default_context` (https://docs.python.org/3/library/ssl.html#ssl.create_default_context) method or you can use the wrapper function :function:`~elasticsearch.connection.http_urllib3.create_ssl_context`. +To create an `SSLContext` object you only need to use one of cafile, capath or cadata:: + + >>> from elasticsearch.connection.http_urllib3 import create_ssl_context + >>> context = create_ssl_context(cafile=None, capath=None, cadata=None) + +* `cafile` is the path to your CA File +* `capath` is the directory of a collection of CA's +* `cadata` is either an ASCII string of one or more PEM-encoded certificates or a bytes-like object of DER-encoded certificates. .. autoclass:: Urllib3HttpConnection :members: From 415b3e7dc75013ab1247e2788bf379e58190eea0 Mon Sep 17 00:00:00 2001 From: Nick Lang Date: Thu, 28 Dec 2017 12:29:41 -0700 Subject: [PATCH 2/4] more docs updates --- docs/index.rst | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 03fd52ae..054893e7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -59,8 +59,8 @@ Example Usage es = Elasticsearch() doc = { - 'author': 'kimchy', - 'text': 'Elasticsearch: cool. bonsai cool.', + 'author': 'kimchy', + 'text': 'Elasticsearch: cool. bonsai cool.', 'timestamp': datetime.now(), } res = es.index(index="test-index", doc_type='tweet', id=1, body=doc) @@ -191,34 +191,32 @@ elasticsearch cluster, including certificate verification and http auth:: # ... or specify common parameters as kwargs - # use certifi for CA certificates - import certifi - es = Elasticsearch( ['localhost', 'otherhost'], http_auth=('user', 'secret'), + scheme="https", port=443, - use_ssl=True ) # SSL client authentication using client_cert and client_key + from elasticsearch.connection.http_urllib3 import create_ssl_context + + context = create_ssl_context(cafile="path/to/cert.pem") es = Elasticsearch( ['localhost', 'otherhost'], http_auth=('user', 'secret'), + scheme="https", port=443, - use_ssl=True, - ca_certs='/path/to/cacert.pem', - client_cert='/path/to/client_cert.pem', - client_key='/path/to/client_key.pem', + ssl_context=context, ) .. warning:: ``elasticsearch-py`` doesn't ship with default set of root certificates. To have working SSL certificate validation you need to either specify your own - as ``ca_certs`` or install `certifi`_ which will be picked up - automatically. + as ``cafile`` or ``capath`` or ``cadata`` or install `certifi`_ which will + be picked up automatically. See class :class:`~elasticsearch.Urllib3HttpConnection` for detailed From 456e598c5b818433d52177184ac16db1d07d93e2 Mon Sep 17 00:00:00 2001 From: Nick Lang Date: Thu, 28 Dec 2017 13:09:16 -0700 Subject: [PATCH 3/4] moving import --- elasticsearch/connection/__init__.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/elasticsearch/connection/__init__.py b/elasticsearch/connection/__init__.py index c2f484a1..6eb68967 100644 --- a/elasticsearch/connection/__init__.py +++ b/elasticsearch/connection/__init__.py @@ -1,3 +1,4 @@ from .base import Connection from .http_requests import RequestsHttpConnection -from .http_urllib3 import Urllib3HttpConnection +from .http_urllib3 import Urllib3HttpConnection, create_ssl_context + From 50f89e4d47d337155e2bb17853174c292e8b97bd Mon Sep 17 00:00:00 2001 From: Nick Lang Date: Thu, 28 Dec 2017 13:12:04 -0700 Subject: [PATCH 4/4] moving import --- README | 2 +- docs/connection.rst | 2 +- docs/index.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README b/README index 8a0b360d..bb306bb4 100644 --- a/README +++ b/README @@ -97,7 +97,7 @@ Elastic Cloud (and SSL) use-case:: Using SSL Context with a self-signed cert use-case:: >>> from elasticsearch import Elasticsearch - >>> from elasticsearch.connection.http_urllib3 import create_ssl_context + >>> from elasticsearch.connection import create_ssl_context >>> context = create_ssl_context(cafile="path/to/cafile.pem") >>> es = Elasticsearch("https://elasticsearch.url:port", ssl_context=context, http_auth=('elastic','yourpassword')) diff --git a/docs/connection.rst b/docs/connection.rst index 8bccce36..a14d19ae 100644 --- a/docs/connection.rst +++ b/docs/connection.rst @@ -56,7 +56,7 @@ or you can use the wrapper function :function:`~elasticsearch.connection.http_ur To create an `SSLContext` object you only need to use one of cafile, capath or cadata:: - >>> from elasticsearch.connection.http_urllib3 import create_ssl_context + >>> from elasticsearch.connection import create_ssl_context >>> context = create_ssl_context(cafile=None, capath=None, cadata=None) * `cafile` is the path to your CA File diff --git a/docs/index.rst b/docs/index.rst index 054893e7..e4218a9d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -200,7 +200,7 @@ elasticsearch cluster, including certificate verification and http auth:: # SSL client authentication using client_cert and client_key - from elasticsearch.connection.http_urllib3 import create_ssl_context + from elasticsearch.connection import create_ssl_context context = create_ssl_context(cafile="path/to/cert.pem") es = Elasticsearch(