Merge branch 'docs-serverless-ssl' into 'master'

Docs serverless ssl See merge request gitlab-org/gitlab-ce!29946

Merge branch 'docs-serverless-ssl' into 'master'
Docs serverless ssl See merge request gitlab-org/gitlab-ce!29946
bf82e838 · Evan Read · 36451a75 · 4ecf3dab · bf82e838 · bf82e838
Commit bf82e838 authored Jun 28, 2019 by Evan Read
2 changed files
--- a/doc/user/project/clusters/serverless/img/function-endpoint.png
+++ b/doc/user/project/clusters/serverless/img/function-endpoint.png
--- a/doc/user/project/clusters/serverless/index.md
+++ b/doc/user/project/clusters/serverless/index.md
@@ -325,3 +325,275 @@ loading or is not available at this time._  It will appear upon the first access
 page, but should go away after a few seconds. If the message does not disappear, then it
 is possible that GitLab is unable to connect to the Prometheus instance running on the
 cluster.
+
+## Enabling TLS for Knative services
+
+By default, a GitLab serverless deployment will be served over `http`. In order to serve over `https` you
+must manually obtain and install TLS certificates.
+
+The simplest way to accomplish this is to 
+use [Certbot to manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS.
+
+NOTE: **Note:**
+The instructions below relate to installing and running Certbot on a Linux server and may not work on other operating systems.
+
+1. Install Certbot by running the 
+   [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto).
+   On the command line of your server, run the following commands:
+
+    ```sh
+    wget https://dl.eff.org/certbot-auto
+    sudo mv certbot-auto /usr/local/bin/certbot-auto
+    sudo chown root /usr/local/bin/certbot-auto
+    chmod 0755 /usr/local/bin/certbot-auto
+    /usr/local/bin/certbot-auto --help
+    ```
+
+    To check the integrity of the `certbot-auto` script, run:
+
+      ```sh
+      wget -N https://dl.eff.org/certbot-auto.asc
+      gpg2 --keyserver ipv4.pool.sks-keyservers.net --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2
+      gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc /usr/local/bin/certbot-auto
+      ```
+
+    The output of the last command should look something like:
+
+      ```sh
+      gpg: Signature made Mon 10 Jun 2019 06:24:40 PM EDT
+      gpg:                using RSA key A2CFB51FA275A7286234E7B24D17C995CD9775F2
+      gpg: key 4D17C995CD9775F2 marked as ultimately trusted
+      gpg: checking the trustdb
+      gpg: marginals needed: 3  completes needed: 1  trust model: pgp
+      gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+      gpg: next trustdb check due at 2027-11-22
+      gpg: Good signature from "Let's Encrypt Client Team <letsencrypt-client@eff.org>" [ultimate]
+      ```
+
+1. Run the following command to use Certbot to request a certificate
+   using DNS challenge during authorization:
+
+
+    ```sh
+    ./certbot-auto certonly --manual --preferred-challenges dns -d '*.<namespace>.example.com'
+    ```
+
+    Where `<namespace>` is the namespace created by GitLab for your serverless project (composed of `<projectname+id>`) and
+    `example.com` is the domain being used for your project. If you are unsure what the namespace of your project is, navigate
+    to the **Operations > Serverless** page of your project and inspect
+    the endpoint provided for your function/app.
+
+    ![function_endpoint](img/function-endpoint.png)
+
+    In the above image, the namespace for the project is `node-function-11909507` and the domain is `knative.info`, thus
+    certificate request line would look like this:
+
+    ```sh
+    ./certbot-auto certonly --manual --preferred-challenges dns -d '*.node-function-11909507.knative.info'
+    ```
+
+    The Certbot tool walks you through the steps of validating that you own each domain that you specify by creating TXT records in those domains.
+    After this process is complete, the output should look something like this:
+
+    ```sh
+    IMPORTANT NOTES:
+    - Congratulations! Your certificate and chain have been saved at:
+      /etc/letsencrypt/live/namespace.example.com/fullchain.pem
+      Your key file has been saved at:
+      /etc/letsencrypt/live/namespace.example/privkey.pem
+      Your cert will expire on 2019-09-19. To obtain a new or tweaked
+      version of this certificate in the future, simply run certbot-auto
+      again. To non-interactively renew *all* of your certificates, run
+      "certbot-auto renew"
+    -----BEGIN PRIVATE KEY-----
+    - Your account credentials have been saved in your Certbot
+      configuration directory at /etc/letsencrypt. You should make a
+      secure backup of this folder now. This configuration directory will
+      also contain certificates and private keys obtained by Certbot so
+      making regular backups of this folder is ideal.
+    ```
+
+1. Create certificate and private key files. Using the contents of the files
+   returned by Certbot, we'll create two files in order to create the
+   Kubernetes secret:
+
+      Run the following command to see the contents of `fullchain.pem`:
+
+      ```sh
+      sudo cat /etc/letsencrypt/live/node-function-11909507.knative.info/fullchain.pem
+      ```
+
+      Output should look like this:
+
+      ```sh
+      -----BEGIN CERTIFICATE-----
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b4ag==
+      -----END CERTIFICATE-----
+      -----BEGIN CERTIFICATE-----
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      K2fcb195768c39e9a94cec2c2e30Qg==
+      -----END CERTIFICATE-----
+      ```
+
+      Create a file with the name `cert.pem` with the contents of the entire output.
+
+      Once `cert.pem` is created, run the following command to see the contents of `privkey.pem`:
+
+      ```sh
+      sudo cat /etc/letsencrypt/live/namespace.example/privkey.pem
+      ```
+
+      Output should look like this:
+
+      ```sh
+      -----BEGIN PRIVATE KEY-----
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
+      -----BEGIN CERTIFICATE-----
+      fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
+      4f294d1eaca42b8692017b4262==
+      -----END PRIVATE KEY-----
+      ```
+
+      Create a new file with the name `cert.pk` with the contents of the entire output.
+
+1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and
+   the private key `cert.pk`:
+
+    NOTE: **Note:**
+    Running `kubectl` commands on your cluster requires setting up access to the cluster first.
+    For clusters created on GKE, see
+    [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl).
+    For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+
+    ```sh
+    kubectl create --namespace istio-system secret tls istio-ingressgateway-certs \
+    --key cert.pk \
+    --cert cert.pem
+    ```
+
+    Where `cert.pem` and `cert.pk` are your certificate and private key files. Note that the `istio-ingressgateway-certs` secret name is required.
+
+1. Configure Knative to use the new secret that you created for HTTPS
+   connections. Run the 
+  following command to open the Knative shared `gateway` in edit mode:
+
+    ```sh
+    kubectl edit gateway knative-ingress-gateway --namespace knative-serving
+    ```
+
+      Update the gateway to include the following tls: section and configuration:
+
+      ```sh
+      tls:
+        mode: SIMPLE
+        privateKey: /etc/istio/ingressgateway-certs/tls.key
+        serverCertificate: /etc/istio/ingressgateway-certs/tls.crt
+      ```
+
+      Example:
+
+      ```sh
+      apiVersion: networking.istio.io/v1alpha3
+      kind: Gateway
+      metadata:
+        # ... skipped ...
+      spec:
+        selector:
+          istio: 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
+      ```
+
+      After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services.
+      In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway`
+      to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates.
\ No newline at end of file