Tutorial: Automatización de extremo a extremo en Fabric

En este tutorial, construyes un flujo de lanzamiento completo y repetible para Microsoft Fabric usando la infraestructura como código. Provisionas dos espacios de trabajo (dev y test) con Terraform, conectas el espacio de trabajo dev a Git, creas un elemento en dev y luego lo promocionas para probar con la biblioteca Python fabric-cicid. Todo funciona bajo un único principio de servicio, así que el mismo flujo funciona hoy en tu portátil y mañana en una cadena CI/CD.

En este tutorial, usted hará lo siguiente:

Dos aviones, dos herramientas

Automatizar una versión de Fabric tiene dos preocupaciones distintas, y ayuda mantenerlas separadas: el plano de control estable (la infraestructura en la que se encuentra tu contenido) y el plano de datos volátil (el contenido que editas cada día). Ajusta la herramienta de despliegue a la frecuencia con la que cambia cada cosa.

• El plano de control contiene infraestructuras no volátils que provisionas una vez y rara vez cambias: capacidades, espacios de trabajo y sus configuraciones, dominios, conexiones, configuraciones de inquilinos, y cableado RBAC y Git. Este tutorial lo aprovisiona con Terraform.
• El plano de datos contiene contenido volátil que evoluciona con cada sprint y circula por Git: cuadernos, lakehouses y almacenes, modelos semánticos e informes, canalizaciones y flujos de datos, y valores de la biblioteca de variables. Este tutorial lo mueve con fabric-cicd.

La idea guía: provisionar la plataforma estable una vez con Terraform, y luego dejar que los objetos volátiles fluyan continuamente por Git y fabric-cicd.

Este es un enfoque para automatizar Fabric, y favorece a equipos que ya tratan la infraestructura como código y quieren una configuración scriptable y controlada por códigos. Fabric también ofrece pipelines de despliegue basados en portales e integración con Git, que puedes manejar desde la interfaz sin necesidad de escribir Terraform o Python. Para una comparación de las opciones, consulta opciones de flujo de trabajo CI/CD en Fabric.

Concretamente, para el despliegue del plano de datos, fabric-cicd es una opción. También puedes llamar directamente a las APIs REST de Fabric bulk (CRUD) si quieres tener control total sobre crear, actualizar y eliminar llamadas sin depender de la biblioteca. Este tutorial utiliza fabric-cicd porque se encarga de la reasignación según el entorno por usted.

Por qué Terraform para el plano de control

• Declarativo e idempotente. Describes el estado deseado de tus espacios de trabajo una vez; Terraform crea lo que falta y deja el resto en paz.
• Detección de deriva. terraform plan Muestra exactamente cómo el inquilino en vivo difiere de tu fuente de verdad, de modo que un cambio fuera de banda en el portal se vuelve visible y reversible.
• Un proveedor para múltiples recursos. El proveedor de Microsoft Fabric gestiona espacios de trabajo, capacidades, conexiones, enlaces Git y RBAC a través de las APIs REST de Fabric.

¿Por qué usar fabric-cicd para el plano de datos?

• Se despliega como Fabric espera. fabric-cicd lee la representación Git de tus elementos y los publica con la semántica correcta de crear o actualizar, para que no tengas que hacer manualmente las llamadas REST.
• Parametrización. Un parameter.yml archivo vuelve a enlazar valores específicos del entorno, como señalar la casa del lago predeterminada de un cuaderno o la conexión de un modelo semántico al objetivo correcto por entorno.
• Limpieza. Puede despublicar elementos que fueron eliminados de Git, manteniendo cada entorno como un reflejo fiel de la rama que rastrea.

El flujo de extremo a extremo

Los dos planos se unen en una única automatización continua. Provisionas la plataforma una vez, y a partir de ahí cada cambio de contenido sigue el mismo bucle repetible—desde tu editor, pasando por Git, hasta el entorno de prueba—sin pasos manuales en el portal entre medias.

El mismo principio de servicio autentica cada etapa, así que el flujo que ejecutas manualmente en este tutorial es exactamente lo que ejecuta un pipeline CI/CD en tu nombre: una etapa de provisión (Terraform), luego una etapa de despliegue (fabric-cicd) que se ejecuta cada vez que cambia la rama rastreada. Cada etapa corresponde a un paso a continuación:

Prerequisites

