docs: Revamp Deployment Docs for Unified Data Foundation in Fabric Solution Accelerator #49

Yamini-Microsoft · 2025-12-02T23:16:07Z

Purpose

This pull request makes significant improvements to the deployment documentation for the Unified Data Foundation with Fabric solution accelerator. The changes enhance clarity, structure, and usability, especially for new users and teams deploying in different environments. The documentation now provides clearer prerequisites, a more detailed overview of the deployment process, expanded environment options, and improved navigation.

Documentation structure and usability improvements:

Added a Quick Navigation section to docs/DeploymentGuideFabric.md, outlining key sections and providing direct links for easier access to relevant content.
Reorganized the deployment guide to clearly separate prerequisites, deployment overview, options for different environments (local, cloud shell, Codespaces, Dev Container, CI/CD), and expected results. This includes expanded instructions for each environment and removal of less-used options like VS Code Web. [1] [2] [3]

Clarity and accuracy enhancements:

Improved the explanation of deployment phases (Azure infrastructure and Fabric data platform), emphasizing idempotency, safe re-runs, and the orchestration process.
Updated the manual deployment guide to clarify the use of workspace names and simplify the steps, making it easier for users who already have existing infrastructure.

Consistency and troubleshooting updates:

Standardized section headers and icons for limitations, environment cleanup, and additional resources in docs/DeploymentGuideFabric.md, making the document easier to scan and reference. [1] [2] [3]
Added a troubleshooting note to the Databricks setup guide to help users locate external catalog locations.
Improved instructions for mirroring Unity Catalog in Microsoft Fabric by clarifying the folder creation step and updating the sequence for authentication and review.

Does this introduce a breaking change?

Yes
No

How to Test

Get the code

git clone [repo-address]
cd [repo-name]
git checkout [branch-name]

Test the code

What to Check

Verify that the following are valid

...

Other Information

Copilot

Pull request overview

This PR significantly improves the deployment documentation for the Unified Data Foundation with Fabric solution accelerator, focusing on enhanced clarity, structure, and usability for new users and teams deploying across different environments.

Key changes:

Added Quick Navigation section with direct links to key sections for easier document navigation
Reorganized prerequisites, deployment overview, and deployment options sections for better flow and clarity
Enhanced troubleshooting guidance for Databricks setup with detailed manual external location creation steps

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
docs/SetupDatabricks.md	Added comprehensive troubleshooting section for manually creating external locations when not auto-created
docs/DeploymentGuideFabricManual.md	Simplified variable descriptions and streamlined deployment instructions by removing redundant quick start section
docs/DeploymentGuideFabric.md	Major restructuring with new Quick Navigation, reorganized prerequisites with detailed software/permissions tables, improved deployment overview explaining two-phase approach, and standardized section headers with emojis
docs/DeploymentGuideDatabricks.md	Added folder creation step before mirroring Azure Databricks catalog, improving workspace organization

Comments suppressed due to low confidence (1)

docs/DeploymentGuideFabric.md:370

Duplicate "Deployment Options" section detected. This section appears twice in the document:

First occurrence at line 158 (new location in this PR)
Second occurrence at line 307 (appears to be the old location that should be removed)

The content of both sections is identical. The duplicate at line 307 should be removed to avoid confusion and maintain document consistency.

## Deployment Options

