Provisioning a DNS Zone

1. Start Locally

Firstly, we need to launch Locally which we can do from a terminal by running:

Once Locally has started, the Locally Dashboard will open automatically:

2. Create a Resource Group

Next we can create the Resource Group to hold the zone:

There's two things to note here:

1. The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with locally run.
2. Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with locally run when you do.

3. Create the DNS Zone

Now we can create the zone. We'll use example.com, which is reserved for documentation. You don't need to own a domain to create a zone for it, in Locally or in Azure:

{
  "location": "global",
  "name": "example.com",
  "type": "Microsoft.Network/dnsZones"
}

DNS Zones are always in the global location, whichever location the Resource Group is in. Let's look at the zone's name servers:

{
  "name": "example.com",
  "nameServers": [
    "ns1-01.dns.locally",
    "ns2-01.dns.locally",
    "ns3-01.dns.locally",
    "ns4-01.dns.locally"
  ],
  "numberOfRecordSets": 2
}

In Azure, these are the name servers you'd delegate the domain to at your registrar. In Locally they're Locally's own. The two record sets are the SOA and NS records every new zone starts with.

4. Add some records

An empty zone doesn't resolve anything, so let's add some records. First an A record, pointing www at an address:

{
  "fqdn": "www.example.com.",
  "records": [
    "10.20.30.40"
  ]
}

Then a CNAME, so that shop is an alias for www:

{
  "cname": "www.example.com",
  "fqdn": "shop.example.com."
}

A record set holds one or more records of the same type, which is why A records are added with add-record. A CNAME can only ever have one value, so it's set-record instead.

Next, an MX record for mail sent to the domain. The @ name means the apex of the zone, so this is for example.com itself:

{
  "fqdn": "example.com.",
  "records": [
    {
      "exchange": "mail.example.com",
      "preference": 10
    }
  ]
}

And finally a TXT record at the apex, here an SPF policy:

{
  "fqdn": "example.com.",
  "records": [
    [
      "v=spf1 mx -all"
    ]
  ]
}

We can see the zone and its records in the Locally Dashboard too:

5. Look up the records

Locally's DNS server answers for the records in your zones. Your machine only sends .locally lookups to it, though, so a plain dig www.example.com would still go to the real example.com. Instead we ask Locally's DNS server directly, on port 5673:

10.20.30.40

The CNAME comes back as the name it points to:

www.example.com.

The MX and TXT records live at the apex, so we ask for example.com along with the record type:

10 mail.example.com.

"v=spf1 mx -all"

A name that isn't in the zone gets NXDOMAIN, as it would from Azure DNS:

; <<>> DiG 9.10.6 <<>> @127.0.0.1 -p 5673 ftp.example.com +noall +comments
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 46726
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 0

6. Change a record

Changes take effect as soon as they're saved. Let's add a second address to www:

{
  "fqdn": "www.example.com.",
  "records": [
    "10.20.30.40",
    "10.20.30.41"
  ]
}

And look it up again:

10.20.30.40
10.20.30.41

If you still see the old answer, give it a second and try again.

7. Tidy up

Finally, we can tidy up. To remove the Resource Group and everything within it:

Once the zone is gone, its names stop resolving too. There's nothing billable to clean up, since everything ran on your machine, but it's still worth checking your teardown scripts work here before you run them against Azure.

Doing this with other tooling

Whilst this guide used the Azure CLI, DNS Zones work the same way through any of the tooling that Locally supports - a Microsoft.Network/dnsZones resource and its record sets in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way.

To check your records from your own code or tests, point its DNS resolver at 127.0.0.1 on port 5673.

Next steps

The DNS Server page lists every record type Locally serves. For names that only resolve inside your virtual networks, see Private DNS Zone.

Should you encounter any issues, please take a look at the troubleshooting section.