Merge pull request #6794 from jonburchel/2025-08-27-golden-paths-454639

2025 08 27 Golden Paths Plan Phase | Substep First run experience - DevOps 454639

Author: JillGrant615

articles/ai-foundry/how-to/set-up-key-vault-connection.md

@@ -0,0 +1,136 @@
+---
+title: Set Up Azure Key Vault Connection in AI Foundry
+description: Learn how to securely connect your Azure Key Vault to AI Foundry. Follow step-by-step instructions to manage secrets and ensure seamless integration.
+author: jonburchel
+ms.author: jburchel
+ms.reviewer: andyaviles
+ms.date: 08/27/2025
+ms.topic: how-to
+ms.service: azure-ai-foundry
+ai.usage: ai-assisted
+zone_pivot_groups: set-up-key-vault
+---
+
+# Set up a Key Vault connection in Azure AI Foundry
+
+Azure Key Vault is a service for securely storing and accessing secrets.
+If you don't create a Key Vault connection, Azure AI Foundry stores connection details in a Microsoft-managed Azure Key Vault. The managed Key Vault doesn't appear in your Azure subscription. If you prefer to manage
+secrets, connect your own Azure Key Vault.
+
+> [!NOTE]
+> Review limitations before you set up your Key Vault connection.
+
+## Limitations
+
+Create Azure Key Vault connections only when needed.
+
+If you bring your own Azure Key Vault, review these limitations:
+
+- One Azure Key Vault connection per AI Foundry resource is allowed.  Delete an Azure Key Vault connection only if no other connections exist at the AI Foundry resource or project level. AI Foundry doesn't support secret migration, so remove and recreate connections yourself.
+- Deleting the underlying Azure Key Vault breaks the AI Foundry resource. Key Vault stores secrets for connections that don't use Entra ID, so any AI Foundry feature that depends on those connections stops working.
+- Deleting the AI Foundry resource's connection secrets stored in your bring-your-own (BYO) Azure Key Vault can break connections to other services. It may break connections to other services.
+
+::: zone pivot="ai-foundry-portal"
+
+## Create an Azure Key Vault connection
+
+Follow these steps to create a new connection to Azure Key Vault.
+
+1. Go to your project in the Azure AI Foundry portal. If you don't have a project, create a new project.
+
+1. Make sure no connections exist in the **Resource** or **Project** sections. If any exist, **Azure Key Vault** isn't available as an option.
+
+1. In the **Resource** section, select **Connected resources**.
+
+1. In the **Connected resources** section, select **+ New connection**.
+
+   :::image type="content" source="../media/setup-key-vault-connection/select-azure-key-vault.jpeg" alt-text="Screenshot of the Connected resources section with the + New connection button selected, showing Azure Key Vault as an available option.":::
+
+1. Select **Azure Key Vault**.
+
+   :::image type="content" source="../media/setup-key-vault-connection/azure-key-vault-connection.jpeg" alt-text="Screenshot of the Azure Key Vault selection dialog with Azure Key Vault selected.":::
+
+1. Select your **Azure Key Vault**, and then select **Connect**.
+
+::: zone-end
+::: zone pivot="bicep"
+
+## Create a Key Vault connection
+
+<!-- Pull this content from the [foundry-samples repository (keyvaultconnection branch)](https://github.com/andyaviles121/foundry-samples/tree/keyvaultconnection) after it's merged.
+
+TBD - DO NOT PUBLISH WITHOUT UPDATING THIS WITH THE REAL CODE FOR THE SAMPLE.
+-->
+
+
+::: zone-end
+
+## Key Vault connection management
+
+### Creation
+
+Create a Key Vault connection only when it's the only connection.
+Make sure no other connections exist at the Foundry resource or project level.
+The service blocks Key Vault connection creation if other connections are present.
+If the UI doesn't show a Key Vault connection category when you choose a connection,
+this can be the reason. Delete other connections, and then try again.
+
+When you create a Key Vault connection, the managed Key Vault in Azure isn't used.
+
+### Deletion
+
+Before you delete an Azure Key Vault connection from AI Foundry, remove all other connections.
+After you remove all other connections at the Foundry resource and project levels,
+delete the Key Vault connection. Foundry doesn't support secret migration.
+
+### Update or change
+
+To switch from Azure Key Vault 1 to Azure Key Vault 2, delete the Azure Key Vault 1 connection, and then create the Azure Key Vault 2 connection. Follow the deletion and creation steps, and migrate any connection secrets.
+
+### Key Vault secret lifecycle
+
+When you delete connections from your managed Key Vault, the corresponding secrets are deleted.
+Deleting a Key Vault connection also deletes its secrets.
+
+### Granting AI Foundry access to your key vault
+
+Depending on how your key vault is provisioned, you might need to apply additional permissions.
+Check whether your Azure Key Vault uses role-based access control (RBAC) or access policies, and then continue.
+
+#### Role-based access control (RBAC)
+
+After you create the Key Vault connection, assign an appropriate RBAC role in the Azure portal. Key Vault Contributor or Key Vault Administrator are two roles that work. For minimal permissions, use the [Key Vault Secrets
+Officer](/azure/role-based-access-control/built-in-roles/security#key-vault-secrets-officer).
+
+#### Access policies
+
+Similar to RBAC roles, assign the appropriate key vault access policy (if applicable) to the Foundry resource's managed identity.
+
+## Infrastructure as code templates
+
+As a best practice, when setting up ARM, Bicep, or Terraform templates to create resources, make sure the Azure Key Vault connection is the first connection you create, and make all other connections depend on the Key Vault connection succeeding. This order helps reduce Key Vault connection failures. If you don't follow this best practice, your templates can encounter race conditions across your connections. As a result, deployments can work sometimes and fail at other times because Foundry doesn't support secret migration.
+
+After you create the Foundry resource and the Key Vault connection, assign the appropriate RBAC roles to the Foundry resource. Make all other connections depend on this role assignment succeeding. The same applies if your Key Vault uses access policies instead of RBAC.
+
+### Follow this order in your infrastructure as code templates
+
+1. Create the Foundry resource.
+1. Create a Foundry project.
+1. Create the Azure Key Vault connection.
+1. Assign the appropriate RBAC role on the Key Vault for the Foundry resource.
+1. (Optional) Validate that the RBAC role has taken effect.
+1. Create any other connections at the resource or project level, and set the `dependsOn` field for steps 3 and 4.
+
+#### Deletion
+
+For cleanup, if you automate resource deletion by using templates, follow the creation steps in reverse:
+
+1. Delete all connections at the Foundry resource or project level.
+1. Delete the Azure Key Vault connection.
+1. Delete all Foundry projects.
+1. Delete the Foundry resource.
+
+## Related content
+
+- [Azure Key Vault documentation](/azure/key-vault/)
+- [AI Foundry documentation](/azure/ai-foundry/) 

articles/ai-foundry/includes/first-run-experience.md

@@ -0,0 +1,61 @@
+---
+title: Include file
+description: Include file
+author: jonburchel
+ms.reviewer: jburchel
+ms.author: jburchel
+ms.service: azure-ai-foundry
+ms.topic: include
+ms.date: 08/27/2025
+ms.custom: include
+---
+## First run experience
+
+Use this fast path when you don't have any projects yet. Pick what you want to do and we create the project and get you into the right playground. It is suggested to start with an agent but you can also explore models through the Foundry portal or model catalog.
+
+# [Agent (_recommended_)](#tab/azure-ai-foundry)
+
+To start with an agent, use the following steps:
+
+1. In the top breadcrumb, select **Azure AI Foundry**, then select **Create an agent**.
+
+1. Enter a project name. Confirm your directory and subscription. Select **Create**.
+
+    :::image type="content" source="../media/quickstarts/create-agent.png" alt-text="Screenshot of Agents playground showing a default agent loaded with GPT-4o deployed. Chat interface and agent details panel are visible." lightbox="../media/quickstarts/create-agent.png":::
+
+1. When prompted, choose a model. We recommend **gpt-4o** for best quality, or **gpt-4o-mini** for lower cost.
+
+    :::image type="content" source="../media/quickstarts/agent-model-selection.png" alt-text="Screenshot showing the model selection dialog during agent deployment.":::
+
+1. Select **Deploy** on the final confirmation page after selecting a deployment type, and you see the Agents playground with your agent ready to chat.
+
+    :::image type="content" source="../media/quickstarts/deploy-agent-model.png" alt-text="Screenshot of Agents playground showing a default agent loaded with GPT-4o deployed. The chat interface and agent details panel are visible." lightbox="../media/quickstarts/deploy-agent-model.png":::
+
+1. You see the Agents playground with your agent ready to chat.
+
+    :::image type="content" source="../media/quickstarts/agents-playground.png" alt-text="Screenshot of the Agents playground using gpt-4o." lightbox="../media/quickstarts/agents-playground.png":::
+
+# [Model](#tab/azure-ai-foundry-model)
+
+In the portal, you can explore a rich catalog of cutting-edge models from Microsoft, OpenAI, DeepSeek, Hugging Face, Meta, and more. For this tutorial, search and then select the **gpt-4o** model. 
+
+1. From the [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs) or **[Model catalog](https://ai.azure.com/explore/models)**, select **gpt-4o** (or **gpt-4o-mini**).
+
+   :::image type="content" source="../media/quickstarts/start-building.png" alt-text="Screenshot shows how to start building an Agent in Azure AI Foundry portal.":::
+
+1. Select **Use this model**. When prompted, enter a project name and select **Create**.
+1. Review the deployment name and select **Create**.
+
+   :::image type="content" source="../media/quickstarts/create-foundry-model.png" alt-text="Screenshot showing how to create a model from the AI Foundry Model Catalog.":::
+
+1. Then select **Connect and deploy** after selecting a deployment type.
+
+   :::image type="content" source="../media/quickstarts/deploy-foundry-model.png" alt-text="Screenshot showing how to deploy a model from the AI Foundry model catalog.":::
+
+1. Select **Open in playground** from the deployment page after it's deployed.
+
+1. You land in the Chat playground with the model pre-deployed and ready to use.
+
+   :::image type="content" source="../media/quickstarts/model-chat-playground.png" alt-text="Screenshot showing the model chat playground after deploying an Azure AI Foundry model from the model catalog.":::
+
+---

articles/ai-foundry/includes/get-started-fdp.md

@@ -34,21 +34,7 @@ The Azure AI Foundry SDK is available in multiple languages, including Python, J
 
 [!INCLUDE [feature-preview](feature-preview.md)]
 
-## Start with a project and model
-
-1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs).
-1. In the portal, you can explore a rich catalog of cutting-edge models from Microsoft, OpenAI, DeepSeek, Hugging Face, Meta, and more. For this tutorial, search and then 
-select the **gpt-4o** model. 
-    
-   :::image type="content" source="../media/quickstarts/start-building.png" alt-text="Screenshot shows how to start building an Agent in Azure AI Foundry portal.":::
-
-   > [!NOTE]
-   > You can check out the [model catalog](https://ai.azure.com/explore/models) to confirm pricing on individual models.
-
-1. On the model details page, select **Use this model**.
-1. Fill in a name to use for your project and select **Create**. 
-1. Review the deployment information then select **Deploy**.
-1. Once your resources are created, you are in the chat playground. 
+[!INCLUDE [feature-preview](first-run-experience.md)]
 
 ## Set up your environment