Enabling auto-TLS certs

    The following must be installed on your Knative cluster:

    • Knative Serving.

    • A Networking layer such as Kourier, Istio with SDS v1.3 or higher, or Contour v1.1 or higher. See or Istio with SDS, version 1.3 or higher.

    • .

    • Your Knative cluster must be configured to use a custom domain.

    • 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.

    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 Knative Service is supported when using DNS-01 challenge mode.

        • This is the recommended mode for better certificate isolation 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.

    2. Using HTTP-01 challenge

      • In this type, your cluster does not need to be able to talk to your DNS server. You must map your domain to the IP of the cluser ingress.
      • When using HTTP-01 challenge, a certificate will be provisioned per Knative Service.
      • HTTP-01 does not support provisioning a certificate per namespace.

    1. Create and add the configuration file to your Knative cluster to define who issues the TLS certificates, how requests are validated, and which DNS provider validates those requests.

      • ClusterIssuer for DNS-01 challenge: use the cert-manager reference to determine how to configure your ClusterIssuer file.

        For example, the following ClusterIssuer file named letsencrypt-issuer is configured for the Let’s Encrypt CA and Google Cloud DNS. The Let’s Encrypt account info, required DNS-01 challenge type, and Cloud DNS provider info is defined under spec.

      • ClusterIssuer for HTTP-01 challenge

        To apply the ClusterIssuer for HTTP01 challenge:

          1. apiVersion: cert-manager.io/v1
          2. kind: ClusterIssuer
          3. metadata:
          4. spec:
          5.   acme:
          6.     privateKeySecretRef:
          7.       name: letsencrypt
          8.     server: https://acme-v02.api.letsencrypt.org/directory
          9.     solvers:
          10.     - http01:
          11.        ingress:
          12.          class: istio

        2. Apply the YAML file by running the command:

          1. kubectl apply -f <filename>.yaml

          Where <filename> is the name of the file you created in the previous step.

    2. Ensure that the ClusterIssuer is created successfully:

      1. kubectl get clusterissuer <cluster-issuer-name> -o yaml

      Result: The Status.Conditions should include Ready=True.

    If you choose to use DNS-01 challenge, configure which DNS provider is used to validate the DNS-01 challenge requests.

    Instructions about configuring cert-manager, for all the supported DNS providers, are provided in .

    Note that DNS-01 challenges can be used to either validate an individual domain name or to validate an entire namespace using a wildcard certificate like *.my-ns.example.com.

    Install net-certmanager-controller deployment

    1. Determine if net-certmanager-controller is already installed by running the following command:

      1. kubectl get deployment net-certmanager-controller -n knative-serving

    2. If net-certmanager-controller is not found, run the following command:

      1. kubectl apply -f https://github.com/knative/net-certmanager/releases/download/knative-v1.5.0/release.yaml

    Warning

    Provisioning a certificate per namespace only works with DNS-01 challenge. This component cannot be used with HTTP-01 challenge.

    The per-namespace certificate manager uses namespace labels to select which namespaces should have a certificate applied. For more details on namespace selectors, see .

    Prior to release 1.0, the fixed label networking.knative.dev/disableWildcardCert: true was used to disable certificate generation for a namespace. In 1.0 and later, other labels such as kubernetes.io/metadata.name may be used to select or restrict namespaces.

    To enable certificates for all namespaces except those with the networking.knative.dev/disableWildcardCert: true label, use the following command:

    This selects all namespaces where the label value is not in the set "true".

    Configure config-certmanager ConfigMap

    Update your in the namespace to reference your new ClusterIssuer.

    1. Run the following command to edit your config-certmanager ConfigMap:

      1. kubectl edit configmap config-certmanager -n knative-serving

    2. Add the issuerRef within the data section:

      1. apiVersion: v1
      2. kind: ConfigMap
      3. metadata:
      4.   name: config-certmanager
      5.   namespace: knative-serving
      6.   labels:
      7.     networking.knative.dev/certificate-provider: cert-manager
      8. data:
      9.   issuerRef: |
      10.     kind: ClusterIssuer
      11.     name: letsencrypt-http01-issuer

    3. Ensure that the file was updated successfully:

      1. kubectl get configmap config-certmanager -n knative-serving -o yaml

    Update the config-network ConfigMap in the knative-serving namespace to enable auto-tls and specify how HTTP requests are handled:

    1. Run the following command to edit your config-network ConfigMap:

      1. kubectl edit configmap config-network -n knative-serving

    2. Add the auto-tls: Enabled attribute under the data section:

      1. apiVersion: v1
      2. metadata:
      3.   name: config-network
      4.   namespace: knative-serving
      5. data:
      6.    ...
      8.    ...

    3. Configure how HTTP and HTTPS requests are handled in the attribute.

      By default, Knative ingress is configured to serve HTTP traffic (http-protocol: 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 http-protocol 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.

      Example:

      1. apiVersion: v1
      2. kind: ConfigMap
      3. metadata:
      4.   name: config-network
      5.   namespace: knative-serving
      6. data:
      7.   ...
      8.   auto-tls: Enabled
      9.   http-protocol: Redirected
      10.   ...

      Note

      When using HTTP-01 challenge, http-protocol field has to be set to Enabled to make sure HTTP-01 challenge requests can be accepted by the cluster.

    4. Ensure that the file was updated successfully:

      1. kubectl get configmap config-network -n knative-serving -o 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:

      1. kubectl apply -f https://raw.githubusercontent.com/knative/docs/main/docs/serving/autoscaling/autoscale-go/service.yaml

    2. When the certificate is provisioned (which could take up to several minutes depending on the challenge type), you should see something like:

      1. NAME               URL                                           LATESTCREATED            LATESTREADY              READY   REASON
      2. 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.

    If you have Auto TLS enabled in your cluster, you can choose to disable Auto TLS for individual services or routes by adding the annotation networking.knative.dev/disable-auto-tls: true.

    Using the previous autoscale-go example:

    1. Edit the service using kubectl edit service.serving.knative.dev/autoscale-go -n default and add the annotation:

      1.  apiVersion: serving.knative.dev/v1
      2.  kind: Service
      3.  metadata:
      4.    annotations:
      5.     ...
      6.      networking.knative.dev/disable-auto-tls: "true"