• Una capacidad de Fabric. Ambos espacios de trabajo en este tutorial están asignados a la misma capacidad. Una capacidad de prueba funciona.
• Una entidad de servicio (registro de aplicaciones de Microsoft Entra) con un secreto de cliente. Esta identidad única provisiona los espacios de trabajo y ejecuta el despliegue.
• La configuración del inquilino Las entidades de servicio pueden usar las API de Fabric está habilitada para un grupo de seguridad que contiene la entidad de servicio. Para más información, consulte Habilitar la autenticación del principal de servicio para la API de Fabric.
• Una organización, proyecto y repositorio Git de Azure DevOps a la que el principal del servicio puede acceder. El repositorio debe contener ya la rama (por ejemplo, main) y la carpeta en la que se establece ado_directory_name (por ejemplo, /workspace). La conexión Git usa PreferRemote, que lee esa carpeta en la rama cuando se conecta, por lo que ambas deben existir previamente. Si falta la carpeta, terraform apply falla con GitProviderResourceNotFound. Para crearlo, confirma un archivo de marcador de posición vacío (como .gitkeep) en esa ruta de la rama correspondiente antes de ejecutar Terraform.
• Las siguientes herramientas instaladas localmente:
  • Terraform 1.8 o posterior.
  • Python 3.9 o posterior (hasta 3.13).
  • La CLI de Azure.

Configuración de la autenticación

Tanto Terraform como fabric-cicd se autentican como la entidad de servicio. Exporta sus credenciales como variables de entorno para que ambas herramientas puedan detectarlas:

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

Paso 1: Aprovisionar los espacios de trabajo con Terraform

En este paso, defines el plano de control como código y lo aplicas. Crea una carpeta para tu configuración de Terraform y añade los siguientes archivos.

Configurar el proveedor

Crea provider.tf. Fijar la versión del proveedor mantiene a todos los ingenieros en el mismo comportamiento.

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

Declarar las entradas

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
}

Definir los recursos

Crea main.tf. Esta configuración crea dos áreas de trabajo, una conexión al control de código fuente, el vínculo de Git en dev y asignaciones de rol.

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

Declarar las salidas

Crea outputs.tf. El nombre del espacio de trabajo de prueba alimenta el paso de despliegue.

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
}

Aplicación de la configuración

Proporciona valores para las variables (por ejemplo, en un terraform.tfvars archivo que mantengas fuera de Git) y luego ejecuta:

terraform init
terraform plan
terraform apply

Terraform informa de los recursos que creó e imprime los resultados.

Desafíos de aprovisionamiento que hay que conocer

El proveedor de Fabric es potente, pero algunos comportamientos pueden confundir a la gente. Ten esto en cuenta antes de ejecutarlo en producción:

• La conexión Git no se puede importar. El fabric_workspace_git recurso no soporta terraform import. Trátalo como un bootstrap único y mantenlo en estado remoto para que en las partidas posteriores no intentes recrearlo. Guarda tu estado en un backend compartido como Azure Storage en lugar de en un solo portátil.
• Nombres Git sensibles a mayúsculas y minúsculas. La API de Fabric devuelve los nombres de proyectos y repositorios de Azure DevOps en minúsculas. Si los apruebas en casos mixtos, Terraform informa que "el proveedor produjo resultados inconsistentes tras aplicar." Envuélvelos en lower(), como se muestra arriba.
• Alcance principal del servicio. La misma identidad debe poder crear espacios de trabajo en la capacidad y ser agregada como miembro del espacio de trabajo. Si falla la provisión por un error de autorización, vuelve a comprobar la configuración del inquilino y la asignación de roles de capacidad desde los prerrequisitos.
• Los secretos deben mantenerse fuera del estado siempre que sea posible. El secreto de conexión usa el argumento client_secret_wo de solo escritura, por lo que no se almacena en el estado en texto plano. Aun así, protege tu archivo de estado como si fuera confidencial.

Paso 2: Verifica la conexión Git

Terraform ya conectó el espacio de trabajo de desarrollo a Git en el paso 1. Confírmalo:

1. En el portal de Fabric, abre el espacio de trabajo releaseflow-dev.
2. Seleccione Configuración del área de trabajo>Integración de Git.
3. Confirma que el espacio de trabajo está conectado a tu organización Azure DevOps, proyecto, repositorio, rama y a la carpeta en la que has configuradoado_directory_name.

Paso 3: Redacta contenido en el entorno de desarrollo y haz un commit

Ahora añade contenido al espacio de trabajo de desarrollo y súbelo a Git. En este tutorial creas dos elementos: una casa del lago y un cuaderno que lee de ella.

