Tutorial: Automazione dall'inizio alla fine in Fabric

In questo tutorial, costruisci un flusso di rilascio completo e ripetibile per Microsoft Fabric usando l'infrastruttura come codice. Fornisci due workspace (dev e test) con Terraform, colleghi lo workspace dev a Git, crei un elemento in dev e poi lo promuovi per testare con la libreria Python di fabric-cicid. Tutto funziona sotto un unico principio di servizio, quindi lo stesso flusso funziona oggi sul tuo portatile e in una pipeline CI/CD domani.

In questa esercitazione, imparerai a:

Due piani, due attrezzi

L'automazione di un rilascio Fabric presenta due preoccupazioni distinte, e aiuta a mantenerle separate: il piano di controllo stabile (l'infrastruttura in cui risiede il tuo contenuto) e il piano dati volatile (il contenuto che modifichi ogni giorno). Abbina lo strumento di distribuzione con la frequenza con cui ogni cosa cambia.

• Il piano di controllo contiene infrastrutture non volatili che si approvvigionano una volta e raramente si modificano: capacità, spazi di lavoro e le loro impostazioni, domini, connessioni, impostazioni del tenant e cablaggio RBAC e Git. Questo tutorial lo fornisce con Terraform.
• Il piano dati contiene contenuti volatili che si sviluppano ad ogni sprint e scorrono attraverso Git: notebook, lakehouse e warehouse, modelli semantici e report, pipeline e flussi di dati, e valori delle Librerie Variabili. Questo tutorial lo sposta con fabric-cicd.

L'idea guida: fornire la piattaforma stabile una volta con Terraform, poi lasciare che gli oggetti volatili fluiscano continuamente attraverso Git e fabric-cicd.

Questo è un approccio per automatizzare Fabric, e favorisce team che già trattano l'infrastruttura come codice e desiderano una configurazione scriptabile e controllata dal sorgente. Fabric offre anche pipeline di distribuzione basate su portali e integrazione con Git, che puoi gestire dall'interfaccia utente senza dover scrivere Terraform o Python. Per un confronto delle opzioni, vedi le opzioni di flusso di lavoro CI/CD in Fabric.

Per la distribuzione del piano dati nello specifico, fabric-cicd è una delle opzioni. Puoi anche chiamare direttamente le API REST di Fabric bulk (CRUD) se vuoi avere il pieno controllo sulle chiamate di creazione, aggiornamento e cancellazione senza assumere una dipendenza dalla libreria. Questo tutorial usa fabric-cicd perché gestisce automaticamente la ridefinizione specifica dell'ambiente.

Perché Terraform per il piano di controllo

• Dichiarativo e idempotente. Descrivi lo stato desiderato dei tuoi spazi di lavoro una volta; Terraform crea ciò che manca e lascia il resto in pace.
• Rilevamento della deriva. terraform plan Mostra esattamente come il tenant live differisce dalla tua fonte di verità, così un cambiamento fuori banda nel portale diventa visibile e reversibile.
• Un unico fornitore per molte risorse. Il provider Microsoft Fabric gestisce spazi di lavoro, capacità, connessioni, Git link e RBAC tramite le API Fabric REST.

Perché scegliere fabric-cicd per il piano dati

• Viene distribuito nel modo previsto da Fabric. fabric-cicd legge la rappresentazione Git dei tuoi elementi e li pubblica con la semantica corretta di creare o aggiornare, così non devi fare manualmente le chiamate REST.
• Parametrizzazione. Un file parameter.yml rimappa i valori specifici dell'ambiente, ad esempio facendo puntare il lakehouse predefinito di un notebook o la connessione di un modello semantico alla destinazione corretta per ogni ambiente.
• Pulizia. Può annullare la pubblicazione degli elementi rimossi da Git, mantenendo ogni ambiente come una copia fedele del ramo che segue.

Il flusso dall'inizio alla fine

I due piani si uniscono in un'unica automazione continua. Predisponi la piattaforma una sola volta, e da quel momento ogni modifica ai contenuti segue lo stesso ciclo ripetibile, dal tuo editor, attraverso Git, fino all'ambiente di test, senza alcun passaggio manuale nel portale.

Lo stesso principio di servizio autentica ogni fase, quindi il flusso che esegui manualmente in questo tutorial è esattamente quello che una pipeline CI/CD gestisce per te: uno stadio di provisioning (Terraform), poi uno stadio di distribuzione (fabric-cicd) che si attiva ogni volta che il branch tracciato cambia. Ogni livello è corrispondente a un passo sotto:

Prerequisiti

