How to configure a private link for Azure AI Foundry hubs

Article
2025-04-30

We have two network isolation aspects. One is the network isolation to access an Azure AI Foundry hub. Another is the network isolation of computing resources in your hub and projects such as compute instances, serverless, and managed online endpoints. This article explains the former highlighted in the diagram. You can use private link to establish the private connection to your hub and its default resources. This article is for Azure AI Foundry (hub and projects). For information on Azure AI services, see the Azure AI services documentation.

You get several hub default resources in your resource group. You need to configure following network isolation configurations.

Disable public network access of hub default resources such as Azure Storage, Azure Key Vault, and Azure Container Registry.
Establish private endpoint connection to hub default resources. You need to have both a blob and file private endpoint for the default storage account.
If your storage account is private, assign roles to allow access.

Prerequisites

You must have an existing Azure Virtual Network to create the private endpoint in.

Important

We do not recommend using the 172.17.0.0/16 IP address range for your VNet. This is the default subnet range used by the Docker bridge network or on-premises.
Disable network policies for private endpoints before adding the private endpoint.

Create a hub that uses a private endpoint

If you are creating a new hub, use the following methods to create the hub (Azure portal or Azure CLI). Each of these methods requires an existing virtual network:

Note

The information in this document is only about configuring a private link. For a walkthrough of creating a secure hub in the portal, see Create a secure hub in the Azure portal.

From the Azure portal, search for Azure AI Foundry and create a new resource by selecting + New Azure AI.
After configuring the Basics and Storage tabs, select the Networking tab and pick the Network isolation option that best suits your needs.
Scroll down to Workspace Inbound access and choose + Add.
Input required fields. When selecting the Region, select the same region as your virtual network.

Note

The information in this section doesn't cover basic hub configuration. For more information, see Create a hub using the Azure CLI.

After creating the hub, use the Azure networking CLI commands to create a private link endpoint for the hub.

az network private-endpoint create \
    --name <private-endpoint-name> \
    --vnet-name <vnet-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>" \
    --group-id amlworkspace \
    --connection-name workspace \
    --location <location> \
    --resource-group <resource-group-name>

To create the private DNS zone entries for the workspace, use the following commands:

# Add privatelink.api.azureml.ms
az network private-dns zone create \
    -g <resource-group-name> \
    --name privatelink.api.azureml.ms

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name privatelink.api.azureml.ms \
    --name <link-name> \
    --virtual-network <vnet-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group create \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name myzonegroup \
    --private-dns-zone privatelink.api.azureml.ms \
    --zone-name privatelink.api.azureml.ms

Add a private endpoint to a hub

Use one of the following methods to add a private endpoint to an existing hub:

From the Azure portal, select your hub.
From the left side of the page, select Settings, Networking, and then select the Private endpoint connections tab. Select + Private endpoint.
When going through the forms to create a private endpoint, be sure to:
- From Basics, select the same Region as your virtual network.
- From Resource, select amlworkspace as the target sub-resource.
- From the Virtual Network form, select the virtual network and subnet that you want to connect to.
After populating the forms with any additional network configurations you require, use the Review + create tab to review your settings and select Create to create the private endpoint.

Use the Azure networking CLI commands to create a private link endpoint for the hub.

az network private-endpoint create \
    --name <private-endpoint-name> \
    --vnet-name <vnet-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>" \
    --group-id amlworkspace \
    --connection-name workspace \
    --location <location> \
    --resource-group <resource-group-name>

To create the private DNS zone entries for the workspace, use the following commands:

# Add privatelink.api.azureml.ms
az network private-dns zone create \
    -g <resource-group-name> \
    --name privatelink.api.azureml.ms

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name privatelink.api.azureml.ms \
    --name <link-name> \
    --virtual-network <vnet-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group create \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name myzonegroup \
    --private-dns-zone privatelink.api.azureml.ms \
    --zone-name privatelink.api.azureml.ms

# Add privatelink.notebooks.azure.net
az network private-dns zone create \
    -g <resource-group-name> \
    --name privatelink.notebooks.azure.net

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name privatelink.notebooks.azure.net \
    --name <link-name> \
    --virtual-network <vnet-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group add \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name myzonegroup \
    --private-dns-zone privatelink.notebooks.azure.net \
    --zone-name privatelink.notebooks.azure.net

Remove a private endpoint

You can remove one or all private endpoints for a hub. Removing a private endpoint removes the hub from the Azure Virtual Network that the endpoint was associated with. Removing the private endpoint might prevent the hub from accessing resources in that virtual network, or resources in the virtual network from accessing the workspace. For example, if the virtual network doesn't allow access to or from the public internet.

Warning

Removing the private endpoints for a hub doesn't make it publicly accessible. To make the hub publicly accessible, use the steps in the Enable public access section.

To remove a private endpoint, use the following information:

From the Azure portal, select your hub.
From the left side of the page, select Settings, Networking, and then select the Private endpoint connections tab.
Select the endpoint to remove and then select Remove.

When using the Azure CLI, use the following command to remove the private endpoint:

az network private-endpoint delete \
    --name <private-endpoint-name> \
    --resource-group <resource-group-name>

Enable public access

In some situations, you might want to allow someone to connect to your secured hub over a public endpoint, instead of through the virtual network. Or you might want to remove the workspace from the virtual network and re-enable public access.

Important

Enabling public access doesn't remove any private endpoints that exist. All communications between components behind the virtual network that the private endpoint(s) connect to are still secured. It enables public access only to the hub, in addition to the private access through any private endpoints.

To enable public access, use the following steps:

From the Azure portal, select your hub.
From the left side of the page, select Networking and then select the Public access tab.
Select Enabled from all networks, and then select Save.

Use the following Azure CLI command to enable public access:

az ml workspace update --set public_network_access=Enabled -n <workspace-name> -g <resource-group-name>

If you receive an error that the ml command isn't found, use the following commands to install the Azure Machine Learning CLI extension:

az extension add --name ml

Enable Public Access only from internet IP ranges (preview)

You can use IP network rules to allow access to your secured hub from specific public internet IP address ranges by creating IP network rules. Each Azure AI Foundry hub supports up to 200 rules. These rules grant access to specific internet-based services and on-premises networks and block general internet traffic. This feature is currently in preview.

Warning

Enable your endpoint's public network access flag if you want to allow access to your endpoint from specific public internet IP address ranges.
You can only use IPv4 addresses.
If the workspace goes from Enable from selected IPs to Disabled or Enabled, the IP ranges will be reset.

Portal
Azure CLI

From the Azure portal, select your Azure Machine AI Foundry hub.
From the left side of the page, select Networking and then select the Public access tab.
Select Enabled from selected IP addresses, input address ranges and then select Save.

Use the az ml workspace update Azure CLI command to manage public access from an IP address or address range:

Tip

The configurations for the selected IP addresses are stored in the hub's properties, under network_acls:

name: sample_hub
location: centraluseuap
display_name: sample hub
description: desc
public_network_access: enabled
network_acls:
    ip_rules:
        value: "X.X.X.X/X"
        value: "X.X.X.X"
    default_action: Deny

Disabled: az ml workspace update -n test-ws -g test-rg --public-network-access Disabled
Enabled from selected IP addresses: az ml workspace update -n test-ws -g test-rg --public-network-access Enabled --network-acls "167.220.238.199/32,167.220.238.194/32"
Enabled from all networks: az ml workspace update -n test-ws -g test-rg --public-network-access Enabled --network-acls none

You can also use the Workspace class from the Azure Machine Learning Python SDK to define which IP addresses are allowed inbound access:

class Workspace(Resource):
    """Azure ML workspace.
    :param public_network_access: Whether to allow public endpoint connectivity
        when a workspace is private link enabled.
    :type public_network_access: str
    :param network_acls: The network access control list (ACL) settings of the workspace.
    :type network_acls: ~azure.ai.ml.entities.NetworkAcls
 
    def __init__(
        self,
        *,
        public_network_access: Optional[str] = None,
        network_acls: Optional[NetworkAcls] = None,

Restrictions for IP network rules

The following restrictions apply to IP address ranges:

IP network rules are allowed only for public internet IP addresses.

Reserved IP address ranges aren't allowed in IP rules such as private addresses that start with 10, 172.16 to 172.31, and 192.168.
You must provide allowed internet address ranges by using CIDR notation in the form 16.17.18.0/24 or as individual IP addresses like 16.17.18.19.
Only IPv4 addresses are supported for configuration of storage firewall rules.
When this feature is enabled, you can test public endpoints using any client tool such as Curl, but the Endpoint Test tool in the portal isn't supported.
You can only set the IP addresses for the AI Foundry hub after the hub has been created.

Private storage configuration

If your storage account is private (uses a private endpoint to communicate with your project), you perform the following steps:

Our services need to read/write data in your private storage account using Allow Azure services on the trusted services list to access this storage account with following managed identity configurations. Enable the system assigned managed identity of Azure AI Service and Azure AI Search, then configure role-based access control for each managed identity.

Role	Managed Identity	Resource	Purpose	Reference
`Reader`	Azure AI Foundry project	Private endpoint of the storage account	Read data from the private storage account.
`Storage File Data Privileged Contributor`	Azure AI Foundry project	Storage Account	Read/Write prompt flow data.	Prompt flow doc
`Storage Blob Data Contributor`	Azure AI Service	Storage Account	Read from input container, write to preprocess result to output container.	Azure OpenAI Doc
`Storage Blob Data Contributor`	Azure AI Search	Storage Account	Read blob and write knowledge store	Search doc.

Tip

Your storage account may have multiple private endpoints. You need to assign the Reader role to each private endpoint for your Azure AI Foundry project managed identity.

Assign the Storage Blob Data reader role to your developers. This role allows them to read data from the storage account.
Verify that the project's connection to the storage account uses Microsoft Entra ID for authentication. To view the connection information, go to the Management center, select Connected resources, and then select the storage account connections. If the credential type isn't Entra ID, select the pencil icon to update the connection and set the Authentication method to Microsoft Entra ID.

For information on securing playground chat, see Securely use playground chat.

Custom DNS configuration

See Azure Machine Learning custom DNS article for the DNS forwarding configurations.

If you need to configure custom DNS server without DNS forwarding, use the following patterns for the required A records.

<AI-STUDIO-GUID>.workspace.<region>.cert.api.azureml.ms
<AI-PROJECT-GUID>.workspace.<region>.cert.api.azureml.ms
<AI-STUDIO-GUID>.workspace.<region>.api.azureml.ms
<AI-PROJECT-GUID>.workspace.<region>.api.azureml.ms
ml-<workspace-name, truncated>-<region>-<AI-STUDIO-GUID>.<region>.notebooks.azure.net
ml-<workspace-name, truncated>-<region>-<AI-PROJECT-GUID>.<region>.notebooks.azure.net

Note

The workspace name for this FQDN might be truncated. Truncation is done to keep ml-<workspace-name, truncated>-<region>-<workspace-guid> at 63 characters or less.
<instance-name>.<region>.instances.azureml.ms
Note
- Compute instances can be accessed only from within the virtual network.
- The IP address for this FQDN is not the IP of the compute instance. Instead, use the private IP address of the workspace private endpoint (the IP of the *.api.azureml.ms entries.)
<instance-name>.<region>.instances.azureml.ms - Only used by the az ml compute connect-ssh command to connect to computers in a managed virtual network. Not needed if you aren't using a managed network or SSH connections.
<managed online endpoint name>.<region>.inference.ml.azure.com - Used by managed online endpoints
models.ai.azure.com - Used for deploying Models as a Service

To find the private IP addresses for your A records, see the Azure Machine Learning custom DNS article. To check AI-PROJECT-GUID, go to the Azure portal, select your project, settings, properties, and the workspace ID is displayed.

Limitations

You might encounter problems trying to access the private endpoint for your hub if you're using Mozilla Firefox. This problem might be related to DNS over HTTPS in Mozilla Firefox. We recommend using Microsoft Edge or Google Chrome.

Share via