Migrate a Virtual Network injected cluster to private endpoints

This article describes the migration of a Microsoft Azure Virtual Network injected Azure Data Explorer cluster to an Azure Private Endpoints network security model. For a detailed comparison, see Private endpoint vs. virtual network injection.

The process of the migration takes several minutes. The migration creates a new cluster for the engine and data management services, which reside in a virtual network managed by Microsoft. The connection is switched to the newly created services for you. This process results in a minimal downtime for querying the cluster.

Following the migration, you can still connect to your cluster using the private-[clustername].[geo-region].kusto.windows.net (engine) and ingest-private-[clustername].[geo-region].kusto.windows.net\private-ingest-[clustername].[geo-region].kusto.windows.net (data management) FQDNs. Nevertheless, we recommend moving to the regular cluster endpoints that aren't prefixed with private.

Prerequisites

• You have an existing Azure Data Explorer cluster that uses Virtual Network injection and you want to migrate it. For more information, see Find clusters that use Virtual Network injection.
• (Optional) You have a virtual network and a subnet where you want to create the private endpoint for the Azure Data Explorer cluster.
• You have the necessary permissions to establish and oversee private endpoints and private DNS zones within your subscription and resource group. For the Azure Data Explorer cluster, Contributor access is required, while other resources like Azure Storage or Event Hubs require Owner permissions.

Find clusters that use Virtual Network injection

You can use Azure Resource Graph to determine which clusters in your subscription use Virtual Network injection by exploring your Azure resources with the Kusto Query Language (KQL).

Azure Resource Graph

1. Go to the Resource Graph Explorer in the Azure portal.

2. Copy and paste the following query. Then select Run query to list all clusters that use Virtual Network injection:

   The query filters the resources to only include clusters (microsoft.kusto/clusters) where the virtualNetworkConfiguration property state is set to Enabled, indicating that the cluster is using Virtual Network injection.

   resources 
   | where type == 'microsoft.kusto/clusters' 
   | where properties.virtualNetworkConfiguration.state == 'Enabled' 
   | project name, resourceGroup, subscriptionId, location
   

Azure CLI

You can also use the Azure CLI to run the same query. First, ensure you have the Azure CLI installed and are signed in to your Azure account.

Run the following Azure CLI command to execute the query:

az graph query -q "resources | where type == 'microsoft.kusto/clusters' | where properties.virtualNetworkConfiguration.state == 'Enabled' | project name, resourceGroup, subscriptionId, location"

Prepare to migrate

We recommend configuring your cluster infrastructure in alignment with the Azure Private Endpoints network security model before initiating the migration process. While it's possible to perform this configuration post-migration, doing so can result in a service disruption.

The following steps ensure that post-migration clients in the virtual network can connect to the cluster and that the cluster can connect to other services. When firewalls for Azure Storage or Azure Event Hubs are employed, these steps are crucial. For instance, if Service Endpoints were used for Azure Storage and Azure Event Hubs namespace, migrating the cluster out of the virtual network disrupts connections to these services. To restore connectivity, you need to set up managed private endpoints for Azure Data Explorer.

To prepare your cluster for migration:

1. In the Azure portal, go to the Azure Data Explorer cluster you'd like to migrate.

2. From the left menu, select Networking.

   

3. In order to connect to your cluster even if the public access was set to Disabled, select the Private Endpoints connections tab and create a private endpoint. Make sure that you choose a different subnet than the one you used for your Azure Data Explorer cluster with Azure Virtual Network integration, otherwise, the private endpoint deployment will fail.

   

   Note

   This configuration will take effect only after the migration of your your cluster.

4. In order to allow your cluster to connect to other network secured services, select the Managed private endpoints tab and create a managed private endpoint.

   

   Note

   This configuration will take effect only after the migration of your your cluster.

5. To restrict outbound access, select the Restrict outbound access tab and see the documentation for how to Restrict outbound access. These restrictions take immediate effect.

   

Warning

Failure of your cluster to connect to essential services for ingestion and external tables poses a risk of data loss. Additionally, queries calling out to other network-protected services may cease to function.

Migrate your cluster

Azure portal

To migrate your cluster from the Azure portal:

1. Go to the Azure Data Explorer cluster you would like to migrate.

2. From the left menu, select Networking.

   

3. Select on the Migrate button.

   

4. Wait until the migration finishes.

ARM template

To migrate your cluster by modifying the ARM template:

1. Locate the VirtualNetworkConfiguration in the ARM template of your cluster

   "virtualNetworkConfiguration": {
       "state": "Enabled",
       "subnetId": "[concat(parameters('virtualNetworks_Test_vnet_externalid'), '/subnets/newsubnet')]",
       "enginePublicIpId": "[parameters('publicIPAddresses_vnetclusterwestus3engine_externalid')]",
       "dataManagementPublicIpId": "[parameters('publicIPAddresses_vnetclusterwestus3dm_externalid')]"
    },
   

2. Replace "state": "Enabled" with "state": "Disabled". Don't modify the other properties.

   "virtualNetworkConfiguration": {
       "state": "Disabled",
       "subnetId": "[concat(parameters('virtualNetworks_Test_vnet_externalid'), '/subnets/newsubnet')]",
       "enginePublicIpId": "[parameters('publicIPAddresses_vnetclusterwestus3engine_externalid')]",
       "dataManagementPublicIpId": "[parameters('publicIPAddresses_vnetclusterwestus3dm_externalid')]"
    },
   

3. Deploy the ARM template

Python script

You can use a Python script to automate the migration of multiple your clusters. The script migrateAzure Data Explorerclusters.py available in the Azure Kusto Virtual Network Migration GitHub repository can be used for this purpose.

Detailed steps on how to use this script are provided in the README file in the same repository. For instructions on how to clone the repository, refer to the README. Install the required Python packages, and run the script with the necessary configuration.

This script migrates the specified clusters in one go, saving you the time and effort of migrating them individually.

Verify successful migration

After migrating to private endpoints, perform the following checks to verify the migration was successful:

1. If you created new private endpoints, check that they are working as expected. If needed, refer to the troubleshooting guide.

2. Check that ingestion is working properly with the .show ingestion failures command or refer to the guidance in Monitor queued ingestion with metrics. This verification is especially relevant if you need to connect to network secured services for ingestion with services like Azure Event Hubs.

Related content

• Create a Private Endpoints for Azure Data Explorer
• Create a Managed Private Endpoints for Azure Data Explorer
• How to restrict public access to Azure Data Explorer
• How to restrict outbound access from Azure Data Explorer