Skip to content

CloudAstro/terraform-azurerm-private-dns-resolver

BranchesTags

Repository files navigation

Azure Private DNS Resolver Terraform Module

Changelog Notice MIT License OpenTofu Registry

This Terraform module provisions and manages Azure Private DNS Resolver resources. It supports configuration of the DNS Resolver itself, as well as associated inbound/outbound endpoints, virtual network links, forwarding rules, and DNS forwarding rulesets. The module is designed for flexible integration with custom Azure network topologies.

Features

  • Private DNS Resolver: Deploys a Private DNS Resolver instance in a specified region and resource group.
  • Inbound Endpoints: Configure endpoints to receive DNS queries from on-premises networks or other sources.
  • Outbound Endpoints: Manage endpoints to forward DNS queries to upstream DNS servers.
  • Forwarding Rules: Define custom DNS forwarding rules to route requests based on domain patterns.
  • DNS Forwarding Ruleset: Manage forwarding rulesets for logical grouping and reuse across endpoints.
  • Virtual Network Link: Link virtual networks to the DNS Resolver for internal name resolution.

Example Usage

This example demonstrates how to deploy a full Azure Private DNS Resolver setup, including endpoints, forwarding rules, and VNet links:

resource "azurerm_resource_group" "rg" {
  name     = "rg-pdnsr-example"
  location = "germanywestcentral"
}

module "vnet_1" {
  source              = "CloudAstro/virtual-network/azurerm"
  name                = "vnet-pdnsr-example-1"
  address_space       = ["10.0.0.0/16"]
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
}

module "snet_1" {
  source               = "CloudAstro/subnet/azurerm"
  name                 = "snet-pdnsr-example-1"
  resource_group_name  = azurerm_resource_group.rg.name
  virtual_network_name = module.vnet_1.virtual_network.name
  address_prefixes     = ["10.0.1.0/24"]
  delegation = [
    {
      name = "dnsDelegation"
      service_delegation = {
        name = "Microsoft.Network/dnsResolvers"
        actions = [
          "Microsoft.Network/virtualNetworks/subnets/join/action"
        ]
      }
  }]
}

# This second virtual network is created solely to demonstrate how `virtual_network_links` work
# in the Private DNS Resolver module. It is linked from the forwarding ruleset as "link-to-vnet2".
module "vnet_2" {
  source              = "CloudAstro/virtual-network/azurerm"
  name                = "vnet-pdnsr-example-2"
  address_space       = ["192.168.0.0/16"]
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
}

module "snet_2" {
  source               = "CloudAstro/subnet/azurerm"
  name                 = "snet-example-2"
  resource_group_name  = azurerm_resource_group.rg.name
  virtual_network_name = module.vnet_1.virtual_network.name
  address_prefixes     = ["10.0.2.0/24"]

  delegation = [
    {
      name = "dnsDelegation"
      service_delegation = {
        name = "Microsoft.Network/dnsResolvers"
        actions = [
          "Microsoft.Network/virtualNetworks/subnets/join/action"
        ]
      }
  }]
}

module "private_dns_resolver" {
  source              = "../.."
  name                = "pdnsr-example"
  resource_group_name = azurerm_resource_group.rg.name
  location            = azurerm_resource_group.rg.location
  virtual_network_id  = module.vnet_1.virtual_network.id

  inbound_endpoint = {
    endpoint1 = {
      name     = "inbound1"
      location = azurerm_resource_group.rg.location
      ip_configurations = [
        {
          subnet_id                    = module.snet_2.subnet.id
          private_ip_address           = "10.0.2.4"
          private_ip_allocation_method = "Static"
        }
      ]
    }
  }

  outbound_endpoint = {
    "outbound1" = {
      name      = "outbound-endpoint"
      subnet_id = module.snet_1.subnet.id

      forwarding_ruleset = {
        ruleset-1 = {
          name = "example-ruleset"
          virtual_network_link = {
            "link1" = {
              name               = "link-to-vnet2"
              virtual_network_id = module.vnet_2.virtual_network.id
              metadata = {
                link_owner = "infra-team"
              }
            }
          }

          rule = {
            "google-forward" = {
              name        = "forward-google"
              domain_name = "google.com."
              enabled     = true
              metadata = {
                team = "dns"
              }
              target_dns_servers = [{
                ip_address = "8.8.8.8"
                port       = 53
                }, {
                ip_address = "8.8.4.4"
                port       = 53
              }]
            }
            internal-forward = {
              name        = "internal-forward"
              domain_name = "example.com."
              enabled     = true
              metadata = {
                team = "dns"
              }
              target_dns_servers = [{
                ip_address = "10.0.0.1"
                port       = 53
                }, {
                ip_address = "10.0.0.2"
                port       = 5353
              }]
            }
          }
        }
      }
    }
  }
}

Requirements

Name Version
terraform ~> 1.9.0
azurerm >= 4.0.0

Providers

Name Version
azurerm >= 4.0.0

