Provisioning a Private 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:

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 a Virtual Network

Private DNS Zones are linked to virtual networks, so we'll create one to link to:

Then the zone itself. The name is a domain you control the resolution of within your own networks - it doesn't need to be registered anywhere:

{
  "name": "sample.internal",
  "state": "Succeeded"
}

4. Create the Private DNS Zone and a record

A zone with no records doesn't resolve anything, so let's add an A record pointing at an address inside the subnet:

{
  "fqdn": "api.sample.internal.",
  "records": [
    "10.0.1.10"
  ]
}

5. Link the zone to the network

Finally, the zone has to be linked to a virtual network before anything in that network can resolve names from it. This is the step that's easy to forget, and the symptom - names that simply don't resolve - gives you little to go on:

{
  "name": "vnet-link",
  "registration": false,
  "state": "Succeeded"
}

The -e false disables auto-registration, meaning records are managed by you rather than created automatically as VMs join the network.

We can confirm the zone and its record count:

We can see the Private DNS Zone in the Locally Dashboard too:

6. Tidy up

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

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, Private DNS Zones work the same way through any of the tooling that Locally supports - a Microsoft.Network/privateDnsZones resource in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way, with only the location changed.

Next steps

The DNS Server page covers how Locally resolves the records in your zones. For more on the network the zone is linked to, see Virtual Network.

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