Update the Auto TLS instruction (#2083)

* initial version of auto tls instruction

* Update auto-tls doc to mention namespace cert feature and http01 challenge feature

* address comments

* fix format

* address comments

docs/serving/using-auto-tls.md

@@ -6,56 +6,68 @@ type: "docs"
 ---
 
 If you install and configure cert-manager, you can configure Knative to
-automatically obtain new TLS certificates and renew existing ones. To learn more
+automatically obtain new TLS certificates and renew existing ones for Knative 
-about using secure connections in Knative, see
+Services.
+To learn more about using secure connections in Knative, see
 [Configuring HTTPS with TLS certificates](./using-a-tls-cert.md).
 
+## Automatic TLS provision mode
+
+Knative supports the following Auto TLS modes:
+
+1.  Using DNS-01 challenge
+
+    In this mode, your cluster needs to be able to talk to your DNS server to verify the ownership of your domain.
+    - **Provision Certificate per namespace is supported when using DNS-01 challenge mode.**
+      - This is the recommended mode for faster certificate provision.
+      - In this mode, a single Certificate will be provisioned per namespace and is reused across the Knative Services within the same namespace.
+
+    - **Provision Certificate per namespace is supported when using DNS-01 challenge mode.**
+      - This is the recommended mode for better certificate islation between Knative Services.
+      - In this mode, a Certificate will be provisioned for each Knative Service.
+      - The TLS effective time is longer as it needs Certificate provision for each Knative Service creation.
+
+1.  Using HTTP-01 challenge
+
+    - In this type, your cluster does not need to be able to talk to your DNS server. You just 
+    need to map your domain to the IP of the cluser ingress.
+    - When using HTTP-01 challenge, **a certificate will be provisioned per Knative Service.** Certificate provision per namespace is not supported when using HTTP-01 challenge. 
+
 ## Before you begin
 
-You must meet the following prerequisites to enable automatic certificate
+You must meet the following prerequisites to enable auto TLS:
-provisioning:
 
 - The following must be installed on your Knative cluter:
   - [Knative Serving](../install/).
-  - [Istio with SDS, version 1.1 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway),
+  - [Istio with SDS, version 1.3 or higher](../install/installing-istio.md#installing-istio-with-SDS-to-secure-the-ingress-gateway),
     [Contour, version 1.1 or higher](../install/Knative-with-Contour.md),
     or [Gloo, version 0.18.16 or higher](../install/Knative-with-Gloo.md).
     Note: Currently, [Ambassador](https://github.com/datawire/ambassador) is unsupported.
-  - [cert-manager version `0.6.1` or higher](./installing-cert-manager.md).
+  - [cert-manager version `0.12.0` or higher](./installing-cert-manager.md).
 - Your Knative cluster must be configured to use a
   [custom domain](./using-a-custom-domain.md).
 - Your DNS provider must be setup and configured to your domain.
+- If you want to use HTTP-01 challenge, you need to configure your custom 
+domain to map to the IP of ingress. You can achieve this by adding a DNS A record to map the domain to the IP according to the instructions of your DNS provider.
 
-## Enabling automatic certificate provisioning
+## Enabling Auto TLS
 
-To enable support for automatic TLS certificate provisioning in Knative:
+To enable support for Auto TLS in Knative:
 
-1. Determine if `networking-certmanager` is already installed by running the 
+### Create cert-manager ClusterIssuer
-    following command:
-
-    ```shell
-    kubectl get deployment networking-certmanager -n knative-serving
-    ```
-
-1. If `networking-certmanager` is not found, run the following command:
-
-    ```shell
-    kubectl apply --filename https://github.com/knative/serving/releases/download/{{< version >}}/serving-cert-manager.yaml
-    ```
 
 1.  Create and add the `ClusterIssuer` configuration file to your Knative cluster
-   to define who issues the TLS certificates, how requests are validated
+to define who issues the TLS certificates, how requests are validated,
-   (`DNS-01`), and which DNS provider validates those requests.
+and which DNS provider validates those requests.
 
-   1. Create the `ClusterIssuer` file:
+    #### ClusterIssuer for DNS-01 challenge
 
     Use the cert-manager reference to determine how to configure your
     `ClusterIssuer` file:
-
     - See the generic
       [`ClusterIssuer` example](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme.html#creating-a-basic-acme-issuer)
     - Also see the
-        [`DNS-01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html)
+      [`DNS01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html)
 
       **Example**: Cloud DNS `ClusterIssuer` configuration file:
 
@@ -67,11 +79,10 @@ To enable support for automatic TLS certificate provisioning in Knative:
       [Configuring HTTPS with cert-manager and Google Cloud DNS](./using-cert-manager-on-gcp.md).
 
       ```shell
-      apiVersion: certmanager.k8s.io/v1alpha1
+      apiVersion: cert-manager.io/v1alpha2
       kind: ClusterIssuer
       metadata:
-        name: letsencrypt-issuer
+        name: letsencrypt-dns-issuer
-        namespace: cert-manager
       spec:
         acme:
           server: https://acme-v02.api.letsencrypt.org/directory
@@ -80,10 +91,9 @@ To enable support for automatic TLS certificate provisioning in Knative:
           email: myemail@gmail.com
           privateKeySecretRef:
             # Set privateKeySecretRef to any unused secret name.
-            name: letsencrypt-issuer
+            name: letsencrypt-dns-issuer
-          dns01:
+          solvers:
-            providers:
+          - dns01:
-            - name: cloud-dns-provider
             clouddns:
               # Set this to your GCP project-id
               project: $PROJECT_ID
@@ -94,28 +104,73 @@ To enable support for automatic TLS certificate provisioning in Knative:
                 key: key.json
       ```
 
-   1. Add your `ClusterIssuer` configuration to your Knative cluster by running
+    ####  ClusterIssuer for HTTP-01 challenge
-      the following commands, where `<filename>` is the name of the file that
-      you created:
 
-      1. Add the configuration file to Knative:
+    Run the following command to apply the ClusterIssuer for HTT01 challenge:
 
     ```shell
-         kubectl apply -f  <filename>.yaml
+    kubectl apply -f - <<EOF
+    apiVersion: cert-manager.io/v1alpha2
+    kind: ClusterIssuer
+    metadata:
+      name: letsencrypt-http01-issuer
+    spec:
+      acme:
+        privateKeySecretRef:
+          name: letsencrypt
+        server: https://acme-v02.api.letsencrypt.org/directory
+        solvers:
+        - http01:
+           ingress:
+             class: istio
+    EOF
     ```
 
-      1. Ensure that the file is created successfully:
+1.  Ensure that the ClusterIssuer is created successfully:
 
     ```shell
-         kubectl get clusterissuer --namespace cert-manager letsencrypt-issuer --output yaml
+    kubectl get clusterissuer <cluster-issuer-name> --output yaml
     ```
 
     Result: The `Status.Conditions` should include `Ready=True`.
 
-1. Update your
+
-   [`config-certmanager` ConfigMap](https://github.com/knative/serving/blob/master/config/config-certmanager.yaml)
+### Install networking-certmanager deployment
-   in the `knative-serving` namespace to define your new `ClusterIssuer`
+
-   configuration and your your DNS provider.
+1.  Determine if `networking-certmanager` is already installed by running the 
+    following command:
+
+    ```shell
+    kubectl get deployment networking-certmanager -n knative-serving
+    ```
+
+1.  If `networking-certmanager` is not found, run the following command:
+
+    ```shell
+    kubectl apply --filename https://github.com/knative/serving/releases/download/v{{< version >}}/serving-cert-manager.yaml
+    ```
+
+### Install networking-ns-cert component
+
+If you choose to use the mode of provisioning certificate per namespace, you need to install `networking-ns-cert` components.
+
+1. Determine if `networking-ns-cert` deployment is already installed by 
+running the following command:
+
+    ```shell
+    kubectl get deployment networking-ns-cert -n knative-serving
+    ```
+
+1. If `networking-ns-cert` deployment is not found, run the following command:
+
+    ```shell
+    kubectl apply --filename https://github.com/knative/serving/releases/download/v{{< version >}}/serving-nscert.yaml
+    ```
+
+### Configure config-certmanager ConfigMap
+
+Update your [`config-certmanager` ConfigMap](https://github.com/knative/serving/blob/master/config/config-certmanager.yaml)
+in the `knative-serving` namespace to reference your new `ClusterIssuer`.
 
 1.  Run the following command to edit your `config-certmanager` ConfigMap:
 
@@ -123,7 +178,7 @@ To enable support for automatic TLS certificate provisioning in Knative:
     kubectl edit configmap config-certmanager --namespace knative-serving
     ```
 
-   1. Add the `issuerRef` and `solverConfig` sections within the `data` section:
+1.  Add the `issuerRef` within the `data` section:
 
     ```shell
     ...
@@ -132,10 +187,6 @@ To enable support for automatic TLS certificate provisioning in Knative:
       issuerRef: |
         kind: ClusterIssuer
         name: letsencrypt-issuer
-
-        solverConfig: |
-          dns01:
-            provider: cloud-dns-provider
     ```
 
     Example:
@@ -151,19 +202,21 @@ To enable support for automatic TLS certificate provisioning in Knative:
     data:
       issuerRef: |
         kind: ClusterIssuer
-          name: letsencrypt-issuer
+        name: letsencrypt-http01-issuer
-        solverConfig: |
-          dns01:
-            provider: cloud-dns-provider
     ```
 
+    `issueRef` defines which `ClusterIssuer` will be used by Knative to issue 
+    certificates.
+
 1.  Ensure that the file was updated successfully:
 
     ```shell
     kubectl get configmap config-certmanager --namespace knative-serving --output yaml
     ```
 
-1. Update the
+### Turn on Auto TLS
+
+Update the
 [`config-network` ConfigMap](https://github.com/knative/serving/blob/master/config/config-network.yaml)
 in the `knative-serving` namespace to enable `autoTLS`and specify how HTTP
 requests are handled:
@@ -214,7 +267,6 @@ To enable support for automatic TLS certificate provisioning in Knative:
     - `Redirected`: Responds to HTTP request with a `302` redirect to ask the
       clients to use HTTPS.
 
-
      ```shell
      ...
      data:
@@ -239,6 +291,9 @@ To enable support for automatic TLS certificate provisioning in Knative:
        ...
      ```
 
+    **Note:**
+    When using HTTP-01 challenge, `httpProtocol` field has to be set to `Enabled` to make sure HTTP-01 challenge requests can be accepted by the cluster.
+
 1.  Ensure that the file was updated successfully:
 
     ```shell
@@ -248,3 +303,19 @@ To enable support for automatic TLS certificate provisioning in Knative:
 Congratulations! Knative is now configured to obtain and renew TLS certificates.
 When your TLS certificate is active on your cluster, your Knative services will
 be able to handle HTTPS traffic.
+
+### Verify Auto TLS
+
+1.  Run the following comand to create a Knative Service:
+    ```shell
+    kubectl apply -f https://raw.githubusercontent.com/knative/docs/master/docs/serving/samples/autoscale-go/service.yaml
+    ```
+
+1.  When the certificate is provisioned (which could take up to several minutes depending on 
+    the challenge type), you should see something like:
+    ```
+    NAME               URL                                           LATESTCREATED            LATESTREADY              READY   REASON
+    autoscale-go       https://autoscale-go.default.{custom-domain}   autoscale-go-6jf85 autoscale-go-6jf85       True  
+    ```
+
+    Note that the URL will be **https** in this case.