Merge pull request #14 from microsoft/agh-doc-review

docs: Enhance documentation with all deployment options

Author: alguadam

.devcontainer/devcontainer.json

@@ -1,5 +1,5 @@
 {
-    "name": "Unified Data Foundation with Fabric",
+    "name": "Real-Time Intelligence Operations Solution Accelerator Dev Container",
     "image": "mcr.microsoft.com/devcontainers/python:3.12-bookworm",
     "features": {
         "ghcr.io/devcontainers/features/azure-cli:1": {

README.md

@@ -83,12 +83,10 @@ Quick deploy
 
 Follow these steps to deploy the solution to your own Azure subscription:
 
-| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://vscode.dev/github/microsoft/real-time-intelligence-operations-solution-accelerator) |
-|---|---|---|
-
-<br/>
+| [![GitHub Codespaces](https://img.shields.io/badge/GitHub_Codespaces-Open-grey?style=flat&labelColor=grey&message=Open&color=blue&logo=github)](https://codespaces.new/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Visual Studio Code Dev Containers](https://img.shields.io/badge/Visual_Studio_Code_Dev_Container-Open-gray?style=flat&labelColor=grey&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Visual Studio Code Web](https://img.shields.io/badge/Visual_Studio_Code_Web-Open-gray?style=flat&labelColor=grey&message=Open&color=blue)](https://vscode.dev/github/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Azure Cloud Shell](https://img.shields.io/badge/Azure_Cloud_Shell-Open-grey?style=flat&labelColor=grey&message=Open&color=blue)](https://portal.azure.com/#cloudshell/) |
+|---|---|---|---|
 
-**One-command deployment** - Deploy everything with [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) and [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) (Check [prerequisites](./docs/DeploymentGuide.md#prerequisites)):
+**One-command deployment** - Deploy everything with [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) and [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) (check [prerquisites](./docs/DeploymentGuide.md#prerequisites)):
 
 ```bash
 # Clone and navigate to repository
@@ -127,7 +125,7 @@ Check more deployment aspects in our [deployment guide](./docs/DeploymentGuide.m
 | [**Deployment validation**](./docs/DeploymentGuide.md#deployment-results) | Once deployed, verify Azure infrastructure, Fabric workspace components, and real-time data flow |
 | [**Deployment overview**](./docs/DeploymentGuide.md#deployment-overview) | Two-phase deployment process: Azure infrastructure provisioning and Fabric workspace setup |
 | [**Advanced configuration**](./docs/DeploymentGuide.md#advanced-configuration-options) | Customize workspace names, component names, email alerts, and capacity deployment options |
-| [**Alternative deployment options**](./docs/DeploymentGuide.md#deployment-options) | Deploy locally, Azure Cloud Shell, GitHub Codespaces, or VS Code Dev Container |
+| [**Alternative deployment options**](./docs/DeploymentGuide.md#deployment-options) | Deploy locally, Azure Cloud Shell, GitHub Codespaces, VS Code Dev Container or GitHub Actions|
 | [**Limitations**](./docs/DeploymentGuide.md#known-limitations) | See identified limitations of the solution |
 | [**Cleanup**](./docs/DeploymentGuide.md#environment-cleanup) | Remove all deployed resources and clean up your environment with `azd down` |
 

azure.yaml

@@ -5,7 +5,7 @@ metadata:
   template: real-time-intelligence-operations-solution-accelerator@1.0
 
 requiredVersions:
-  azd: ">1.20.0"
+  azd: ">1.19.0"
 
 hooks:
   postprovision:

docs/DeploymentGuide.md

@@ -2,7 +2,7 @@
 
 Deploy the **Real-Time Intelligence Data Platform** solution accelerator using Azure Developer CLI - get a complete real-time analytics platform with Event Hub, Fabric Eventhouse, and KQL dashboards in minutes.
 
-## 🚀 Quick Start
+## Quick Start
 
 **One-command deployment** - Deploy everything with Azure Developer CLI ([prerequisites required](#prerequisites)). See also other available [deployment options](#deployment-options):
 
@@ -70,8 +70,9 @@ Before starting, ensure your deployment identity has the following requirements.
 - [ ] **`Microsoft.EventHub` Resource Provider Access**: Verify your Azure Subscription has Event Hub resource provider enabled
 
 ### 🔗 API Permissions
-- [ ] **Fabric REST API - Workspace Management**: Access to create and manage Fabric workspaces
-- [ ] **Fabric REST API - Item Creation**: Access to create Eventhouses, KQL databases, and dashboards
+- [ ] **Service principals and managed identities support on Fabric REST API**: To use service principals and managed identities with Fabric REST APIs (GitHub actions require it), [enable the `Service principals can use Fabric` APIs tenant setting](https://learn.microsoft.com/rest/api/fabric/articles/identity-support)
+- [ ] **Fabric REST API - Workspace Management**: Access to create and manage Fabric workspaces ([see scopes](https://learn.microsoft.com/rest/api/fabric/articles/scopes))
+- [ ] **Fabric REST API - Item Creation**: Access to create Eventhouses, KQL databases, and dashboards ([see scopes](https://learn.microsoft.com/rest/api/fabric/articles/scopes))
 - [ ] **Azure Event Hubs API**: Access to create and manage Event Hub resources
 
 ### 💻 Software Requirements
@@ -216,57 +217,74 @@ The solution includes comprehensive sample data for real-time analytics scenario
 
 Choose your deployment environment based on your workflow and requirements. All options use the same [Deploy with AZD](#deploy-with-azd) commands with environment-specific setup.
 
-| Environment | Best For | Setup Required | Notes |
-|-------------|----------|----------------|-------|
-| **[Local Machine](#local-machine)** | Full development control | Install [software requirements](#software-requirements) | Most flexible, requires local setup |
-| **[Azure Cloud Shell](#azure-cloud-shell)** | Zero setup | Just a web browser | Pre-configured tools, session timeouts |
-| **[GitHub Codespaces](#github-codespaces)** | Team consistency | GitHub account | Cloud development environment |
-| **[Dev Container](#vs-code-dev-container)** | Standardized tooling | Docker Desktop + VS Code | Containerized consistency |
+| Environment | Setup Required | Notes |
+|-------------|----------------|-------|
+| **[Local Machine](#local-machine)** | Install [software requirements](#software-requirements) | Most flexible, requires local setup |
+| **[Visual Studio Code Dev Container](#visual-studio-code-dev-container)** | Docker Desktop + VS Code | Containerized consistency |
+| **[GitHub Codespaces](#github-codespaces)** | GitHub account | Cloud development environment |
+| **[Azure Cloud Shell](#azure-cloud-shell)** | Web browser | Pre-configured tools, session timeouts |
+| **[GitHub Actions](#github-actions)** | Azure service principal | Federated identity, automated deployment |
 
 ### Local Machine
+
 Deploy with full control over your development environment.
 
-**Setup requirements**: Install the [software requirements](#software-requirements)
+**Setup**: Install the [software requirements](#software-requirements)
 
-**Deployment**: Use the standard [Deploy with AZD](#deploy-with-azd) commands
+**Deployment**: Follow the [quick start steps](#quick-start) commands
 
-### Azure Cloud Shell
-Deploy from Azure's browser-based terminal with zero local installation.
+### Visual Studio Code Dev Container
+Deploy from a containerized environment for team consistency.
 
-**Setup**: Open [Azure Cloud Shell](https://shell.azure.com) and install Azure Developer CLI:
-```bash
-curl -fsSL https://aka.ms/install-azd.sh | bash && exec bash
-```
+**Setup**: 
+1. Install Visual Studio Code, [Docker Desktop](https://www.docker.com/products/docker-desktop) and [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+2. Clone repository and open in VS Code
+3. Reopen in container when prompted
 
-**Deployment**: Run the [Deploy with AZD](#deploy-with-azd) commands (Azure CLI pre-authenticated)
+**Deployment**: All tools pre-installed - follow the [quick start steps](#quick-start) commands
 
 ### GitHub Codespaces  
+
 Deploy from a cloud development environment with pre-configured tools.
 
 **Setup**: 
 1. Go to the repository
-2. Click **Code** → **Codespaces** → **Create codespace**
+2. Click **Code** → **Codespaces** → **Create codespace on main**
 
-**Deployment**: Install azd and run deployment commands with device authentication:
+**Deployment**: All tools pre-installed - follow the [quick start steps](#quick-start) commands
+
+### Azure Cloud Shell
+
+Deploy from Azure's browser-based terminal with zero local installation.
+
+**Setup**: Open [Azure Cloud Shell](https://shell.azure.com) and install Azure Developer CLI:
 ```bash
-# Install azd if needed
 curl -fsSL https://aka.ms/install-azd.sh | bash && exec bash
+```
 
-# Use device code authentication  
-azd auth login --use-device-code
+**Deployment**: Follow the [quick start steps](#quick-start) commands
 
-# Continue with deployment commands
-```
+### GitHub Actions
 
-### VS Code Dev Container
-Deploy from a containerized environment for team consistency.
+Deploy using automated CI/CD pipeline with GitHub Actions and Azure federated identity.
 
-**Setup**: 
-1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) and [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
-2. Clone repository and open in VS Code
-3. Reopen in container when prompted
+**Setup**:
+1. Fork the repository to your GitHub account
+2. Configure [Azure service principal with federated identity credentials](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect) for GitHub Actions (recommened)
+3. Set repository variables in GitHub:
+   - `AZURE_CLIENT_ID`: Service principal client ID
+   - `AZURE_TENANT_ID`: Azure tenant ID  
+   - `AZURE_SUBSCRIPTION_ID`: Target subscription ID
+   - `AZURE_ENV_NAME`: Environment name for resource naming
+4. Set optinall repository  variables in GitHub if needed:
+   - `FABRIC_WORKSPACE_ADMINISTRATORS`: Comma-separated admin identities
+   - `FABRIC_ACTIVATOR_ALERTS_EMAIL`: Email for alert notifications
 
-**Deployment**: All tools pre-installed - run [Deploy with AZD](#deploy-with-azd) commands directly
+**Deployment**: 
+1. Navigate to **Actions** tab in your GitHub repository
+2. Select **CI/CD Azure - Real-Time Intelligence Operations** workflow
+3. Click **Run workflow** to trigger deployment
+4. Monitor deployment progress and view summary with Azure Portal links
 
 ---
 
@@ -359,8 +377,9 @@ The `azd down` command orchestrates a complete environment cleanup process that:
 
 1. **Removes Fabric Workspace Components**: Executes [`delete_fabric_rti.py`](../infra/scripts/fabric/delete_fabric_rti.py) via `predown` hook to safely delete workspace connections and components
 2. **Deletes Fabric Workspace**: Removes the Microsoft Fabric workspace and all associated items 
-3. **Deprovisions Azure Resources**: Removes all Azure infrastructure components including Event Hub and Fabric Capacity
-4. **Preserves Local Environment**: Keeps your local development environment and configurations intact
+3. **Deletes Fabric connection**: Removes the Microsoft Fabric Event Hub connection 
+4. **Deprovisions Azure Resources**: Removes all Azure infrastructure components including Event Hub and Fabric Capacity
+5. **Preserves Local Environment**: Keeps your local development environment and configurations intact
 
 **Complete cleanup commands:**