fix: Add support for reusing existing Azure AI Foundry projects in deployment

docs/deploymentguide.md

@@ -192,42 +192,6 @@ Edit `infra/main.bicepparam` or set environment variables:
 # var fabricWorkspacePreset = 'none'
 ```
 
-#### Reusing an Existing Fabric Capacity and Workspace (BYO mode)
-
-If you already have a Fabric capacity and workspace, set `byo` mode so the deployment skips creating new ones. The bicepparam variables are driven by environment variables, so the recommended approach is to set them with `azd env set` before running `azd up`:
-
-**Step 1 — Set the mode** ( The default value is `create`, so override it to `byo`):
-
-```bicep
-// infra/main.bicepparam
-var fabricCapacityPreset = readEnvironmentVariable('fabricCapacityMode', 'create')
-```
-
-The `fabricCapacityMode` env variable controls both capacity and workspace preset (they are tied together). Set it explicitly to use BYO mode:
-
-```powershell
-azd env set fabricCapacityMode byo
-```
-
-**Step 2 — Supply the existing resource identifiers:**
-
-```powershell
-# ARM resource ID of the existing Fabric capacity
-azd env set fabricCapacityResourceId "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.Fabric/capacities/<capacity-name>"
-
-# GUID of the existing Fabric workspace (from the workspace URL or Fabric portal)
-azd env set FABRIC_WORKSPACE_ID "<workspace-guid>"
-
-# Display name of the existing workspace (used for naming/UX; optional but recommended)
-azd env set FABRIC_WORKSPACE_NAME "<workspace-display-name>"
-```
-
-> **How to find the workspace GUID:** Open the workspace in [app.fabric.microsoft.com](https://app.fabric.microsoft.com), copy the URL. The segment after `/groups/` is the workspace GUID (e.g., `https://app.fabric.microsoft.com/groups/e9c7ed61-0cdc-4356-a239-9d49cc755fe0/...` → `e9c7ed61-0cdc-4356-a239-9d49cc755fe0`).
-
-> **How to find the capacity resource ID:** In Azure Portal, open the Fabric capacity resource → **Properties** → copy **Resource ID**. It follows the pattern `/subscriptions/.../providers/Microsoft.Fabric/capacities/<name>`.
-
-After setting these variables, run `azd up` normally. The deployment will attach to your existing capacity and workspace instead of creating new ones.
-
 </details>
 
 <details>
@@ -240,6 +204,7 @@ After setting these variables, run `azd up` normally. The deployment will attach
 | `useExistingVNet` | Reuse an existing VNet | `false` |
 | `existingVnetResourceId` | Existing VNet resource ID (when `useExistingVNet=true`) | `` |
 | `existingLogAnalyticsWorkspaceResourceId` | Existing Log Analytics workspace to receive PostgreSQL diagnostics. May live in another subscription within the same tenant. | `` |
+| `existingAiProjectResourceId` | Existing Microsoft Foundry **project** resource ID to reuse instead of creating a new Foundry account + project. When set, `deployAiFoundry` and `deployAfProject` are auto-disabled. Read from `AZURE_EXISTING_AI_PROJECT_RESOURCE_ID`. | `` |
 | `vmUserName` | Jump box VM admin username | `VM_ADMIN_USERNAME` env var or `testvmuser` |
 | `vmAdminPassword` | Jump box VM admin password | `VM_ADMIN_PASSWORD` env var |
 
