diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index abb0cb4..6164933 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -1,448 +1,407 @@ -# Deployment Guide - Microsoft IQ Solution Accelerator +# Deployment Guide -Deploy the complete **Microsoft IQ Solution Accelerator** using Azure Developer CLI in minutes. This deployment provisions Fabric IQ (data platform) and Microsoft Foundry (intelligent agents) components. +Deploy the **Microsoft IQ Solution Accelerator** using Azure Developer CLI (`azd`) and the repo's automated deployment artifacts. This guide walks you through deploying the Fabric IQ, Foundry IQ, and Work IQ components. + +## Key Sections + +| Section | Description | +|---|---| +| [Overview](#overview) | High-level deployment architecture and workflow | +| [Step 1: Prerequisites & Setup](#step-1-prerequisites--setup) | Azure, Fabric, and software requirements | +| [Step 2: Choose Your Deployment Environment](#step-2-choose-your-deployment-environment) | Local, Codespaces, Dev Container, Cloud Shell, or GitHub Actions | +| [Step 3: Configure Deployment Settings (Optional)](#step-3-configure-deployment-settings-optional) | Customize deployment variables and reuse existing resources | +| [Step 4: Deploy the Solution](#step-4-deploy-the-solution) | Run `azd up` and validate deployment | +| [Step 5: Post-Deployment Configuration](#step-5-post-deployment-configuration) | Work IQ import and verification steps | +| [Step 6: Deployment Results](#step-6-deployment-results) | Verify Azure and Fabric resources | +| [Step 7: Clean Up (Optional)](#step-7-clean-up-optional) | Remove deployed resources safely | +| [Known Issues and Troubleshooting](#known-issues-and-troubleshooting) | Common errors and resolutions | +| [Next Steps](#next-steps) | Further guides and resources | +| [Need Help?](#need-help) | Support and repo guidance | --- -## Introduction - -The Microsoft IQ Solution Accelerator is an end-to-end data and AI platform that combines: - -- **Fabric IQ**: Data lakehouse, notebooks, semantic models, and data agents for unified data foundation -- **Microsoft Foundry**: Intelligent agents with knowledge base search for document-based question answering -- **Work IQ**: Copilot Studio email-triggered agent (deployed manually after `azd up`) that orchestrates Fabric IQ and Foundry IQ from a single conversational ingress — see [Post-Deployment Steps — Work IQ](#post-deployment-steps--work-iq) - -The `azd up` deployment is fully automated and idempotent, provisioning Fabric IQ and Microsoft Foundry. Work IQ is configured manually after `azd up` completes by importing the Power Platform zip solution file inside the [solution file folder](../src/copilot/sln). - -### Table of Contents - -1. [Prerequisites](#prerequisites) - - [Common requirements (all options)](#common-requirements-all-options) - - [Environment-specific tooling](#environment-specific-tooling) - - [Enable Ontology and required features in Fabric Admin Portal](#enable-ontology-and-required-features-in-fabric-admin-portal) -2. [Deployment Environment Setup](#deployment-environment-setup) -3. [Deployment Commands](#deployment-commands) -4. [Post-Deployment Steps — Work IQ](#post-deployment-steps--work-iq) -5. [Optional Configuration Variables](#optional-configuration-variables) -6. [Deployment Overview](#deployment-overview) - - [Infrastructure Provisioned](#infrastructure-provisioned) - - [Deployment Phases](#deployment-phases) -7. [Deployment Results](#deployment-results) - - [Azure Resources (Resource Group)](#azure-resources-resource-group) - - [Fabric IQ Components](#fabric-iq-components) - - [Microsoft Foundry Components](#microsoft-foundry-components) - - [Environment Variables](#environment-variables) - - [Next Steps](#next-steps) -8. [Environment Cleanup](#environment-cleanup) -9. [Additional Resources](#additional-resources) +## Overview + +The Microsoft IQ Solution Accelerator consists of three components: + +- **Foundry IQ** – Provisions Azure AI Foundry resources, including Agents, knowledge bases, and search indexes for intelligent document-based question answering. +- **Fabric IQ** – Deploys Fabric artifacts, including lakehouses, notebooks, semantic models, pipelines, and data agents for a unified data foundation. +- **Work IQ** – A Copilot Studio email-triggered agent that orchestrates Fabric IQ and Foundry IQ. It is deployed manually after `azd up` by importing the Power Platform solution from `src/copilot/sln`. + +The azd up deployment is fully automated, idempotent, and deploys both Foundry IQ and Fabric IQ. Work IQ is configured separately as a post-deployment step. --- -## Prerequisites -Before starting the deployment, ensure the following requirements are met. +## Step 1: Prerequisites & Setup + +Before starting the deployment, ensure the following prerequisites are met. + +### 1.1 Azure Account Requirements + +Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions: + +| Permission | Level | Purpose | +|-----------|-------|---------| +| **Contributor** | Subscription/Resource Group | Deploy Bicep templates and create Azure resources | +| **User Access Administrator** | Subscription/Resource Group | Configure role-based access control (RBAC) | +| **Resource Provider Registration** | Subscription | Register the required Azure resource providers: `Microsoft.Fabric`, `Microsoft.EventHub`, and `Microsoft.Storage`. | -### Common requirements (all options) -- An **Azure subscription** with permissions to create resources (Contributor + Role Based Access Control / User Access Administrator on the target subscription or resource group) -- **Microsoft Fabric** enabled on your subscription ([register provider](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-providers-and-types)) -- **Fabric Admin Portal** tenant settings enabled — see [Enable Ontology and required features in Fabric Admin Portal](#enable-ontology-and-required-features-in-fabric-admin-portal) below +### 1.2 Microsoft Fabric Requirements -### Environment-specific tooling +Your organization must have the following setup: -Install the tools matching the [Deployment Environment Setup](#deployment-environment-setup) option you plan to use: +| Requirement | Details | +|-------------|---------| +| **Fabric License** | [Microsoft Fabric](https://learn.microsoft.com/en-us/fabric/admin/fabric-switch) must be enabled in your organization | +| **Fabric Capacity** | Dedicated capacity available for your deployments (or deployment will create one) | +| **Workspace Creation** | Permissions to create new Fabric workspaces | +| **REST API Access** | If using Service Principals or Managed Identities, [enable the tenant setting](https://learn.microsoft.com/rest/api/fabric/articles/identity-support) for "Service principals and managed identities support on Fabric REST API" | -- **Option 1 · Local Deployment** — on your host machine: - - [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) (`azd`) - - [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) (`az`) - - [Python 3.9+](https://www.python.org/downloads/) - - [PowerShell 7+](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) — required because [`azure.yaml`](../azure.yaml) hooks invoke [`infra/scripts/utils/Run-PythonScript.ps1`](../infra/scripts/utils/Run-PythonScript.ps1) - - [Git](https://git-scm.com/downloads) -- **Option 2 · GitHub Codespaces** — zero local install; only a [GitHub account](https://github.com/join) with access to launch Codespaces is required. All tooling is pre-installed by [`.devcontainer/`](../.devcontainer/README.md). -- **Option 3 · Dev Container (VS Code + Docker Desktop)** — on your host machine: - - [Visual Studio Code](https://code.visualstudio.com/) - - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - - [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) - - [Git](https://git-scm.com/downloads) -- **Option 4 · GitHub Actions** — in your fork/repository: - - A Microsoft Entra ID **federated credential** configured for GitHub OIDC ([guide](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-config-app-trust-create#github-actions)) - - A GitHub environment named `miq-build` with secrets `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_SUBSCRIPTION_ID` +### 1.3 Fabric tenant settings -### Enable Ontology and required features in Fabric Admin Portal +Before deployment, enable these [Fabric tenant settings](https://learn.microsoft.com/en-us/fabric/iq/ontology/overview-tenant-settings) in the Fabric Admin Portal: -> **Fabric IQ must be enabled.** You must enable Ontology and related preview features in the Fabric Admin Portal before proceeding. +- **Ontology (preview)** +- **Graph (preview)** +- **Copilot and Azure OpenAI Service** -Follow these steps to enable the required tenant settings: +If Fabric Admin permissions are not available, ask your tenant administrator to enable these settings. Settings may take several minutes to propagate. -1. Navigate to the [Fabric Admin Portal](https://app.fabric.microsoft.com/admin-portal). +### 1.4 Identity options for deployment - > If you don't see the **Admin Portal** option, ensure you have **Fabric Admin** or **Global Admin** permissions on your tenant. +Choose the identity that best matches your deployment scenario: -2. In the left-hand navigation pane, select **Tenant settings**. +| Identity | Recommended for | +|----------|------------------| +| **User account** | Interactive deployments from your local machine or GitHub Codespaces. | +| **Service principal (federated identity)** | Automated CI/CD deployments using GitHub Actions with OpenID Connect (OIDC). | +| **Managed identity** | Azure-hosted deployment environments that support managed identities. | -3. **Enable Ontology (preview):** - - In the **Tenant settings** page, use the search bar at the top and search for **Ontology**. - - Locate the **Ontology (preview)** setting. - - Toggle the setting to **Enabled**. - - Choose whether to enable it for **The entire organization** or for **Specific security groups** based on your needs. - - Click **Apply**. +> [Note] +> For GitHub Actions, configure a Microsoft Entra ID federated credential and a GitHub environment with the required Azure credentials before running the workflow. -4. **Enable Graph (preview):** - - Search for **Graph** in the **Tenant settings** search bar. - - Locate the **Graph (preview)** setting. - - Toggle the setting to **Enabled**. - - Choose the appropriate scope (entire organization or specific security groups). - - Click **Apply**. +### 1.5 Software requirements -5. **Enable Copilot and Azure OpenAI Service:** - - Search for **Copilot** in the **Tenant settings** search bar. - - Locate the **Copilot and Azure OpenAI Service** setting. - - Toggle the setting to **Enabled**. - - Choose the appropriate scope. - - Click **Apply**. +**Note:** Skip this section if using GitHub Codespaces, VS Code Dev Container, or Azure Cloud Shell—all tools are pre-installed in these environments. -> **Propagation delay:** These settings may take up to **15 minutes** to take effect across your tenant. If you don't see the **Ontology** or **Data Agent** options in your workspace immediately, wait and refresh the page. +Install the following tools on your local machine: + +| Tool | Version | Installation | +|------|---------|--------------| +| **Python** | 3.9 or later | [Download from python.org](https://www.python.org/downloads/) | +| **Azure CLI** | Latest | [Install Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) | +| **Azure Developer CLI (azd)** | Latest | [Install azd](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) | +| **Bicep CLI** | 0.33.0 or later | [Install Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install) | +| **Git** | Latest | [Download from git-scm.com](https://git-scm.com/downloads) | -For detailed instructions, refer to the official documentation: [Fabric IQ Tenant Settings](https://learn.microsoft.com/en-us/fabric/iq/ontology/overview-tenant-settings). --- -## Deployment Environment Setup +## Step 2: Choose Your Deployment Environment + +Use the environment that best matches your workflow. + +| Environment | Setup Required | Notes | +|-------------|----------------|-------| +| **[GitHub Codespaces](#option-a-github-codespaces)** | GitHub account | Cloud development environment | +| **[Visual Studio Code Dev Container](#option-b-vs-code-dev-container)** | Docker Desktop + VS Code | Containerized consistency | +| **[Local Machine](#option-c-local-machine)** | Install [software requirements](#14-software-requirements) | Most flexible, requires local setup | +| **[GitHub Actions](#option-d-github-actions)** | Azure service principal | Federated identity, automated deployment | + +### Option A: GitHub Codespaces + +1. Go to the [Microsoft IQ Solution accelerator repository in GitHub Codespaces](https://github.com/codespaces/new/microsoft/microsoft-iq-solution-accelerator) +2. Follow the instructions on screen to create a new codespace with default setup. +3. Wait for the environment to initialize (2-3 minutes) +4.. All tools are pre-installed; proceed to [Step 4: Deploy](#step-4-deploy-the-solution) -You can deploy the accelerator from any of the four environments below. Each option leads to the common [Deployment Commands](#deployment-commands). Pick whichever fits your workflow, and make sure the matching tools are installed per [Prerequisites → Environment-specific tooling](#environment-specific-tooling). -
-Option 1 · Local Deployment — your own machine +### Option B: VS Code Dev Container -Use this option to run the deployment from your local shell. +**Consistent development environment using Docker.** + +1. Install [Visual Studio Code](https://code.visualstudio.com/) +2. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) +3. Install [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VS Code +4. Clone the repository: -1. Ensure the **Option 1** tools from [Prerequisites → Environment-specific tooling](#environment-specific-tooling) are installed on your host. -2. **Clone the repository** and `cd` into it: ```bash git clone https://github.com/microsoft/microsoft-iq-solution-accelerator.git cd microsoft-iq-solution-accelerator ``` -3. Continue with the [Deployment Commands](#deployment-commands) below. -
+5. Open the folder in VS Code +6. Click "Reopen in Container" when prompted +7. All tools are pre-installed; proceed to [Step 4: Deploy](#step-4-deploy-the-solution) -
-Option 2 · GitHub Codespaces — zero-install browser environment -[GitHub Codespaces](https://github.com/features/codespaces) provisions a cloud dev container that already contains every tool needed by the accelerator (defined in [`.devcontainer/`](../.devcontainer/README.md)). +### Option C: Local Machine -[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/microsoft-iq-solution-accelerator) +1. Install the software requirements from [Step 1.4](#15-software-requirements). +2. Clone the repository: -1. Click the **Open in GitHub Codespaces** badge above (or use **Code → Codespaces → Create codespace** on the repository page) to launch a codespace on the default branch. To target a fork or branch, replace `microsoft/microsoft-iq-solution-accelerator` in the URL with `/` and append `?ref=` if needed. -2. Wait for the codespace to finish building. The `postCreateCommand` runs [`post-create.sh`](../.devcontainer/post-create.sh) and [`setup_env.sh`](../.devcontainer/setup_env.sh) automatically — they install Python deps, `msodbcsql18`, dev tooling, and helpful aliases. -3. Continue with the [Deployment Commands](#deployment-commands) below — the repository is already cloned at the working directory. If `azd auth login` opens a browser window that fails to redirect back to the codespace, use `azd auth login --use-device-code`. +```bash +git clone https://github.com/microsoft/microsoft-iq-solution-accelerator.git +cd microsoft-iq-solution-accelerator +``` -> See [`.devcontainer/README.md`](../.devcontainer/README.md) for the full list of pre-installed tools and extensions. +3. Continue to [Step 4: Deploy the Solution](#step-4-deploy-the-solution). -
+### Option D: GitHub Actions -
-Option 3 · Dev Container (VS Code + Docker Desktop) — local container, same image as Codespaces +**Automated deployment using GitHub Actions with OpenID Connect (OIDC).** -Run the same dev container locally for an isolated, reproducible environment without polluting your host. +1. Complete the [GitHub Actions prerequisites](#15-software-requirements), including: + - Configure a Microsoft Entra ID federated credential. + - Create the `miq-build` GitHub environment with the required Azure values. +2. (Optional) Update the workflow configuration (for example, `AZURE_LOCATION` or other deployment settings) in `.github/workflows/azure-dev.yml`. +3. Trigger the workflow by: + - Pushing changes to a branch that matches the workflow path filters, or + - Running the workflow manually from the **Actions** tab. +4. The workflow automatically authenticates to Azure using OIDC, validates the infrastructure, and runs `azd up` to deploy the solution. -1. Ensure the **Option 3** tools from [Prerequisites → Environment-specific tooling](#environment-specific-tooling) are installed on your host. -2. **Clone the repository** and open it in VS Code: - ```bash - git clone https://github.com/microsoft/microsoft-iq-solution-accelerator.git - code microsoft-iq-solution-accelerator - ``` -3. Run **Command Palette → *Dev Containers: Reopen in Container***. VS Code builds the image from [`.devcontainer/Dockerfile`](../.devcontainer/Dockerfile) and runs the post-create scripts. -4. Continue with the [Deployment Commands](#deployment-commands) below. Existing `azd` credentials from the host's `~/.azure` (or `%USERPROFILE%\.azure`) are bind-mounted into the container, so a previous `azd auth login` carries over. +> [!NOTE] +> You do not need to perform the manual deployment steps. The GitHub Actions workflow completes the deployment automatically. -> See [`.devcontainer/README.md`](../.devcontainer/README.md) for configuration details and troubleshooting. +--- -
+## Step 3: Configure Deployment Settings (Optional) -
-Option 4 · GitHub Actions — automated CI/CD deployment +Before deploying, optionally override defaults with `azd env set`. -The repository ships with [`.github/workflows/azure-dev.yml`](../.github/workflows/azure-dev.yml), which runs `azd up` end-to-end on `push` to a branch (and on `workflow_dispatch`) using **OIDC federated credentials** — no secrets stored. +### Common configuration variables -1. Ensure the **Option 4** items from [Prerequisites → Environment-specific tooling](#environment-specific-tooling) are configured (federated credential and the `miq-build` environment with secrets). See [`azd pipeline config`](https://learn.microsoft.com/azure/developer/azure-developer-cli/configure-devops-pipeline), which can configure the federated credential for you. -2. (Optional) Adjust `AZURE_LOCATION` in the workflow `env:` block (default `westus3`) and any `azd env set …` lines for SKU, region, or model overrides. -3. **Trigger** the workflow by pushing to a branch matching the `paths:` filters (`infra/**`, `src/**`, `.github/workflows/azure-dev.yml`) or by running it manually from the **Actions** tab. The workflow: - - Logs in via `azure/login@v2` and `azd auth login --federated-credential-provider github` - - Runs Bicep static analysis and validation - - Executes `azd up --no-prompt` (which itself triggers Phase 2) +```bash +azd env set FABRIC_CAPACITY_SKU_NAME F4 +# REQUIRED: set the AI deployment region to your preferred Azure region (no default) +# Example: azd env set AZURE_AI_DEPLOYMENTS_LOCATION eastus +azd env set AZURE_AI_DEPLOYMENTS_LOCATION +azd env set AZURE_OPENAI_DEPLOYMENT_MODEL gpt-5-mini +azd env set AZURE_OPENAI_MODEL_VERSION 2025-04-14 +azd env set AZURE_OPENAI_EMBEDDING_MODEL text-embedding-3-small +azd env set AZURE_SEARCH_SERVICE_LOCATION eastus +``` -> The same six post-provision steps described above run inside the workflow. You do **not** need to run the [Deployment Commands](#deployment-commands) section manually for this option — the workflow performs them on your behalf. +### Fabric workspace configuration -
+```bash +azd env set FABRIC_WORKSPACE_NAME "My IQ Workspace" +azd env set FABRIC_WORKSPACE_ADMINISTRATORS "user@contoso.com,11111111-2222-3333-444444444444" +``` ---- +### Reuse existing resources -## Deployment Commands +If you already have existing resources in your tenant, set one or more of these: -> For fine-grained tuning of the deployment (Fabric capacity SKU, workspace name, AI deployment region, model selection, existing-resource reuse, etc.), set any of the variables documented in [Optional Configuration Variables](#optional-configuration-variables) **before** running `azd up`. +```bash +azd env set AZURE_EXISTING_FABRIC_CAPACITY_NAME "my-existing-fabric-capacity" +azd env set FABRIC_WORKSPACE_NAME "My Existing Workspace" +azd env set AZURE_SEARCH_SERVICE_LOCATION "eastus" +``` -### Deploy +> Note: The accelerator can reuse existing Fabric capacity or workspace resources if they already exist. -Run the following commands in a single bash session: +### Work IQ / Copilot configuration + +This repository includes the Work IQ solution in `src/copilot/sln`. `azd up` deploys the Fabric IQ and Foundry components, but Work IQ requires manual import after deployment. + +### Configuration summary + +- `FABRIC_CAPACITY_SKU_NAME` — Fabric capacity SKU. +- `AZURE_AI_DEPLOYMENTS_LOCATION` — Azure AI deployment region. +- `AZURE_OPENAI_DEPLOYMENT_MODEL` — OpenAI GPT deployment model. +- `AZURE_OPENAI_EMBEDDING_MODEL` — Embedding model. +- `FABRIC_WORKSPACE_NAME` — Fabric workspace name. +- `FABRIC_WORKSPACE_ADMINISTRATORS` — Additional workspace admins. +- `AZURE_EXISTING_FABRIC_CAPACITY_NAME` — Reuse capacity. + +--- + +## Step 4: Deploy the Solution + +### 4.1 Authenticate ```bash -# Authenticate with Azure Developer CLI azd auth login - -# Authenticate with Azure CLI az login +``` -# (Optional) Override defaults — Fabric SKU, AI region, model selection, etc. -# See the "Optional Configuration Variables" section below for the full list. -# azd env set FABRIC_CAPACITY_SKU_NAME F4 -# azd env set AZURE_AI_DEPLOYMENTS_LOCATION eastus +If you are deploying to a specific tenant, use `--tenant-id` with `azd auth login`. -# Deploy the solution -azd up +### 4.2 Set environment variables (optional) -# (Optional) View all deployment outputs -azd env get-values -``` +If you want to customize the deployment, set values before running `azd up`. -The entire deployment typically completes in **10–15 minutes**. +```bash +azd env set FABRIC_CAPACITY_SKU_NAME F4 +## REQUIRED: set `AZURE_AI_DEPLOYMENTS_LOCATION` to your preferred region (no default) +# Example: azd env set AZURE_AI_DEPLOYMENTS_LOCATION eastus +azd env set AZURE_AI_DEPLOYMENTS_LOCATION +azd env set FABRIC_WORKSPACE_NAME "My IQ Workspace" +``` -### Re-running Deployment +### 4.3 Run deployment -The deployment is **idempotent** and safe to re-run: ```bash azd up ``` -- Existing resources are updated (not recreated) -- Fabric workspace content is refreshed to latest version -- New administrators can be added without affecting existing ones +The deployment will prompt for: ---- +1. Environment name +2. Azure subscription +3. Azure resource group -## Post-Deployment Steps — Work IQ +The deployment typically completes in **10–15 minutes**. -The `azd up` workflow provisions **Fabric IQ** and **Microsoft Foundry**. The third component of the accelerator — **Work IQ** (the Copilot Studio email-triggered agent that orchestrates Fabric IQ and Foundry IQ from a single conversational ingress) — is deployed **manually after `azd up` completes successfully**. +### 4.4 Verify deployment outputs -Work IQ ships as a Power Platform zip solution file inside the [solution file folder](../src/copilot/sln). Follow the dedicated guide for the full step-by-step procedure: +After deployment completes, run: -> 👉 **[Copilot Studio Integration — Deployment Guide](./copilot/DeploymentGuide.md)** +```bash +azd env get-values +``` -Summary of the manual steps it covers: +This displays key outputs such as the Azure resource group, Fabric workspace name, and Foundry endpoint values. -1. **Import the solution** Import the Power Platform zip solution file inside the [solution file folder](../src/copilot/sln) into your Power Platform environment -2. **Configure connections** — sign in to and authorize the Work IQ, Microsoft Teams, Copilot Studio, Office 365 Outlook, Fabric Data Agent, and Foundry Agent connections. The Foundry Agent connection uses the `AZURE_AI_AGENT_ENDPOINT` value emitted by `azd env get-values`. -3. **Configure the email trigger** in the Power Automate flow — select the target inbox/folder to monitor and (optionally) add a subject filter such as `IQ Request`. -4. **Publish the agent** in [Copilot Studio](https://copilotstudio.microsoft.com) and enable the **Microsoft Teams** channel. +### 4.5 Re-run deployment -For an architecture overview of how Work IQ orchestrates Fabric IQ and Foundry IQ, see [`docs/copilot/README.md`](./copilot/README.md). For end-to-end QA, see the [Copilot Studio Testing Guide](./copilot/TestingGuide.md). +The deployment is idempotent. Rerun with: + +```bash +azd up +``` + +Existing resources are updated instead of recreated. --- -## Optional Configuration Variables +## Step 5: Post-Deployment Configuration -Customize your deployment by setting `azd` environment variables before running `azd up`. Use `azd env set ` to configure any of the following: +`azd up` provisions Fabric IQ and Microsoft Foundry components. After successful deployment, complete the Work IQ integration manually. -| Category | Variable | Description | Default | Example | -|----------|----------|-------------|---------|---------| -| **Common** | `ENABLE_TELEMETRY` | Enable/disable usage telemetry | `true` | `azd env set ENABLE_TELEMETRY false` | -| **Fabric Capacity** | `FABRIC_CAPACITY_SKU_NAME` | Fabric capacity SKU | `F2` | `azd env set FABRIC_CAPACITY_SKU_NAME F4` | -| | `AZURE_EXISTING_FABRIC_CAPACITY_NAME` | Use an existing Fabric capacity (skips creation) | _(empty)_ | `azd env set AZURE_EXISTING_FABRIC_CAPACITY_NAME "my-capacity"` | -| | `FABRIC_ADMIN_MEMBERS` | Additional Fabric capacity admins (JSON array of UPNs or object IDs) | `[]` | `azd env set FABRIC_ADMIN_MEMBERS '["user@contoso.com"]'` | -| **Fabric Workspace** | `FABRIC_WORKSPACE_NAME` | Override the default Fabric workspace name | `Microsoft IQ - {suffix}` | `azd env set FABRIC_WORKSPACE_NAME "My Workspace"` | -| | `FABRIC_WORKSPACE_ADMINISTRATORS` | Comma-separated additional workspace admins (UPNs and/or object IDs) | _(empty)_ | `azd env set FABRIC_WORKSPACE_ADMINISTRATORS "user@contoso.com,11111111-2222-3333-4444-555555555555"` | -| **Microsoft Foundry** | `AZURE_AI_DEPLOYMENTS_LOCATION` | AI deployment region (**required**) | _(prompted)_ | `azd env set AZURE_AI_DEPLOYMENTS_LOCATION eastus` | -| | `AZURE_OPENAI_DEPLOYMENT_MODEL` | GPT model to deploy | `gpt-5-mini` | `azd env set AZURE_OPENAI_DEPLOYMENT_MODEL gpt-4o` | -| | `AZURE_OPENAI_MODEL_VERSION` | GPT model version | `2025-04-14` | `azd env set AZURE_OPENAI_MODEL_VERSION 2025-04-14` | -| | `AZURE_OPENAI_DEPLOYMENT_MODEL_CAPACITY` | GPT capacity (tokens/min in thousands) | `150` | `azd env set AZURE_OPENAI_DEPLOYMENT_MODEL_CAPACITY 200` | -| | `AZURE_OPENAI_MODEL_DEPLOYMENT_TYPE` | GPT deployment type | `GlobalStandard` | `azd env set AZURE_OPENAI_MODEL_DEPLOYMENT_TYPE Standard` | -| | `AZURE_OPENAI_EMBEDDING_MODEL` | Embedding model to deploy | `text-embedding-3-small` | `azd env set AZURE_OPENAI_EMBEDDING_MODEL text-embedding-3-small` | -| | `AZURE_OPENAI_EMBEDDING_CAPACITY` | Embedding capacity (tokens/min in thousands) | `80` | `azd env set AZURE_OPENAI_EMBEDDING_CAPACITY 120` | -| | `AZURE_SEARCH_SERVICE_LOCATION` | Azure AI Search service location | Same as `AZURE_LOCATION` | `azd env set AZURE_SEARCH_SERVICE_LOCATION eastus` | -| | `AZURE_ENV_USE_CASE` | Industry use case scenario | `Retail-sales-analysis` | `azd env set AZURE_ENV_USE_CASE Insurance-improve-customer-meetings` | -| | `AZURE_EXISTING_LOG_ANALYTICS_WORKSPACE_ID` | Use an existing Log Analytics workspace | _(empty)_ | `azd env set AZURE_EXISTING_LOG_ANALYTICS_WORKSPACE_ID "/subscriptions/..."` | -| | `AZURE_EXISTING_AI_PROJECT_RESOURCE_ID` | Use an existing AI Foundry project | _(empty)_ | `azd env set AZURE_EXISTING_AI_PROJECT_RESOURCE_ID "/subscriptions/..."` | -| | `DEPLOYING_USER_PRINCIPAL_TYPE` | Deploying principal type (use `ServicePrincipal` for CI/CD with OIDC) | `User` | `azd env set DEPLOYING_USER_PRINCIPAL_TYPE ServicePrincipal` | +### 5.1 Import Work IQ solution -**Available Fabric SKUs**: `F2`, `F4`, `F8`, `F16`, `F32`, `F64`, `F128`, `F256`, `F512`, `F1024`, `F2048` +1. Open Power Platform and import the solution ZIP from `src/copilot/sln`. +2. Configure the required connections for Copilot Studio, Microsoft Teams, Outlook, Fabric Data Agent, and Foundry Agent. +3. Use the `AZURE_AI_AGENT_ENDPOINT` and other output values from `azd env get-values` when configuring connections. +4. Publish the agent in Copilot Studio. -**Available AI Deployment Regions**: `australiaeast`, `eastus`, `eastus2`, `francecentral`, `japaneast`, `swedencentral`, `uksouth`, `westus`, `westus3` +For a step-by-step guide, see `docs/copilot/DeploymentGuide.md`. -**Available Use Cases**: `Retail-sales-analysis`, `Insurance-improve-customer-meetings` +### 5.2 Validate Fabric IQ and Foundry -**Available Deployment Types**: `GlobalStandard`, `Standard` +Verify: ---- +- Fabric workspace and artifacts are present in `app.fabric.microsoft.com` +- Microsoft Foundry agent endpoints are available +- Data ingestion, search, and knowledge base components are configured -## Deployment Overview - -### Infrastructure Provisioned - -The deployment creates two integrated components in a single Azure Resource Group: - -#### 1. Fabric IQ Resources -- **[Fabric Capacity](https://learn.microsoft.com/fabric/enterprise/licenses)**: Compute engine (F2-F2048 SKU) powering data workloads -- **[Fabric Workspace](https://learn.microsoft.com/fabric/get-started/workspaces)**: Organized workspace containing: - - [Lakehouse](https://learn.microsoft.com/fabric/data-engineering/lakehouse-overview) with ingested sample data - - [Data processing notebooks](https://learn.microsoft.com/fabric/data-engineering/how-to-use-notebook) - - [Semantic models](https://learn.microsoft.com/fabric/data-warehouse/semantic-models) and [reports](https://learn.microsoft.com/power-bi/create-reports/service-report-create-new) - - [Ontology definitions](https://learn.microsoft.com/fabric/data-science/ontology) - - [Data agents](https://learn.microsoft.com/fabric/data-science/ai-services/data-agent-overview) - -#### 2. Microsoft Foundry Resources -- **[Microsoft Foundry Hub & Project](https://learn.microsoft.com/azure/ai-studio/concepts/ai-resources)**: Core AI platform for agent management -- **[Azure AI Search](https://learn.microsoft.com/azure/search/search-what-is-azure-search)**: Document indexing with [vector search](https://learn.microsoft.com/azure/search/vector-search-overview) and [knowledge base](https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-create-knowledge-base?tabs=rbac%2C2025-11-01-preview&pivots=csharp) -- **[Azure Storage Account](https://learn.microsoft.com/azure/storage/common/storage-account-overview)**: [Blob storage](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-overview) for documents with direct citations -- **[Azure OpenAI Models](https://learn.microsoft.com/azure/ai-services/openai/)**: - - [`gpt-5-mini`](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) - Chat completion (150K TPM) - - [`text-embedding-3-small`](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#embeddings) - Vector embeddings (80K TPM) -- **[Chat Agent](https://learn.microsoft.com/azure/ai-studio/how-to/develop/create-agent)**: Knowledge Base-powered agent for document Q&A - -### Deployment Phases - -The deployment follows a **two-phase automated workflow**, both phases triggered by a single `azd up` command: - -| # | Phase | Driver | Step / Resource | Description | -|---|---|---|---|---| -| — | **Phase 1: Infrastructure** | [`main.bicep`](../infra/main.bicep) (Bicep) | Fabric capacity & [managed identity](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) | Provision the [Fabric capacity](https://learn.microsoft.com/fabric/enterprise/licenses) and the user-assigned managed identity used by deployment scripts. | -| — | | | [Microsoft Foundry hub](https://learn.microsoft.com/azure/ai-studio/concepts/ai-resources), [project](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects) & [connections](https://learn.microsoft.com/azure/ai-studio/how-to/connections-add) | Create the Foundry hub/project and the AI Search + Storage connections. | -| — | | | AI Search service & Storage account | Provision the indexer + blob storage backing the knowledge base. | -| — | | | [OpenAI model deployments](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource) | Deploy the chat completion and embedding models. | -| 1 | **Phase 2: Solution Bootstrap** | [`install_microsoft_iq_solution.py`](../infra/scripts/install_microsoft_iq_solution.py) (Python, `postprovision` hook) | `setup_knowledge_base` ([`step_knowledge_base.py`](../infra/scripts/foundry/step_knowledge_base.py)) | Create the Azure AI Search index, upload PDFs from [`src/foundry/data/documents/`](../src/foundry/data/documents/), and provision the Foundry IQ knowledge source and knowledge base. | -| 2 | | | `setup_agent` ([`step_agent_setup.py`](../infra/scripts/foundry/step_agent_setup.py)) | Create the AI Foundry chat agent wired to the Knowledge Base via [MCP](https://modelcontextprotocol.io/introduction). **Best-effort**: transient platform errors are logged as warnings and the deployment continues. | -| 3 | | | `setup_workspace` ([`step_workspace_setup.py`](../infra/scripts/fabric/step_workspace_setup.py)) | Create or find the Fabric workspace, assign it to the capacity, and resume the capacity if paused. | -| 4 | | | `setup_administrators` ([`step_workspace_admins.py`](../infra/scripts/fabric/step_workspace_admins.py)) | Add [workspace administrators](https://learn.microsoft.com/fabric/get-started/roles-workspaces) using [Graph API](https://learn.microsoft.com/graph/overview) resolution with fallback. | -| 5 | | | `upload_installer` ([`step_notebook_installer.py`](../infra/scripts/fabric/step_notebook_installer.py)) | Upload [`fabric_solution_installer.ipynb`](../infra/fabric/deploy/fabric_solution_installer.ipynb), patched in-memory with the current git branch. | -| 6 | | | `run_installer` ([`step_notebook_installer.py`](../infra/scripts/fabric/step_notebook_installer.py)) | Execute the installer notebook as a Fabric job. The notebook uses [`fabric-launcher`](https://github.com/microsoft/fabric-launcher) to deploy items from [`src/fabric/fabric_workspace/`](../src/fabric/fabric_workspace/), then runs `pipeline_main` for data ingestion, deploys ontologies, and organizes folders. | +### 5.3 Optional verification + +- Open Fabric workspace and check the deployed Fabric IQ workspace components. +- Confirm Microsoft Foundry knowledge base and agent setup. +- Validate that the Work IQ Power Platform solution is published successfully. --- -## Deployment Results +## Step 6: Deployment Results -After successful deployment, you will have a single Azure Resource Group containing the resources below, plus a Fabric workspace populated by the installer notebook. +### Azure resources -### Azure Resources (Resource Group) +The deployment creates or reuses the following Azure resources: -| Component | Purpose | -|---|---| -| **Fabric Capacity** (`{solution_suffix}-fabric-capacity` or your existing capacity) | Compute backing the Fabric workspace. Resumed automatically if paused. | -| **User-assigned Managed Identity** | Identity used by deployment scripts and Foundry connections to call Azure AI Search and Storage without secrets. | -| **Microsoft Foundry Hub & Project** | Container for AI agents, model deployments, knowledge bases, and connections. | -| **Azure OpenAI deployments** | Two model deployments inside the Foundry project: a chat completion model (default `gpt-5-mini`) and an embedding model (default `text-embedding-3-small`). | -| **Azure AI Search** | Vector + keyword search service. Backs the Foundry knowledge base; index name `{solution_suffix}-documents`. | -| **Azure Storage Account** | Blob storage for source documents. Container `{solution_suffix}-documents` is uploaded to by `setup_knowledge_base` and referenced by AI Search citations. | -| **Log Analytics workspace + Application Insights** | Diagnostic and monitoring sink for the Foundry project, AI Search, and the chat agent. Reused if `AZURE_EXISTING_LOG_ANALYTICS_WORKSPACE_ID` is set. | -| **Foundry connections** | Project connections wiring Foundry to AI Search, Blob Storage, and the Knowledge Base MCP endpoint (`{solution_suffix}-kb-mcp-connection`). | +- Resource Group +- Fabric Capacity +- Azure AI/OpenAI deployment resources +- Azure Search service location +- Microsoft Foundry-related service endpoints -**Access in the Azure portal**: open [portal.azure.com](https://portal.azure.com) → **Resource groups** → select the group named after your `azd` environment (the value of `AZURE_RESOURCE_GROUP`, shown by `azd env get-values`). Use the resource list to navigate to any individual resource. Diagnostic logs are available under **Monitoring → Logs** on the Foundry project, AI Search, and Storage resources. +### Fabric IQ components -### Fabric IQ Components +The Fabric workspace contains: -The installer notebook deploys workspace items from [`src/fabric/fabric_workspace/`](../src/fabric/fabric_workspace/) into the Fabric workspace: +- Workspace +- Semantic models and datasets +- Data agent configuration artifacts +- Notebooks and environment definitions for Fabric IQ -``` -Microsoft IQ - {suffix} -├── 📊 Lakehouses -│ └── miqsadata (with sample data tables) -├── 📓 Notebooks -│ ├── pipeline_main (data ingestion orchestrator) -│ ├── pipeline_update (pipeline maintenance) -│ ├── data_processing/ (per-domain load notebooks) -│ ├── schema/ (per-domain table schemas) -│ └── … -├── 📈 Semantic Models & Reports -│ ├── RetailSupplyChainModel.SemanticModel -│ ├── Sales Overview.SemanticModel -│ ├── Sales Overview.Report -│ ├── Supply Chain Management.SemanticModel -│ └── Supply Chain Management.Report -├── 🧬 Ontologies -│ └── RetailSupplyChainOntologyModel -└── 🤖 Data Agents - └── RetailSC Ontology Agent -``` +### Microsoft Foundry components -Access your workspace: -- Open the [Microsoft Fabric portal](https://app.fabric.microsoft.com) and sign in with the same account used for `azd auth login`. -- Switch the experience to **Fabric Developer** (top-right) and select your workspace from the left sidebar (default name: `Microsoft IQ - {SOLUTION_SUFFIX}`). -- The lakehouse, notebooks, semantic models, ontologies, and data agents above appear under the workspace's items list — use the folder filters to narrow by type. -- Direct link template: `https://app.fabric.microsoft.com/groups/{workspace_id}?experience=fabric-developer` (the `workspace_id` is printed in the deployment summary and saved as `FABRIC_WORKSPACE_ID` in your `azd` environment). +The deployment also provisions: -### Microsoft Foundry Components +- Foundry agent service endpoints +- Knowledge base search integration +- Agent runtime configuration used by Work IQ -Sourced and named by [`install_microsoft_iq_solution.py`](../infra/scripts/install_microsoft_iq_solution.py) (steps `setup_knowledge_base` and `setup_agent`). +### Output values -| Component | Default name | Purpose | -|---|---|---| -| **Search Index** | `{solution_suffix}-documents` | Azure AI Search index containing chunked PDFs from [`src/foundry/data/documents/`](../src/foundry/data/documents/) with embeddings for hybrid (vector + keyword) retrieval. Override with `AZURE_AI_SEARCH_INDEX`. | -| **Knowledge Source** | `{solution_suffix}-ks` | Foundry IQ pointer to the AI Search index. | -| **Knowledge Base** | `{solution_suffix}-kb` | Foundry IQ knowledge base with automatic query planning over the knowledge source. Used by the agent for grounded answers with citations. | -| **KB MCP project connection** | `{solution_suffix}-kb-mcp-connection` | Foundry connection that exposes the Knowledge Base to the agent through the [Model Context Protocol](https://modelcontextprotocol.io/introduction). Override with `KB_MCP_CONNECTION_NAME`. | -| **Chat Agent** | `ChatAgent` | AI Foundry agent wired to the Knowledge Base via the MCP tool above. Answers questions with document citations. | +Important output values are available from `azd env get-values` and are used for: -#### Verify in the Foundry portal +- Copilot Studio connection setup +- Foundry agent endpoint configuration +- Fabric workspace access -Open [ai.azure.com](https://ai.azure.com) and sign in with the same account used for `azd auth login`. From the landing page, select your hub and then your project (the project name is stored as `AZURE_AI_PROJECT_NAME` in your `azd` environment; the endpoint is `AZURE_AI_AGENT_ENDPOINT`). Once inside the project, confirm: +--- -1. **Knowledge Bases** → `{solution_suffix}-kb` exists, status is *Ready*, and it lists `{solution_suffix}-ks` as its source. -2. **Agents** → an agent named `ChatAgent` exists, its model matches `AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME` / `AZURE_CHAT_MODEL` (default `gpt-5-mini`), and the **Tools** panel shows the `{solution_suffix}-kb-mcp-connection` MCP tool attached. -3. **Connections** → the AI Search, Blob Storage, and KB MCP connections are all *Connected*. +## Step 7: Clean Up (Optional) -> If `setup_agent` finished with a warning during deployment, this verification is the recommended way to check whether the agent was actually created. If `ChatAgent` is missing, simply re-run `azd up`. +When you no longer need the deployment, remove resources safely: -**Test the agent from the CLI**: ```bash -# From the repository root -python infra/scripts/foundry/test_agent.py +cd microsoft-iq-solution-accelerator +azd down --force --purge ``` -### Environment Variables +This command removes deployed Azure and Fabric resources created by the deployment while preserving your local source code. -All connection details are saved in your azd environment. View them with: -```bash -azd env get-values -``` +If `azd down` fails, remove the resource group manually from the Azure Portal. -Key outputs: -- `AZURE_AI_AGENT_ENDPOINT` — Microsoft Foundry agent endpoint -- `AZURE_AI_SEARCH_ENDPOINT` — Search service endpoint -- `AZURE_STORAGE_BLOB_ENDPOINT` — Document storage endpoint -- `AZURE_FABRIC_CAPACITY_NAME` — Fabric capacity name -- `SOLUTION_NAME` / `SOLUTION_SUFFIX` — Your solution identifier and suffix used in resource names +--- -### Next Steps +## Known Issues and Troubleshooting -1. **Add your documents**: drop PDFs into [`src/foundry/data/documents/`](../src/foundry/data/documents/) and re-run the deployment to refresh the knowledge base: - ```bash - azd up - ``` - This re-executes `setup_knowledge_base` (Step 1), which re-uploads PDFs to blob storage and re-indexes them. -2. **Explore the Fabric workspace**: open notebooks and run the data pipelines. -3. **Test the agent**: use the test script above, or chat with `ChatAgent` from the Foundry portal. -4. **View dashboards**: access the Power BI reports in the Fabric workspace. +### Fabric tenant access issues ---- +If the Fabric API returns a 403 or requests are denied by inbound policy, verify: -## Environment Cleanup +- Tenant Fabric settings are enabled +- Your account has access to the Fabric workspace +- Network or proxy restrictions are not blocking `api.fabric.microsoft.com` -To remove all deployed resources: +### Deployment permission issues -```bash -azd down -``` +If deployment fails due to authorization: + +- Confirm your identity has Contributor access on the target subscription or resource group +- Confirm service principal or federated identity is allowed to use Fabric REST API +- Ensure required Azure resource providers are registered + +### Work IQ import issues + +If manual Work IQ import fails: + +- Confirm Power Platform connectors are authorized +- Use the outputs from `azd env get-values` for endpoint configuration +- Verify the Copilot solution version in `src/copilot/sln` + +--- + +## Next Steps + +After deployment, explore these guides: -This command: -- Runs the `predown` hook ([`remove_microsoft_iq_solution.py`](../infra/scripts/remove_microsoft_iq_solution.py)) to delete the Fabric workspace -- Deletes the Azure Resource Group and all resources inside it (including the Fabric capacity) -- Preserves your local `.azure/{environment}` configuration unless you also pass `--purge` +- `docs/TechnicalArchitecture.md` +- `docs/FAQs.md` +- `docs/copilot/README.md` +- `docs/copilot/TestingGuide.md` --- -## Additional Resources +## Need Help? -- **Manual Fabric Notebook Deployment**: [DeploymentGuideFabricManual.md](./fabric/DeploymentGuideFabricManual.md) — Fabric workspace items only, no Azure infrastructure or Foundry. -- **Work IQ (Copilot Studio) Deployment**: [docs/copilot/DeploymentGuide.md](./copilot/DeploymentGuide.md) -- **Work IQ (Copilot Studio) Testing**: [docs/copilot/TestingGuide.md](./copilot/TestingGuide.md) -- **Azure Developer CLI Documentation**: [learn.microsoft.com/azure/developer/azure-developer-cli](https://learn.microsoft.com/azure/developer/azure-developer-cli/overview) -- **Microsoft Fabric Documentation**: [learn.microsoft.com/fabric](https://learn.microsoft.com/fabric/) -- **Microsoft Foundry Documentation**: [learn.microsoft.com/azure/foundry](https://learn.microsoft.com/azure/foundry/what-is-foundry) -- **GitHub Repository**: [microsoft/microsoft-iq-solution-accelerator](https://github.com/microsoft/microsoft-iq-solution-accelerator) \ No newline at end of file +- Open an issue in the repository if you encounter bugs. +- Review `CONTRIBUTING.md` for contribution guidance. +- See `SUPPORT.md` for support and escalation paths. diff --git a/docs/DeploymentGuide_v2.md b/docs/DeploymentGuide_v2.md new file mode 100644 index 0000000..6164933 --- /dev/null +++ b/docs/DeploymentGuide_v2.md @@ -0,0 +1,407 @@ +# Deployment Guide + +Deploy the **Microsoft IQ Solution Accelerator** using Azure Developer CLI (`azd`) and the repo's automated deployment artifacts. This guide walks you through deploying the Fabric IQ, Foundry IQ, and Work IQ components. + +## Key Sections + +| Section | Description | +|---|---| +| [Overview](#overview) | High-level deployment architecture and workflow | +| [Step 1: Prerequisites & Setup](#step-1-prerequisites--setup) | Azure, Fabric, and software requirements | +| [Step 2: Choose Your Deployment Environment](#step-2-choose-your-deployment-environment) | Local, Codespaces, Dev Container, Cloud Shell, or GitHub Actions | +| [Step 3: Configure Deployment Settings (Optional)](#step-3-configure-deployment-settings-optional) | Customize deployment variables and reuse existing resources | +| [Step 4: Deploy the Solution](#step-4-deploy-the-solution) | Run `azd up` and validate deployment | +| [Step 5: Post-Deployment Configuration](#step-5-post-deployment-configuration) | Work IQ import and verification steps | +| [Step 6: Deployment Results](#step-6-deployment-results) | Verify Azure and Fabric resources | +| [Step 7: Clean Up (Optional)](#step-7-clean-up-optional) | Remove deployed resources safely | +| [Known Issues and Troubleshooting](#known-issues-and-troubleshooting) | Common errors and resolutions | +| [Next Steps](#next-steps) | Further guides and resources | +| [Need Help?](#need-help) | Support and repo guidance | + +--- + +## Overview + +The Microsoft IQ Solution Accelerator consists of three components: + +- **Foundry IQ** – Provisions Azure AI Foundry resources, including Agents, knowledge bases, and search indexes for intelligent document-based question answering. +- **Fabric IQ** – Deploys Fabric artifacts, including lakehouses, notebooks, semantic models, pipelines, and data agents for a unified data foundation. +- **Work IQ** – A Copilot Studio email-triggered agent that orchestrates Fabric IQ and Foundry IQ. It is deployed manually after `azd up` by importing the Power Platform solution from `src/copilot/sln`. + +The azd up deployment is fully automated, idempotent, and deploys both Foundry IQ and Fabric IQ. Work IQ is configured separately as a post-deployment step. + +--- + + +## Step 1: Prerequisites & Setup + +Before starting the deployment, ensure the following prerequisites are met. + +### 1.1 Azure Account Requirements + +Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions: + +| Permission | Level | Purpose | +|-----------|-------|---------| +| **Contributor** | Subscription/Resource Group | Deploy Bicep templates and create Azure resources | +| **User Access Administrator** | Subscription/Resource Group | Configure role-based access control (RBAC) | +| **Resource Provider Registration** | Subscription | Register the required Azure resource providers: `Microsoft.Fabric`, `Microsoft.EventHub`, and `Microsoft.Storage`. | + + +### 1.2 Microsoft Fabric Requirements + +Your organization must have the following setup: + +| Requirement | Details | +|-------------|---------| +| **Fabric License** | [Microsoft Fabric](https://learn.microsoft.com/en-us/fabric/admin/fabric-switch) must be enabled in your organization | +| **Fabric Capacity** | Dedicated capacity available for your deployments (or deployment will create one) | +| **Workspace Creation** | Permissions to create new Fabric workspaces | +| **REST API Access** | If using Service Principals or Managed Identities, [enable the tenant setting](https://learn.microsoft.com/rest/api/fabric/articles/identity-support) for "Service principals and managed identities support on Fabric REST API" | + +### 1.3 Fabric tenant settings + +Before deployment, enable these [Fabric tenant settings](https://learn.microsoft.com/en-us/fabric/iq/ontology/overview-tenant-settings) in the Fabric Admin Portal: + +- **Ontology (preview)** +- **Graph (preview)** +- **Copilot and Azure OpenAI Service** + +If Fabric Admin permissions are not available, ask your tenant administrator to enable these settings. Settings may take several minutes to propagate. + +### 1.4 Identity options for deployment + +Choose the identity that best matches your deployment scenario: + +| Identity | Recommended for | +|----------|------------------| +| **User account** | Interactive deployments from your local machine or GitHub Codespaces. | +| **Service principal (federated identity)** | Automated CI/CD deployments using GitHub Actions with OpenID Connect (OIDC). | +| **Managed identity** | Azure-hosted deployment environments that support managed identities. | + +> [Note] +> For GitHub Actions, configure a Microsoft Entra ID federated credential and a GitHub environment with the required Azure credentials before running the workflow. + +### 1.5 Software requirements + +**Note:** Skip this section if using GitHub Codespaces, VS Code Dev Container, or Azure Cloud Shell—all tools are pre-installed in these environments. + +Install the following tools on your local machine: + +| Tool | Version | Installation | +|------|---------|--------------| +| **Python** | 3.9 or later | [Download from python.org](https://www.python.org/downloads/) | +| **Azure CLI** | Latest | [Install Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) | +| **Azure Developer CLI (azd)** | Latest | [Install azd](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) | +| **Bicep CLI** | 0.33.0 or later | [Install Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install) | +| **Git** | Latest | [Download from git-scm.com](https://git-scm.com/downloads) | + + +--- + +## Step 2: Choose Your Deployment Environment + +Use the environment that best matches your workflow. + +| Environment | Setup Required | Notes | +|-------------|----------------|-------| +| **[GitHub Codespaces](#option-a-github-codespaces)** | GitHub account | Cloud development environment | +| **[Visual Studio Code Dev Container](#option-b-vs-code-dev-container)** | Docker Desktop + VS Code | Containerized consistency | +| **[Local Machine](#option-c-local-machine)** | Install [software requirements](#14-software-requirements) | Most flexible, requires local setup | +| **[GitHub Actions](#option-d-github-actions)** | Azure service principal | Federated identity, automated deployment | + +### Option A: GitHub Codespaces + +1. Go to the [Microsoft IQ Solution accelerator repository in GitHub Codespaces](https://github.com/codespaces/new/microsoft/microsoft-iq-solution-accelerator) +2. Follow the instructions on screen to create a new codespace with default setup. +3. Wait for the environment to initialize (2-3 minutes) +4.. All tools are pre-installed; proceed to [Step 4: Deploy](#step-4-deploy-the-solution) + + +### Option B: VS Code Dev Container + +**Consistent development environment using Docker.** + +1. Install [Visual Studio Code](https://code.visualstudio.com/) +2. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) +3. Install [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VS Code +4. Clone the repository: + + ```bash + git clone https://github.com/microsoft/microsoft-iq-solution-accelerator.git + cd microsoft-iq-solution-accelerator + ``` + +5. Open the folder in VS Code +6. Click "Reopen in Container" when prompted +7. All tools are pre-installed; proceed to [Step 4: Deploy](#step-4-deploy-the-solution) + + +### Option C: Local Machine + +1. Install the software requirements from [Step 1.4](#15-software-requirements). +2. Clone the repository: + +```bash +git clone https://github.com/microsoft/microsoft-iq-solution-accelerator.git +cd microsoft-iq-solution-accelerator +``` + +3. Continue to [Step 4: Deploy the Solution](#step-4-deploy-the-solution). + +### Option D: GitHub Actions + +**Automated deployment using GitHub Actions with OpenID Connect (OIDC).** + +1. Complete the [GitHub Actions prerequisites](#15-software-requirements), including: + - Configure a Microsoft Entra ID federated credential. + - Create the `miq-build` GitHub environment with the required Azure values. +2. (Optional) Update the workflow configuration (for example, `AZURE_LOCATION` or other deployment settings) in `.github/workflows/azure-dev.yml`. +3. Trigger the workflow by: + - Pushing changes to a branch that matches the workflow path filters, or + - Running the workflow manually from the **Actions** tab. +4. The workflow automatically authenticates to Azure using OIDC, validates the infrastructure, and runs `azd up` to deploy the solution. + +> [!NOTE] +> You do not need to perform the manual deployment steps. The GitHub Actions workflow completes the deployment automatically. + +--- + +## Step 3: Configure Deployment Settings (Optional) + +Before deploying, optionally override defaults with `azd env set`. + +### Common configuration variables + +```bash +azd env set FABRIC_CAPACITY_SKU_NAME F4 +# REQUIRED: set the AI deployment region to your preferred Azure region (no default) +# Example: azd env set AZURE_AI_DEPLOYMENTS_LOCATION eastus +azd env set AZURE_AI_DEPLOYMENTS_LOCATION +azd env set AZURE_OPENAI_DEPLOYMENT_MODEL gpt-5-mini +azd env set AZURE_OPENAI_MODEL_VERSION 2025-04-14 +azd env set AZURE_OPENAI_EMBEDDING_MODEL text-embedding-3-small +azd env set AZURE_SEARCH_SERVICE_LOCATION eastus +``` + +### Fabric workspace configuration + +```bash +azd env set FABRIC_WORKSPACE_NAME "My IQ Workspace" +azd env set FABRIC_WORKSPACE_ADMINISTRATORS "user@contoso.com,11111111-2222-3333-444444444444" +``` + +### Reuse existing resources + +If you already have existing resources in your tenant, set one or more of these: + +```bash +azd env set AZURE_EXISTING_FABRIC_CAPACITY_NAME "my-existing-fabric-capacity" +azd env set FABRIC_WORKSPACE_NAME "My Existing Workspace" +azd env set AZURE_SEARCH_SERVICE_LOCATION "eastus" +``` + +> Note: The accelerator can reuse existing Fabric capacity or workspace resources if they already exist. + +### Work IQ / Copilot configuration + +This repository includes the Work IQ solution in `src/copilot/sln`. `azd up` deploys the Fabric IQ and Foundry components, but Work IQ requires manual import after deployment. + +### Configuration summary + +- `FABRIC_CAPACITY_SKU_NAME` — Fabric capacity SKU. +- `AZURE_AI_DEPLOYMENTS_LOCATION` — Azure AI deployment region. +- `AZURE_OPENAI_DEPLOYMENT_MODEL` — OpenAI GPT deployment model. +- `AZURE_OPENAI_EMBEDDING_MODEL` — Embedding model. +- `FABRIC_WORKSPACE_NAME` — Fabric workspace name. +- `FABRIC_WORKSPACE_ADMINISTRATORS` — Additional workspace admins. +- `AZURE_EXISTING_FABRIC_CAPACITY_NAME` — Reuse capacity. + +--- + +## Step 4: Deploy the Solution + +### 4.1 Authenticate + +```bash +azd auth login +az login +``` + +If you are deploying to a specific tenant, use `--tenant-id` with `azd auth login`. + +### 4.2 Set environment variables (optional) + +If you want to customize the deployment, set values before running `azd up`. + +```bash +azd env set FABRIC_CAPACITY_SKU_NAME F4 +## REQUIRED: set `AZURE_AI_DEPLOYMENTS_LOCATION` to your preferred region (no default) +# Example: azd env set AZURE_AI_DEPLOYMENTS_LOCATION eastus +azd env set AZURE_AI_DEPLOYMENTS_LOCATION +azd env set FABRIC_WORKSPACE_NAME "My IQ Workspace" +``` + +### 4.3 Run deployment + +```bash +azd up +``` + +The deployment will prompt for: + +1. Environment name +2. Azure subscription +3. Azure resource group + +The deployment typically completes in **10–15 minutes**. + +### 4.4 Verify deployment outputs + +After deployment completes, run: + +```bash +azd env get-values +``` + +This displays key outputs such as the Azure resource group, Fabric workspace name, and Foundry endpoint values. + +### 4.5 Re-run deployment + +The deployment is idempotent. Rerun with: + +```bash +azd up +``` + +Existing resources are updated instead of recreated. + +--- + +## Step 5: Post-Deployment Configuration + +`azd up` provisions Fabric IQ and Microsoft Foundry components. After successful deployment, complete the Work IQ integration manually. + +### 5.1 Import Work IQ solution + +1. Open Power Platform and import the solution ZIP from `src/copilot/sln`. +2. Configure the required connections for Copilot Studio, Microsoft Teams, Outlook, Fabric Data Agent, and Foundry Agent. +3. Use the `AZURE_AI_AGENT_ENDPOINT` and other output values from `azd env get-values` when configuring connections. +4. Publish the agent in Copilot Studio. + +For a step-by-step guide, see `docs/copilot/DeploymentGuide.md`. + +### 5.2 Validate Fabric IQ and Foundry + +Verify: + +- Fabric workspace and artifacts are present in `app.fabric.microsoft.com` +- Microsoft Foundry agent endpoints are available +- Data ingestion, search, and knowledge base components are configured + +### 5.3 Optional verification + +- Open Fabric workspace and check the deployed Fabric IQ workspace components. +- Confirm Microsoft Foundry knowledge base and agent setup. +- Validate that the Work IQ Power Platform solution is published successfully. + +--- + +## Step 6: Deployment Results + +### Azure resources + +The deployment creates or reuses the following Azure resources: + +- Resource Group +- Fabric Capacity +- Azure AI/OpenAI deployment resources +- Azure Search service location +- Microsoft Foundry-related service endpoints + +### Fabric IQ components + +The Fabric workspace contains: + +- Workspace +- Semantic models and datasets +- Data agent configuration artifacts +- Notebooks and environment definitions for Fabric IQ + +### Microsoft Foundry components + +The deployment also provisions: + +- Foundry agent service endpoints +- Knowledge base search integration +- Agent runtime configuration used by Work IQ + +### Output values + +Important output values are available from `azd env get-values` and are used for: + +- Copilot Studio connection setup +- Foundry agent endpoint configuration +- Fabric workspace access + +--- + +## Step 7: Clean Up (Optional) + +When you no longer need the deployment, remove resources safely: + +```bash +cd microsoft-iq-solution-accelerator +azd down --force --purge +``` + +This command removes deployed Azure and Fabric resources created by the deployment while preserving your local source code. + +If `azd down` fails, remove the resource group manually from the Azure Portal. + +--- + +## Known Issues and Troubleshooting + +### Fabric tenant access issues + +If the Fabric API returns a 403 or requests are denied by inbound policy, verify: + +- Tenant Fabric settings are enabled +- Your account has access to the Fabric workspace +- Network or proxy restrictions are not blocking `api.fabric.microsoft.com` + +### Deployment permission issues + +If deployment fails due to authorization: + +- Confirm your identity has Contributor access on the target subscription or resource group +- Confirm service principal or federated identity is allowed to use Fabric REST API +- Ensure required Azure resource providers are registered + +### Work IQ import issues + +If manual Work IQ import fails: + +- Confirm Power Platform connectors are authorized +- Use the outputs from `azd env get-values` for endpoint configuration +- Verify the Copilot solution version in `src/copilot/sln` + +--- + +## Next Steps + +After deployment, explore these guides: + +- `docs/TechnicalArchitecture.md` +- `docs/FAQs.md` +- `docs/copilot/README.md` +- `docs/copilot/TestingGuide.md` + +--- + +## Need Help? + +- Open an issue in the repository if you encounter bugs. +- Review `CONTRIBUTING.md` for contribution guidance. +- See `SUPPORT.md` for support and escalation paths.