Skip to main content

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 random subdomains under the traefikhub.io namespace.

warning

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.

You can control the generation of traefikhub.io domains in the workspace settings.

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).

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 the above example, _acme-challenge.api.example.com. is configured as CNAME of acme-challenge.traefikhub.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.

Once, you're done, your configuration should look like 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-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.

For better security, Traefik Hub uses CNAME records to delegate the validation to an external domain (no credentials needed, the ACME client will query the DNS system for validation).

Related Content​

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