@@ -269,19 +234,11 @@ To check and adjust quota settings, follow the [Quota Check Guide](./quota_check
 <details>
   <summary><b>Reusing Existing Resources</b></summary>
 
-**Log Analytics Workspace (BYO observability):**
-
-By default the wrapper does not create a Log Analytics workspace or Application Insights, so the deployed Foundry application and wrapper-managed PostgreSQL Flexible Server have no telemetry sink. If you already have a centralized workspace, point the deployment at it:
-
-```powershell
-azd env set EXISTING_LOG_ANALYTICS_WORKSPACE_RESOURCE_ID "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.OperationalInsights/workspaces/<workspace-name>"
-```
-
-When set, the deployment will:
-1. Route PostgreSQL diagnostic logs and metrics to your workspace (when PostgreSQL is deployed by the wrapper).
-2. Create an Application Insights component in the deployment resource group, linked to your existing workspace — only when Application Insights deployment is enabled and the deployment is not creating a new Log Analytics workspace (i.e. `deployAppInsights = true` and `deployLogAnalytics = false`, which are the wrapper defaults).
+You can reuse existing Azure resources instead of provisioning new ones. Refer to the dedicated guides below:
 
-The workspace may live in a different resource group or subscription within the same tenant. The identity running `azd up` needs **`Microsoft.Insights/diagnosticSettings/write`** on the workspace itself (covered by the built-in **Log Analytics Contributor** role scoped to the workspace or its resource group — subscription-wide rights are not required). See the **Observability — Bring Your Own Log Analytics Workspace** section in the [Parameter Guide](./parameter_guide.md) for the full output reference (including App Insights values when that component is deployed) and notes on deployment-history exposure of those values.
+- [Reusing an Existing Azure AI Foundry Project](./re-use-foundry-project.md)
+- [Reusing an Existing Log Analytics Workspace](./re-use-log-analytics.md)
+- [Reusing an Existing Fabric Capacity and Workspace](./re-use-fabric-capacity.md)
 
 </details>
 

docs/parameter_guide.md

@@ -14,120 +14,6 @@ This guide focuses on configuration concepts for the **AI Landing Zone**.
 
 > **Deployment flow**: This repo deploys the AI Landing Zone submodule from `submodules/ai-landing-zone/main.bicep` during the preprovision hook. The single source of truth for parameters is `infra/main.bicepparam`.
 
-## Fabric Configuration
-
-### Modes: create, byo, none
-
-| Mode | Description |
-|------|-------------|
-| `create` | Provisions a new Fabric capacity (Bicep) and workspace (postprovision script) |
-| `byo` | Reuses an existing Fabric capacity and workspace — no new resources created |
-| `none` | Disables all Fabric automation; OneLake indexing will be skipped |
-
-Both capacity and workspace modes are controlled by the same `fabricCapacityMode` environment variable (they are tied together in `infra/main.bicepparam`).
-
-### Setting Mode via azd env
-
-The recommended way to configure Fabric mode is with `azd env set` — these values are read directly by `infra/main.bicepparam` at provision time:
-
-```powershell
-# Choose one:
-azd env set fabricCapacityMode create   # create new capacity + workspace (default if not set)
-azd env set fabricCapacityMode byo      # reuse existing capacity + workspace
-azd env set fabricCapacityMode none     # disable all Fabric automation
-```
-
-### Reusing Existing Fabric Resources (BYO)
-
-When `fabricCapacityMode` is `byo`, supply the identifiers of your existing resources:
-
-```powershell
-# ARM resource ID of the existing Fabric capacity
-azd env set fabricCapacityResourceId "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.Fabric/capacities/<capacity-name>"
-
-# GUID of the existing Fabric workspace (from the workspace URL)
-azd env set FABRIC_WORKSPACE_ID "<workspace-guid>"
-
-# Display name of the existing workspace (optional, used for naming/UX)
-azd env set FABRIC_WORKSPACE_NAME "<workspace-display-name>"
-```
-
-> **How to find the workspace GUID:** Open the workspace in [app.fabric.microsoft.com](https://app.fabric.microsoft.com). The URL segment after `/groups/` is the GUID (e.g., `https://app.fabric.microsoft.com/groups/e9c7ed61-0cdc-4356-a239-9d49cc755fe0/...`).
->
-> **How to find the capacity resource ID:** Azure Portal → Fabric capacity resource → **Properties** → **Resource ID**.
-
-You can also set these directly in `infra/main.bicepparam` if you prefer source-controlled values:
-
-```bicep
-// infra/main.bicepparam
-var fabricCapacityPreset = 'byo'
-param fabricCapacityResourceId = '/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.Fabric/capacities/<name>'
-param fabricWorkspaceId = '<workspace-guid>'
-param fabricWorkspaceName = '<workspace-display-name>'
-```
-
-> **Note:** Values set via `azd env set` take precedence over hardcoded bicepparam values because `readEnvironmentVariable(...)` is evaluated at deploy time.
-
-### Creating New Fabric Resources
-
-When `fabricCapacityMode` is `create`, you must provide at least one admin principal:
-
-```bicep
-// infra/main.bicepparam
-param fabricCapacityAdmins = ['user@contoso.com']
-param fabricCapacitySku = 'F2'  // adjust SKU as needed
-```
-
-> **Permission requirement:** The identity running `azd` must have the **Fabric Administrator** role (or Power BI tenant admin) to call the workspace admin APIs used during postprovision.
-
----
-
-## Observability — Bring Your Own Log Analytics Workspace
-
-By default the wrapper sets `deployLogAnalytics = false`, so the AI Landing Zone does not create a new Log Analytics workspace and Application Insights is not provisioned. If you already have a centralized Log Analytics workspace (for example one shared across the platform), you can wire the deployed Foundry application and the wrapper-managed PostgreSQL Flexible Server to it.
-
-### How it works
-
-When you set `existingLogAnalyticsWorkspaceResourceId`:
-
-1. An **Application Insights** component is created in the deployment resource group and linked to your existing workspace via `WorkspaceResourceId` — **only when `deployAppInsights = true` and `deployLogAnalytics = false`** (the wrapper defaults). Its name follows the same `appInsightsName` convention (`appi-<resourceToken>`).
-2. **PostgreSQL Flexible Server** diagnostic settings (all logs + AllMetrics) are routed to your workspace (only when PostgreSQL is deployed by the wrapper).
-3. The connection string and instrumentation key are exposed as deployment outputs (when the Application Insights component is created) so post-provision automation (or your application configuration) can pick them up.
-
-> **Note:** This is wrapper-side wiring. The upstream AI Landing Zone submodule does not natively support a BYO Log Analytics workspace, so leave `deployLogAnalytics = false` and `deployAppInsights = true` (the defaults) when using BYO so the LAZ does not create its own workspace + Application Insights pair.
-
-### Setting it via azd env
-
-```powershell
-azd env set EXISTING_LOG_ANALYTICS_WORKSPACE_RESOURCE_ID "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.OperationalInsights/workspaces/<workspace-name>"
-```
-
-Or set it directly in `infra/main.bicepparam`:
-
-```bicep
-param existingLogAnalyticsWorkspaceResourceId = '/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.OperationalInsights/workspaces/<workspace-name>'
-```
-
-### Outputs
-
-| Output | Description |
-|--------|-------------|
-| `existingLogAnalyticsWorkspaceResourceIdOut` | Echo of the supplied workspace resource ID |
-| `byoApplicationInsightsResourceId` | Resource ID of the App Insights component created against the BYO workspace |
-| `byoApplicationInsightsName` | Name of the App Insights component |
-| `byoApplicationInsightsConnectionString` | Connection string for app instrumentation |
-| `byoApplicationInsightsInstrumentationKey` | Instrumentation key for legacy SDKs |
-
-> **Sensitive outputs:** The connection string and instrumentation key are bootstrap credentials for sending telemetry to your Application Insights resource. They are emitted as deployment outputs so post-provision scripts and `azd` env can wire them into application configuration. Anyone with read access to the deployment history (subscription/RG `Microsoft.Resources/deployments/read`) can retrieve these values — keep that access scoped appropriately.
-
-### Permissions
-
-The identity running the deployment needs permission to attach diagnostic settings to the workspace and to create the Application Insights component:
-
-- **`Microsoft.Insights/diagnosticSettings/write`** on the BYO Log Analytics workspace (or its resource group). The built-in **Log Analytics Contributor** role on the workspace (or its RG) covers this — there is no need to grant subscription-wide rights.
-- **`Microsoft.Insights/components/write`** on the deployment resource group (covered by **Contributor** on the deployment RG, which the deployment identity already needs to provision the rest of the stack).
-- The PostgreSQL Flexible Server that emits diagnostics is wrapper-managed in the deployment RG, so no additional cross-resource permissions are required.
-
 ---
 
 ## Table of Contents

docs/re-use-fabric-capacity.md

@@ -0,0 +1,43 @@
+[← Back to *DEPLOYMENT* guide](/docs/deploymentguide.md#deployment-steps)
+
+# Reusing an Existing Fabric Capacity and Workspace (BYO mode)
+
+If you already have a Fabric capacity and workspace, set `byo` mode so the deployment skips creating new ones. The bicepparam variables are driven by environment variables, so the recommended approach is to set them with `azd env set` before running `azd up`:
+
+## Step 1 — Set the mode
+
+(The default value is `create`, so override it to `byo`):
+
+```bicep
+// infra/main.bicepparam
+var fabricCapacityPreset = readEnvironmentVariable('fabricCapacityMode', 'create')
+```
+
+The `fabricCapacityMode` env variable controls both capacity and workspace preset (they are tied together). Set it explicitly to use BYO mode:
+
+```powershell
+azd env set fabricCapacityMode byo
+```
+
+## Step 2 — Supply the existing resource identifiers
+
+```powershell
+# ARM resource ID of the existing Fabric capacity
+azd env set fabricCapacityResourceId "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.Fabric/capacities/<capacity-name>"
+
+# GUID of the existing Fabric workspace (from the workspace URL or Fabric portal)
+azd env set FABRIC_WORKSPACE_ID "<workspace-guid>"
+
+# Display name of the existing workspace (used for naming/UX; optional but recommended)
+azd env set FABRIC_WORKSPACE_NAME "<workspace-display-name>"
+```
+
+> **How to find the workspace GUID:** Open the workspace in [app.fabric.microsoft.com](https://app.fabric.microsoft.com), copy the URL. The segment after `/groups/` is the workspace GUID (e.g., `https://app.fabric.microsoft.com/groups/e9c7ed61-0cdc-4356-a239-9d49cc755fe0/...` → `e9c7ed61-0cdc-4356-a239-9d49cc755fe0`).
+
+> **How to find the capacity resource ID:** In Azure Portal, open the Fabric capacity resource → **Properties** → copy **Resource ID**. It follows the pattern `/subscriptions/.../providers/Microsoft.Fabric/capacities/<name>`.
+
+After setting these variables, run `azd up` normally. The deployment will attach to your existing capacity and workspace instead of creating new ones.
+
+---
+
+[← Back to *DEPLOYMENT* guide](/docs/deploymentguide.md#deployment-steps)

docs/re-use-foundry-project.md

@@ -0,0 +1,60 @@
+[← Back to *DEPLOYMENT* guide](/docs/deploymentguide.md#deployment-steps)
+
+# Reusing an Existing Azure AI Foundry Project
+
+To configure your environment to use an existing Azure AI Foundry Project, follow these steps:
+
+---
+
+### 1. Go to Azure Portal
+
+Go to https://portal.azure.com
+
+### 2. Search for Azure AI Foundry
+
+In the search bar at the top, type "Azure AI Foundry" and click on it. Then select the Foundry service instance where your project exists.
+
+![alt text](../docs/images/azure_ai_foundry_list.png)
+
+### 3. Navigate to Projects under Resource Management
+
+On the left sidebar of the Foundry service blade:
+
+- Expand the **Resource Management** section
+- Click on **Projects** (this refers to the active Foundry project tied to the service)
+
+### 4. Click on the Project
+
+From the Projects view: Click on the project name to open its details.
+
+> **Note:** You will see only one project listed here, as each Foundry service maps to a single project in this accelerator.
+
+![alt text](../docs/images/navigate_to_projects.png)
+
+### 5. Copy Resource ID
+
+In the left-hand menu of the project blade:
+
+- Click on **Properties** under **Resource Management**
+- Locate the **Resource ID** field
+- Click on the copy icon next to the Resource ID value
+
+![alt text](../docs/images/project_resource_id.png)
+
+### 6. Set the Foundry Project Resource ID in Your Environment
+
+Run the following command in your terminal:
+
+```bash
+azd env set AZURE_EXISTING_AI_PROJECT_RESOURCE_ID '<Existing Foundry Project Resource ID>'
+```
+
+Replace `<Existing Foundry Project Resource ID>` with the value obtained from Step 5.
+
+### 7. Continue Deployment
+
+Proceed with the next steps in the [deployment guide](/docs/deploymentguide.md#deployment-steps).
+
+---
+
+[← Back to *DEPLOYMENT* guide](/docs/deploymentguide.md#deployment-steps)

docs/re-use-log-analytics.md

@@ -0,0 +1,45 @@
+[← Back to *DEPLOYMENT* guide](/docs/deploymentguide.md#deployment-steps)
+
+# Reusing an Existing Log Analytics Workspace
+
+To configure your environment to use an existing Log Analytics Workspace, follow these steps:
+
+---
+
+### 1. Go to Azure Portal
+
+Go to https://portal.azure.com
+
+### 2. Search for Log Analytics
+
+In the search bar at the top, type "Log Analytics workspaces" and click on it, then click on the workspace you want to use.
+
+![alt text](../docs/images/re_use_log/logAnalyticsList.png)
+
+### 3. Copy Resource ID
+
+In the **Overview** pane, click on **JSON View**.
+
+![alt text](../docs/images/re_use_log/logAnalytics.png)
+
+Copy the **Resource ID** that is your Workspace ID.
+
+![alt text](../docs/images/re_use_log/logAnalyticsJson.png)
+
+### 4. Set the Workspace ID in Your Environment
+
+Run the following command in your terminal:
+
+```bash
+azd env set EXISTING_LOG_ANALYTICS_WORKSPACE_RESOURCE_ID '<Existing Log Analytics Workspace Resource ID>'
+```
+
+Replace `<Existing Log Analytics Workspace Resource ID>` with the value obtained from Step 3.
+
+### 5. Continue Deployment
+
+Proceed with the next steps in the [deployment guide](/docs/deploymentguide.md#deployment-steps).
+
+---
+
+[← Back to *DEPLOYMENT* guide](/docs/deploymentguide.md#deployment-steps)