Tutoriel : Automatisation de bout en bout dans Fabric

Dans ce tutoriel, vous construisez un flux de version complet et reproductible pour Microsoft Fabric en utilisant l’infrastructure comme code. Vous fournissez deux espaces de travail (dev et test) avec Terraform, connectez l’espace de travail dev à Git, créez un élément dans dev, puis le promouvez pour test avec la bibliothèque Python de fabric-cicd. Tout fonctionne sous un seul principe de service, donc le même flux fonctionne sur votre ordinateur portable aujourd’hui et dans un pipeline CI/CD demain.

Dans ce tutoriel, vous allez :

Deux plans, deux outils

L’automatisation d’une version Fabric comporte deux préoccupations distinctes, et cela aide à les séparer : le plan de contrôle stable (l’infrastructure dans laquelle se trouve votre contenu) et le plan de données volatile (le contenu que vous éditez chaque jour). Associez l’outil de déploiement à la fréquence à laquelle chaque élément change.

• Le plan de contrôle contient une infrastructure non volatile que vous provisionnez une fois et que vous modifiez rarement : capacités, espaces de travail et leurs paramètres, domaines, connexions, paramètres locataires, ainsi que câblage RBAC et Git. Ce tutoriel le fournit avec Terraform.
• Le plan de données contient du contenu volatile qui évolue à chaque sprint et transite par Git : notebooks, lakehouses et entrepôts de données, modèles sémantiques et rapports, pipelines et flux de données, ainsi que les valeurs de la bibliothèque de variables. Ce tutoriel explique comment le faire avec fabric-cicd.

L’idée directrice : provisionner la plateforme stable une fois avec Terraform, puis laisser les objets volatils circuler en continu via Git et fabric-cicd.

C’est une approche pour automatiser Fabric, et elle favorise les équipes qui considèrent déjà l’infrastructure comme du code et souhaitent une configuration scriptable et contrôlée par le code source. Fabric propose également des pipelines de déploiement basés sur des portails et une intégration Git, que vous pouvez piloter depuis l’interface utilisateur sans écrire Terraform ou Python. Pour une comparaison des options, voir les options de flux de travail CI/CD dans Fabric.

Pour le déploiement du plan de données plus précisément, fabric-cicd est une option. Vous pouvez également appeler directement les API REST Fabric bulk (CRUD) si vous souhaitez avoir un contrôle total sur les appels de création, mise à jour et suppression sans dépendre de la bibliothèque. Ce tutoriel utilise fabric-cicd, car il se charge de la re-liaison propre à chaque environnement pour vous.

Pourquoi Terraform pour le plan de contrôle

• Déclarative et idempotente. Vous décrivez une fois l’état souhaité de vos espaces de travail ; Terraform crée ce qui manque et laisse le reste tranquille.
• Détection de dérive. terraform plan indique exactement en quoi le locataire actif diffère de votre source de référence, de sorte qu’une modification effectuée hors bande dans le portail est visible et peut être annulée.
• Un seul fournisseur pour de nombreuses ressources. Le fournisseur Microsoft Fabric gère les espaces de travail, les capacités, les connexions, les liens Git et le RBAC via les API Fabric REST.

Pourquoi fabric-cicd pour le plan de données

• Se déploie comme Fabric l’attend. fabric-cicd lit la représentation Git de vos éléments et les publie selon la sémantique appropriée de création ou de mise à jour, afin que vous n’ayez pas à écrire vous-même des appels REST.
• Paramétrisation. Un fichier parameter.yml redéfinit des valeurs spécifiques à l’environnement, par exemple en faisant pointer le lakehouse par défaut d’un notebook ou la connexion d’un modèle sémantique vers la cible appropriée pour chaque environnement.
• Nettoyage. Il peut dépublier les éléments qui ont été retirés de Git, ce qui permet à chaque environnement de rester un reflet fidèle de la branche qu’il suit.

Le flux de bout en bout

Les deux plans se réunissent en une seule automatisation continue. Vous provisionnez la plateforme une seule fois, et à partir de là, chaque changement de contenu suit la même boucle répétable — de votre éditeur, via Git, jusqu’à l’environnement de test — sans aucune étape manuelle entre les deux.

Le même principal de service authentifie chaque étape, donc le flux que vous exécutez manuellement dans ce tutoriel est exactement ce qu’un pipeline CI/CD exécute pour vous : une étape de provisionnement (Terraform), puis une étape de déploiement (fabric-cicd) qui s’exécute chaque fois que la branche suivie change. Chaque niveau correspond à une étape ci-dessous :

Prerequisites

