From 0d138a2b9b2079bb3169ee941e10cc8e9e20fa54 Mon Sep 17 00:00:00 2001 From: Dmitri Bourlatchkov Date: Fri, 19 May 2023 13:12:47 -0400 Subject: [PATCH 1/5] Add user guide for TLS ingress --- site/docs/guides/tls.md | 83 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 site/docs/guides/tls.md diff --git a/site/docs/guides/tls.md b/site/docs/guides/tls.md new file mode 100644 index 00000000000..9bdfe1300df --- /dev/null +++ b/site/docs/guides/tls.md @@ -0,0 +1,83 @@ +# TLS Ingress with Minikube + +In this guide we walk through the process of configuring a Nessie Service with secure HTTPS transport in +[Minikube](https://minikube.sigs.k8s.io/docs/). + +## Setting up Minikube + +1. Start Minikube cluster: `minikube start` +2. Enable NGINX Ingress controller: `minikube addons enable ingress` + +## Creating Certificates + +If you have your own trusted certificate you can use it to sign a new certificate for the Nessie service. + +Otherwise, the rest of this section shows how can create a self-signed certificate and add it the list of trusted +certificates in the client OS. + +To generate a fresh pair of a key and a (self-signed) certificate: + +```shell +openssl req -new -subj "/CN=Nessie" -addext "subjectAltName = DNS:nessie.local" \ + -newkey rsa:2048 -keyout nessie-key.pem -out nessie.crt -noenc +``` + +Note the `-noenc` option. It is used only for the sake of simplicity of this example deployment. + +Add the new certificate to the local set of CA certificates on the client host (where the Nessie clients, +such as Nessie CLI / `curl` / browser, are going to run). + +The following example is for Linux: + +1. `sudo cp nessie.crt /usr/local/share/ca-certificates/nessie.crt` +2. `sudo update-ca-certificates` + +This should output something like "Certificate added: CN=Nessie". + +## Creating a k8s Secret for the Nessie Certificate + +```shell +kubectl -n nessie-ns create secret tls nessie-tls \ + --cert=nessie.crt --key=nessie-key.pem +``` + +## Deploying Nessie with Helm + +```shell +helm install nessie -n nessie-ns helm/nessie \ + --set ingress.enabled=true \ + --set ingress.hosts[0].host='nessie.local' \ + --set ingress.hosts[0].paths[0]='/' \ + --set ingress.tls[0].secretName=nessie-tls \ + --set ingress.tls[0].hosts[0]='nessie.local' +``` + +The deployment process may take some time. Use the following command to check its status and get the ingress IP address. + +```shell +kubectl get ingress -n nessie-ns +``` + +Add an entry in the local hosts file (e.g. `/etc/hosts`) mapping that IP address to `nessie.local`, for example: + +```shell +192.168.49.2 nessie.local +``` + +Use `curl` to verify that the server is accessible: + +```shell +$ curl https://nessie.local/api/v2/config +{ + "defaultBranch" : "main", + "minSupportedApiVersion" : 1, + "maxSupportedApiVersion" : 2, + "actualApiVersion" : 2, + "specVersion" : "2.0.0" +} +``` + +## Accessing Nessie UI over HTTPS + +Please note that most browsers do not trust self-signed certificates, so an exception will have to be manually +granted to the "Nessie" certificate. From 45da97248e3827fb294ef65545f065e00fdfa7ca Mon Sep 17 00:00:00 2001 From: Dmitri Bourlatchkov Date: Thu, 25 May 2023 16:45:41 -0400 Subject: [PATCH 2/5] Review: fix key generation command --- site/docs/guides/tls.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/site/docs/guides/tls.md b/site/docs/guides/tls.md index 9bdfe1300df..cc04bf74dd3 100644 --- a/site/docs/guides/tls.md +++ b/site/docs/guides/tls.md @@ -19,10 +19,11 @@ To generate a fresh pair of a key and a (self-signed) certificate: ```shell openssl req -new -subj "/CN=Nessie" -addext "subjectAltName = DNS:nessie.local" \ - -newkey rsa:2048 -keyout nessie-key.pem -out nessie.crt -noenc + -newkey rsa:2048 -keyout nessie-key.pem -out nessie.crt -x509 -nodes ``` -Note the `-noenc` option. It is used only for the sake of simplicity of this example deployment. +Note the `-nodes` option. It is used only for the sake of simplicity of this example deployment. Also, newer `openssl` +versions deprecated it in favour of `-noenc`. Add the new certificate to the local set of CA certificates on the client host (where the Nessie clients, such as Nessie CLI / `curl` / browser, are going to run). From 19d617e539a46b820a8d19de888341bc3edb6e26 Mon Sep 17 00:00:00 2001 From: Dmitri Bourlatchkov Date: Fri, 26 May 2023 09:52:36 -0400 Subject: [PATCH 3/5] Update site/docs/guides/tls.md Co-authored-by: Alexandre Dutra --- site/docs/guides/tls.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/site/docs/guides/tls.md b/site/docs/guides/tls.md index cc04bf74dd3..92e54a31f2a 100644 --- a/site/docs/guides/tls.md +++ b/site/docs/guides/tls.md @@ -46,11 +46,11 @@ kubectl -n nessie-ns create secret tls nessie-tls \ ```shell helm install nessie -n nessie-ns helm/nessie \ - --set ingress.enabled=true \ - --set ingress.hosts[0].host='nessie.local' \ - --set ingress.hosts[0].paths[0]='/' \ - --set ingress.tls[0].secretName=nessie-tls \ - --set ingress.tls[0].hosts[0]='nessie.local' + --set 'ingress.enabled=true' \ + --set 'ingress.hosts[0].host=nessie.local' \ + --set 'ingress.hosts[0].paths[0]=/' \ + --set 'ingress.tls[0].secretName=nessie-tls' \ + --set 'ingress.tls[0].hosts[0]=nessie.local' ``` The deployment process may take some time. Use the following command to check its status and get the ingress IP address. From daa82810809f8b89413ec01c4f0849605125e0ea Mon Sep 17 00:00:00 2001 From: Dmitri Bourlatchkov Date: Fri, 26 May 2023 09:52:47 -0400 Subject: [PATCH 4/5] Update site/docs/guides/tls.md Co-authored-by: Alexandre Dutra --- site/docs/guides/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/guides/tls.md b/site/docs/guides/tls.md index 92e54a31f2a..44fdf5ac5c5 100644 --- a/site/docs/guides/tls.md +++ b/site/docs/guides/tls.md @@ -45,7 +45,7 @@ kubectl -n nessie-ns create secret tls nessie-tls \ ## Deploying Nessie with Helm ```shell -helm install nessie -n nessie-ns helm/nessie \ +helm install nessie -n nessie-ns nessie-helm/nessie \ --set 'ingress.enabled=true' \ --set 'ingress.hosts[0].host=nessie.local' \ --set 'ingress.hosts[0].paths[0]=/' \ From 7f29a69574daa507687f7f3ca5797a076574cfe1 Mon Sep 17 00:00:00 2001 From: Dmitri Bourlatchkov Date: Fri, 26 May 2023 10:06:01 -0400 Subject: [PATCH 5/5] review: clarifies k8s namespace and /etc/hosts usage --- site/docs/guides/tls.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/site/docs/guides/tls.md b/site/docs/guides/tls.md index 44fdf5ac5c5..d3ca855a0a6 100644 --- a/site/docs/guides/tls.md +++ b/site/docs/guides/tls.md @@ -37,6 +37,15 @@ This should output something like "Certificate added: CN=Nessie". ## Creating a k8s Secret for the Nessie Certificate +Make sure a dedicated k8s namespace exists. This example uses the `nessie-ns` name. If it does not exist run the +following command to create it: + +```shell +kubectl create namespace nessie-ns +``` + +Create a TLS secret for Nessie: + ```shell kubectl -n nessie-ns create secret tls nessie-tls \ --cert=nessie.crt --key=nessie-key.pem @@ -44,6 +53,14 @@ kubectl -n nessie-ns create secret tls nessie-tls \ ## Deploying Nessie with Helm +Add the Nessie repository to Helm: + +```shell +helm repo add nessie-helm https://charts.projectnessie.org +``` + +Install the Nessie helm chart: + ```shell helm install nessie -n nessie-ns nessie-helm/nessie \ --set 'ingress.enabled=true' \ @@ -65,6 +82,11 @@ Add an entry in the local hosts file (e.g. `/etc/hosts`) mapping that IP address 192.168.49.2 nessie.local ``` +Note: Some tools allow substituting host names with specific IP addresses on the command line. +(e.g. `curl --resolve "nessie.local:443:$(minikube ip)" ...`) If you intend to use only those tools, then modifying +`/etc/hosts` is not necessary. However, Nessie python CLI and java client rely on the OS to be able to resolve +`nessie.local`, so to be able to use them the simplest approach is to define `nessie.local` in `/etc/hosts`. + Use `curl` to verify that the server is accessible: ```shell