Using custom certificates in the networking layers

Knative allows to use custom TLS certificates to enable secure HTTPS connections for your Knative Services for the external domain (like application.example.com). Please note that we are working on bringing automatic HTTPS connections for cluster-local domains (like application.namespace.svc.cluster.local) as well (for more details see the issue).

For external domains, you can configure Knative to handle certificates that you manually specify, or you can enable Knative to automatically obtain and renew certificates.

You can use either Certbot or cert-manager to obtain certificates. Both tools support TLS certificates but if you want to enable Knative for automatic TLS certificate provisioning, you must install and configure the cert-manager tool:

  • Manually obtain and renew certificates: Both the Certbot and cert-manager tools can be used to manually obtain TLS certificates. 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.

  • Enable Knative to automatically obtain and renew TLS certificates: You can also use cert-manager to configure Knative to automatically obtain new TLS certificates and renew existing ones. If you want to enable Knative to automatically provision TLS certificates, instead see the Enabling automatic TLS certificate provisioning topic.

By default, the Let’s Encrypt Certificate Authority (CA) is used to demonstrate how to enable HTTPS connections, but you can configure Knative to use any certificate from a CA that supports the ACME protocol. However, you must use and configure your certificate issuer to use the DNS-01 challenge type.

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.

Before you begin

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

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.

Obtaining a TLS certificate

If you already have a signed certificate for your domain, see manually adding a TLS certificate for details about configuring your Knative cluster.

If you need a new TLS certificate, you can choose to use one of the following tools to obtain a certificate from Let’s Encrypt:

  • Setup Certbot to manually obtain Let’s Encrypt certificates
  • Setup cert-manager to either manually obtain a certificate, or to automatically provision certificates

This page covers details for both options.

For details about using other CA’s, see the tool’s reference documentation:

Using Certbot to manually obtain Let’s Encrypt certificates

Use the following steps to install Certbot and the use the tool to manually obtain a TLS certificate from Let’s Encrypt.

  1. Install Certbot by following the certbot-auto wrapper script instructions.

  2. Run the following command to use Certbot to request a certificate using DNS challenge during authorization:

    1. ./certbot-auto certonly --manual --preferred-challenges dns -d '*.default.yourdomain.com'

where -d specifies your domain. If you want to validate multiple domain’s, you can include multiple flags: -d MY.EXAMPLEDOMAIN.1 -d MY.EXAMPLEDOMAIN.2. For more information, see the Cerbot command-line reference.

The Certbot tool walks you through the steps of validating that you own each domain that you specify by creating TXT records in those domains.

Result: CertBot creates two files:

  • Certificate:fullchain.pem
  • Private key: privkey.pem

What’s next:

Add the certificate and private key to your Knative cluster by creating a Kubernetes secret.

Using cert-manager to obtain Let’s Encrypt certificates

You can install and use cert-manager to either manually obtain a certificate or to configure your Knative cluster for automatic certificate provisioning:

Manual certificates:

  1. Install and configure cert-manager.

  2. Continue to the steps about manually adding a TLS certificate by creating and using a Kubernetes secret.

Automatic certificates:

See enabling automatic TLS certificate provisioning.

Manually adding a TLS certificate

If you have an existing certificate or have used one of the Certbot or cert-manager tool to manually obtain a new certificate, you can use the following steps in the relevant tab to add that certificate to your Knative cluster.

ContourIstio

To manually 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 manually 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

What’s next:

After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services on external domains.