1. En releaseflow-dev, crea una casa lacustre llamada demoLakehouse.
2. Crea un cuaderno llamado demoNotebook. Adjunta demoLakehouse como su lakehouse predeterminado y añade una celda que lea una tabla o escriba un pequeño ejemplo de DataFrame.
3. Ejecuta el notebook una vez para confirmar que funciona con el lakehouse de desarrollo.
4. Abre Control de código fuente en el área de trabajo, selecciona ambos elementos y haz Commit en tu rama.

Después del commit, tu repositorio contiene una demoLakehouse.Lakehouse carpeta y una demoNotebook.Notebook carpeta bajo el directorio que configuraste.

Paso 4: Desplegar desde dev para probar con fabric-cicd

El espacio de trabajo de pruebas sigue vacío. Usa fabric-cicd para publicar los elementos de Git en el entorno de prueba, volviendo a vincular el notebook al lakehouse de prueba durante el proceso.

Instalación de fabric-cicd

Crea requirements.txt:

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

Instálalo:

pip install -r requirements.txt

Añadir un archivo de parámetros

El cuaderno almacenado en Git apunta al dev lakehouse y al espacio de trabajo dev. Cuando despliegas para probar, esas referencias deben cambiar para que el cuaderno lea y escriba datos de prueba. Fabric-CICD hace esto con un parameter.yml archivo.

Crea parameter.yml junto a tu script de despliegue. Sustituye los dos GUIDs provisionales por el ID real de dev lakehouse y el dev workspace ID que aparecen en el contenido comprometido de tu 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"

Los tokens $items.Lakehouse.demoLakehouse.$id y $workspace.$id son resueltos por fabric-cicd en el momento del despliegue a los GUID del espacio de trabajo target.

Escribe el script de despliegue

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

Ejecución de la implementación

Haz que el script apunte al nombre del espacio de trabajo de prueba que Terraform imprimió como test_workspace_name. Clona tu repositorio (o reutiliza la copia local que el desarrollador ha commitido) para que las carpetas de objetos estén disponibles localmente, y luego ejecuta:

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

fabric-cicd crea el lakehouse y el cuaderno de notas en el entorno de prueba, aplica las reglas find_replace e informa de cada elemento publicado.

Paso 5: Verifica la promoción

Confirma que la prueba recibió una copia correctamente recargada del contenido:

1. En el portal de Fabric, abre el espacio de trabajo releaseflow-test.
2. Confirma que demoLakehouse y demoNotebook ya existen.
3. Abre demoNotebook y confirma que su lakehouse predeterminado es testdemoLakehouse, no el de dev.
4. Ejecute el cuaderno. Debería leer y escribir la prueba de la casa del lago.

Ahora tienes un flujo de trabajo repetible: cambiar elementos en dev, confirmar los cambios en Git y volver a ejecutar deploy.py para promover a test.

Automatizar en Azure DevOps

Todo lo que ejecutaste localmente usa el mismo principio de servicio que usa un pipeline, así que pasar a CI/CD es principalmente cuestión de poner estos comandos en etapas de pipeline: una etapa se ejecuta terraform apply (plano de control), una etapa posterior se ejecuta deploy.py (plano de datos). Para obtener un tutorial completo en Azure Pipelines sobre la etapa de implementación de fabric-cicd, incluidos los grupos de variables y las aprobaciones, consulta Tutorial: CI/CD con Azure DevOps y la biblioteca fabric-cicd.

Extiende este tutorial

Este tutorial incluye un cuaderno y una casa del lago. El mismo patrón escala a más parte del plano de datos:

• Añada SemanticModel y Report a ITEM_TYPES y añada una regla de semantic_model_binding en parameter.yml para apuntar los modelos a la conexión de cada entorno.
• Añade un VariableLibrary y permite que fabric-cicd active el conjunto de valores correspondiente al --environment que pasas.
• Añadir un paso posterior al despliegue (por ejemplo, actualizar un modelo semántico o ejecutar un cuaderno de prueba de humo) después de publish_all_items.

Limpieza de recursos

Para evitar consumir capacidad, elimina los espacios de trabajo que creaste. Desde tu carpeta Terraform:

terraform destroy

Alternativamente, elimina los releaseflow-dev espacios de trabajo y releaseflow-test del portal Fabric.

Contenido relacionado

• ¿Qué es CI/CD en Microsoft Fabric?
• Opciones de flujo de trabajo de CI/CD en Fabric
• Tutorial: CI/CD con Azure DevOps y la biblioteca fabric-cicd
• Tutorial: CI/CD con la API masiva de Fabric
• Tutorial: Gestión del ciclo de vida de aplicaciones en Fabric
• Proveedor de Microsoft Fabric Terraform
• Documentación de la biblioteca Fabric-CICD