Add user guide for TLS ingress

[dimas-b]

No description provided.

[adutra]

While this works, you could avoid fiddling with /etc/hosts by using one or both of the methods below:

1. for curl only: use the --resolve option, e.g.

curl --resolve "nessie.local:443:$(minikube ip)" https://nessie.local/api/v2/config

2. for all tools and browsers: use a nip.io hostname, e.g. nessie.$(minikube ip).nip.io: such a host name will resolve to whatever IP minikube ip indicates. E.g.

ping nessie.$(minikube ip).nip.io
PING nessie.192.168.49.2.nip.io (192.168.49.2): 56 data bytes
64 bytes from 192.168.49.2: icmp_seq=0 ttl=64 time=0.108 ms

Then you would use nessie.192.168.49.2.nip.io as the hostname for your certificates and ingress rules.

[dimas-b]

Yeah, but the certificate must have the exact host name, which is not known until we start / configure ingress... I guess that would create a chicken and egg problem. Even if adding the TLS cert after startup works, it might be too complex for a guide... WDYT?

Also, the java client still depends on OS-level host name resolution (although I did not put and example for it).

[dimas-b]

updated

[adutra]

I finally got this to work on macOS, so I'm approving the PR, but it required many changes:

1. First, ingress ports are not exposed on macOS, see docker: Ingress not exposed on MacOS kubernetes/minikube#7332 for background. So mac users must run the following command after installing the ingress:

minikube tunnel

This will detect the ingress rule and open ports for it:

✅  Tunnel successfully started
📌  NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ...
❗  The service/ingress nessie requires privileged ports to be exposed: [80 443]
🔑  sudo permission will be asked for it.
🏃  Starting tunnel for service nessie.
Password:

2. Once this is done, the service is accessible, but under 127.0.0.1, not $(minikube ip). So you need to change all the commands above, e.g.

curl --resolve "nessie.local:443:127.0.0.1" https://nessie.local/api/v2/config
{
  "defaultBranch" : "main",
  "minSupportedApiVersion" : 1,
  "maxSupportedApiVersion" : 2,
  "actualApiVersion" : 2,
  "specVersion" : "2.0.0",
  "noAncestorHash" : "2e1cfa82b035c26cbbbdae632cea070514eb8b773f616aaeaf668e2f0be8f10d",
  "repositoryCreationTimestamp" : "2023-05-26T10:28:53.462334804Z",
  "oldestPossibleCommitTimestamp" : "2023-05-26T10:28:53.462334804Z"
}

[dimas-b]

@adutra : Could you update with Mac specifics after merging? I do not have a Mac to play with :)

[adutra]

Good idea, will do!