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.

Warning

Istio only supports a single certificate per Kubernetes cluster. To serve multiple domains using your Knative cluster, you must ensure that your new or existing certificate is signed for each of the domains that you want to serve.

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:

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

kubectl edit configmap config-network -n knative-serving

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-network
  namespace: knative-serving
data:
   ...
   external-domain-tls: Enabled
   ...

Restart the Knative Serving controller to start the Knative cert-manager integration:
```
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:

namespace-wildcard-cert-selector: |-
  matchExpressions:
  - key: "networking.knative.dev/disableWildcardCert"
    operator: "NotIn"
    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:

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

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

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:

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.

Create a Kubernetes secret to hold your TLS certificate, cert.pem, and the private key, key.pem, by running the command:
```
kubectl create -n contour-external secret tls default-cert \
  --key key.pem \
  --cert cert.pem
```
Note

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

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:

apiVersion: projectcontour.io/v1
kind: TLSCertificateDelegation
metadata:
  name: default-delegation
  namespace: contour-external
spec:
  delegations:
    - secretName: default-cert
      targetNamespaces:
      - "*"

Apply the YAML file by running the command:
```
kubectl apply -f <filename>.yaml
```
Where <filename> is the name of the file you created in the previous step.

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

kubectl patch configmap config-contour -n knative-serving \
  -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:

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

kubectl create --namespace istio-system secret tls tls-cert \
  --key key.pem \
  --cert cert.pem

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:

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

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

tls:
  mode: SIMPLE
  credentialName: tls-cert

Example:

# Edit the following object. Lines beginning with a '#' will be ignored.
# An empty file will abort the edit. If an error occurs while saving this
# file will be reopened with the relevant failures.
apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
  # ... skipped ...
spec:
  selector:
    istio: ingressgateway
  servers:
    - hosts:
        - "*"
      port:
        name: http
        number: 80
        protocol: HTTP
    - hosts:
        - TLS_HOSTS
      port:
        name: https
        number: 443
        protocol: HTTPS
      tls:
        mode: SIMPLE
        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¶

Deploy a Knative Service
Check the URL with kubectl get ksvc -n <your-namespace>

The service URL should now be https:

NAME           URL                                          LATEST               AGE     CONDITIONS   READY   REASON
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

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.
```
data:
  http-protocol: Redirected
```
Example:
```
apiVersion: v1
kind: ConfigMap
metadata:
  name: config-network
  namespace: knative-serving
data:
  ...
  external-domain-tls: Enabled
  http-protocol: Redirected
  ...
```

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:

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

 apiVersion: serving.knative.dev/v1
 kind: Service
 metadata:
   annotations:
    ...
     networking.knative.dev/disable-external-domain-tls: "true"
    ...

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

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