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 only works with Istio as automatically installed when you set up your cluster for Knative serving: it does not work with the Istio addon or with other Istio configurations. If you need to use the Istio addon, you may need to use your own TLS certificates.
• 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 Istio ingress service (istio-ingress service under gke-system) is exposed to the public internet.
• If you use managed certificates, when you map domains you cannot use a domain mapping name that is exactly the same as the URL of the service you are mapping to. For example, if the URL of your service is test.default.example.com, you cannot set the DomainMapping name as test.default.example.com.

Before you begin

The instructions on this page assume the following:

• Your Knative serving cluster uses one of the cluster versions supporting managed TLS.
• 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 Cloud Domains 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.
• If you obtained your domain from Cloud Domains, use Cloud DNS, or a DNS server of your choice. Using a domain from Cloud Domains is the easiest option.

Note: By default, gke-system-gateway supports HTTP requests that have the Host header. However, if you have customized this gateway, make sure it still accepts the HTTP requests that contain the Host header.

Supported cluster versions

For versions 1.17.7-gke.15 and newer versions, managed certificates are enabled by default, for public clusters on Google Cloud.

For the following cluster versions, the managed certificates feature is disabled by default, but you can enable managed certificates if you want to use them:

• 1.16.0
• 1.15.7-gke.23
• 1.14.10-gke.17
• 1.14.9-gke.23
• 1.14.8-gke.33

To determine what your current cluster version is:

1. Visit the Google Kubernetes Engine page in the Google Cloud console:

   Go to Google Kubernetes Engine

2. Click on the cluster to open its detail page.

3. Locate the cluster version next to the label Master version.

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: example.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
   example.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: example.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

Important: HTTPS redirect is available for cluster version 1.17.7-gke.8 and later.

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.

Related topics

• Troubleshooting managed TLS for details on checking domain mappings, certificate quotas, order status and order timeouts, and authorization failures.
• Bring your own TLS certificates for instructions on using your own TLS certificates instead of the managed TLS certificates.