From 8f413e239f53fdc5f98b2e796857bf81fb64ba4a Mon Sep 17 00:00:00 2001
From: Nghia Tran <tcnghia@gmail.com>
Date: Thu, 19 Jul 2018 15:33:33 -0700
Subject: [PATCH] How to use paid SSL cert with Knative (#146)

* Add simple SSL instruction.

* Remove whitespaces.

* Revise based on the comments

* Add license footer

* Add LetsEncrypt instructions

* Remove TLS limitation
---
 serving/README.md            |  3 --
 serving/using-an-ssl-cert.md | 96 ++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 3 deletions(-)
 create mode 100644 serving/using-an-ssl-cert.md

diff --git a/serving/README.md b/serving/README.md
index ee96e6c91..f08b0a559 100644
--- a/serving/README.md
+++ b/serving/README.md
@@ -84,9 +84,6 @@ in the Knative Serving repository.
 See the [Knative Serving Issues](https://github.com/knative/serving/issues) page for a full list of
 known issues.
 
-* **No support for TLS** - Currently the Knative Serving components do not support TLS connections for
-  inbound HTTPS traffic. See [#537](https://github.com/knative/serving/issues/537) for more details.
-
 ---
 
 Except as otherwise noted, the content of this page is licensed under the
diff --git a/serving/using-an-ssl-cert.md b/serving/using-an-ssl-cert.md
new file mode 100644
index 000000000..3e9062a00
--- /dev/null
+++ b/serving/using-an-ssl-cert.md
@@ -0,0 +1,96 @@
+# Configuring HTTPS with a custom certificate
+
+If you already have an SSL/TLS certificate for your domain you can
+follow the steps below to configure Knative to use your certificate
+and enable HTTPS connections.
+
+Before you begin, you will need to 
+[configure Knative to use your custom domain](./using-a-custom-domain.md).
+
+**Note:** due to limitations in Istio, Knative only supports a single 
+certificate per cluster. If you will serve multiple domains in the same
+cluster, make sure the certificate is signed for all the domains.
+
+## Add the Certificate and Private Key into a secret
+
+Assuming you have two files, `cert.pk` which contains your certificate private
+key, and `cert.pem` which contains the public certificate, you can use the 
+following command to create a secret that stores the certificate. Note the
+name of the secret, `istio-ingressgateway-certs` is required.
+
+```shell
+kubectl create -n istio-system secret tls istio-ingressgateway-certs \
+  --key cert.pk \
+  --cert cert.pem
+```
+
+## Configure the Knative shared Gateway to use the new secret
+
+Once you have created a secret that contains the certificate,
+you need to update the Gateway spec to use the HTTPS.
+
+To edit the shared gateway, run:
+
+```shell
+kubectl edit gateway knative-shared-gateway -n knative-serving
+```
+
+Change the Gateway spec to include the `tls:` section as shown below, then
+save the changes.
+
+```yaml
+# Please edit the object below. Lines beginning with a '#' will be ignored.
+# and an empty file will abort the edit. If an error occurs while saving this file will be
+# reopened with the relevant failures.
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  # ... skipped ...
+spec:
+  selector:
+    knative: ingressgateway
+  servers:
+  - hosts:
+    - '*'
+    port:
+      name: http
+      number: 80
+      protocol: HTTP
+  - hosts:
+    - '*'
+    port:
+      name: https
+      number: 443
+      protocol: HTTPS
+    tls:
+      mode: SIMPLE
+      privateKey: /etc/istio/ingressgateway-certs/tls.key
+      serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+```
+
+Once the change has been made, you can now use the HTTPS protocol to access
+your deployed services.
+
+
+## Obtaining an SSL/TLS certificate using LetsEncrypt
+
+If you don't have an existing SSL/TLS certificate, you can use [LetsEncrypt](https://letsencrypt.org)
+to obtain a certificate manually.
+
+1. Install the `certbot-auto` script from the [Certbot website](https://certbot.eff.org/docs/install.html#certbot-auto).
+1. Use the certbot to request a certificate, using DNS validation. The certbot tool will walk
+   you through validating your domain ownership by creating TXT records in your domain.
+
+    ```shell
+    ./certbot-auto certonly --manual --preferred-challenges dns -d '*.default.yourdomain.com'
+    ```
+
+1. When certbot is complete, you will have two output files, `privkey.pem` and `fullchain.pem`. These files
+   map to the `cert.pk` and `cert.pem` files used above.
+
+---
+
+Except as otherwise noted, the content of this page is licensed under the
+[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/),
+and code samples are licensed under the
+[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).