Use a custom domain and certificate

Add your own domain, such as api.example.com, to a Load Balancer so that your users reach your app on a name you own. The Load Balancer keeps answering on its E2E address with HTTPS as well, so the two work side by side.

Before you begin

• A Load Balancer that has finished starting. A custom domain is added after the Load Balancer exists, because the domain has to point at the Load Balancer’s address. To make one, see Create a Load Balancer.
• Access to the DNS settings of your domain at your DNS provider.
• Permission to update Load Balancers in the project. See TIR Access Control.
• If you want to use your own certificate, a certificate chain and a private key in PEM text, in the form described in Upload your own certificate.

Add the domain

1. Open the Load Balancer and select the Domains tab.
2. Select Add custom domain.
3. In Your domain, enter the domain, for example api.example.com. It must be a host name with at least one dot, and it must be a name outside e2enetworks.net. TIR saves it in lowercase. A domain can be attached to only one Load Balancer at a time, in any project.
4. In Certificate, choose how the domain gets its certificate:
   • Get a free certificate, the default. E2E issues it and renews it for you. Take this one unless you already own a certificate for the domain.
   • Upload my own certificate uses a certificate that you own. You renew it yourself.
5. Save the form. To finish, point your DNS at the Load Balancer, as the next section describes.

If the domain is under e2enetworks.net, or TIR reports “That does not look like a domain name.”, change the domain and try again.

Point your DNS at the Load Balancer

Add a CNAME record at your DNS provider. Use a CNAME record rather than an IP address. The Domains tab gives the record to add:

• Name is your custom domain.
• Value is the Load Balancer’s E2E hostname, the one ending in .e2enetworks.net.

Add the record whichever certificate you chose. DNS changes can take a while to spread.

Wait for the certificate

What happens next depends on the certificate you chose.

With a free certificate, E2E issues the certificate once your DNS points at the Load Balancer.

Keep HTTP on while a free certificate is in use, because E2E issues the certificate over port 80. While the certificate is in use, HTTP cannot be turned off. If the Load Balancer served HTTPS only when you added the domain, TIR turns HTTP on.

An uploaded certificate is yours to renew; see Upload your own certificate.

Upload your own certificate

If you choose Upload my own certificate, pick one of the project’s unexpired certificates under Certificate. Certificates belong to the project, so every Load Balancer in it can use them. To add one, select Upload next to the list. In Upload certificate, fill in:

• Name: a name that is unique among the project’s certificates.
• Certificate chain: your certificate first, then any intermediate certificates, leaving out the root certificate. List each issuer after the certificate it issued.
• Private key: the key in decrypted form, with its passphrase removed. TIR stores it encrypted and keeps it hidden after the upload.

Both must be PEM text. The upload is refused when:

• the private key belongs to a different certificate;
• the certificate has expired;
• the key is too small, under 2048 bits for RSA or under 256 bits for an elliptic-curve key;
• the key has a passphrase, so upload a decrypted key;
• the chain is out of order, or the intermediate certificates are missing for a certificate that another issuer signed.

The certificate has to cover your domain: a name matches exactly, or a wildcard such as *.example.com matches one level deeper, for example api.example.com. A wildcard certificate covers that one level only, so a.b.example.com and example.com fall outside it. If the chosen certificate seems to miss the domain, TIR warns you, because browsers can show an error.

Check the domain

On the Domains tab, your domain has its certificate’s name and expiry date. A free certificate is renewed for you. To renew an uploaded one, upload a new certificate before it expires. Open https://<your-domain> in a browser to see the Load Balancer answer on your own domain.

Remove the domain

To stop serving the domain, remove it from the Domains tab and confirm in Remove custom domain. The Load Balancer keeps answering on its E2E address. A free certificate is deleted with the domain, and an uploaded certificate stays in the project.

To rename the Load Balancer or find where its other settings are changed, see Edit a Load Balancer.