-
Notifications
You must be signed in to change notification settings - Fork 12
Documentation: Add guidelines about debugging connectivity problems #425
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
=============== | ||
Troubleshooting | ||
=============== | ||
|
||
This sections enumerates potential connection problems with ``crash``, | ||
and how to investigate and resolve them. | ||
|
||
|
||
Debugging connection errors | ||
=========================== | ||
|
||
If you are connecting to `CrateDB`_, for example like this:: | ||
|
||
crash --hosts 'http://localhost:4200' -U 'admin' -W | ||
|
||
... and ``crash`` responds with a connection error message like this:: | ||
|
||
CONNECT ERROR | ||
|
||
you may want to add the ``--verbose`` command line option, in order to find out | ||
about the reason why the connection fails. It could be a DNS / name resolution | ||
error, or it could be a problem related to SSL termination. | ||
|
||
Other than ``--verbose``, you can also use the shorthand version ``-v``:: | ||
|
||
crash --hosts 'http://localhost:4200' -U 'admin' -W -v | ||
|
||
|
||
|
||
SSL connection errors | ||
===================== | ||
|
||
`A recent problem`_ outlined SSL connectivity problems when connecting to | ||
`CrateDB Cloud`_:: | ||
|
||
crash --hosts 'https://MY-CLUSTER-NAME.eks1.eu-west-1.aws.cratedb.net:4200' -U 'admin' -W -v | ||
|
||
The verbose output using ``crash -v`` signaled a certificate verification error | ||
like that:: | ||
|
||
Server not available, exception: HTTPSConnectionPool(host='MY-CLUSTER-NAME.eks1.eu-west-1.aws.cratedb.net', port=4200): | ||
Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(1, ' | ||
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)'))) | ||
|
||
If you are on macOS, the Python Installer offers an easy option to install the | ||
required SSL root certificates. Because ``crash`` uses Python, this is the | ||
right choice to resolve the problem durably. | ||
|
||
.. figure:: https://github.com/crate/crash/assets/453543/c4e49d7e-86d8-40f6-b0d8-f64889f9d972 | ||
Comment on lines
+30
to
+49
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it possible this can also happen on Windows? Are we running some sort of integration tests against CrateDB Cloud? It might sound like overkill, but it may also be absolutely reasonable. For this patch about the documentation, maybe someone wants to provide a corresponding screenshot if it is the same story there, if someone has a Windows machine at hand? Note to self: For the integration tests, this is another use-case for quickly whipping up an automation with Racker. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
CrateDB Cloud is using Let's Encrypt certificates. You need your Python installation to trust/have access to Let's Encrypt intermediate certificates to verify their validity. Not much one could test 🤷 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Aight. Do we know about LE coverage in regular trust stores? Like, it actually should be inside Windows and macOS already, no? Shall we look at adding certifi or truststore into the mix, to provide a better UX? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It looks like it works well on Windows, at least within a Docker container. I actually don't know where the SSL root certificates are coming from in this case, so please take it with a grain of salt -- it is just "almost native".
|
||
|
||
In order to install the SSL root certificates retroactively, you can use a | ||
command like:: | ||
|
||
/Applications/Python 3.11/Install Certificates.command | ||
|
||
|
||
.. _a recent problem: https://community.cratedb.com/t/issue-connecting-to-cratedb-cloud-cluster-from-local-machine/1707 | ||
.. _CrateDB: https://github.com/crate/crate | ||
.. _CrateDB Cloud: https://console.cratedb.cloud |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is also available after installation in
/Applications/Python 3.11/Install Certificates.command
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks. I will add this guidance to the documentation text.