Veiledning: End-to-end automatisering i Fabric

I denne veiledningen bygger du en komplett, repeterbar release-flyt for Microsoft Fabric ved å bruke infrastruktur som kode. Du provisjonerer to arbeidsområder (dev og test) med Terraform, kobler dev-workspace til Git, oppretter et element i dev, og promoterer det deretter til testing med fabric-cicd Python-biblioteket. Alt kjører under ett enkelt tjenesteprinsipp, så samme flyt fungerer på laptopen din i dag og i en CI/CD-pipeline i morgen.

I denne opplæringen:

To fly, to verktøy

Automatisering av en Fabric-utgivelse har to distinkte bekymringer, og det hjelper å holde dem adskilt: det stabile kontrollplanet (infrastrukturen innholdet ditt befinner seg i) og det volatile dataplanet (innholdet du redigerer hver dag). Match distribusjonsverktøyet til hvor ofte hver ting endres.

• Kontrollplanet inneholder ikke-flyktig infrastruktur som du provisionerer én gang og sjelden endrer: kapasiteter, arbeidsområder og deres innstillinger, domener, tilkoblinger, leietakerinnstillinger og RBAC- og Git-kabler. Denne veiledningen gir den Terraform.
• Dataplanet inneholder flyktig innhold som utvikler hver sprint og flyter gjennom Git: notatbøker, innsjøhus og lagre, semantiske modeller og rapporter, pipelines og dataflyter, og verdier i variabelbibliotek. Denne veiledningen flytter den med fabric-cicd.

Den ledende ideen: å forberede den stabile plattformen én gang med Terraform, og deretter la flyktige gjenstander flyte kontinuerlig gjennom Git og fabric-cicd.

Dette er en tilnærming til automatisering av Fabric, og det favoriserer team som allerede behandler infrastruktur som kode og ønsker et skriptbasert, kildekontrollert oppsett. Fabric tilbyr også portalbaserte distribusjonspipelines og Git-integrasjon, som du kan styre fra brukergrensesnittet uten å skrive Terraform eller Python. For en sammenligning av alternativene, se CI/CD-arbeidsflytalternativer i Fabric.

For dataplan-distribusjon spesielt er fabric-cicd ett alternativ. Du kan også kalle Fabric bulk (CRUD) REST-API-ene direkte hvis du vil ha full kontroll over opprettelse, oppdatering og sletting uten å bli avhengig av biblioteket. Denne veiledningen bruker fabric-cicd fordi den håndterer den miljøspesifikke ombindingen for deg.

Hvorfor terraform for kontrollplanet

• Deklarativ og idempotent. Du beskriver ønsket tilstand for arbeidsområdene dine én gang; Terraform skaper det som mangler og lar resten være i fred.
• Driftdeteksjon. terraform plan Viser nøyaktig hvordan den levende leietakeren skiller seg fra sannhetskilden din, slik at en endring utenfor båndet i portalen blir synlig og reversibel.
• Én leverandør for mange ressurser. Microsoft Fabric-leverandøren administrerer arbeidsområder, kapasiteter, tilkoblinger, Git-lenker og RBAC gjennom Fabric REST API-ene.

Hvorfor fabric-cicd for dataplanet

• Distribuerer slik Fabric forventer. fabric-cicd leser Git-representasjonen av elementene dine og publiserer dem med korrekt opprettelses- eller oppdateringssemantikk, slik at du ikke ruller REST-kall manuelt.
• Parameterisering. En parameter.yml fil binder om miljøspesifikke verdier, for eksempel ved å peke en notatboks standard lakehouse eller en semantisk modells tilkobling mot riktig mål per miljø.
• Opprydding. Den kan avpublisere elementer som ble fjernet fra Git, og beholde hvert miljø som et trofast speilbilde av grenen den sporer.

Den ende-til-ende-flyten

De to planene samles som en enkelt, kontinuerlig automatisering. Du provisjonerer plattformen én gang, og fra da av følger hver innholdsendring den samme repeterbare løkken—fra editoren din, gjennom Git, inn i testmiljøet—uten manuelle portalsteg imellom.

Den samme tjenesteprinsippet autentiserer hvert trinn, så flyten du kjører manuelt i denne veiledningen er nøyaktig det en CI/CD-pipeline kjører på dine vegne: en provision-fase (Terraform), deretter en deploy-fase (fabric-cicd) som kjører hver gang den sporede grenen endres. Hver etappe viser et trinn nedenfor:

Forutsetninger

• En Fabric-kapasitet. Begge arbeidsområdene i denne veiledningen er tildelt samme kapasitet. En prøvekapasitet fungerer.
• En tjenesteleder (Microsoft Entra appregistrering) med en klienthemmelighet. Denne ene identiteten oppretter arbeidsområdene og kjører distribusjonen.
• Leietakerinnstillingen Service principals kan bruke Fabric API-er aktivert for en sikkerhetsgruppe som inneholder tjenesteprincipalen. For mer informasjon, se Aktiver autentisering av tjenesteprinsipper for Fabric API-er.
• Et Azure DevOps-organisasjons-, prosjekt- og Git-repositorium som tjenesteprincipalen kan få tilgang til. Repositoriet må allerede inneholde grenen (for eksempel main) og mappen du har satt i ado_directory_name (for eksempel /workspace). Git-tilkoblingen bruker PreferRemote, som leser den mappen på grenen når den kobler til, så begge må eksistere på forhånd. Hvis mappen mangler, terraform apply feiler med GitProviderResourceNotFound. For å opprette den, committer du en tom plassholderfil (som .gitkeep) til den stien på grenen før du kjører Terraform.
• Følgende verktøy installert lokalt:
  • Terraform 1.8 eller nyere.
  • Python 3.9 eller nyere (opp til 3.13).
  • The Azure CLI.

Konfigurere godkjenning

Både Terraform og fabric-cicd autentiserer seg som tjenesteprincipal. Eksporter legitimasjonen som miljøvariabler slik at begge verktøyene kan hente dem:

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

Trinn 1: Provisioner arbeidsområdene med Terraform

I dette steget definerer du kontrollplanet som kode og anvender det. Lag en mappe for Terraform-konfigurasjonen din og legg til følgende filer.

Konfigurer leverandøren

Lag provider.tf. Å feste leverandørversjonen gjør at alle ingeniører oppfører seg på samme måte.

# 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
}

Erklær inputene

Lag 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
}

Definer ressursene

Lag main.tf. Denne konfigurasjonen skaper to arbeidsområder, en kildekontrollforbindelse, Git-lenken på utvikling, og rollefordelinger.

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"
  }
}

Erklær utgangene

Lag outputs.tf. Testarbeidsområdets navn mater distribusjonssteget.

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
}

Bruk konfigurasjonen

Oppgi verdier for variablene (for eksempel i en terraform.tfvars fil du holder utenfor Git), og kjør deretter:

terraform init
terraform plan
terraform apply

Terraform rapporterer ressursene den har laget og skriver ut resultatene.

Forsyningsutfordringer å kjenne til

Fabric-leverandøren er kraftfull, men noen atferder snubler folk. Husk disse før du kjører dette i produksjon:

• Git-tilkoblingen kan ikke importeres. Ressursen fabric_workspace_git støtter terraform importikke . Behandle det som en engangs bootstrap og oppretthold det i fjern tilstand slik at senere kjøringer ikke prøver å gjenskape det. Lagre tilstanden din i en delt backend som Azure Storage i stedet for på én enkelt laptop.
• Git-navn som er følsomme for små og små bokstaver. Fabric API returnerer Azure DevOps-prosjekt- og repository-navn med små bokstaver. Hvis du består dem i blandet tilfelle, rapporterer Terraform "leverandør produserte inkonsekvent resultat etter søknad." Pakk dem inn i lower(), som vist ovenfor.
• Tjenesteprinsippets omfang. Den samme identiteten må kunne opprette arbeidsområder på kapasiteten og legges til som arbeidsområdemedlem. Hvis provisjonen feiler med en autorisasjonsfeil, sjekk leietakerinnstillingen og kapasitetsrolletilordningen på nytt fra forutsetningene.
• Hemmeligheter holdes utenfor staten der det er mulig. Tilkoblingshemmeligheten bruker kun skrive-argumentet client_secret_wo , så den lagres ikke i klarteksttilstand. Likevel, beskytt delstatsfilen din som sensitiv.

Steg 2: Verifiser Git-tilkoblingen

Terraform koblet allerede utviklingsarbeidsområdet til Git i steg 1. Bekreft det:

1. I Fabric-portalen, åpne releaseflow-dev arbeidsområdet.
2. Velg Workspace-innstillinger>Git-integrasjon.
3. Bekreft at arbeidsområdet er koblet til din Azure DevOps-organisasjon, prosjekt, repository, branch og mappen du har satt iado_directory_name.

Trinn 3: Lag innhold i utviklingen og forplikt det

Legg nå til innhold i utviklerarbeidsområdet og flytt det til Git. I denne veiledningen lager du to gjenstander: et innsjøhus og en notatbok som leser fra det.

1. I releaseflow-dev, opprett et innsjøhus kalt demoLakehouse.
2. Lag en notatbok som heter demoNotebook. Legg til demoLakehouse som standard lakehouse og legg til en celle som leser en tabell eller skriver et lite eksempel DataFrame.
3. Kjør notatboken én gang for å bekrefte at den fungerer mot utviklerens lakehouse.
4. Open Source-kontroll i arbeidsområdet, velg begge elementene, og commit dem til din gren.

Etter commiten inneholder repositoriet ditt en demoLakehouse.Lakehouse mappe og en demoNotebook.Notebook mappe under mappen du konfigurerte.

Trinn 4: Distribuer fra utvikler til test med fabric-cicd

Testarbeidsområdet er fortsatt tomt. Bruk fabric-cicd for å publisere elementene fra Git i test, og bind notatboken til testhuset underveis.

Installer fabric-cicd

Lag requirements.txt:

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

Installer den:

pip install -r requirements.txt

Legg til en parameterfil

Notatboken som er lagret i Git peker på dev lakehouse og dev workspace. Når du deployerer for å teste, må disse referansene endres slik at notatboken leser og skriver testdata. fabric-cicd gjør dette med en parameter.yml fil.

Lag parameter.yml ved siden av deployeringsskriptet ditt. Bytt ut de to plassholder-GUID-ene med den faktiske dev lakehouse-ID-en og dev workspace-ID-en som vises i innholdet i din dedikerte notatbok:

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"

Og $items.Lakehouse.demoLakehouse.$id$workspace.$id tokens løses av fabric-cicd ved deploying til GUID-ene i målarbeidsområdet .

Skriv distribusjonsskriptet

Lag 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()

Kjør utplasseringen

Pek skriptet mot navnet på testarbeidsområdet som Terraform skrev ut som test_workspace_name. Klon repoet ditt (eller bruk den lokale kopien utvikleren kommitterte) slik at item-mappene er tilgjengelige lokalt, og kjør deretter:

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

Fabric-CICD oppretter innsjøhuset og notatboken i testen, anvender reglene find_replace og rapporterer hver publiserte post.

Trinn 5: Verifiser forfremmelsen

Bekreft at testen mottok en korrekt rebound-kopi av innholdet:

1. I Fabric-portalen, åpne releaseflow-test arbeidsområdet.
2. Bekreft at demoLakehouse og demoNotebook nå eksisterer.
3. Åpne demoNotebook og bekreft at standard lakehouse er testendemoLakehouse, ikke utvikleren.
4. Kjør notatboken. Den skal stå og skrive testinnsjøhuset.

Du har nå en repeterbar livssyklus: endre elementer i utviklingen, committe til Git, og kjøre deploy.py på nytt for å promotere til test.

Automate in Azure DevOps

Alt du kjørte lokalt bruker samme tjenesteprinsipp som en pipeline bruker, så overgangen til CI/CD handler stort sett om å plassere disse kommandoene i pipeline-faser: ett-trinns kjøringer terraform apply (kontrollplan), senere faser deploy.py (dataplan). For en fullstendig, gated Azure Pipelines-gjennomgang av fabric-cicd-distribusjonsfasen, inkludert variabelgrupper og godkjenninger, se Veiledning: CI/CD ved bruk av Azure DevOps og fabric-cicd-biblioteket.

Utvid denne veiledningen

Denne veiledningen bruker en notatbok og et hytte ved innsjøen. Det samme mønsteret skalerer til mer av dataplanet:

• Legg til SemanticModel og Report til ITEM_TYPES og legg til en semantic_model_binding regel i parameter.yml for å peke modeller på hvert miljøs forbindelse.
• Legg til en VariableLibrary og la fabric-cicd aktivere verdisettet som matcher --environment you pass.
• Legg til et steg etter utrulling (for eksempel oppdater en semantisk modell eller kjør en røyktestnotatbok) etter publish_all_items.

Fjerning av ressurser

For å unngå å bruke kapasitet, fjern arbeidsområdene du har opprettet. Fra din Terraform-mappe:

terraform destroy

Alternativt kan du slette releaseflow-dev og releaseflow-test arbeidsområdene fra Fabric-portalen.

Relatert innhold

• Hva er CI/CD i Microsoft Fabric?
• Alternativer for CI/CD-arbeidsflyt i Fabric
• Veiledning: CI/CD ved bruk av Azure DevOps og fabric-cicd-biblioteket
• Veiledning: CI/CD ved bruk av Fabric bulk API
• Veiledning: Applikasjonslivssyklusstyring i Fabric
• Microsoft Fabric Terraform-leverandør
• Fabric-CICD-bibliotekdokumentasjon