Skip to content
Cloudflare Docs

Set up tenant custom nameservers

Tenant custom nameservers (TCNS) allow you to define tenant-level custom nameservers and use them for different accounts within a Cloudflare tenant .

TCNS are organized in different sets (ns_set) and TCNS names can be provided by any domain, even if the domain does not exist as a zone in Cloudflare.

For instance, if the TCNS are ns1.example.com and ns2.vanity.test, the domains example.com and vanity.test are not required to be zones in Cloudflare.

Configuration conditions

For this configuration to be possible, a few conditions apply:

  • Tenant owners can create up to five different tenant custom nameserver sets. Each nameserver set must have between two and five different nameserver names (ns_name), and each name cannot belong to more than one set. For example, if ns1.example.com is part of ns_set 1 it cannot be part of ns_set 2 or vice versa.
  • Subdomain setup or reverse zones can use tenant custom nameservers as long as they use a different nameserver set (ns_set) than their parent, child, or any other zone in their direct hierarchy tree.

For account owners

Enable tenant custom nameservers on a zone

If you are an account owner and your account is part of a tenant that has custom nameservers, do the following:

  1. Use a PUT command and specify ns_type and ns_set.
Terminal window
curl --request PUT https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_ns \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "enabled": true,
  "ns_type": "tenant",
  "ns_set": <SET>
}'
  1. If you are not using Cloudflare Registrar, update the nameservers at your registrar to use the TCNS names. If you are using Cloudflare Registrar, no further action is needed.

To make these TCNS the default namerservers for all new zones added to your account from now on, use the endpoint Update DNS Settings for an Account. Within the zone_defaults object, set the following:

"zone_defaults": {
  "nameservers": {
    "type": "custom.tenant"
  }
}

Disable tenant custom nameservers on a zone

To remove TCNS and their associated DNS records from a zone, use a PUT command.

If you are not using Cloudflare Registrar, also remove the TCNS at your domain’s registrar.

For tenant owners

Create tenant custom nameservers

If you are a tenant owner and you want to make TCNS available for accounts within your tenant, do the following:

  1. Observe the conditions for ns_name and ns_set, and create TCNS in your tenant by using the following POST command:
Terminal window
curl https://api.cloudflare.com/client/v4/tenants/{tenant_id}/custom_ns \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "ns_name": "<NS_NAME>",
  "ns_set": <SET>
}'

  1. Add the account custom nameservers and IP addresses to your domain's registrar as glue (A and AAAA) records (RFC 1912 ↗).

  2. If the domain or domains that are used for the tenant custom nameservers do not exist within the same account, you must create the A/AAAA records on the configured nameserver names (for example, ns1.example.com) at the authoritative DNS provider.

TypeNameContent
Ans1.example.com<IPv4>

Get a list of all TCNS names

To get a list of all TCNS names in your tenant account, use the following API request:

Terminal window
curl https://api.cloudflare.com/client/v4/tenants/{tenant_id}/custom_ns \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"
Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings