Merge pull request #7182 from MicrosoftDocs/main

Auto Publish – main to live - 2025-09-22 11:00 UTC

Author: learn-build-service-prod[bot]

articles/ai-foundry/how-to/upgrade-azure-openai.md

@@ -45,18 +45,19 @@ Backend limitations:
 
 * Azure OpenAI resources using **customer-managed keys** for encryption aren't supported for upgrade.
 * The AI Foundry resource type doesn't support configuring Weights & Biases.
+* Private network setups require [reconfiguration of private link endpoints and extra DNS configurations](#private-network-configuration) before all Foundry capabilities can be used.
 
 Foundry portal limitations:
 
 * The evaluations view doesn't yet support all the capabilities available in the Azure OpenAI evaluations view.
 
 ## Support level post-upgrade 
 
-The upgrade converts your Azure OpenAI resource type to Azure AI Foundry resource type. Both services are generally available and supported before and after the upgrade. Upgrading your AOAI resource is an opt-in capability. If needed, you can [roll back to your previous setup](#roll-back-to-azure-openai).
+The upgrade converts your Azure OpenAI resource type to Azure AI Foundry resource type. Both services are generally available and supported before and after the upgrade. Upgrading your Azure OpenAI resource is an opt-in capability. If needed, you can [roll back to your previous setup](#roll-back-to-azure-openai).
 
 ## How to upgrade
 
-As a prerequisite to upgrade, managed identity must be enabled on your Azure OpenAI resource. Upgrade can be completed via the Azure AI Foundry portal, or using Azure Bicep or Resource Manager templates (recommended for resource configurations with custom security settings such as private networking).
+As a prerequisite to upgrade, managed identity must be enabled on your Azure OpenAI resource. Upgrade can be completed via the Azure AI Foundry portal, or using Azure Bicep or Resource Manager templates (recommended for resource configurations with custom security settings).
 
 # [Foundry portal](#tab/portal)
 
@@ -115,7 +116,7 @@ After upgrading from Azure OpenAI to Azure AI Foundry, you'll notice updates to
 
 1. **Updated left-side navigation**
 
-   The left-hand menu is re-organized to consolidate playgrounds, including Assistants, under a single landing page, streamlining access to experimentation environments. You find access to new features including Agent service and Content Understanding.
+   The left-hand menu is reorganized to consolidate playgrounds, including Assistants, under a single landing page, streamlining access to experimentation environments. You find access to new features including Agent service and Content Understanding.
 
    An *Azure OpenAI section* provides access to features that are exclusively used with Azure OpenAI models.
 
@@ -136,13 +137,32 @@ After upgrading from Azure OpenAI to Azure AI Foundry, you'll notice updates to
 
 ## Understanding pricing
 
-There are no pricing differences for existing Azure OpenAI functionality when upgrading to Azure AI Foundry—your current usage patterns and costs remain unchanged. However, Azure AI Foundry unlocks access to additional features such as expanded model catalogs, agent services, and evaluation tools, which may have their own pricing structures depending on the models and services used.
+There are no pricing differences for existing Azure OpenAI functionality when upgrading to Azure AI Foundry—your current usage patterns and costs remain unchanged. However, Azure AI Foundry unlocks access to more features such as expanded model catalogs, agent services, and evaluation tools, which may have their own pricing structures depending on the models and services used.
 
 For estimating costs of new features available in Azure AI Foundry, use the [Azure Pricing Calculator](https://azure.microsoft.com/pricing/calculator/).
 
+## Private network configuration
+
+AI Foundry resource is a superset of Azure OpenAI resource and its capabilities are exposed over three FQDNs:
+
+- {custom-domain}.openai.azure.com
+- {custom-domain}.services.ai.azure.com
+- {custom-domain}.cognitive.microsoft.com
+
+Your DNS configuration must be able to resolve each of the above FQDNs in order to use the full set of Foundry capabilities. 
+
+* If you're using Azure DNS, you need to create an [Azure DNS Zone](/azure/dns/dns-zones-records) for each of the above domains.
+
+* If you're using a custom DNS implementation, you need to implement a conditional forwarder for each of the above configurations. 
+
+After this, delete and [re-create a private link endpoint](configure-private-link.md) on your resource. Your private link endpoint creates an IP address in your Azure Virtual Network to map to each endpoint.
+
+> [!IMPORTANT] 
+> When upgrading to Azure AI Foundry, you must recreate your private link endpoint, for the "services.ai.azure.com" and "cognitive.microsoft.com" IP configurations to be created.
+
 ## Roll back to Azure OpenAI
 
-In case you run into any issues, a roll back option is available. As prerequisite to roll back, you're required to delete any of the following configurations first:
+In case you run into any issues, a rollback option is available. As prerequisite to rollback, you're required to delete any of the following configurations first:
 
 * Projects
 * Connections
@@ -155,7 +175,7 @@ Then, use either AI Foundry Portal or ARM template to roll back:
 **Option 1: Use Azure AI Foundry portal**
 
 1. Navigate to management center in the left bottom of your screen.
-1. On your resource overview page, find the roll back option.
+1. On your resource overview page, find the rollback option.
 1. Select **Rollback**.
 
 :::image type="content" source="../media/upgrade-azure-openai/rollback.png" alt-text="Screenshot shows the roll back option in the Azure AI Foundry portal." lightbox = "../media/upgrade-azure-openai/rollback.png":::
@@ -164,7 +184,7 @@ Then, use either AI Foundry Portal or ARM template to roll back:
 
 **Option 2: Use an Azure Bicep template**
 
-To rollback, convert your template configuration back to 'OpenAI' as kind.
+To roll back, convert your template configuration back to 'OpenAI' as kind.
 
   ```bicep
   resource aiFoundry 'Microsoft.CognitiveServices/accounts@2025-06-01' = {
@@ -185,22 +205,24 @@ To rollback, convert your template configuration back to 'OpenAI' as kind.
   }
   ```
 
-  Run the template using Azure CLI options or your VS Code extension for Bicep as a patch operation on your current resource.
+  Run the template using [Azure Bicep CLI](/azure/azure-resource-manager/bicep/bicep-cli) or your [Visual Studio Code extension for Bicep](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep) as a patch operation on your current resource.
+
 
 ---
 
 ## Troubleshooting Common Issues
 
-Azure resource limits and organizational configurations may require additional steps to complete the upgrade. The table below outlines some of the most common issues along with recommended solutions to help troubleshooting.
+Azure resource limits and organizational configurations may require extra steps to complete the upgrade. The table below outlines some of the most common issues along with recommended solutions to help troubleshooting.
 
 |Issue|Solution/mitigation|
 |---|---|
-|User principal lacks account/write permissions|Obtain a privileged Azure RBAC role to manage top-level Azure resources e.g. Owner, Contributor, Azure AI Administrator.| 
-|Managed identity is not enabled on the Azure OpenAI resource|Configure managed identity on your resource via templates or Azure portal.|
-|No permissions to create agents, while you are the owner/contributor on the resource.|An EntraID data plane role is required for development actions including agents. Examples include Azure AI User or Azure AI Project Manager role. Owner and Contributor roles only grant access to management operations in Azure such as managing deployments.|
+|User principal lacks account/write permissions|Obtain a privileged Azure RBAC role to manage top-level Azure resources, e.g. Owner, Contributor, Azure AI Administrator.| 
+|Managed identity isn't enabled on the Azure OpenAI resource|Configure managed identity on your resource via templates or Azure portal.|
+|No permissions to create agents, while you're the owner/contributor on the resource.|An EntraID data plane role is required for development actions including agents. Examples include Azure AI User or Azure AI Project Manager role. Owner and Contributor roles only grant access to management operations in Azure such as managing deployments.|
 |An Azure Policy conflict occurred.|Your organization may have put constraints on resource configurations. Inspect the details of the policy violation error. Then upgrade your resource via template options for further customization. For example, network configurations for Agents can only be configured via template options such as Azure Bicep.|
 |Exceeded number of Azure OpenAI instances of 30 per subscription per region when rolling back.|Delete an Azure OpenAI resource or upgrade it to the Azure AI Foundry. Then retry rolling back your current resource.|
 |Exceeded number of AIServices instances of 100 per subscription per region.|Delete an Azure AI Foundry resource you may not use in this subscription. Then retry upgrading your current resource.|
+|I can't access my resource over the private network|See [private networking configuration](#private-network-configuration) for the required steps.|
 
 ## How to inspect whether a resource has been upgraded