SSL/TLS certificate issues

How an SSL/TLS certificate is issued

Certificates are automatically created and renewed using Let's Encrypt via MedStack Control's managed load balancer service. In order for a certificate to be created and renewed for a service, all the domains configured for a service must have valid DNS records that map the cluster's manager node IP address to the sub/domain at which the service is hosted.

 

To check that a sub/domain DNS is mapped to the cluster manager node IP address, you can use a DNS look up tool: https://mxtoolbox.com/DNSLookup.aspx

 

For more information, please read our article on DNS settings and routing traffic to services works on MedStack Control.

 

The certificate trigger

When a Docker service is created with a domain mapping or has its domain mapping updated, Let's Encrypt immediately attempts to issue a certificate for the configured domains.

 

Success

When a certificate is successfully issued, it is valid for 90 days.

Every 60 days, MedStack Control will attempt to renew the valid certificate for another 90 days.

 

How to resolve expired or unissued SSL/TLS certificates

When a certificate fails to issue, is it usually due to one of the following reasons.

 

1 – DNS settings have not yet propagated

Problem: DNS A record(s) for the sub/domains required by services have not yet propagated in the DNS settings. This can be confirmed using a DNS look up tool.

Solution: Allow time for the DNS settings to propagate. However, if you've already created or updated the service with a domain, it's likely that Let's Encrypt has timed out.

2 – Services were deployed with domain mappings before DNS A records created

Problem: Let's Encrypt will attempt to issue a certificate for a service's configured domains immediately once it's created or updated. If the DNS settings have (1) not been configured or (2) not yet propagated for these domains, Let's Encrypt will timeout for 1 hour after 10 attempts issuing the certificate. This can happen within minutes.

Solution: By restarting the managed load balancer service using its webhook, Let's Encrypt will also restart and thus the timeout is removed. Provided that the DNS settings have propagated for the domains configured to be used by the services, the certificate should successfully issue once the load balancer has restarted.

Method 1 – To create and use a webhook to restart the service:

1. For the relevant cluster, go to Manage Docker | Services | loadbalancer and scroll down to the section called "Image Update Webhooks."
2. Create a webhook if one doesn't already exist.
3. In a terminal, post a cURL command to hit the webhook. For more information, see our section on a service's webhook.

Method 2 – Alternatively, you can reinstall the load balancer and reissue certificates:

1. Delete the load balancer service. Please note that all traffic to cluster services will be temporarily stopped.
2. Delete the acme volume. The load balancer stores certificates in the volume labeled acme.
3. Create the load balancer service. Once the load balancer has started, the acme volume will be created and certificates will attempt to be issued for services with domain configurations.

3 – The service domain and DNS settings are not in sync

Problem: There is a mismatch between the service's domain configuration and the DNS settings. In other words, the service is configured to host the service at domains that no longer have valid A records in the DNS settings.

Solution: This can be resolved by reconciling the difference between the service and the DNS settings. You may also need to do a reinstallation of the load balancer in case the certificate fails to issue for the service.

1. Delete the load balancer service. Please note that all traffic to cluster services will be temporarily stopped.
2. Delete the acme volume. The load balancer stores certificates in the volume labeled acme.
3. Create the load balancer service. Once the load balancer has started, the acme volume will be created and certificates will attempt to be issued for services with domain configurations.