Resources

Name Type
azurerm_private_dns_resolver.this resource
azurerm_private_dns_resolver_dns_forwarding_ruleset.this resource
azurerm_private_dns_resolver_forwarding_rule.this resource
azurerm_private_dns_resolver_inbound_endpoint.this resource
azurerm_private_dns_resolver_outbound_endpoint.this resource
azurerm_private_dns_resolver_virtual_network_link.this resource

Inputs

Name Description Type Default Required
location * location - (Required) Specifies the Azure Region where the Private DNS Resolver will be deployed. Changing this forces a new Private DNS Resolver to be created.

Example Input:
location = "East US"
 string n/a yes
name * name - (Required) Specifies the name of the Private DNS Resolver. Changing this forces a new Private DNS Resolver to be created.

Example Input:
name = "pdnsr-prod"
 string n/a yes
resource_group_name * resource_group_name - (Required) Specifies the name of the Resource Group where the Private DNS Resolver should exist. Changing this forces a new Private DNS Resolver to be created.

Example Input:
resource_group_name = "rg-pdnsr-prod"
 string n/a yes
virtual_network_id * virtual_network_id - (Required) The ID of the Virtual Network that is linked to the Private DNS Resolver. Changing this forces a new Private DNS Resolver to be created.

Example Input:
virtual_network_id = "/subscriptions/12345678-abcd-efgh-ijkl-9876543210aa/resourceGroups/prod-rg/providers/Microsoft.Network/virtualNetworks/prod-vnet"
 string n/a yes
inbound_endpoint * inbound_endpoint - Gets information about an existing Private DNS Resolver Inbound Endpoint.
* name - (Required) Specifies the name which should be used for this Private DNS Resolver Inbound Endpoint. Changing this forces a new Private DNS Resolver Inbound Endpoint to be created.
* private_dns_resolver_id - (Required) Specifies the ID of the Private DNS Resolver Inbound Endpoint. Changing this forces a new Private DNS Resolver Inbound Endpoint to be created.
* ip_configurations - (Required) One ip_configurations block as defined below. Changing this forces a new Private DNS Resolver Inbound Endpoint to be created.
* subnet_id - (Required) The subnet ID of the IP configuration.
* private_ip_address - (Optional) Private IP address of the IP configuration.
* private_ip_allocation_method - (Optional) Private IP address allocation method. Allowed value is Dynamic and Static. Defaults to Dynamic.
* location - (Required) Specifies the Azure Region where the Private DNS Resolver Inbound Endpoint should exist. Changing this forces a new Private DNS Resolver Inbound Endpoint to be created.
* tags - (Optional) A mapping of tags which should be assigned to the Private DNS Resolver Inbound Endpoint.

Example Input:
inbound_endpoint = {
    name                     = "in-endpoint-prd"
    location                 = "East US"
    private_dns_resolver_id  = "/subscriptions/12345678-abcd-efgh-ijkl-9876543210aa/resourceGroups/prod-rg/providers/Microsoft.Network/privateDnsResolver/prod-pdnsr"
    ip_configuration = {
      subnet_id                  = "/subscriptions/12345678-abcd-efgh-ijkl-9876543210aa/resourceGroups/prod-rg/providers/Microsoft.Network/virtualNetworks/prod-vnet/subnets/prod-subnet"
      private_ip_address         = "10.1.0.5"
      private_ip_allocation_method = "Static"
      }
    }
 
map(object({
    name     = string
    location = string
    ip_configurations = list(object({
      subnet_id                    = string
      private_ip_address           = optional(string)
      private_ip_allocation_method = optional(string)
    }))
  }))
 null no
