[DOC] - Update docs about certificates

[viniciusdc]

Preliminary Checks

• [X] This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/nebari-dev/nebari/discussions

Summary

• Update information regarding local deployment and the use of /etc/hosts when using lets-encrypt
• Due to https://github.com/nebari-dev/nebari/pull/2352, we need to tell users that if the domain is updated, the cert.json file present in the PV needs to be deleted so that traefik generates new certs for the new domain

Steps to Resolve this Issue

1. Update docs

3. ...

[viniciusdc]

Just a bit more of context to this:

The current documentation needs updates to address changes in how certificates are managed during local deployments, considering the changes made by now having persistency within the generated self-signed certs, especially in the context of using Let's Encrypt with Traefik Ingress and how /etc/hosts interacts with all this. Recent experiences suggest revising guidelines to avoid confusion and helpful information when encountering issues.

Details & Context

1. /etc/hosts and Certificate Generation Previously, mapping a DNS name in the /etc/hosts to MetalLB's external IP was sufficient for Let's Encrypt (using the production ACME server) to generate a valid certificate.

   • This was mainly because, in the Qhub's era, when developers attempted to deploy it locally, we pinned the range for the external LB IP to always point to 192.168.49.100, which, by that time, we used to have a Cloudflare DNS pointing to it. Its first appearance could be tracked down roughly to here. And since then this mostly was untouched. This has been forgotten, but the docs are still an inverse reflection of that time.

2. Persistent Volume Claims and Certificate Renewal:

   • There have been instances where, despite redeploying a cluster, Traefik continued to utilize an outdated cert.json file from a persistent volume (PV) instead of generating a new certificate. If such a situation occurs, this could get a note section in the Cers docs as a workaround for the user to delete the file in the volume mount manually. This is rare because we don't expect users to change the domain name often.

In conclusion:

To avoid confusion, remove outdated references to /etc/hosts setup in the context of Let's Encrypt certifications. If users are looking for why their domain is interested in their browsers when using LetsEncrypt, they should be told that their SSL certs need to be recognized and pointed to the DNS docs.

• For users who only want to test/dev the deployment and would like to avoid this DNS route, we should direct them to use custom certs instead and opt for openssl or certgen to help in this endeavor

[aktech]

People can general certs for local deployment too with DNS challenge, see this comment: https://github.com/nebari-dev/nebari/issues/1405#issuecomment-2139417252

I would be nice to add docs for that to patch it for local deployment and eventually implement an option to generate certs via dns challenge.

[aktech]

Note regarding certs for local deployment

I saw an issue with terminal on the local deployment, it doesn't loads. (It might just be on my local deployment) I see the terminal websocket connection to terminal endpoint fails.

https://github.com/nebari-dev/nebari-docs/assets/5647941/52049e0e-78d6-4270-9a02-2cb486a7eafc

It worked when nebari is running with valid certs (I generated it via DNS challenge as mentioned above)

[kcpevey]

@aktech / @viniciusdc does https://github.com/nebari-dev/nebari-docs/pull/470 sufficiently cover this such that this can be closed now?

[viniciusdc]

Hi @kcpevey, the above mentioned PR was enough for this issue. I will be closing it now, the above comments from @aktech was due to some experimental changes we are implementing on nebari that will be interesting to document later on (I just asked him to add some notes here so that we didn't forget) -- I will create a new issue for that :)