Configure external domain encryption

Knative allows to use either use custom TLS certificates or to use automatically generated TLS certificates to enable secure HTTPS connections for your Knative Services for the external domain (like application.example.com).

Before you begin

You must meet the following requirements to enable secure HTTPS connections:

  • Knative Serving must be installed. For details about installing the Serving component, see the Knative installation guides.
  • You must configure your Knative cluster to use a custom external domain.
  • Your DNS provider must be setup and configured to your domain.
  • A Networking layer such as Kourier, Istio with SDS v1.3 or higher, or Contour v1.1 or higher. See Install a networking layer.

Automatically obtain and renew certificates

Installing and configuring cert-manager and integration

Info

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.

First, you need to install and configure cert-manager and the Knative cert-manager integration. Please refer to Configuring Knative cert-manager integration for details.

Configuring Knative Serving

Automatic certificate provisioning allows to request certificates in two ways:

  • One certificate for each individual Knative Service
  • One wildcard certificate per namespace

Only one of them can be active at the same time!

Using a certificate for each Knative Service

Update the config-network ConfigMap in the knative-serving namespace to enable external-domain-tls:

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

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

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

    1. apiVersion: v1
    2. kind: ConfigMap
    3. metadata:
    4.   name: config-network
    5.   namespace: knative-serving
    6. data:
    7.    ...
    8.    external-domain-tls: Enabled
    9.    ...

  3. Restart the Knative Serving controller to start the Knative cert-manager integration:

    1. kubectl rollout restart deploy/controller -n knative-serving

Using one wildcard certificate per namespace

Warning

Provisioning a wildcard Certificate per namespace only works with DNS-01 challenge. This feature cannot be used with HTTP-01 challenge.

The per-namespace configuration uses namespace labels to select which namespaces should have a certificate applied. The selection is configured using the key namespace-wildcard-cert-selector in the config-network ConfigMap. For example, you can use the following configurations:

  • namespace-wildcard-cert-selector: "" = Use an empty value to disable the feature (this is the default).
  • namespace-wildcard-cert-selector: {} = Use an empty object to enable for all namespaces.

You can also configure the selector to opt-out when a specific label is on the namespace:

  1. namespace-wildcard-cert-selector: |-
  2.   matchExpressions:
  3.   - key: "networking.knative.dev/disableWildcardCert"
  4.     operator: "NotIn"
  5.     values: ["true"]

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

Or use existing kubernetes labels to select namespaces based on their name:

  1. namespace-wildcard-cert-selector: |-
  2.   matchExpressions:
  3.     - key: "kubernetes.io/metadata.name"
  4.       operator: "In"
  5.       values: ["my-namespace", "my-other-namespace"]

To apply the configuration you can use the following command (optionally adapting the label-selector):

  1. kubectl patch --namespace knative-serving configmap config-network -p '{"data": {"namespace-wildcard-cert-selector": "{\"matchExpressions\": [{\"key\":\"networking.knative.dev/disableWildcardCert\", \"operator\": \"NotIn\", \"values\":[\"true\"]}]}"}}'

For more details on namespace selectors, see the Kubernetes documentation.

Restart the Knative Serving controller to start the Knative cert-manager integration:

  1. kubectl rollout restart deploy/controller -n knative-serving

Congratulations! Knative is now configured to obtain and renew TLS certificates. When your TLS Certificate is issued and available on your cluster, your Knative services will be able to handle HTTPS traffic on the external domain.

Manually obtain and renew certificates

There are various ways on how to obtain certificates manually. You can either use tools like Certbot or cert-manager or provide the certificates manually from another source. In general, after you obtain a certificate, you must create a Kubernetes secret to use that certificate in your cluster. See the procedures later in this topic for details about manually obtaining and configuring certificates.

Obtaining a certificate using a tool

Please refer to the according documentation of the tool:

Knative expects a wildcard certificate signed for the DNS domain of your cluster external domain, like

*.yourdomain.com

Once you have obtained the certificate and the private key, create a Kubernetes Secret for the certificate and key to be used by Knative.

Warning

Certificates issued by Let’s Encrypt are valid for only 90days. Therefore, if you choose to manually obtain and configure your certificates, you must ensure that you renew each certificate before it expires.

Create a Kubernetes Secret

Use the following steps in the relevant tab to add your certificate to your Knative cluster:

ContourIstio