outbound_endpoint * outbound_endpoint - Manages a Private DNS Resolver Outbound Endpoint.
* name - (Required) Specifies the name which should be used for this Private DNS Resolver Outbound Endpoint. Changing this forces a new Private DNS Resolver Outbound Endpoint to be created.
* private_dns_resolver_id - (Required) Specifies the ID of the Private DNS Resolver Outbound Endpoint. Changing this forces a new Private DNS Resolver Outbound Endpoint to be created.
* subnet_id - (Required) The ID of the Subnet that is linked to the Private DNS Resolver Outbound Endpoint. Changing this forces a new resource to be created.
* dns_forwarding_ruleset - Manages a Private DNS Resolver Dns Forwarding Ruleset.
* name - (Required) Specifies the name which should be used for this Private DNS Resolver Dns Forwarding Ruleset. Changing this forces a new Private DNS Resolver Dns Forwarding Ruleset to be created.
* private_dns_resolver_outbound_endpoint_ids - (Required) The list of IDs of the Private DNS Resolver Outbound Endpoint that is linked to the Private DNS Resolver Dns Forwarding Ruleset.
* forwaring_rule - Manages a Private DNS Resolver Forwarding Rule.
* name - (Required) Specifies the name which should be used for this Private DNS Resolver Forwarding Rule. Changing this forces a new Private DNS Resolver Forwarding Rule to be created.
* dns_forwarding_ruleset_id - (Required) Specifies the ID of the Private DNS Resolver Forwarding Ruleset. Changing this forces a new Private DNS Resolver Forwarding Rule to be created.
* domain_name - (Required) Specifies the domain name for the Private DNS Resolver Forwarding Rule. Changing this forces a new Private DNS Resolver Forwarding Rule to be created.
* target_dns_servers - (Required) Can be specified multiple times to define multiple target DNS servers. Each target_dns_servers block as defined below.
* ip_address - (Required) DNS server IP address.
* port - (Optional) DNS server port.
* enabled - (Optional) Specifies the state of the Private DNS Resolver Forwarding Rule. Defaults to true.
* metadata - (Optional) Metadata attached to the Private DNS Resolver Forwarding Rule.
* virtual_network_link - Manages a Private DNS Resolver Virtual Network Link.
* name - (Required) Specifies the name which should be used for this Private DNS Resolver Virtual Network Link. Changing this forces a new Private DNS Resolver Virtual Network Link to be created.
* dns_forwarding_ruleset_id - (Required) Specifies the ID of the Private DNS Resolver DNS Forwarding Ruleset. Changing this forces a new Private DNS Resolver Virtual Network Link to be created.
* virtual_network_id - (Required) The ID of the Virtual Network that is linked to the Private DNS Resolver Virtual Network Link. Changing this forces a new resource to be created.
* metadata - (Optional) Metadata attached to the Private DNS Resolver Virtual Network Link.

Example Input:
outbound_endpoints = {
    "outbound1" = {
      name      = "outbound-endpoint"
      subnet_id = "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.Network/virtualNetworks/vnet/subnets/snet"

      forwarding_ruleset = {
        "example-ruleset" = {
          name = "example-ruleset"

          virtual_network_links = {
            "link1" = {
              name     = "example-vnet-link"
              vnet_id  = "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.Network/virtualNetworks/vnet"
              metadata = {
                link_owner = "infra-team"
              }
            }
          }

          rules = {
            "google-forward" = {
              name        = "forward-google"
              domain_name = "google.com."
              enabled     = true
              metadata = {
                team = "dns"
              }
              destination_ip_addresses = {
                "8.8.8.8" = 53
                "8.8.4.4" = 53
              }
            }
          }
        }
      }
    }
  }
 
map(object({
    name      = string
    subnet_id = string
    forwarding_ruleset = optional(map(object({
      name = optional(string)
      virtual_network_link = optional(map(object({
        name               = string
        virtual_network_id = string
        metadata           = optional(map(string))
      })))
      rule = optional(map(object({
        name        = string
        domain_name = string
        enabled     = optional(bool)
        metadata    = optional(map(string))
        target_dns_servers = list(object({
          ip_address = string
          port       = optional(number)
        }))
      })))
    })))
  }))
 null no
tags * tags - (Optional) A map of tags to associate with the network and subnets.

Example Input:
tags = {
    "environment" = "production"
    "department"  = "IT"
  }
 map(string) null no
timeouts * timeouts - The timeouts block allows you to specify timeouts for certain actions:
* create - (Defaults to 30 minutes) Used when creating the Container App.
* delete - (Defaults to 30 minutes) Used when deleting the Container App.
* read - (Defaults to 5 minutes) Used when retrieving the Container App.
* update - (Defaults to 30 minutes) Used when updating the Container App.

Example Input:
container_app_timeouts = {
    create = "45m"
    delete = "30m"
    read   = "10m"
    update = "40m"
  }
 
object({
    create = optional(string, "90")
    read   = optional(string, "5")
    update = optional(string, "60")
    delete = optional(string, "60")
  })
 null no

Outputs

Name Description
dns_resolver Outputs details for the Azure Private DNS Resolver.
* name - The name of the DNS Resolver.
* resource_group_name - The name of the resource group where the DNS Resolver is deployed.
* location - The Azure region where the DNS Resolver is created.
* id - The resource ID of the DNS Resolver.
* tags - A mapping of tags assigned to the DNS Resolver.

Example output:
output "dns_resolver_name" {
    value = module.module_name.dns_resolver.name
  }

Modules

No modules.

🌐 Additional Information

For comprehensive guidance on Azure Private DNS and configuration scenarios, refer to the Azure Private DNS documentation.
This module allows you to manage private DNS zones and dynamically link them to one or more virtual networks for name resolution within your Azure environment.

📚 Resources

⚠️ Notes

  • A single Private DNS zone can be linked to multiple VNets across different regions.
  • DNS resolution and billing are impacted by the number of zones, query volume, and linked virtual networks.
  • Always validate and review your Terraform plans to ensure accurate creation and association of DNS resources.

🧾 License

This module is licensed under the MIT License. See the LICENSE file for more details.

About

This Terraform module provisions and manages Azure Private DNS Resolver resources.

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 Latest
Jun 26, 2025

Packages

No packages published

Languages