Custom domains

This page explains how to use Traefik Hub with custom domains.

Introduction¶

Custom domains allow you to make your Portal or Gateway accessible at your own domain names (for example, api.example.com).

By using custom domains, you connect your API Portal or Gateway directly from Traefik Hub to your infrastructure without using domains under the traefikhub.io namespace.

We highly recommend the use of custom domains for production deployments!

Domains generated by Traefik Hub will change with every redeployment, resulting in a new domain.

Configure a custom domain¶

On your DNS provider’s site, add a CNAME record for the DNS-01 challenge and a A record with your custom domain name (for example, api.example.com).

See the following example:

_acme-challenge.api.example.com.    CNAME  acme-challenge.traefikhub.io.
api.example.com.                    A      192.0.2.10

Where 192.0.2.10 is the external IP address of your public load-balancer.

DNS CNAME record¶

A DNS CNAME (Canonical Name) record is a type of DNS (Domain Name System) record that's used to create an alias or alternative name for a domain or subdomain.

It allows you to associate a domain or subdomain with another domain or subdomain.

_acme-challenge.api.example.com.    CNAME  acme-challenge.traefikhub.io.

In this example, _acme-challenge.api.example.com. is configured as CNAME of acme-challenge.traefiklabs.io. which is needed for the DNS-01 challenge.

DNS A record¶

A DNS A (Address) record is a type of DNS (Domain Name System) record that's used to map a domain or subdomain to an IPv4 (Internet Protocol version 4) address.

It associates a domain name with the corresponding IP address, allowing DNS resolvers to translate human-readable domain names into machine-readable IP addresses.

When a DNS lookup is performed for a domain or subdomain with an A record, the DNS resolver queries the authoritative DNS server for the IP address associated with that domain or subdomain.

The DNS server then responds with the IPv4 address specified in the A record.

Here's an example of how an A record looks:

api.example.com.    IN A   192.0.2.10

In this example, the A record maps the domain api.example.com to the IPv4 address 192.0.2.10 (the external IP of your public load-balancer).

When someone tries to access api.example.com in a web browser, their computer performs a DNS lookup to find the IP address associated with the domain.

If the A record is properly configured, it will receive the IP address 192.0.2.10 as the response.

DNS-01 challenge¶

Behind the scenes, Traefik Hub uses ACME DNS-01 challenge type to get the certificates for your custom domains.

This challenge asks you to prove that you control the DNS for your domain name.

There are two common ways to configure the ACME client to handle updates in an automated way:

Use a TXT record: _acme.api.example.com TXT <$TOKEN> (The client needs to have access to credentials that can update the TXT records for "_acme-challenge" subdomains)
Use a CNAME to delegate the validation to an external domain (No credentials needed, the ACME client will query the DNS system for validation)

Security¶

Traefik Hub doesn't need DNS credentials!

For better security, Traefik Hub uses CNAME records.

Most DNS software and DNS service providers don't offer granular access controls that allow for limiting these privileges, or don't provide an API to handle automating this outside of the basic DNS zone updates or transfers.

This leaves the possible automation methods either unusable or insecure.

CNAME records act as links to another DNS record.

Let's Encrypt follows the chain of CNAME records and will resolve the challenge validation token from the last record in the chain.

If it finds a match, you can proceed to issue a certificate.

What's next¶

Please visit the Let’s Encrypt documentation about ACME DNS-01 to learn more