From ce6a33e5c6ec1ac50a5b052a1ae635903e0bf7fc Mon Sep 17 00:00:00 2001 From: Rafael Vasquez Date: Thu, 9 Nov 2023 17:20:55 -0500 Subject: [PATCH 1/5] Update TLS docs Signed-off-by: Rafael Vasquez --- docs/configuration/tls.md | 42 +++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/configuration/tls.md b/docs/configuration/tls.md index 492db227..0d4115cf 100644 --- a/docs/configuration/tls.md +++ b/docs/configuration/tls.md @@ -4,17 +4,17 @@ TLS can be configured via the `tls.secretName` and `tls.clientAuth` parameters o When TLS is enabled for the external inferencing interface, all of the ModelMesh Serving internal (intra-Pod) communication will be secured using the same certificates. The internal links will use mutual TLS regardless of whether client authentication is required for the external connections. -There are various ways to generate TLS certificates, below are steps on how to do this using OpenSSL or CertManager. +There are various ways to generate TLS certificates. Below are steps on how to do this using OpenSSL or CertManager. ## Generating TLS Certificates for Dev/Test using OpenSSL -To create a SAN key/cert for TLS, use command: +To create a SAN key/cert for TLS, use the following command: ```shell openssl req -x509 -newkey rsa:4096 -sha256 -days 3560 -nodes -keyout example.key -out example.crt -subj '/CN=modelmesh-serving' -extensions san -config openssl-san.config ``` -Where the contents of `openssl-san.config` look like: +Where the contents of `openssl-san.config` include: ``` [ req ] @@ -23,7 +23,9 @@ distinguished_name = req subjectAltName = DNS:modelmesh-serving.${NAMESPACE},DNS:localhost,IP:0.0.0.0 ``` -With the generated key/cert, create a kube secret with contents like: +`${NAMESPACE}` is the namespace where the ModelMesh Serving Service is deployed. + +From there, you can create a secret using the generated certificate and key: ```yaml apiVersion: v1 @@ -37,13 +39,19 @@ stringData: ca.crt: ``` -For basic TLS, only the fields `tls.crt` and `tls.key` are needed in the kube secret. For mutual TLS, add `ca.crt` in the kube secret and set the configuration `tls.clientAuth` to `require` in the ConfigMap `model-serving-config`. +For basic TLS, only the fields `tls.crt` and `tls.key` are required. For mutual TLS, `ca.crt` should be included and `tls.clientAuth` should be set to `require` in the [`model-serving-config` ConfigMap](./README.md). + +You can also create this secret imperatively using: + +``` +kubectl create secret tls --cert --key +``` ## Creating TLS Certificates using CertManager -1. If necessary, install `cert-manager` in the cluster - follow the steps here: https://cert-manager.io/docs/installation/. +1. [Install `cert-manager`](https://cert-manager.io/docs/installation/) in the cluster. -2. Create an `Issuer` CR +2. Create an `Issuer` CR, modifying its name if needed: kubectl apply -f - < Date: Wed, 22 Nov 2023 16:33:10 -0500 Subject: [PATCH 2/5] Lints Signed-off-by: Rafael Vasquez --- docs/configuration/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/tls.md b/docs/configuration/tls.md index 0d4115cf..efd54361 100644 --- a/docs/configuration/tls.md +++ b/docs/configuration/tls.md @@ -88,7 +88,7 @@ kubectl create secret tls --cert --key kind: Issuer EOF - Above, `${NAMESPACE}` is the namespace where the ModelMesh Serving Service resides, and `modelmesh-serving` is the name of that service (configured via the `inferenceServiceName` [global ConfigMap](./README.md). parameter). You can also replace `issuerRef.name` to match the name of the issuer used above if necessary. + Above, `${NAMESPACE}` is the namespace where the ModelMesh Serving Service resides, and `modelmesh-serving` is the name of that service (configured via the `inferenceServiceName` [global ConfigMap](./README.md). parameter). You can also replace `issuerRef.name` to match the name of the issuer used above if necessary. `${HOSTNAME}` is optional, but should be set when configuring an external Kubernetes Ingress or OpenShift route as described [here](./README.md#exposing-an-external-endpoint-using-an-openshift-route): From fca5322ef3b09c204ab8d76b65c206792c2e5818 Mon Sep 17 00:00:00 2001 From: Rafael Vasquez Date: Fri, 24 Nov 2023 12:33:48 -0500 Subject: [PATCH 3/5] Update for easier execution Signed-off-by: Rafael Vasquez --- docs/configuration/tls.md | 184 ++++++++++++++++++++++---------------- 1 file changed, 105 insertions(+), 79 deletions(-) diff --git a/docs/configuration/tls.md b/docs/configuration/tls.md index efd54361..1c36dc51 100644 --- a/docs/configuration/tls.md +++ b/docs/configuration/tls.md @@ -8,120 +8,146 @@ There are various ways to generate TLS certificates. Below are steps on how to d ## Generating TLS Certificates for Dev/Test using OpenSSL -To create a SAN key/cert for TLS, use the following command: +First, define the variables that will be used in the commands below. Change the values to suit your environment: ```shell -openssl req -x509 -newkey rsa:4096 -sha256 -days 3560 -nodes -keyout example.key -out example.crt -subj '/CN=modelmesh-serving' -extensions san -config openssl-san.config +NAMESPACE="modelmesh-serving" # the controller namespace where ModelMesh Serving was deployed +SECRET_NAME="modelmesh-certificate" ``` -Where the contents of `openssl-san.config` include: +Create an OpenSSL configuration file named `openssl-san.config`: -``` +``` shell +cat > openssl-san.config << EOF [ req ] distinguished_name = req [ san ] subjectAltName = DNS:modelmesh-serving.${NAMESPACE},DNS:localhost,IP:0.0.0.0 +EOF ``` -`${NAMESPACE}` is the namespace where the ModelMesh Serving Service is deployed. +Use the following command to create a SAN key/cert: + +```shell +openssl req -x509 -newkey rsa:4096 -sha256 -days 3560 -nodes \ + -keyout example.key \ + -out example.crt \ + -subj "/CN=${NAMESPACE}" \ + -extensions san \ + -config openssl-san.config +``` From there, you can create a secret using the generated certificate and key: -```yaml +```shell +kubectl apply -f - < - tls.key: - ca.crt: + tls.crt: $(cat example.crt) + tls.key: $(cat example.key) + ca.crt: $(cat example.crt) +EOF ``` -For basic TLS, only the fields `tls.crt` and `tls.key` are required. For mutual TLS, `ca.crt` should be included and `tls.clientAuth` should be set to `require` in the [`model-serving-config` ConfigMap](./README.md). +**Note:** For basic TLS, only the fields `tls.crt` and `tls.key` are required. For mutual TLS, `ca.crt` should be included and `tls.clientAuth` should be set to `require` in the [`model-serving-config` ConfigMap](./README.md). -You can also create this secret imperatively using: +Alternatively, you can create this secret imperatively using: ``` -kubectl create secret tls --cert --key +kubectl create secret tls ${SECRET_NAME} --cert "example.crt" --key "example.key" ``` ## Creating TLS Certificates using CertManager +First, define the variables that will be used in the commands below and change the values as needed. + +```shell +NAMESPACE="modelmesh-serving" # the controller namespace where ModelMesh Serving was deployed +SECRET_NAME="modelmesh-certificate" +HOSTNAME=localhost +``` + 1. [Install `cert-manager`](https://cert-manager.io/docs/installation/) in the cluster. 2. Create an `Issuer` CR, modifying its name if needed: - kubectl apply -f - < ca.crt + ```shell + kubectl get secret ${SECRET_NAME} -o jsonpath="{.data.ca\.crt}" > ca.crt + ``` \ No newline at end of file From 7603c540f83a0efbefa69b59efbee5a0b035ae15 Mon Sep 17 00:00:00 2001 From: Rafael Vasquez Date: Fri, 24 Nov 2023 12:57:54 -0500 Subject: [PATCH 4/5] Replaces HOSTNAME note and lints Signed-off-by: Rafael Vasquez --- docs/configuration/tls.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/configuration/tls.md b/docs/configuration/tls.md index 1c36dc51..ec28920e 100644 --- a/docs/configuration/tls.md +++ b/docs/configuration/tls.md @@ -17,7 +17,7 @@ SECRET_NAME="modelmesh-certificate" Create an OpenSSL configuration file named `openssl-san.config`: -``` shell +```shell cat > openssl-san.config << EOF [ req ] distinguished_name = req @@ -69,7 +69,7 @@ First, define the variables that will be used in the commands below and change t ```shell NAMESPACE="modelmesh-serving" # the controller namespace where ModelMesh Serving was deployed -SECRET_NAME="modelmesh-certificate" +SECRET_NAME="modelmesh-certificate" HOSTNAME=localhost ``` @@ -117,7 +117,9 @@ HOSTNAME=localhost kind: Issuer EOF ``` - + + **Note:** `${HOSTNAME}` is optional but should be set when configuring an external Kubernetes Ingress or OpenShift route as described [here](./README.md#exposing-an-external-endpoint-using-an-openshift-route). + If the certificate request is successful, a TLS secret with the PEM-encoded certs will be created as `modelmesh-serving-cert`, assuming `metadata.name` wasn't modified. 4. Wait for the certificate to be successfully issued: @@ -125,13 +127,14 @@ HOSTNAME=localhost ```shell kubectl get certificate/modelmesh-serving-cert --watch ``` - + Once you see `READY` as `True`, proceed to the next step. + ``` NAME READY SECRET AGE modelmesh-serving-cert True modelmesh-certificate 21h ``` - + 5. Enable TLS in ModelMesh Serving by adding a value for `tls.secretName` in the ConfigMap, pointing to the secret created with the TLS key/cert details. ```shell @@ -146,8 +149,9 @@ HOSTNAME=localhost secretName: ${SECRET_NAME} EOF ``` + 6. Retrieve the `ca.crt` (to be used in clients): ```shell kubectl get secret ${SECRET_NAME} -o jsonpath="{.data.ca\.crt}" > ca.crt - ``` \ No newline at end of file + ``` From 641a889aaa2144c8d113a38ae2674a9e6f6de7c2 Mon Sep 17 00:00:00 2001 From: Rafael Vasquez Date: Fri, 24 Nov 2023 13:00:07 -0500 Subject: [PATCH 5/5] Update example names Signed-off-by: Rafael Vasquez --- docs/configuration/tls.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/configuration/tls.md b/docs/configuration/tls.md index ec28920e..1a4ec916 100644 --- a/docs/configuration/tls.md +++ b/docs/configuration/tls.md @@ -30,8 +30,8 @@ Use the following command to create a SAN key/cert: ```shell openssl req -x509 -newkey rsa:4096 -sha256 -days 3560 -nodes \ - -keyout example.key \ - -out example.crt \ + -keyout server.key \ + -out server.crt \ -subj "/CN=${NAMESPACE}" \ -extensions san \ -config openssl-san.config @@ -49,9 +49,9 @@ metadata: name: ${SECRET_NAME} type: kubernetes.io/tls stringData: - tls.crt: $(cat example.crt) - tls.key: $(cat example.key) - ca.crt: $(cat example.crt) + tls.crt: $(cat server.crt) + tls.key: $(cat server.key) + ca.crt: $(cat server.crt) EOF ``` @@ -60,7 +60,7 @@ EOF Alternatively, you can create this secret imperatively using: ``` -kubectl create secret tls ${SECRET_NAME} --cert "example.crt" --key "example.key" +kubectl create secret tls ${SECRET_NAME} --cert "server.crt" --key "server.key" ``` ## Creating TLS Certificates using CertManager