To add a TLS certificate to your Knative cluster, you must create a Kubernetes secret and then configure the Knative Contour plugin.

  1. Create a Kubernetes secret to hold your TLS certificate, cert.pem, and the private key, key.pem, by running the command:

    1. kubectl create -n contour-external secret tls default-cert \
    2.   --key key.pem \
    3.   --cert cert.pem

    Note

    Take note of the namespace and secret name. You will need these in future steps.

  2. To use this certificate and private key in different namespaces, you must create a delegation. To do so, create a YAML file using the following template:

    1. apiVersion: projectcontour.io/v1
    2. kind: TLSCertificateDelegation
    3. metadata:
    4.   name: default-delegation
    5.   namespace: contour-external
    6. spec:
    7.   delegations:
    8.     - secretName: default-cert
    9.       targetNamespaces:
    10.       - "*"

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

  4. Update the Knative Contour plugin to use the certificate as a fallback when external-domain-tls is disabled by running the command:

    1. kubectl patch configmap config-contour -n knative-serving \
    2.   -p '{"data":{"default-tls-secret":"contour-external/default-cert"}}'

To add a TLS certificate to your Knative cluster, you create a Kubernetes secret and then configure the knative-ingress-gateway:

  1. Create a Kubernetes secret to hold your TLS certificate, cert.pem, and the private key, key.pem, by entering the following command:
  1. kubectl create --namespace istio-system secret tls tls-cert \
  2.   --key key.pem \
  3.   --cert cert.pem

  1. Configure Knative to use the new secret that you created for HTTPS connections:

  2. Run the following command to open the Knative shared gateway in edit mode:

    1. kubectl edit gateway knative-ingress-gateway --namespace knative-serving

  3. Update the gateway to include the following tls: section and configuration:

    1. tls:
    2.   mode: SIMPLE
    3.   credentialName: tls-cert

    Example:

    1. # Edit the following object. Lines beginning with a '#' will be ignored.
    2. # An empty file will abort the edit. If an error occurs while saving this
    3. # file will be reopened with the relevant failures.
    4. apiVersion: networking.istio.io/v1alpha3
    5. kind: Gateway
    6. metadata:
    7.   # ... skipped ...
    8. spec:
    9.   selector:
    10.     istio: ingressgateway
    11.   servers:
    12.     - hosts:
    13.         - "*"
    14.       port:
    15.         name: http
    16.         number: 80
    17.         protocol: HTTP
    18.     - hosts:
    19.         - TLS_HOSTS
    20.       port:
    21.         name: https
    22.         number: 443
    23.         protocol: HTTPS
    24.       tls:
    25.         mode: SIMPLE
    26.         credentialName: tls-cert

    In this example, TLS_HOSTS represents the hosts of your TLS certificate. It can be a single host, multiple hosts, or a wildcard host. For detailed instructions, please refer Istio documentation

Verification

  1. Deploy a Knative Service

  2. Check the URL with kubectl get ksvc -n <your-namespace>

  3. The service URL should now be https:

    1. NAME           URL                                          LATEST               AGE     CONDITIONS   READY   REASON
    2. autoscale-go   https://autoscale-go.default.1.example.com   autoscale-go-dd42t   8m17s   3 OK / 3     True

Trust

Note

A quick note on trust, all clients that call the external domain of a Knative Service need to trust the Certificate Authority that signed the certificates. This is out of scope of Knative, but needs to be addressed to ensure a working system. Especially, when a Certificate Authority performs a rotation of the CA or the intermediate certificates. Find more information on Configuring Knative cert-manager integration.

Additional configuration

Configuring HTTP redirects

Knative Serving allows to automatically redirect HTTP traffic, when HTTPS is enabled on external domains. To configure this

  1. Configure how HTTP and HTTPS requests are handled with the http-protocol 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 on external domains, you can specify whether any HTTP traffic is allowed or not.

    Supported http-protocol values:

    • Enabled: Serve HTTP traffic.
    • Redirected: Responds to HTTP request with a 302 redirect to ask the clients to use HTTPS.
    1. data:
    2.   http-protocol: Redirected

    Example:

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

Disable automatic TLS certificate provisioning per Service or Route

If you have automatic TLS certificate provisioning enabled in your cluster, you can choose to disable the feature for individual Knative Services or Routes by adding the annotation networking.knative.dev/disable-external-domain-tls: true.

Using the 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-external-domain-tls: "true"
    7.     ...

  2. The service URL should now be http, indicating that automatic TLS Certificate provisioning is disabled:

    1. NAME           URL                                          LATEST               AGE     CONDITIONS   READY   REASON
    2. autoscale-go   http://autoscale-go.default.1.example.com    autoscale-go-dd42t   8m17s   3 OK / 3     True