• Una capacità di Fabric. Entrambi gli spazi di lavoro in questo tutorial sono assegnati alla stessa funzione. Una capacità di prova funziona.
• Un service principal (registrazione dell'app Microsoft Entra) con un segreto client. Questa unica identità fornisce i workspace e gestisce la distribuzione.
• L'impostazione del tenant I service principal possono usare le API di Fabric è abilitata per un gruppo di sicurezza che contiene l'entità servizio. Per ulteriori informazioni, vedere Abilitare l'autenticazione dell'entità servizio per le API di Fabric.
• Un'organizzazione, un progetto e un repository Git di Azure DevOps a cui l'entità servizio può accedere. Il repository deve già contenere il branch (ad esempio, main) e la cartella che hai impostato ado_directory_name (ad esempio, /workspace). La connessione Git usa PreferRemote, che legge quella cartella sul branch quando si connette, quindi entrambe devono esistere in precedenza. Se manca la cartella, terraform apply fallisce con GitProviderResourceNotFound. Per crearlo, esegui il commit di un file segnaposto vuoto (ad esempio .gitkeep) in quel percorso nel branch prima di eseguire Terraform.
• I seguenti strumenti installati localmente:
  • Terraform 1.8 o versione successiva.
  • Python 3.9 o successivo (fino alla 3.13).
  • interfaccia della riga di comando di Azure.

Configurare l'autenticazione

Sia Terraform che fabric-cicd si autenticano come principale di servizio. Esporta le sue credenziali come variabili ambientali così che entrambi gli strumenti possano rilevarle:

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

Passo 1: Provisiona gli spazi di lavoro con Terraform

In questo passaggio, definisci il piano di controllo come codice e lo applichi. Crea una cartella per la configurazione di Terraform e aggiungi i seguenti file.

Configura il provider

Crea provider.tf. Bloccare la versione del provider garantisce a tutti gli ingegneri un comportamento identico.

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

Dichiara gli input

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

Definisci le risorse

Crea main.tf. Questa configurazione crea due aree di lavoro, una connessione al controllo della versione, il collegamento Git in dev e assegnazioni di ruolo.

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

Dichiara le uscite

Crea outputs.tf. Il nome dello spazio di lavoro di test alimenta il passaggio di implementazione.

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
}

Applicare la configurazione

Fornisci i valori per le variabili (ad esempio, in un terraform.tfvars file che tieni fuori da Git), poi esegui:

terraform init
terraform plan
terraform apply

Terraform riporta le risorse create e stampa i risultati.

Sfide del provisioning da tenere presenti

Il fornitore Fabric è potente, ma alcuni comportamenti mettono in difficoltà le persone. Tieni a mente questi aspetti prima di farlo partire in produzione:

• La connessione Git non può essere importata. La fabric_workspace_git risorsa non supporta terraform import. Trattalo come un’operazione di bootstrap eseguita una sola volta e salvalo nello stato remoto, così le esecuzioni successive non tenteranno di ricrearlo. Salva il tuo stato in un backend condiviso come Archiviazione di Azure invece che su un singolo laptop.
• Nomi Git con distinzione tra maiuscole e minuscole. L'API Fabric restituisce i nomi dei progetti e dei repository di Azure DevOps in lettere minuscole. Se li passi con maiuscole e minuscole, Terraform riporta "il provider ha prodotto un risultato incoerente dopo l'applicazione." Racchiudili in lower(), come mostrato sopra.
• Ambito principale del servizio. La stessa identità deve essere in grado di creare spazi di lavoro nella capacità ed essere aggiunta come membro dello spazio di lavoro. Se il provisioning non riesce a causa di un errore di autorizzazione, ricontrolla l'impostazione del tenant e l'assegnazione del ruolo della capacità nei prerequisiti.
• I segreti vengono mantenuti al di fuori dello stato, ove possibile. Il connection secret utilizza l'argomento write-only client_secret_wo quindi non viene memorizzato nello stato di testo chiaro. Tuttavia, proteggi il tuo file di stato come dato sensibile.

Passo 2: Verifica la connessione Git

Terraform ha già collegato lo spazio di sviluppo a Git nel Passo 1. Conferma:

1. Nel portale Fabric, apri lo releaseflow-dev spazio di lavoro.
2. Selezionare Impostazioni dell'area di lavoro>Integrazione Git.
3. Conferma che lo spazio di lavoro sia collegato alla tua organizzazione Azure DevOps, progetto, repository, branch e alla cartella in cui hai impostatoado_directory_name.

Passo 3: Crea contenuti nell'ambiente di sviluppo ed esegui il commit

Ora aggiungi contenuti allo spazio di sviluppo e inviali su Git. In questo tutorial crei due elementi: una casa sul lago e un quaderno che legge da essa.

1. In releaseflow-dev, crea una casa sul lago chiamata demoLakehouse.
2. Crea un quaderno chiamato demoNotebook. Associa demoLakehouse come lakehouse predefinita e aggiungi una cella per leggere una tabella o scrivere un piccolo DataFrame di esempio.
3. Esegui il notebook una volta per confermare che funzioni con il lakehouse di sviluppo.
4. Apri Controllo del codice sorgente nell'area di lavoro, seleziona entrambi gli elementi ed esegui il commit nel tuo branch.

Dopo il commit, il tuo repository contiene una demoLakehouse.Lakehouse cartella e una demoNotebook.Notebook cartella sotto la directory che hai configurato.

Passo 4: Distribuisci dall'ambiente di sviluppo a quello di test con fabric-cicd

L'area di lavoro di test è ancora vuota. Usa fabric-cicd per pubblicare gli elementi di Git nell'ambiente di test, ricollegando nel frattempo il notebook al lakehouse di test.

Installare fabric-cicd

Crea requirements.txt:

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

Installalo:

pip install -r requirements.txt

Aggiungi un file di parametri

Il notebook archiviato in Git punta al lakehouse dev e all'area di lavoro dev. Quando si deploya per testare, quei riferimenti devono cambiare affinché il quaderno legga e scriva i dati di test. Fabric-CICD fa questo con un parameter.yml file.

Crea parameter.yml accanto allo script di deployment. Sostituisci i due GUID provvisori con l'ID reale di dev lakehouse e l'ID dello spazio di lavoro di sviluppo che appaiono nel contenuto dedicato del tuo notebook:

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"

I token $items.Lakehouse.demoLakehouse.$id e $workspace.$id vengono risolti da fabric-cicd al momento della distribuzione nei GUID dell'area di lavoro di destinazione.

Scrivi lo script di distribuzione

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

Avviare la distribuzione

Punta lo script al nome dello spazio di lavoro di test che Terraform ha stampato come test_workspace_name. Clona il tuo repository (o riutilizza la copia locale che lo sviluppatore ha effettuato) in modo che le cartelle degli oggetti siano disponibili localmente, poi esegui:

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

fabric-cicd crea il lakehouse e il notebook nell'ambiente di test, applica le regole find_replace e segnala ogni elemento pubblicato.

Passo 5: Verifica la promozione

Conferma che il test ha ricevuto una copia corretta del contenuto:

1. Nel portale Fabric, apri lo releaseflow-test spazio di lavoro.
2. Conferma che demoLakehouse e demoNotebook ora esistono.
3. Apri demoNotebook e conferma che il lakehouse predefinito sia testdemoLakehouse, non quello di sviluppo.
4. Esegui il notebook. Dovrebbe leggere e scrivere il test della casa sul lago.

Ora hai un ciclo di vita ripetibile: modifica gli elementi nell’ambiente di sviluppo, esegui il commit in Git e riesegui deploy.py per promuovere in test.

Automatizzare in Azure DevOps

Tutto ciò che hai eseguito in locale usa la stessa entità servizio usata da una pipeline, quindi passare a CI/CD consiste principalmente nell’inserire questi comandi nelle fasi della pipeline: una fase esegue terraform apply (piano di controllo), una fase successiva esegue deploy.py (piano dati). Per una guida dettagliata di Azure Pipelines alla fase di distribuzione di fabric-cicd, con controlli di approvazione, inclusi i gruppi di variabili e le approvazioni, vedi Esercitazione: CI/CD con Azure DevOps e la libreria fabric-cicd.

Estendi questo tutorial

Questo tutorial include un quaderno e una casa sul lago. Lo stesso schema si scala a più parti del piano dati:

• Aggiungi SemanticModel e Report a ITEM_TYPES e aggiungi una regola semantic_model_binding in parameter.yml per indirizzare i modelli alla connessione di ciascun ambiente.
• Aggiungi un VariableLibrary e lascia che il fabric-cicd attivi il set di valori che corrisponde a quello --environment che superi.
• Aggiungi un passaggio post-deploy (ad esempio, l'aggiornamento di un modello semantico o l'esecuzione di un notebook di smoke test) dopo publish_all_items.

Pulire le risorse

Per evitare di consumare capacità, rimuovi gli spazi di lavoro che hai creato. Dalla tua cartella Terraform:

terraform destroy

In alternativa, elimina gli releaseflow-devreleaseflow-test spazi di lavoro dal portale Fabric.

Contenuti correlati

• Cos'è CI/CD in Microsoft Fabric?
• Opzioni del flusso di lavoro CI/CD in Fabric
• Esercitazione: CI/CD con Azure DevOps e la libreria fabric-cicd
• Tutorial: CI/CD usando l'API Fabric bulk
• Tutorial: Gestione del ciclo di vita delle applicazioni in Fabric
• Fornitore Microsoft Fabric Terraform
• Documentazione della libreria Fabric-CICD