• Une capacité Fabric. Les deux espaces de travail de ce tutoriel sont attribués à la même capacité. Une capacité d’essai fonctionne.
• Un principal de service (enregistrement de l’application Microsoft Entra) avec un secret client. Cette identité unique fournit les espaces de travail et exécute le déploiement.
• Le paramètre de locataire Les principaux de service peuvent utiliser les API Fabric est activé pour un groupe de sécurité qui contient le principal de service. Pour plus d’informations, voir Activer l’authentification du principal de service pour les API Fabric.
• Une organisation, un projet et un dépôt Git Azure DevOps auxquels le principal du service peut accéder. Le dépôt doit déjà contenir la branche (par exemple, main) et le dossier que vous avez défini ado_directory_name (par exemple, /workspace). La connexion Git utilise PreferRemote, qui lit ce dossier sur la branche lorsqu’elle se connecte ; les deux doivent donc exister au préalable. Si le dossier manque, terraform apply échoue avec GitProviderResourceNotFound. Pour le créer, validez un fichier vide servant d’espace réservé (tel que .gitkeep) à cet emplacement sur la branche avant d’exécuter Terraform.
• Les outils suivants installés localement :
  • Terraform 1.8 ou une version ultérieure.
  • Python 3.9 ou plus (jusqu’à 3.13).
  • Azure CLI.

Configurer l’authentification

Terraform et fabric-cicd s’authentifient tous deux en tant que principal de service. Exportez ses références sous forme de variables d’environnement afin que les deux outils puissent les capter :

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

Étape 1 : Provisionner les espaces de travail avec Terraform

À cette étape, vous définissez le plan de contrôle comme du code et l’appliquez. Créez un dossier pour votre configuration Terraform et ajoutez les fichiers suivants.

Configurez le fournisseur

Créez provider.tf. Le fait de verrouiller la version du fournisseur garantit un comportement identique pour tous les ingénieurs.

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

Déclarez les entrées

Créez 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
}

Définir les ressources

Créez main.tf. Cette configuration crée deux espaces de travail, une connexion au contrôle de version, le lien Git sur dev et des attributions de rôles.

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

Déclarez les sorties

Créez outputs.tf. Le nom de l’espace de travail de test alimente l’étape de déploiement.

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
}

Appliquer la configuration

Fournissez les valeurs des variables (par exemple, dans un terraform.tfvars fichier que vous gardez hors de Git), puis exécutez :

terraform init
terraform plan
terraform apply

Terraform rapporte les ressources qu’il a créées et imprime les résultats.

Défis de provisionnement à connaître

Le fournisseur Fabric est puissant, mais quelques comportements posent des problèmes aux gens. Gardez ces éléments en tête avant de le faire passer en production :

• La connexion Git ne peut pas être importée. La ressource fabric_workspace_git ne prend pas en charge terraform import. Considérez-le comme une initialisation unique et enregistrez-le dans l’état distant afin que les exécutions suivantes n’essaient pas de le recréer. Stockez votre état dans un backend partagé comme stockage Azure plutôt que sur un seul ordinateur portable.
• Noms Git sensibles à la majuscule. L’API Fabric renvoie les noms de projets et de dépôts Azure DevOps en minuscules. Si vous les réussissez en cas mixtes, Terraform rapporte « le fournisseur a produit un résultat incohérent après application ». Enveloppez-les dans lower(), comme montré ci-dessus.
• Portée principale du service. La même identité doit pouvoir créer des espaces de travail dans la capacité et pouvoir être ajoutée en tant que membre de l’espace de travail. Si le provisionnement échoue avec une erreur d’autorisation, vérifiez à nouveau le paramètre du locataire et l’attribution du rôle de capacité indiqués dans les prérequis.
• Les secrets restent hors de l’État autant que possible. Le secret de connexion utilise l’argument d’écriture unique client_secret_wo , donc il n’est pas stocké en état texte clair. Cela dit, protégez votre dossier d’État comme étant sensible.

Étape 2 : Vérifier la connexion Git

Terraform a déjà connecté l’espace de travail dev à Git à l’étape 1. Confirmez-le :

1. Dans le portail Fabric, ouvrez l’espace releaseflow-dev de travail.
2. Sélectionnez Paramètres de l’espace de travail>Intégration Git.
3. Confirmez que l’espace de travail est connecté à votre organisation Azure DevOps, projet, dépôt, branche, ainsi qu’au dossier que vous avez défini ado_directory_name.

Étape 3 : Rédigez le contenu en développement et effectuez le commit

Ajoutez maintenant du contenu à l’espace de travail développeur et poussez-le vers Git. Dans ce tutoriel, vous créez deux éléments : une maison au bord du lac et un carnet qui en lit.

1. Dans releaseflow-dev, créez une maison lacustre nommée demoLakehouse.
2. Créez un carnet nommé demoNotebook. Définissez demoLakehouse comme lakehouse par défaut et ajoutez une cellule qui lit une table ou écrit un petit DataFrame d’exemple.
3. Lance le notebook une fois pour confirmer qu’il fonctionne contre le Lakehouse des développeurs.
4. Ouvrez Gestion du code source dans l’espace de travail, sélectionnez les deux éléments et validez-les sur votre branche.

Après le commit, votre dépôt contient un demoLakehouse.Lakehouse dossier et un demoNotebook.Notebook dossier sous le répertoire que vous avez configuré.

Étape 4 : Déploiement depuis le développement pour tester avec fabric-cicd

L’espace de travail de test est toujours vide. Utilisez fabric-cicd pour publier les éléments de Git dans l’environnement de test, en reconfigurant au passage la liaison du notebook vers le lakehouse de test.

installer fabric-cicd

Créez requirements.txt:

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

Installez-le :

pip install -r requirements.txt

Ajouter un fichier de paramètres

Le carnet stocké dans Git pointe vers le lakehouse dev et l’espace de travail dev. Lorsque vous déployez pour tester, ces références doivent changer pour que le notebook lise et écrive les données de test. Fabric-CICD fait cela avec un parameter.yml fichier.

Créez parameter.yml à côté de votre script de déploiement. Remplacez les deux GUID de substitution par l’ID réel du lakehouse de développement et l’ID réel de l’espace de travail de développement qui figurent dans le contenu validé de votre 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"

Les tokens $items.Lakehouse.demoLakehouse.$id et $workspace.$id sont résolus par fabric-cicd lors du déploiement en GUID de l’espace de travail cible.

Écrire le script de déploiement

Créez 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()

Exécuter le déploiement

Pointer le script vers le nom de l’espace de travail de test que Terraform a imprimé comme test_workspace_name. Clonez votre dépôt (ou réutilisez la copie locale que le développeur a commitée) pour que les dossiers d’objets soient disponibles localement, puis exécutez :

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

fabric-cicd crée le lakehouse et le notebook dans l’environnement de test, applique les règles find_replace et signale chaque élément publié.

Étape 5 : Vérifier la promotion

Confirmez que le test a reçu une copie correctement reliée du contenu :

1. Dans le portail Fabric, ouvrez l’espace releaseflow-test de travail.
2. Confirmez que demoLakehouse et demoNotebook existent désormais.
3. Ouvre demoNotebook et confirme que c’est son lakehouse par défaut qui est le testdemoLakehouse, pas celui du développeur.
4. Exécutez le notebook. Il devrait lire et écrire le test de la maison du lac.

Vous disposez maintenant d’un cycle de vie reproductible : modifiez les éléments en développement, validez les modifications dans Git, puis relancez deploy.py pour promouvoir vers l’environnement de test.

Automatiser dans Azure DevOps

Tout ce que vous avez exécuté localement utilise le même principe de service qu’un pipeline, donc passer au CI/CD consiste surtout à placer ces commandes dans des étapes du pipeline : une étape s’exécute terraform apply (plan de contrôle), une étape ultérieure s’exécute deploy.py (plan de données). Pour un guide détaillé complet, avec validations, d’Azure Pipelines sur l’étape de déploiement fabric-cicd, y compris les groupes de variables et les approbations, consultez Tutoriel : CI/CD avec Azure DevOps et la bibliothèque fabric-cicd.

Prolongez ce tutoriel

Ce tutoriel utilise un carnet et une maison au lac. Le même motif s’adapte à une plus grande partie du plan de données :

• Ajoutez SemanticModel et Report à ITEM_TYPES, puis ajoutez une règle semantic_model_binding dans parameter.yml pour faire pointer les modèles vers la connexion de chaque environnement.
• Ajoutez un VariableLibrary et laissez fabric-cicd activer le jeu de valeurs qui correspond au --environment que vous transmettez.
• Ajouter une étape post-déploiement (par exemple, rafraîchir un modèle sémantique ou lancer un carnet de tests de fumée) après publish_all_items.

Nettoyer les ressources

Pour éviter de consommer de la capacité, supprimez les espaces de travail que vous avez créés. Depuis votre dossier Terraform :

terraform destroy

Sinon, supprimez les espaces de travail releaseflow-dev et releaseflow-test du portail Fabric.

Contenu connexe

• Qu’est-ce que le CI/CD dans Microsoft Fabric ?
• Options de flux de travail CI/CD dans Fabric
• Tutoriel : CI/CD à l’aide de Azure DevOps et de la bibliothèque fabric-cicd
• Tutoriel : CI/CD utilisant l’API Fabric bulk
• Tutoriel : Gestion du cycle de vie des applications dans Fabric
• Fournisseur Microsoft Fabric Terraform
• Documentation de la bibliothèque Fabric-CICD