Documentation: Add guidelines about debugging connectivity problems #425
Conversation
| 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 |
There was a problem hiding this comment.
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.
Are we running some sort of integration tests against CrateDB Cloud?
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.
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?
-- https://community.cratedb.com/t/issue-connecting-to-cratedb-cloud-cluster-from-local-machine/1707/14
There was a problem hiding this comment.
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".
# Acquire a Windows terminal shell, in DOS mode.
export RACKER_WDM_MACHINE=2019-box
racker --verbose run --rm -it --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2019 -- cmd
rem Install Python, including registration on %PATH%.
scoop install python
C:\Users\ContainerAdministrator\scoop\apps\python\current\install-pep-514.reg
set PATH=%PATH%;C:\Users\ContainerAdministrator\scoop\apps\python\current\Scripts
rem Invoke crash connecting to CrateDB Cloud.
pip install crash
crash --hosts "https://admin:{REDACTED}@testdrive.aks1.westeurope.azure.cratedb.net:4200"
amotl
force-pushed
the
amo/docs-cloud-connect-problems
branch
from
00979c0 to
5916108
Compare
amotl
force-pushed
the
amo/docs-cloud-connect-problems
branch
from
5916108 to
5144b03
Compare
| 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 |
There was a problem hiding this comment.
It is also available after installation in /Applications/Python 3.11/Install Certificates.command
There was a problem hiding this comment.
Thanks. I will add this guidance to the documentation text.
Python may have skipped installing its SSL root certificate bundle on macOS. Educate the user about how to improve the situation.
amotl
force-pushed
the
amo/docs-cloud-connect-problems
branch
from
5144b03 to
07e0343
Compare
3 participants
Problem
When connecting to CrateDB Cloud, you may observe connection errors when using
crashon macOS. The reason is because Python may have skipped installing its SSL root certificate bundle on macOS. Thanks for reporting this, @simonprickett.Improvement
This patch adds a new troubleshooting section to the documentation, in order to educate users about how to improve the situation / resolve the issue.
Preview
https://crash--425.org.readthedocs.build/en/425/troubleshooting.html
References
Issue connecting to CrateDB Cloud cluster from local machine
Review Request
Please advise wording improvements as applicable.