Porter uses cert-manager and Let’s Encrypt to manage SSL certificates. In this document, we cover some detailed information about the SSL certificates, along with steps for troubleshooting certificates.

SSL Certificate Information

When you create a cluster on Porter, the email address of the cluster creator is registered with the Let’s Encrypt ACME server. This email address is used to identify the owner of a certificate, and is used to send you email updates on certificate expiry. Note that is is not expected that you receive certificate expiry emails, since the certificates should be automatically renewed starting 30 days before they expire, as recommended by Let’s Encrypt best practices.

If you receive an expiry email, you will usually have several weeks before the certificate expires. See the troubleshooting section for some tips on how to resolve these issues.

Certificates issued by Let’s Encrypt’s ACME servers are usually trusted by client’s computers by default. Thus, if there is a certificate trust issue, it is usually because a default certificate is returned before the certificate has been received from Let’s Encrypt. You will initially see the certificate listed as Kubernetes Ingress Controller Fake Certificate — this is expected behavior, and should resolve within a few minutes. If you are waiting more than 30 minutes for a certificate to be issued, see the troubleshooting section below.

Troubleshooting

Check DNS propagation

The most common cause of certificate issues is that DNS did not propagate before the application was deployed. This results in Let’s Encrypt being unable to verify that you own the application that the certificate is being issued for, and thus the certificate renewal fails. There are two steps that you can take if you suspect that DNS did not propagate before the application was deployed:

  • Delete the application and re-deploy it with the same configuration.
  • If deleting the application is not an option, attempt to manually renew the certificate by following these steps

Check Let’s Encrypt Status

While this does not occur frequently, it is possible that Let’s Encrypt is experiencing an outage and cannot issue your certificate. See letsencrypt.status.io and make sure that Let’s Encrypt is not experiencing an outage.

Check Cluster Resources

In order to issue a certificate, a small application pod runs on your cluster that responds to the HTTP-01 challenge from Let’s Encrypt. If there are not enough cluster resources, this pod might not be created. Make sure that your nodes have enough resources and space available to run your application.

View and Renew Certificates

Porter offers a view for seeing all certificates requests in the cluster and manually renewing them. The manual renewal involves deleting the existing certificate request, but does not delete the actual certificate from the cluster. However, this could disrupt certificate requests and renewal, so make sure you only do this if the steps above have failed. To view the certificates and request status, navigate to the cert-manager namespace, where you should see a cert-manager application:

Cert Manager

Click on the cert-manager application, and navigate to the Certificates tab. In this tab, you will see the certificates on the cluster. From this section, you can choose to manually renew a certificate:

Cert Manager Renewal

Reach out for Support

If none of these steps worked, reach out on Discord or email and we’ll help you get this resolved!