Choose your deployment environment based on your workflow and requirements. All options use the same [Quick Start commands](#quick-start) 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 |
| **[GitHub Actions](#github-actions-cicd)** | Automated CI/CD | Service principal setup | Production deployments |

### Local Machine
Deploy with full control over your development environment.

**Setup requirements**: Install the [software requirements](#-software-requirements)

**Deployment**: Use the standard [Quick Start commands](#quick-start)

### 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
curl -fsSL https://aka.ms/install-azd.sh | bash && exec bash

Deployment: Run the Quick Start commands (Azure CLI pre-authenticated)

GitHub Codespaces

Deploy from a cloud development environment with pre-configured tools.

Setup:

Go to the repository
Click Code → Codespaces → Create codespace

Deployment: Install azd and run Quick Start commands with device authentication:

# Install azd if needed
curl -fsSL https://aka.ms/install-azd.sh | bash && exec bash

# Use device code authentication  
az login --use-device-code
azd auth login --use-device-code

# Continue with Quick Start deployment commands

VS Code Dev Container

Deploy from a containerized environment for team consistency.

Setup:

Install Docker Desktop and Dev Containers extension
Clone repository and open in VS Code
Reopen in container when prompted

Deployment: All tools pre-installed - run Quick Start commands directly

GitHub Actions (CI/CD)

Automated deployment using the included workflow.

Setup: Configure repository variables and set up service principal with federated credentials

Triggers: Push to main branch or manual workflow dispatch

</details>



---

💡 <a href="/microsoft/unified-data-foundation-with-fabric-solution-accelerator/new/main/.github/instructions?filename=*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

Copilot · 2025-12-02T23:20:31Z

docs/DeploymentGuideFabric.md

+| Tool | Version | Purpose | Download |
+|------|---------|---------|----------|


The table header row uses inconsistent pipe alignment. The first column should start with a pipe character like the data rows for proper markdown table formatting.

Suggested fix:

| Tool | Version | Purpose | Download | |------|---------|---------|----------|

Copilot · 2025-12-02T23:20:31Z

docs/DeploymentGuideFabric.md

+| Section | Description |
+|---------|-------------|


The table header row uses inconsistent pipe alignment. The first column should start with a pipe character like the data rows for proper markdown table formatting.

Suggested fix:

| Section | Description | |---------|-------------|

Copilot · 2025-12-02T23:20:31Z

docs/DeploymentGuideFabric.md

+| Environment | Best For | Setup Required | Notes |
+|-------------|----------|----------------|-------|


The table header row uses inconsistent pipe alignment. The first column should start with a pipe character like the data rows for proper markdown table formatting.

Suggested fix:

| Environment | Best For | Setup Required | Notes | |-------------|----------|----------------|-------|

Copilot · 2025-12-02T23:20:32Z

docs/DeploymentGuideFabric.md

-The deployment executes in two coordinated phases using dedicated scripts:
+| Environment | Best For | Setup Required | Notes |
+|-------------|----------|----------------|-------|
+| **[Local Machine](#local-machine)** | Full development control | Install [software requirements](#-software-requirements) | Most flexible, requires local setup |


Broken internal link reference. The link [software requirements](#-software-requirements) references a section that doesn't exist. The actual section is titled "Software Tools" (line 40), so the link should be [software requirements](#️⃣-software-tools) or the section should be renamed to "Software Requirements" to match the link text.

Copilot · 2025-12-02T23:20:32Z

docs/DeploymentGuideFabric.md

-   - **Sample Data**: Uploads CSV files to bronze lakehouse ⚠️ *overwrites existing files with same names*
-   - **Power BI Reports**: Creates or overwrites dashboard components for data visualization ⚠️ *replaces existing reports with same names*
-   - **Administrators**: Adds new workspace administrators without removing existing ones
+**Setup requirements**: Install the [software requirements](#-software-requirements)


Broken internal link reference. The link [software requirements](#-software-requirements) references a section that doesn't exist. The actual section is titled "Software Tools" (line 40), so the link should be [software requirements](#️⃣-software-tools) or the section should be renamed to "Software Requirements" to match the link text.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-03T00:15:59Z

docs/DeploymentGuideFabric.md

+- **New to this solution?** Start with [Deployment Overview](#deployment-overview) → [Prerequisites](#prerequisites) → [Quick Start](#quick-start)
+- **Ready to deploy?** Jump directly to [Quick Start](#quick-start)


The anchor links in these lines are inconsistent with the actual heading anchors. When headings include emojis, GitHub generates anchors with the emoji converted to a dash. The correct anchors should be:

#-deployment-overview (not #deployment-overview)

#-prerequisites (not #prerequisites)

#-quick-start (not #quick-start)

These should match the format used in the table on lines 19-27 for consistency.

Suggested change

- **New to this solution?** Start with [Deployment Overview](#deployment-overview) → [Prerequisites](#prerequisites) → [Quick Start](#quick-start)

- **Ready to deploy?** Jump directly to [Quick Start](#quick-start)

- **New to this solution?** Start with [Deployment Overview](#-deployment-overview) → [Prerequisites](#-prerequisites) → [Quick Start](#-quick-start)

- **Ready to deploy?** Jump directly to [Quick Start](#-quick-start)

Copilot · 2025-12-03T00:16:00Z

docs/DeploymentGuideFabric.md

+  - *Data*: Preserved (sample data is re-uploaded if missing).
+  - *Admins*: New admins are added; existing ones remain.
+
+The deployment orchestration coordinates both phases, passing deployment parameters and ensuring proper sequencing. See [deployment options](#deployment-options) for different ways to run this deployment based on your preferred environment.


The anchor link #deployment-options is incorrect. The heading ## 💻 Deployment Options generates the anchor #-deployment-options (emoji becomes a dash). This should be updated to #-deployment-options to match the actual heading anchor.

Suggested change

The deployment orchestration coordinates both phases, passing deployment parameters and ensuring proper sequencing. See [deployment options](#deployment-options) for different ways to run this deployment based on your preferred environment.

The deployment orchestration coordinates both phases, passing deployment parameters and ensuring proper sequencing. See [deployment options](#-deployment-options) for different ways to run this deployment based on your preferred environment.

Copilot · 2025-12-03T00:16:00Z

docs/DeploymentGuideFabric.md

-## Deployment Overview
+## 💻 Deployment Options
+
+Choose your deployment environment based on your workflow and requirements. All options use the same [Quick Start commands](#quick-start) with environment-specific setup.


The anchor link #quick-start is incorrect. The heading ## 🚀 Quick Start generates the anchor #-quick-start (emoji becomes a dash). This should be updated to #-quick-start to match the actual heading anchor.

Copilot · 2025-12-03T00:16:00Z

docs/DeploymentGuideFabric.md

-1. **Infrastructure Provisioning** - Executes [`main.bicep`](../infra/main.bicep) to create Azure resources using [ARM idempotency](https://learn.microsoft.com/azure/azure-resource-manager/templates/deployment-tutorial-local-template?tabs=azure-powershell#deploy-template):
-   - **Microsoft Fabric Capacity**: Dedicated compute resources with configured admin permissions (updates configuration if parameters change)
-   - **Resource Group**: Container for all Azure resources
+**Deployment**: Use the standard [Quick Start commands](#quick-start)


The anchor link #quick-start is incorrect. The heading ## 🚀 Quick Start generates the anchor #-quick-start (emoji becomes a dash). This should be updated to #-quick-start to match the actual heading anchor.

Copilot · 2025-12-03T00:16:00Z

docs/DeploymentGuideFabric.md

+curl -fsSL https://aka.ms/install-azd.sh | bash && exec bash
+```
+
+**Deployment**: Run the [Quick Start commands](#quick-start) (Azure CLI pre-authenticated)


The anchor link #quick-start is incorrect. The heading ## 🚀 Quick Start generates the anchor #-quick-start (emoji becomes a dash). This should be updated to #-quick-start to match the actual heading anchor.

Suggested change

**Deployment**: Run the [Quick Start commands](#quick-start) (Azure CLI pre-authenticated)

**Deployment**: Run the [Quick Start commands](#-quick-start) (Azure CLI pre-authenticated)

Copilot · 2025-12-03T00:16:01Z

docs/DeploymentGuideFabric.md

+2. Clone repository and open in VS Code
+3. Reopen in container when prompted
+
+**Deployment**: All tools pre-installed - run [Quick Start commands](#quick-start) directly


The anchor link #quick-start is incorrect. The heading ## 🚀 Quick Start generates the anchor #-quick-start (emoji becomes a dash). This should be updated to #-quick-start to match the actual heading anchor.

Suggested change

**Deployment**: All tools pre-installed - run [Quick Start commands](#quick-start) directly

**Deployment**: All tools pre-installed - run [Quick Start commands](#-quick-start) directly

Copilot · 2025-12-03T00:16:01Z

docs/DeploymentGuideFabric.md

+| **[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 |
+| **[GitHub Actions](#github-actions-cicd)** | Automated CI/CD | Service principal setup | Production deployments |


Copilot · 2025-12-03T00:16:01Z

docs/DeploymentGuideFabric.md

+1. Go to the [repository](https://github.com/microsoft/unified-data-foundation-with-fabric-solution-accelerator)
+2. Click **Code** → **Codespaces** → **Create codespace**
+
+**Deployment**: Install azd and run [Quick Start commands](#quick-start) with device authentication:


The anchor link #quick-start is incorrect. The heading ## 🚀 Quick Start generates the anchor #-quick-start (emoji becomes a dash). This should be updated to #-quick-start to match the actual heading anchor.

Suggested change

**Deployment**: Install azd and run [Quick Start commands](#quick-start) with device authentication:

**Deployment**: Install azd and run [Quick Start commands](#-quick-start) with device authentication:

Copilot · 2025-12-03T00:16:01Z

docs/SetupDatabricks.md

+2. **Find the storage path URL:**
+     - Go to the [Azure Portal](https://portal.azure.com/).
+     - Navigate to your Azure Databricks resource group.
+     - Locate and click on the **Managed Resource Group**,


There's a punctuation error at the end of this line. The comma should be a period since this completes the instruction.

Suggested change

- Locate and click on the **Managed Resource Group**,

- Locate and click on the **Managed Resource Group**.

Fixed punctuation in instructions for locating Managed Resource Group and Access Connector.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/DeploymentGuideFabricManual.md

Updated the storage path URL format to include an optional path.

Prajwal-Microsoft · 2025-12-03T15:05:02Z

docs/DeploymentGuideFabricManual.md


-## Quick Manual Deployment

-### 1. Set Environment Variables


Are these instructions not required ?
Users may not be aware about how to set these.

Prajwal-Microsoft · 2025-12-03T15:17:22Z

docs/DeploymentGuideFabric.md

+python --version
+```
+
 ## 🚀 Quick Start


Looks like this step should come after the Deployment Options, I see from deployment options we are navigating back to this step rather we should move forward.

Yamini-Microsoft added 2 commits December 3, 2025 04:23

docs: Update Deployment Guides for better readability

2d3c945

Merge remote-tracking branch 'origin/main' into psl-images-update

07b1d5e

Yamini-Microsoft requested review from Avijit-Microsoft, Prajwal-Microsoft, Roopan-Microsoft, Vinay-Microsoft, aniaroramsft, dgp10801, nchandhi and toherman-msft as code owners December 2, 2025 23:16

Yamini-Microsoft requested a review from Copilot December 2, 2025 23:17

Copilot started reviewing on behalf of Yamini-Microsoft December 2, 2025 23:18 View session

Copilot finished reviewing on behalf of Yamini-Microsoft December 2, 2025 23:19

Copilot AI reviewed Dec 2, 2025

View reviewed changes

minor fixes

4582976

Yamini-Microsoft requested a review from Copilot December 3, 2025 00:10

Copilot started reviewing on behalf of Yamini-Microsoft December 3, 2025 00:10 View session

Copilot finished reviewing on behalf of Yamini-Microsoft December 3, 2025 00:14

Copilot AI reviewed Dec 3, 2025

View reviewed changes

Yamini-Microsoft added 2 commits December 3, 2025 11:31

Fix markdown links and formatting in deployment guide

b2d2fcd

Correct punctuation in SetupDatabricks.md

b4e540a

Fixed punctuation in instructions for locating Managed Resource Group and Access Connector.

Yamini-Microsoft requested a review from Copilot December 3, 2025 06:05

Copilot started reviewing on behalf of Yamini-Microsoft December 3, 2025 06:05 View session

Copilot finished reviewing on behalf of Yamini-Microsoft December 3, 2025 06:07

Copilot AI reviewed Dec 3, 2025

View reviewed changes

docs/DeploymentGuideFabricManual.md Show resolved Hide resolved

Modify storage path URL format in setup guide

3fd7328

Updated the storage path URL format to include an optional path.

Prajwal-Microsoft reviewed Dec 3, 2025

View reviewed changes

		\| Tool \| Version \| Purpose \| Download \|
		\|------\|---------\|---------\|----------\|

		\| Environment \| Best For \| Setup Required \| Notes \|
		\|-------------\|----------\|----------------\|-------\|

		- New to this solution? Start with [Deployment Overview](#deployment-overview) → [Prerequisites](#prerequisites) → [Quick Start](#quick-start)
		- Ready to deploy? Jump directly to [Quick Start](#quick-start)

	The deployment orchestration coordinates both phases, passing deployment parameters and ensuring proper sequencing. See [deployment options](#deployment-options) for different ways to run this deployment based on your preferred environment.
	The deployment orchestration coordinates both phases, passing deployment parameters and ensuring proper sequencing. See [deployment options](#-deployment-options) for different ways to run this deployment based on your preferred environment.

	Deployment: Run the [Quick Start commands](#quick-start) (Azure CLI pre-authenticated)
	Deployment: Run the [Quick Start commands](#-quick-start) (Azure CLI pre-authenticated)

	Deployment: All tools pre-installed - run [Quick Start commands](#quick-start) directly
	Deployment: All tools pre-installed - run [Quick Start commands](#-quick-start) directly

	Deployment: Install azd and run [Quick Start commands](#quick-start) with device authentication:
	Deployment: Install azd and run [Quick Start commands](#-quick-start) with device authentication:

	- Locate and click on the Managed Resource Group,
	- Locate and click on the Managed Resource Group.

docs: Revamp Deployment Docs for Unified Data Foundation in Fabric Solution Accelerator #49

Are you sure you want to change the base?

docs: Revamp Deployment Docs for Unified Data Foundation in Fabric Solution Accelerator #49

Uh oh!

Conversation

Yamini-Microsoft commented Dec 2, 2025

Purpose

Does this introduce a breaking change?

How to Test

What to Check

Other Information

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

GitHub Codespaces

VS Code Dev Container

GitHub Actions (CI/CD)

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Prajwal-Microsoft Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Prajwal-Microsoft Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels