Using Custom Top-Level Domains for Mesos-DNS

Updated: November 7, 2016

DC/OS uses Mesos-DNS for internal service discovery. While the .mesos domain can be used to reach services in DC/OS, an additional instance of Mesos-DNS must be running to support the use of custom suffixes. This tutorial outlines the steps for configuring and starting Mesos-DNS on DC/OS and configuring your authoritative DNS appropriately. This tutorial is also useful when configuring DNS for DC/OS clusters in multiple datacenters and environments.


  • A functioning DC/OS cluster.
  • A configurable authoritative DNS server.

DC/OS Configuration

  1. Create a configuration directory for the new Mesos-DNS instance:
    mkdir /opt/mesos-dns-ext && cd /opt/mesos-dns-ext
  2. Create and edit /opt/mesos-dns-ext/config.json:
      "domain": "<domain>",
      "externalon": false,
      "listener": "<listen_ip>",
      "masters": ["<dcos_master1>/mesos","<dcos_master2>/mesos","<dcos_master3>/mesos"],
      "port": 53,
      "recurseon": false,
      "refreshSeconds": 60,
      "resolvers": ["<resolver1>","<resolver2>","<resolver3>"],
      "SOAExpire": 86400,
      "SOAMinttl": 60,
      "SOAMname": "ns1.<domain>",
      "SOARefresh": 60,
      "SOARetry": 600,
      "SOARname": "root.ns1.<domain>",
      "ttl": 60,
      "zk": "zk://zk-1.zk,zk-2.zk,zk-3.zk:2181/mesos"
    Parameter Description
    domain Your custom DNS suffix
    listen_ip IP to listen on (default
    dcos_master{1..3} IP addresses of DC/OS masters
    resolver{1..3} Additional resolvers (at least one required)
    dcos_zookeeper{1..3} IP Addresses of ZooKeeper servers
  3. Download the latest Mesos-DNS binary and copy it to /opt/mesos-dns-ext/mesos-dns: https://github.com/mesosphere/mesos-dns/releases.

  4. Create an application definition for Mesos-DNS, /opt/mesos-dns-ext/mesos-dns-ext.json:

      "id": "/mesos-dns-ext",
      "cmd": "/opt/mesos-dns-ext/mesos-dns --config=/opt/mesos-dns-ext/config.json",
      "instances": 1,
      "cpus": 1,
      "mem": 1024,
      "disk": 0,
      "executor": "",
      "constraints": [
      "uris": [],
      "storeUrls": [],
      "ports": [
    Parameter Definition
    mesos_agent A specific agent to pin Mesos-DNS to. Since Mesos-DNS will be acting as a delegate, its IP must remain static. For multiple Mesos-DNS instances (and redundancy), the LIKE constraint operator can be used to define hosts using regex. See https://mesosphere.github.io/marathon/docs/constraints.html for more information. As a best-practice, we also recommend using healthchecks to ensure that Mesos-DNS remains running.
  5. Create a new application for Mesos-DNS in Marathon:
    $ curl -X POST -H 'Content-Type: application/json' -d @mesos-dns-ext.json http://<marathon>:8080/v2/apps
    Parameter Definition
    marathon IP/hostname of Marathon leader

DNS Configuration

Important: DNS configuration varies from environment-to-environment. These instructions are a guide of how your DNS should be modified.

  1. Add the following A and NS records to your DNS (glue record):
    ns.<domain> IN A <mesos_dns_ext>
    <domain> IN NS ns1.<domain>
    Parameter Definition
    domain Your custom DNS suffix
    mesos_dns_ext IP Address of the Mesos Agent that Mesos-DNS is running on (see DC/OS Configuration, Step 4, ).


Here is a datacenter with DC/OS clusters in development and production environments: