Vejledning: End-to-end automatisering i Fabric

I denne vejledning bygger du et komplet, gentageligt releaseflow for Microsoft Fabric ved hjælp af infrastruktur som kode. Du provisionerer to workspaces (dev og test) med Terraform, forbinder dev-workspace til Git, opretter et element i dev og promoverer det derefter til test med fabric-cicd Python-biblioteket. Alt kører under en enkelt serviceprincip, så det samme flow fungerer på din bærbare i dag og i en CI/CD-pipeline i morgen.

I dette selvstudium skal du:

To planer, to værktøjer

Automatisering af en Fabric-udgivelse har to tydelige bekymringer, og det hjælper med at holde dem adskilt: det stabile kontrolplan (infrastrukturen, dit indhold ligger i) og det flygtige dataplan (det indhold, du redigerer hver dag). Match deployment-værktøjet til, hvor ofte hver ting ændrer sig.

• Kontrolplanet indeholder ikke-flygtig infrastruktur, som du provisionerer én gang og sjældent ændrer: kapaciteter, arbejdsområder og deres indstillinger, domæner, forbindelser, lejerindstillinger samt RBAC- og Git-kabler. Denne tutorial forsyner den med Terraform.
• Dataplanet indeholder flygtigt indhold, der udvikler hver sprint og flyder gennem Git: notesbøger, lakehouses og warehouses, semantiske modeller og rapporter, pipelines og dataflows samt værdier i variabelbiblioteket. Denne tutorial flytter den med fabric-cicd.

Den ledende idé: at provisionere den stabile platform én gang med Terraform, og derefter lade flygtige genstande flyde kontinuerligt gennem Git og fabric-cicd.

Dette er en tilgang til automatisering af Fabric, og det favoriserer teams, der allerede behandler infrastruktur som kode og ønsker en scriptbar, kildekontrolleret opsætning. Fabric tilbyder også portalbaserede deploymentspipelines og Git-integration, som du kan styre fra UI'en uden at skulle skrive Terraform eller Python. For en sammenligning af mulighederne, se CI/CD workflow-muligheder i Fabric.

Specifikt for dataplan-udrulningen er fabric-cicd en mulighed. Du kan også kalde Fabric bulk (CRUD) REST API'erne direkte, hvis du vil have fuld kontrol over oprettelse, opdatering og sletning uden at blive afhængig af biblioteket. Denne tutorial bruger fabric-cicd, fordi den håndterer den miljøspecifikke rebinding for dig.

Hvorfor terraform til kontrolplanet

• Deklarativ og idempotent. Du beskriver den ønskede tilstand af dine arbejdsområder én gang; Terraform skaber det, der mangler, og lader resten være.
• Drift-detektion. terraform plan viser præcis, hvordan den levende lejer adskiller sig fra din sandhedskilde, så en ændring uden for båndet i portalen bliver synlig og reversibel.
• En udbyder for mange ressourcer. Microsoft Fabric-udbyderen administrerer arbejdsområder, kapaciteter, forbindelser, Git-links og RBAC via Fabric REST API'erne.

Hvorfor fabric-cicd for dataplanet

• Udsendes, som Fabric forventer. fabric-cicd læser Git-repræsentationen af dine elementer og offentliggør dem med den korrekte create-or-update-semantik, så du ikke ruller REST-kald manuelt.
• Parameterisering. En parameter.yml fil ombinder miljøspecifikke værdier, såsom at pege en notesbogs standard lakehouse eller en semantisk models forbindelse mod det rigtige mål for hvert miljø.
• Oprydning. Den kan afpublicere elementer, der er fjernet fra Git, og dermed bevare hvert miljø som et trofast spejlbillede af den gren, den følger.

Den ende-til-ende flow

De to planer samles som en enkelt, kontinuerlig automatisering. Du provisionerer platformen én gang, og fra da af følger hver indholdsændring den samme gentagelige løkke—fra din editor, via Git, ind i testmiljøet—uden manuelle portaltrin imellem.

Den samme serviceprincipal autentificerer hvert trin, så det flow, du kører manuelt i denne tutorial, er præcis det, en CI/CD-pipeline kører på dine vegne: et provision-trin (Terraform), derefter et deploy-trin (fabric-cicd), der kører, når den trackede branch ændres. Hver bane korresponderer til et trin nedenfor:

Forudsætninger

• En Fabric-kapacitet. Begge arbejdsområder i denne vejledning er tildelt samme kapacitet. En prøvekapacitet virker.
• En serviceprincipal (Microsoft Entra app-registrering) med en klienthemmelighed. Denne ene identitet leverer arbejdsområderne og kører udrulningen.
• Lejerindstillingen Service principals kan bruge Fabric API'er aktiveret for en sikkerhedsgruppe, der indeholder service principalen. For mere information, se Aktiver service principal authentication for Fabric APIs.
• En Azure DevOps-organisation, projekt og Git-repository, som serviceprincipalen kan få adgang til. Repositoryet skal allerede indeholde grenen (for eksempel main) og den mappe, du har sat i ado_directory_name (for eksempel /workspace). Git-forbindelsen bruger PreferRemote, som læser den mappe på grenen, når den forbinder, så begge skal eksistere på forhånd. Hvis mappen mangler, terraform apply fejler med GitProviderResourceNotFound. For at oprette den, committer du en tom pladsholderfil (såsom .gitkeep) til den sti på branchen, før du kører Terraform.
• Følgende værktøjer installeres lokalt:
  • Terraform 1.8 eller nyere.
  • Python 3.9 eller nyere (op til 3.13).
  • Azure CLI.

Konfigurer godkendelse

Både Terraform og fabric-cicd autentificerer sig som tjenestehovedmand. Eksporter dens legitimationsoplysninger som miljøvariabler, så begge værktøjer 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

Trin 1: Provisioner arbejdsområderne med Terraform

I dette trin definerer du kontrolplanet som kode og anvender det. Opret en mappe til din Terraform-konfiguration og tilføj følgende filer.

Konfigurér udbyderen

Skab provider.tf. At fastgøre udbyderversionen sikrer, at hver ingeniør opfører sig på samme måde.

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

Deklarer inputtene

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

Definér ressourcerne

Skab main.tf. Denne konfiguration skaber to arbejdsområder, en source-control-forbindelse, Git-linket på udvikleren og rolletildelinger.

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

Deklarér outputtene

Skab outputs.tf. Testarbejdsområdets navn fodrer udrulningstrinnet.

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
}

Anvend konfigurationen

Giv værdier til variablerne (for eksempel i en terraform.tfvars fil, du holder ude af Git), og kør derefter:

terraform init
terraform plan
terraform apply

Terraform rapporterer de ressourcer, den har skabt, og printer outputtene.

Udfordringer med provisionering, du bør kende til

Fabric-leverandøren er stærk, men nogle adfærdsmønstre får folk til at snuble. Husk disse, før du kører dette i produktion:

• Git-forbindelsen kan ikke importeres. Ressourcen, der fabric_workspace_git understøtter terraform importikke . Behandl det som en engangs-bootstrap og behold det i fjerntilstand, så senere kørsler ikke forsøger at genskabe det. Gem din tilstand i en delt backend som Azure Storage i stedet for på en enkelt bærbar computer.
• Små og små bogstavsfølsomme Git-navne. Fabric API'en returnerer Azure DevOps-projekt- og repositorynavne med små bogstaver. Hvis du består dem i blandede tilfælde, rapporterer Terraform: "udbyder producerede inkonsekvent resultat efter ansøgning." Indpak dem i lower(), som vist ovenfor.
• Serviceprincips omfang. Den samme identitet skal kunne oprette arbejdsområder på kapaciteten og tilføjes som arbejdsområdemedlem. Hvis provisionering fejler med en autorisationsfejl, skal du tjekke lejerindstillingen og kapacitetsrolle-tildelingen ud fra forudsætningerne.
• Hemmeligheder skal holdes uden for staten, hvor det er muligt. Forbindelseshemmeligheden bruger skrive-kun client_secret_wo argumentet, så den ikke gemmes i klarteksttilstand. Beskyt dog din statsfil som følsom.

Trin 2: Verificér Git-forbindelsen

Terraform har allerede forbundet udviklingsarbejdsområdet til Git i trin 1. Bekræft det:

1. I Fabric-portalen åbner du arbejdsområdetreleaseflow-dev.
2. Vælg Workspace-indstillinger>Git-integration.
3. Bekræft, at arbejdsområdet er forbundet til din Azure DevOps-organisation, projekt, repository, branch og den mappe, du har sat iado_directory_name.

Trin 3: Lav indhold i dev og commit det

Tilføj nu indhold til dev-arbejdsområdet og skub det til Git. I denne vejledning opretter du to ting: et søhus og en notesbog, der læser fra det.

1. I releaseflow-dev, opret et lakehouse kaldet demoLakehouse.
2. Opret en notesbog ved navn demoNotebook. Vedhæft demoLakehouse som standard søhus og tilføj en celle, der læser en tabel eller skriver en lille eksempelDataFrame.
3. Kør notesbogen én gang for at bekræfte, at den virker mod udviklerens lakehouse.
4. Open Source-kontrol i arbejdsområdet, vælg begge elementer, og commit dem til din branch.

Efter commiten indeholder dit repository en demoLakehouse.Lakehouse mappe og en demoNotebook.Notebook mappe under den mappe, du har konfigureret.

Trin 4: Deploy fra udvikler til test med fabric-cicd

Testarbejdsområdet er stadig tomt. Brug fabric-cicd til at udgive elementerne fra Git i test, og bind notesbogen til test-lakehouse undervejs.

Installer fabric-cicd

Opret requirements.txt:

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

Installer den:

pip install -r requirements.txt

Tilføj en parameterfil

Notesbogen, der er gemt i Git, peger på udviklingssøhuset og udviklingsarbejdsområdet . Når du deployer for at teste, skal disse referencer ændres, så notebooken læser og skriver testdata. fabric-cicd gør dette med en parameter.yml fil.

Opret parameter.yml ved siden af dit deployment-script. Erstat de to pladsholder-GUID'er med det faktiske dev lakehouse ID og dev workspace ID, der vises i dit dedikerede notesbogsindhold:

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 af fabric-cicd ved deployering til GUID'erne i målarbejdsområdet .

Skriv deployment-scriptet

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

Kør udrulningen

Peg scriptet mod navnet på testarbejdsområdet, som Terraform har udskrevet som test_workspace_name. Klon dit repo (eller genbrug den lokale kopi, som udvikleren har committet), så item-mapperne er tilgængelige lokalt, og kør så:

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

Fabric-CicD opretter Lakehouse og notesbogen i testen, anvender find_replace reglerne og rapporterer hvert offentliggjort element.

Trin 5: Verificér forfremmelsen

Bekræft, at testen modtog en korrekt rebound kopi af indholdet:

1. I Fabric-portalen åbner du arbejdsområdetreleaseflow-test.
2. Bekræft at demoLakehouse og demoNotebook nu eksisterer.
3. Åbn demoNotebook og bekræft, at det er standard-lakehouse, der er testendemoLakehouse, ikke udvikleren.
4. Kør notesbogen. Den skal læse og skrive test-lakehouse.

Du har nu en gentagelig livscyklus: skift elementer i udviklingen, commit til Git og kør deploy.py igen for at promovere til test.

Automate in Azure DevOps

Alt, hvad du kørte lokalt, bruger det samme serviceprincip, som en pipeline bruger, så overgangen til CI/CD handler mest om at placere disse kommandoer i pipeline-faser: ét-trins kørsler terraform apply (kontrolplan), senere faser deploy.py (dataplan). For en fuld, gated Azure Pipelines gennemgang af fabric-cicd deployment-fasen, inklusive variabelgrupper og godkendelser, se Tutorial: CI/CD using Azure DevOps og fabric-cicd-biblioteket.

Forlænge denne vejledning

Denne vejledning bruger en notesbog og et sommerhus ved søen. Det samme mønster skalerer til mere af dataplanet:

• Tilføj SemanticModel og Report til ITEM_TYPES og tilføj en semantic_model_binding regel i parameter.yml for at pege modeller på hver miljøs forbindelse.
• Tilføj a VariableLibrary og lad fabric-cicd aktivere det værdisæt, der matcher you --environment pass.
• Tilføj et post-deploy-trin (for eksempel opdater en semantisk model eller kør en røgtest-notebook) efter publish_all_items.

Fjerne ressourcer

For at undgå at forbruge kapacitet, fjern de arbejdsområder, du har oprettet. Fra din Terraform-mappe:

terraform destroy

Alternativt kan du releaseflow-dev slette og releaseflow-test workspaces fra Fabric-portalen.

Relateret indhold

• Hvad er CI/CD i Microsoft Fabric?
• Indstillinger for CI/CD-arbejdsproces i Fabric
• Tutorial: CI/CD ved brug af Azure DevOps og fabric-cicd-biblioteket
• Tutorial: CI/CD ved brug af Fabric bulk API'en
• Vejledning: Applikationslivscyklusstyring i Fabric
• Microsoft Fabric Terraform-udbyder
• Fabric-CICD Biblioteksdokumentation