Using managed TLS certificates and HTTPS

This page shows how to turn off and re-enable the managed TLS certificates feature that automatically provides and renews TLS certificates to support HTTPS connections on Knative serving.

If you want to use HTTPS,

  • Your container should continue listening on $PORT
  • You must choose how you are supplying TLS certificates:

    • Use managed TLS certificates, where TLS certificates are automatically created as needed, and are automatically renewed. This page describes this feature, which is available in the supported Google Kubernetes Engine versions.
    • Use your own certificates, where you are responsible for obtaining and renewing certificates. In some situations, described under Limitations, you must use your own certificates.
  • If you are using managed certificates, you must also map your custom domain in order to use the managed certificates feature.

Using HTTPS and HTTP

By default, if you use managed certificates, clusters or Knative serving services with managed certificates are exposed to both HTTP and HTTPS traffic. If you want only HTTPS traffic, you can enable HTTPS redirects to force all traffic to use HTTPS only.

Troubleshooting

If you experience issues when using managed TLS certificates, refer to the managed TLS troubleshooting page.

Limitations

The following considerations apply to the use of the managed TLS certificates feature:

  • Managed TLS certificates are disabled and not supported for Knative serving private clusters on Google Cloud.
  • To use the managed certificates feature, your service must be exposed externally: it cannot be a cluster-local service or a service exposed by Virtual Private Cloud.
  • The managed certificates feature works only with Cloud Service Mesh. The Istio addon or other Istio configurations are not supported.
  • This feature uses Let's Encrypt, which has an initial quota limit of 50 TLS certificates per week per registered domain. You can ask for a quota increase by following the Let's Encrypt documentation.
  • When running a Knative serving cluster on other platforms, such as on-prem or AWS, this feature is disabled. To use this feature, you must make sure your cluster is able to access Let's Encrypt, and your Cloud Service Mesh ingress service is exposed to the public internet.

Before you begin

The instructions on this page assume the following:

  • You have deployed your Knative serving service to the cluster.
  • You own a domain. If you don't have a domain, you can obtain one from Google or from another domain vendor.
  • You created a domain mapping for your service and updated your DNS record accordingly following the instructions at the domains mapping page.
  • Use Cloud DNS, or a DNS server of your choice.

Disabling managed TLS certificates and HTTPS for a whole cluster

Disable managed TLS for a cluster by updating the ConfigMap config-domainmapping:

kubectl patch cm config-domainmapping -n knative-serving -p '{"data":{"autoTLS":"Disabled"}}'

Disabling managed TLS and HTTPS for a specific domain mapping

If needed, you can turn off managed TLS for a specific domain mapping:

  1. Add the annotation domains.cloudrun.com/disableAutoTLS: "true"`:

    kubectl annotate domainmappings DOMAIN domains.cloudrun.com/disableAutoTLS=true
  2. Verify that HTTPS does not work:

    curl https://DOMAIN

  3. Verify that HTTP is being used for the service:

    gcloud run domain-mappings describe --domain DOMAIN

    Replace DOMAIN with your own domain name, for example: your-domain.com

    Check the url: field in the return from the above command: the URL should have http, not https.

Re-enabling managed TLS certificates and HTTPS

To re-enable managed TLS:

  1. If you haven't already done so, create a domain mapping for your service and update your DNS record accordingly following the instructions at the domains mapping page.

  2. Turn on managed TLS certificates and HTTPS by updating the ConfigMap config-domainmapping:

    kubectl patch cm config-domainmapping -n knative-serving -p '{"data":{"autoTLS":"Enabled"}}'
  3. Wait for a few minutes after the command succeeds, then make sure the certificates feature is working:

    kubectl get kcert

    If the certificate is ready, you should see a message similar to this one:

    NAME              READY   REASON
    your-domain.com              True

    It may take from 20 seconds to 2 minutes for the Kcert to become ready. If you experience any issues, see the troubleshooting instructions for this feature.

Verifying success

  1. Verify that the DNS record has gone into effect by running the command:

    gcloud run domain-mappings describe --domain DOMAIN

    Replace DOMAIN with your own domain name, for example: your-domain.com

  2. Check the url: field in the return from the above command: the URL should have https, not http.

  3. Check the IP address from the above command, listed under resourceRecords:rrdata, and compare it to the value you see when you execute the command host DOMAIN. They should be the same.

Enabling HTTPS redirects for Knative serving

If you use the managed TLS certificates feature, by default the cluster is exposed to both HTTP and HTTPS traffic for backwards compatibility reasons. If you want to force all traffic to use HTTPS only, you can enable HTTPS redirects for an existing domain mapping by invoking the command

kubectl annotate domainmappings DOMAIN domains.cloudrun.com/httpsRedirect=Enabled

where DOMAIN is the name of the domain mapping.