Configure an Azure Dedicated Cloud Gateway with virtual hub peering and outbound DNS resolution

Uses: Kong Gateway

Incompatible with

on-prem

Prerequisites

Kong Konnect

This tutorial requires a Konnect Plus account. If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

Microsoft Entra

To approve the Dedicated Cloud Gateway app, you need a Microsoft Entra admin account with the Application Administrator role.

Copy your Entra tenant ID from your dashboard.

Microsoft Azure CLI

Install the Azure CLI and authenticate:

az login

Copied!

Azure virtual network

To configure virtual hub peering in Konnect, you’ll need:

A virtual network configured in Azure that is associated with a virtual WAN
A virtual hub associated with your virtual WAN

Copy your virtual WAN subscription ID and resource group name, and the name of the virtual hub associated with your virtual WAN.

Important: Your Azure virtual network must use a different IP than your network in Konnect, which is 10.0.0.0/16 by default but can be edited. The Azure virtual network and virtual WAN must also use CIDRs that don’t overlap.

Azure private DNS resolver

Before you can configure outbound DNS in Konnect, you must configure private resolvers in Azure:

Create a DNS resolver inside your virtual network in Azure. Save the name of your DNS resolver.
Configure the outbound endpoints in your DNS resolver in Azure.
Configure a DNS forwarding ruleset in Azure.

Create an Azure Dedicated Cloud Gateway

First, configure a Dedicated Cloud Gateway with an Azure network.

In the Konnect sidebar, click API Gateways.
From the New dropdown menu, select “New API gateway”.
Select Dedicated Cloud.
In the Gateway name field, enter Azure.
Click Create and configure.
From the Provider dropdown menu, select “Azure”.
From the Region dropdown menu, select the region you want to configure the cluster in.
Edit the Network range as needed.

Important: Your Azure virtual network must use a different IP than your network in Konnect, which is 10.0.0.0/16 by default but can be edited.
From the Access dropdown menu, select “Public” or “Private”.
Click Create data plane node.

Important: Wait until your Azure network displays as Ready before proceeding to the next step.

Configure Azure virtual hub peering in Konnect

Now that your Dedicated Cloud Gateway Azure network is ready, you can configure virtual hub peering to connect your Azure virtual WAN to your Dedicated Cloud Gateway.

In the Konnect sidebar, click API Gateways.
Click your Azure Dedicated Cloud Gateway.
In the API Gateways sidebar, click Networks.
From the action menu next to your Azure network, select “Configure private networking”.
Click Virtual hub peering.
In the Tenant ID field, enter your Microsoft Entra tenant ID.
In the Subscription ID field, enter your virtual WAN’s subscription ID.
In the Resource group name field, enter your virtual WAN’s resource group name.
In the Virtual hub name field, enter your virtual WAN’s hub name.
Click Next.
Grant access to the Dedicated Cloud Gateway app in Microsoft Entra using the link provided in the setup wizard.

Important: You need an admin account to approve the app.
Create a peering role with the Azure CLI using the command in the UI wizard.

Konnect requires permission to create and manage peering resources. You must define a role named Kong Cloud Gateway Peering Creator with the following permissions:
- Read and write access to virtual hub configurations
- Permission to perform peering actions
Assign the role to the service principal so it has permission to peer with your virtual hub using the command in the UI wizard.
Select I’ve completed the Azure setup steps above.
Click Done.

An outbound DNS resolver is already created when the virtual hub peering is set up. We just need to add additional outbound endpoints.

Configure an outbound DNS resolver for your Azure network in Konnect

After your Azure private networking configuration is ready in Konnect, you can configure outbound DNS.

In the Konnect sidebar, click API Gateways.
Click your Azure Dedicated Cloud Gateway.
In the API Gateways sidebar, click Networks.
From the action menu next to your Azure network, select “Configure private DNS”.
Click Outbound DNS resolver.
In the Outbound Resolver name field, enter the name of your private DNS resolver in Azure.
In the Domain name field, enter your domain.
In the Target IP address field, enter the IP addresses of your outbound endpoint subnets.
Click Save.

DNS mappings

The following table describes how DNS is mapped:

Mapping type	Description	Example
1-to-1 mapping	Each domain is mapped to a unique IP address.	`example.com` → `192.168.1.1`
N-to-1 mapping	Multiple domains share the same IP address.	`example.com`, `example2.com` → `192.168.1.1`
M-to-N mapping	Multiple domains are mapped to multiple IP addresses, without a strict one-to-one relationship.	`example.com` → `192.168.1.2` `example3.com` → `192.168.1.1`

Validate

Once your outbound DNS resolver configuration displays as ready, you can begin using your Dedicated Cloud Gateway. To verify that it’s ready, do the following:

In the Konnect sidebar, click API Gateways.
Click your Azure Dedicated Cloud Gateway.
In the API Gateways sidebar, click Networks.
From the action menu next to your Azure network, select “Configure private DNS”.
Scroll until you see Ready for your outbound DNS resolver.

When I try to create the VNET peering role and assign the role to the service principal, I get the following errors: (RoleDefinitionWithSameNameExists) A custom role with the same name already exists in this directory. and Role 'Kong Cloud Gateway Peering Creator - Kong' doesn't exist.. How do I fix this?

This error can occur because you have multiple subscriptions in the same Entra tenant and the Azure CLI can’t assign another subscription to the role. To resolve this in Azure, search for the role and manually add additional subscription IDs to it instead of using the CLI.

Next Steps

Dedicated Cloud Gateways production readiness checklist