Tutorial: Durchgängige Automatisierung in Fabric

In diesem Tutorial baust du einen vollständigen, wiederholbaren Release-Flow für Microsoft Fabric anhand von Infrastruktur als Code. Du stellst zwei Arbeitsbereiche (Entwicklung und Test) mit Terraform bereit, verbindest den Entwicklungsarbeitsbereich mit Git, entwickelst ein Element in der Entwicklung und promovierst es dann, um es mit der fabric-cicd Python-Bibliothek zu testen. Alles läuft unter einem einzigen Serviceprinzip, sodass der gleiche Flow heute auf deinem Laptop und morgen in einer CI/CD-Pipeline funktioniert.

In diesem Tutorial lernen Sie:

Zwei Ebenen, zwei Werkzeuge

Die Automatisierung eines Fabric-Releases hat zwei klare Anliegen, und es hilft, diese getrennt zu halten: die stabile Kontrollebene (die Infrastruktur, in der deine Inhalte leben) und die volatile Datenebene (die Inhalte, die du täglich bearbeitest). Wählen Sie das Bereitstellungstool danach aus, wie häufig sich die jeweiligen Komponenten ändern.

• Die Kontrollebene enthält nichtflüchtige Infrastruktur, die Sie einmal bereitstellen und selten ändern: Kapazitäten, Arbeitsbereiche und deren Einstellungen, Domänen, Verbindungen, Mietereinstellungen sowie RBAC- und Git-Verkabelung. Dieses Tutorial stellt es mit Terraform zur Verfügung.
• Die Datenebene enthält veränderliche Inhalte, die sich mit jedem Sprint weiterentwickeln und über Git fließen: Notebooks, Lakehouses und Warehouses, semantische Modelle und Berichte, Pipelines und Datenflüsse sowie Werte der Variablenbibliothek. Dieses Tutorial verschiebt es mit fabric-cicd.

Die Leitidee: Die stabile Plattform einmal mit Terraform bereitstellen und dann volatile Items kontinuierlich durch Git und fabric-cicd fließen lassen.

Dies ist ein Ansatz zur Automatisierung von Fabric und bevorzugt Teams, die Infrastruktur bereits als Code behandeln und ein skriptbares, quellcodebasiertes Setup wünschen. Fabric bietet außerdem portalbasierte Deployment-Pipelines und Git-Integration an, die man über die Benutzeroberfläche steuern kann, ohne Terraform oder Python schreiben zu müssen. Für einen Vergleich der Optionen siehe CI/CD-Workflow-Optionen in Fabric.

Speziell für die Data-Plane-Bereitstellung ist fabric-cicd eine Option. Du kannst auch die Fabric Bulk (CRUD) REST-APIs direkt aufrufen, wenn du die volle Kontrolle über die Aufrufe erstellen, aktualisieren und löschen möchtest, ohne eine Abhängigkeit von der Bibliothek zu entwickeln. Dieses Tutorial verwendet fabric-cicd, weil es die umgebungsspezifische Neubindung für Sie übernimmt.

Warum Terraform für die Steuerebene

• Deklarativ und idempotent. Du beschreibst den gewünschten Zustand deiner Arbeitsbereiche einmal; Terraform schafft, was fehlt, und lässt den Rest in Ruhe.
• Drifterkennung. terraform plan zeigt genau, wie sich der Live-Tenant von deiner Wahrheitsquelle unterscheidet, sodass eine Out-of-Band-Änderung im Portal sichtbar und reversibel wird.
• Ein Anbieter für viele Ressourcen. Der Microsoft Fabric-Anbieter verwaltet Arbeitsbereiche, Kapazitäten, Verbindungen, Git-Links und RBAC über die Fabric REST APIs.

Warum fabric-cicd für die Datenebene

• Es wird so eingesetzt, wie Fabric es erwartet. fabric-cicd liest die Git-Darstellung deiner Objekte und veröffentlicht sie mit der korrekten Create-or-Update-Semantik, sodass du REST-Aufrufe nicht manuell ausführst.
• Parametrisierung. Eine parameter.yml Datei bindet umgebungsspezifische Werte neu, etwa indem man das Standard-Lakehouse eines Notizbuchs oder die Verbindung eines semantischen Modells auf das richtige Ziel pro Umgebung zeigt.
• Bereinigung. Es kann Items entveröffentlichen, die aus Git entfernt wurden, wodurch jede Umgebung ein treues Spiegelbild des von ihm verfolgten Zweigs bleibt.

Der End-to-End-Fluss

Die beiden Ebenen kommen als einzige, kontinuierliche Automatisierung zusammen. Man stellt die Plattform einmal zur Verfügung, und von da an folgt jede Inhaltsänderung derselben wiederholbaren Schleife – vom Editor über Git bis in die Testumgebung – ohne manuelle Portal-Schritte dazwischen.

Der gleiche Service-Principal authentifiziert jede Phase, daher ist der Flow, den du in diesem Tutorial manuell ausführen, genau das, was eine CI/CD-Pipeline in deinem Namen ausführt: eine Provision-Phase (Terraform), dann eine Deploy-Phase (fabric-cicd), die läuft, wann immer sich der getrackte Branch ändert. Jede Stufe folgt einem folgenden Schritt:

Voraussetzungen

• Eine Fabric-Kapazität. Beide Arbeitsbereiche in diesem Tutorial sind derselben Kapazität zugewiesen. Eine Testkapazität funktioniert.
• Ein Service Principal (Microsoft Entra App-Registrierung) mit einem Clientgeheimnis. Diese einzige Identität stellt die Arbeitsbereiche bereit und führt die Bereitstellung durch.
• Die Tenant-Einstellung Service Principals kann Fabric-APIs verwenden, die für eine Sicherheitsgruppe aktiviert sind, die den Service Principal enthält. Weitere Informationen finden Sie unter Dienstprinzipalauthentifizierung für Fabric-APIs aktivieren.
• Eine Azure DevOps-Organisation, ein Projekt und ein Git-Repository, auf das der Service-Principal zugreifen kann. Das Repository muss bereits den Branch enthalten (zum Beispiel main) und den Ordner, den du in ado_directory_name festgelegt hast (zum Beispiel /workspace). Die Git-Verbindung verwendet PreferRemote, die diesen Ordner auf dem Branch liest, wenn sie sich verbindet, daher müssen beide vorher existieren. Wenn der Ordner fehlt, schlägt terraform apply mit GitProviderResourceNotFound fehl. Um sie zu erstellen, übertrage vor dem Ausführen von Terraform eine leere Platzhalterdatei (z. B. .gitkeep) in dem Branch unter diesem Pfad.
• Die folgenden Werkzeuge werden lokal installiert:
  • Terraform 1.8 oder später.
  • Python 3.9 oder neuer (bis 3.13).
  • Die Azure CLI.

Authentifizierung einrichten

Sowohl Terraform als auch fabric-cicd authentifizieren sich als Service-Principal. Exportiere seine Zugangsdaten als Umweltvariablen, damit beide Tools sie abfangen können:

export FABRIC_TENANT_ID="<tenant-id>"
export FABRIC_CLIENT_ID="<app-client-id>"
export FABRIC_CLIENT_SECRET="<client-secret>"

# fabric-cicd (via DefaultAzureCredential) reads the AZURE_* names:
export AZURE_TENANT_ID="$FABRIC_TENANT_ID"
export AZURE_CLIENT_ID="$FABRIC_CLIENT_ID"
export AZURE_CLIENT_SECRET="$FABRIC_CLIENT_SECRET"

$env:FABRIC_TENANT_ID   = "<tenant-id>"
$env:FABRIC_CLIENT_ID   = "<app-client-id>"
$env:FABRIC_CLIENT_SECRET = "<client-secret>"

$env:AZURE_TENANT_ID    = $env:FABRIC_TENANT_ID
$env:AZURE_CLIENT_ID    = $env:FABRIC_CLIENT_ID
$env:AZURE_CLIENT_SECRET = $env:FABRIC_CLIENT_SECRET

Schritt 1: Bereite die Arbeitsbereiche mit Terraform bereit

In diesem Schritt definierst du die Steuerebene als Code und wendest sie an. Erstelle einen Ordner für deine Terraform-Konfiguration und füge die folgenden Dateien hinzu.

Konfigurieren Sie den Anbieter

Erstellen Sie provider.tf. Das Festpinnen der Provider-Version sorgt dafür, dass sich alle Ingenieure identisch verhalten.

# We strongly recommend using the required_providers block to set the Fabric Provider source and version being used
terraform {
  required_version = ">= 1.8, < 2.0"
  required_providers {
    fabric = {
      source  = "microsoft/fabric"
      version = "1.12.0"
    }
  }
}

# Configure the Microsoft Fabric Terraform Provider.
# Auth is via the service principal exported as FABRIC_TENANT_ID /
# FABRIC_CLIENT_ID / FABRIC_CLIENT_SECRET. Never hard-code secrets here.
provider "fabric" {
  # Configuration options
}

Deklarieren Sie die Eingaben

Erstellen Sie variables.tf:

variable "capacity_name" {
  description = "Name of an existing Fabric capacity that backs both workspaces."
  type        = string
}

variable "workspace_prefix" {
  description = "Prefix for the workspace display names."
  type        = string
  default     = "releaseflow"
}

# Azure DevOps Git settings for the DEV workspace.
variable "ado_organization_name" {
  type = string
}
variable "ado_project_name" {
  type = string
}
variable "ado_repository_name" {
  type = string
}
variable "ado_branch_name" {
  type    = string
  default = "main"
}
variable "ado_repo_url" {
  type = string
}
variable "ado_directory_name" {
  type    = string
  default = "/workspace"
}

# Service principal used by the source-control connection.
variable "tenant_id" {
  type = string
}
variable "client_id" {
  type = string
}
variable "client_secret" {
  type      = string
  sensitive = true
}

# Object id of the developer or group to grant Contributor on DEV.
variable "contributor_principal_id" {
  type = string
}

Definieren Sie die Ressourcen

Erstellen Sie main.tf. Diese Konfiguration erzeugt zwei Arbeitsbereiche, eine Quellcode-Verbindung, den Git-Link in der Entwicklung und Rollenzuweisungen.

data "fabric_capacity" "capacity" {
  display_name = var.capacity_name
}

# DEV workspace — authored here, committed to Git.
resource "fabric_workspace" "dev" {
  display_name = "${var.workspace_prefix}-dev"
  description  = "Development workspace."
  capacity_id  = data.fabric_capacity.capacity.id
}

# TEST workspace — populated by fabric-cicd from the Git repo.
resource "fabric_workspace" "test" {
  display_name = "${var.workspace_prefix}-test"
  description  = "Test workspace."
  capacity_id  = data.fabric_capacity.capacity.id
}

# Source-control connection (service principal).
resource "fabric_connection" "ado" {
  display_name      = "${var.workspace_prefix}-ado-conn"
  connectivity_type = "ShareableCloud"
  privacy_level     = "Organizational"

  connection_details = {
    type            = "AzureDevOpsSourceControl"
    creation_method = "AzureDevOpsSourceControl.Contents"
    parameters = [{ name = "url", value = var.ado_repo_url }]
  }

  credential_details = {
    credential_type      = "ServicePrincipal"
    skip_test_connection = false
    service_principal_credentials = {
      client_id                = var.client_id
      client_secret_wo         = var.client_secret
      client_secret_wo_version = 1
      tenant_id                = var.tenant_id
    }
  }
}

# Connect the DEV workspace to Git.
resource "fabric_workspace_git" "dev" {
  workspace_id            = fabric_workspace.dev.id
  initialization_strategy = "PreferRemote"

  git_provider_details = {
    git_provider_type = "AzureDevOps"
    organization_name = var.ado_organization_name
    # The Fabric API returns project/repository names lowercased. Pass them
    # lowercased so Terraform's post-apply consistency check matches.
    project_name    = lower(var.ado_project_name)
    repository_name = lower(var.ado_repository_name)
    branch_name     = var.ado_branch_name
    directory_name  = var.ado_directory_name
  }

  git_credentials = {
    source        = "ConfiguredConnection"
    connection_id = fabric_connection.ado.id
  }
}

# RBAC: grant the dev team Contributor on DEV.
# If contributor_principal_id is a security group rather than a user, change
# type to "Group".
resource "fabric_workspace_role_assignment" "dev_contributor" {
  workspace_id = fabric_workspace.dev.id
  role         = "Contributor"
  principal = {
    id   = var.contributor_principal_id
    type = "User"
  }
}

Deklarieren Sie die Ausgaben

Erstellen Sie outputs.tf. Der Name des Testarbeitsbereichs führt den Bereitstellungsschritt ein.

output "dev_workspace_id"   { value = fabric_workspace.dev.id }
output "test_workspace_id"  { value = fabric_workspace.test.id }
output "test_workspace_name" {
  description = "Pass this as --workspace_name to the fabric-cicd deploy step."
  value       = fabric_workspace.test.display_name
}

Anwenden der Konfiguration

Gib Werte für die Variablen an (zum Beispiel in einer terraform.tfvars Datei, die du aus Git heraushältst), und führe dann aus:

terraform init
terraform plan
terraform apply

Terraform meldet die erstellten Ressourcen und druckt die Ausgaben aus.

Bereitstellungsherausforderungen, die man kennen sollte

Der Fabric-Anbieter ist leistungsstark, aber einige Eigenheiten führen bei Nutzern leicht zu Verwirrung. Behalte diese Dinge im Hinterkopf, bevor du es in der Produktion einleitest:

• Die Git-Verbindung kann nicht importiert werden. Die Ressource fabric_workspace_git unterstützt terraform importnicht . Behandle es als einmaliges Bootstrap und speichere es im Remote-State, damit spätere Durchläufe nicht versuchen, es erneut zu erstellen. Speichere deinen Zustand in einem gemeinsamen Backend wie Azure Storage statt auf einem einzelnen Laptop.
• Git-Namen mit Berücksichtigung der Groß-/Kleinschreibung. Die Fabric API liefert Azure DevOps-Projekt- und Repository-Namen mit Kleinbuchstaben zurück. Wenn du sie in gemischter Groß-/Kleinschreibung übergibst, meldet Terraform: "Provider hat nach dem Anwenden ein inkonsistentes Ergebnis erzeugt." Umschließe sie mit lower(), wie oben gezeigt.
• Umfang des Dienstprinzips. Dieselbe Identität muss in der Lage sein, Arbeitsbereiche auf der Kapazität zu erstellen und als Workspace-Mitglied hinzugefügt zu werden. Wenn die Bereitstellung durch einen Autorisierungsfehler fehlschlägt, überprüfen Sie erneut die Mietereinstellung und die Kapazitätsrollenzuweisung anhand der Voraussetzungen.
• Geheimnisse bleiben, wo möglich, außerhalb des Bundesstaates. Das Verbindungsgeheimnis verwendet das Write-only-Argument client_secret_wo , sodass es nicht im Klartextzustand gespeichert wird. Trotzdem solltest du deine Staatsakte als sensibel schützen.

Schritt 2: Verifiziere die Git-Verbindung

Terraform hat den Entwicklungsarbeitsbereich bereits in Schritt 1 mit Git verbunden. Bestätigen Sie es:

1. Im Fabric-Portal öffnen Sie den releaseflow-dev Arbeitsbereich.
2. Wählen Sie Arbeitsbereichseinstellungen>Git-Integration aus.
3. Bestätigen Sie, dass der Arbeitsbereich mit Ihrer Azure DevOps-Organisation, Ihrem Projekt, dem Repository, dem Branch und dem von Ihnen festgelegten ado_directory_nameOrdner verbunden ist.

Schritt 3: Erstellen Sie Inhalte in der Entwicklungsumgebung und committen Sie diese

Füge jetzt Inhalte zum Dev Workspace hinzu und pushe sie auf Git. In diesem Tutorial erstellst du zwei Gegenstände: ein Seehaus und ein Notizbuch, das daraus liest.

1. In releaseflow-dev, erstelle ein Seehaus namens demoLakehouse.
2. Erstellen Sie ein Notizbuch namens demoNotebook. Fügen Sie als Standard-Lakehouse hinzu demoLakehouse und fügen Sie eine Zelle hinzu, die eine Tabelle liest oder ein kleines Beispiel-DataFrame schreibt.
3. Führe das Notebook einmal aus, um zu prüfen, ob es mit dem Dev-Lakehouse funktioniert.
4. Öffne im Arbeitsbereich die Quellcodeverwaltung, wähle beide Elemente aus und committe sie auf deinem Branch.

Nach dem Commit enthält dein Repository einen demoLakehouse.Lakehouse Ordner und einen demoNotebook.Notebook Ordner unter dem konfigurierten Verzeichnis.

Schritt 4: Vom Entwickler zum Testen mit fabric-cicd bereitstellen

Der Testarbeitsbereich ist immer noch leer. Verwende fabric-cicd, um die Elemente aus Git im Testbereich zu veröffentlichen und dabei das Notebook dem Test-Lakehouse neu zuzuordnen.

Fabric-cicd installieren

Erstellen Sie requirements.txt:

fabric-cicd>=0.1.20
azure-identity>=1.17.0

Installieren Sie es:

pip install -r requirements.txt

Fügen Sie eine Parameterdatei hinzu

Das in Git gespeicherte Notizbuch verweist auf das dev-Lakehouse und den dev-Arbeitsbereich. Wenn du zum Testen deployest, müssen sich diese Referenzen ändern, sodass das Notizbuch Testdaten liest und schreibt. Fabric-CICD macht das mit einer parameter.yml Datei.

Erstelle parameter.yml neben deinem Deployment-Skript. Ersetzen Sie die beiden Platzhalter-GUIDs durch die tatsächliche Dev Lakehouse ID und Dev Workspace ID, die in Ihrem Notebook-Inhalt erscheinen:

find_replace:
  # DEV lakehouse id -> the deployed demoLakehouse id in the target workspace.
  - find_value: "<dev-lakehouse-guid>"
    replace_value:
      test: "$items.Lakehouse.demoLakehouse.$id"
    item_type: "Notebook"
    item_name: "demoNotebook"
    file_path: "/demoNotebook.Notebook/notebook-content.py"

  # DEV workspace id -> the target workspace id.
  - find_value: "<dev-workspace-guid>"
    replace_value:
      test: "$workspace.$id"
    item_type: "Notebook"
    item_name: "demoNotebook"
    file_path: "/demoNotebook.Notebook/notebook-content.py"

Die Token $items.Lakehouse.demoLakehouse.$id und $workspace.$id werden von fabric-cicd bei der Bereitstellung in die GUIDs im Ziel-Arbeitsbereich aufgelöst.

Schreibe das Deployment-Skript

Erstellen Sie deploy.py:

import argparse
from azure.identity import DefaultAzureCredential
from fabric_cicd import (
    FabricWorkspace,
    publish_all_items,
    unpublish_all_orphan_items,
)

ITEM_TYPES = ["Lakehouse", "Notebook"]


def main() -> None:
    p = argparse.ArgumentParser()
    p.add_argument("--workspace_name", required=True)
    p.add_argument("--environment", required=True)
    p.add_argument("--repository_directory", default="./workspace")
    p.add_argument("--parameter_file", default="./parameter.yml")
    args = p.parse_args()

    target = FabricWorkspace(
        workspace_name=args.workspace_name,
        environment=args.environment,
        repository_directory=args.repository_directory,
        item_type_in_scope=ITEM_TYPES,
        parameter_file_path=args.parameter_file,
        token_credential=DefaultAzureCredential(),
    )

    # Create or update every item, applying parameter.yml.
    publish_all_items(target)
    # Remove items deleted from the repo so test mirrors the branch.
    unpublish_all_orphan_items(target)

    print(f"Deployment to '{args.workspace_name}' complete.")


if __name__ == "__main__":
    main()

Führen Sie die Bereitstellung aus

Verweisen Sie das Skript auf den Namen des Test-Arbeitsbereichs, den Terraform als test_workspace_name ausgegeben hat. Klone dein Repository (oder verwende die lokale Kopie, die der Entwickler committed hat), sodass die Item-Ordner lokal verfügbar sind, und führe dann:

python deploy.py \
  --workspace_name releaseflow-test \
  --environment test \
  --repository_directory ./workspace \
  --parameter_file ./parameter.yml

fabric-cicd erstellt das Lakehouse und Notebook in der Testumgebung, wendet find_replace Regeln an und meldet jedes veröffentlichte Element.

Schritt 5: Verifizieren Sie die Beförderung

Bestätigen Sie, dass der Test eine korrekt zurückgebundene Kopie des Inhalts erhalten hat:

1. Im Fabric-Portal öffnen Sie den releaseflow-test Arbeitsbereich.
2. Bestätigen Sie, dass demoLakehouse und demoNotebook jetzt existieren.
3. Öffne demoNotebook und bestätige, dass das Standard-Lakehouse testdemoLakehouse ist, nicht das Dev-Lakehouse.
4. Führen Sie das Notizbuch aus. Es sollte das Test-Seehaus lesen und schreiben.

Du hast jetzt einen wiederholbaren Ablauf: Ändere Elemente in der Entwicklungsumgebung, committe sie in Git und führe deploy.py erneut aus, um sie in die Testumgebung zu übernehmen.

Automatisieren in Azure DevOps

Alles, was du lokal ausgeführt hast, nutzt denselben Dienstprinzipal wie eine Pipeline, daher ist der Wechsel zu CI/CD im Wesentlichen nur noch eine Frage, diese Befehle in Pipeline-Phasen unterzubringen: In einer Phase wird terraform apply ausgeführt (Steuerebene), in einer späteren Phase deploy.py (Datenebene). Für einen vollständigen, geschlossenen Azure Pipelines-Walkthrough der Fabric-cicd-Bereitstellungsphase, einschließlich Variablengruppen und Genehmigungen, siehe Tutorial: CI/CD using Azure DevOps und die fabric-cicd-Bibliothek.

Erweitern Sie dieses Tutorial

Dieses Tutorial verwendet ein Notizbuch und ein Seehaus. Das gleiche Muster skaliert auf einen größeren Teil der Datenebene:

• Füge SemanticModel und Report zu ITEM_TYPES hinzu und füge in semantic_model_binding eine parameter.yml-Regel hinzu, damit Modelle auf die Verbindung der jeweiligen Umgebung verweisen.
• Füge ein VariableLibrary hinzu und lasse fabric-cicd den Wertesatz aktivieren, der dem --environment entspricht, den du übergibst.
• Fügen Sie nach publish_all_items einen Schritt nach der Bereitstellung hinzu (zum Beispiel ein semantisches Modell aktualisieren oder ein Smoke-Test-Notebook ausführen).

Bereinigen von Ressourcen

Um zu vermeiden, dass Kapazität verbraucht wird, lösche die von dir erstellten Arbeitsbereiche. Aus deinem Terraform-Ordner:

terraform destroy

Alternativ löschen Sie die Arbeitsbereiche releaseflow-dev und releaseflow-test aus dem Fabric-Portal.

Verwandte Inhalte

• Was ist CI/CD in Microsoft Fabric?
• CI/CD-Workflowoptionen in Fabric
• Lernprogramm: CI/CD mit Azure DevOps und der fabric-cicd-Bibliothek
• Tutorial: CI/CD unter Verwendung der Fabric Bulk API
• Tutorial: Anwendungslebenszyklusverwaltung in Fabric
• Microsoft Fabric Terraform-Anbieter
• Dokumentation der fabric-cicd-Bibliothek