From 27382eee2c26d06a9c7e18827a38e38f6790ce1d Mon Sep 17 00:00:00 2001 From: Zhimin Xiang Date: Wed, 22 Jan 2020 14:27:24 -0800 Subject: [PATCH] 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 | 441 +++++++++++++++++++-------------- 1 file changed, 256 insertions(+), 185 deletions(-) diff --git a/docs/serving/using-auto-tls.md b/docs/serving/using-auto-tls.md index 0fc84d823..9881300bf 100644 --- a/docs/serving/using-auto-tls.md +++ b/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 -about using secure connections in Knative, see +automatically obtain new TLS certificates and renew existing ones for Knative +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 -provisioning: +You must meet the following prerequisites to enable auto TLS: - 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  - following command: +### Create cert-manager ClusterIssuer - ```shell - kubectl get deployment networking-certmanager -n knative-serving - ``` +1. Create and add the `ClusterIssuer` configuration file to your Knative cluster +to define who issues the TLS certificates, how requests are validated, +and which DNS provider validates those requests. -1. If `networking-certmanager` is not found, run the following command: + #### ClusterIssuer for DNS-01 challenge - ```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 - (`DNS-01`), and which DNS provider validates those requests. - - 1. Create the `ClusterIssuer` file: - - 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) + 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 + [`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 - namespace: cert-manager + name: letsencrypt-dns-issuer spec: acme: server: https://acme-v02.api.letsencrypt.org/directory @@ -80,171 +91,231 @@ 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 - dns01: - providers: - - name: cloud-dns-provider - clouddns: - # Set this to your GCP project-id - project: $PROJECT_ID - # Set this to the secret that we publish our service account key - # in the previous step. - serviceAccountSecretRef: - name: cloud-dns-key - key: key.json + name: letsencrypt-dns-issuer + solvers: + - dns01: + clouddns: + # Set this to your GCP project-id + project: $PROJECT_ID + # Set this to the secret that we publish our service account key + # in the previous step. + serviceAccountSecretRef: + name: cloud-dns-key + key: key.json ``` - 1. Add your `ClusterIssuer` configuration to your Knative cluster by running - the following commands, where `` is the name of the file that - you created: + #### ClusterIssuer for HTTP-01 challenge - 1. Add the configuration file to Knative: + Run the following command to apply the ClusterIssuer for HTT01 challenge: - ```shell - kubectl apply -f .yaml - ``` + ```shell + kubectl apply -f - < --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) - in the `knative-serving` namespace to define your new `ClusterIssuer` - configuration and your your DNS provider. - - 1. Run the following command to edit your `config-certmanager` ConfigMap: - - ```shell - kubectl edit configmap config-certmanager --namespace knative-serving - ``` - - 1. Add the `issuerRef` and `solverConfig` sections within the `data` section: - - ```shell - ... - data: - ... - issuerRef: | - kind: ClusterIssuer - name: letsencrypt-issuer - - solverConfig: | - dns01: - provider: cloud-dns-provider - ``` - - Example: - - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-certmanager - namespace: knative-serving - labels: - networking.knative.dev/certificate-provider: cert-manager - data: - issuerRef: | - kind: ClusterIssuer - name: letsencrypt-issuer - solverConfig: | - dns01: - provider: cloud-dns-provider - ``` - - 1. Ensure that the file was updated successfully: - - ```shell - kubectl get configmap config-certmanager --namespace knative-serving --output yaml - ``` - -1. 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: - - 1. Run the following command to edit your `config-network` ConfigMap: - - ```shell - kubectl edit configmap config-network --namespace knative-serving - ``` - - 1. Add the `autoTLS: Enabled` attribute under the `data` section: - - ```shell - ... - data: - ... - autoTLS: Enabled - ... - ``` - - Example: - - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-network - namespace: knative-serving - data: - ... - autoTLS: Enabled - ... - ``` - - 1. Configure how HTTP and HTTPS requests are handled in the - [`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110) - attribute. - - By default, Knative ingress is configured to serve HTTP traffic - (`httpProtocol: Enabled`). Now that your cluster is configured to use TLS - certificates and handle HTTPS traffic, you can specify whether or not any - HTTP traffic is allowed. - - Supported `httpProtocol` values: - - - `Enabled`: Serve HTTP traffic. - - `Disabled`: Rejects all HTTP traffic. - - `Redirected`: Responds to HTTP request with a `302` redirect to ask the - clients to use HTTPS. + Result: The `Status.Conditions` should include `Ready=True`. - ```shell - ... - data: - ... - autoTLS: Enabled - ... - ``` +### Install networking-certmanager deployment - Example: +1. Determine if `networking-certmanager` is already installed by running the + following command: - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-network - namespace: knative-serving - data: - ... - autoTLS: Enabled - ... - httpProtocol: Redirected - ... - ``` + ```shell + kubectl get deployment networking-certmanager -n knative-serving + ``` - 1. Ensure that the file was updated successfully: +1. If `networking-certmanager` is not found, run the following command: - ```shell - kubectl get configmap config-network --namespace knative-serving --output yaml - ``` + ```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: + + ```shell + kubectl edit configmap config-certmanager --namespace knative-serving + ``` + +1. Add the `issuerRef` within the `data` section: + + ```shell + ... + data: + ... + issuerRef: | + kind: ClusterIssuer + name: letsencrypt-issuer + ``` + + Example: + + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-certmanager + namespace: knative-serving + labels: + networking.knative.dev/certificate-provider: cert-manager + data: + issuerRef: | + kind: ClusterIssuer + name: letsencrypt-http01-issuer + ``` + + `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 + ``` + +### 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: + +1. Run the following command to edit your `config-network` ConfigMap: + + ```shell + kubectl edit configmap config-network --namespace knative-serving + ``` + +1. Add the `autoTLS: Enabled` attribute under the `data` section: + + ```shell + ... + data: + ... + autoTLS: Enabled + ... + ``` + + Example: + + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-network + namespace: knative-serving + data: + ... + autoTLS: Enabled + ... + ``` + +1. Configure how HTTP and HTTPS requests are handled in the + [`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110) + attribute. + + By default, Knative ingress is configured to serve HTTP traffic + (`httpProtocol: Enabled`). Now that your cluster is configured to use TLS + certificates and handle HTTPS traffic, you can specify whether or not any + HTTP traffic is allowed. + + Supported `httpProtocol` values: + + - `Enabled`: Serve HTTP traffic. + - `Disabled`: Rejects all HTTP traffic. + - `Redirected`: Responds to HTTP request with a `302` redirect to ask the + clients to use HTTPS. + + ```shell + ... + data: + ... + autoTLS: Enabled + ... + ``` + + Example: + + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-network + namespace: knative-serving + data: + ... + autoTLS: Enabled + ... + httpProtocol: Redirected + ... + ``` + + **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 + kubectl get configmap config-network --namespace knative-serving --output yaml + ``` 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. \ No newline at end of file