DevOps y observabilidad

CI/CD de Microsoft Fabric con fabric-cicd: de Git a DEV, QA y PROD

Una guía de producción para desplegar elementos de Microsoft Fabric desde Git con la biblioteca fabric-cicd de Microsoft: estructura del repositorio, autenticación, parametrización, CI y CD.

Por JaviPublicado 15 min de lecturaIntermedio

Un repositorio Git que alimenta un pipeline de despliegue hacia los workspaces de Fabric DEV, QA y PROD

Conectar un workspace de Fabric a Git te da un historial de versiones. No te da un proceso de publicación. Tarde o temprano hay que responder preguntas más difíciles: cómo llega a QA un notebook revisado, cómo termina la copia de producción apuntando al Lakehouse de producción y cómo sabes que lo que se ejecuta en PROD es lo que hay en main.

La biblioteca de código abierto fabric-cicd de Microsoft responde a esas preguntas con una pequeña API de Python. Esta guía muestra cómo la uso en producción: dónde encaja, cómo estructurar el repositorio, cómo autenticarse, cómo se reemplazan los identificadores de cada entorno y de qué debe encargarse la CI y de qué el CD. Los ejemplos usan Azure DevOps, pero las mismas ideas se aplican a GitHub Actions.

Por qué existe fabric-cicd

Hay tres actividades que a menudo se confunden:

  • Desarrollo en Fabric. Los ingenieros crean notebooks, pipelines y modelos en un workspace, normalmente desde la interfaz de Fabric.
  • Control de código fuente. La integración de Git en Fabric serializa cada elemento en archivos (los metadatos .platform y archivos de definición como notebook-content.py o pipeline-content.json) y los sincroniza con una rama.
  • Despliegue. Las mismas definiciones se aplican a otro workspace, reemplazando los valores propios de cada entorno, de forma repetible y auditable.

La integración de Git cubre las dos primeras. Es un mecanismo de sincronización entre un workspace y una rama, no un mecanismo de promoción entre entornos. fabric-cicd cubre la tercera: lee las definiciones de los elementos desde un directorio del repositorio y llama a las API REST de Fabric para crear o actualizar esos elementos en un workspace de destino.

Esa distinción tiene una consecuencia operativa. Los workspaces que reciben despliegues no son workspaces de desarrollo. Si alguien edita elementos directamente en QA o PROD, el siguiente despliegue sobrescribe el cambio o, peor aún, el cambio sobrevive en algunos elementos y en otros no. Un workspace desplegado solo debe cambiar cuando se ejecuta el pipeline.

El modelo de despliegue

  1. 1Rama de funcionalidadCreada desde main
  2. 2Workspace de desarrolloConectado mediante Git Sync
  3. 3Pull requestRevisión y validación de CI
  4. 4mainRama protegida
  5. 5Despliegue con fabric-cicdPipeline de publicación
  6. 6QAWorkspace desplegado
  7. 7PRODMismo commit, aprobado
El desarrollo ocurre en workspaces de funcionalidad sincronizados con Git; QA y PROD solo cambian cuando el pipeline de publicación despliega un commit revisado.

El flujo sigue el Git flow y la filosofía de despliegue que Microsoft documenta para fabric-cicd:

  • Las ramas de funcionalidad se conectan a workspaces de desarrollo mediante Git Sync. Ahí es donde se trabaja con la interfaz de Fabric.
  • Los workspaces desplegados no están conectados a Git. Solo se actualizan mediante despliegues con scripts.
  • Cada ejecución es un despliegue completo. fabric-cicd no examina el historial de commits ni calcula diferencias. Cada elemento cuyo tipo está en item_type_in_scope se crea o actualiza en cada ejecución, de modo que el destino converge al estado del repositorio, independientemente de lo que haya ocurrido antes.
  • Los elementos huérfanos se eliminan de forma explícita. unpublish_all_orphan_items() elimina los elementos de los tipos incluidos que existen en el workspace pero ya no existen en el repositorio.

El despliegue selectivo y la detección de cambios a partir de Git existen como funcionalidades experimentales, pero Microsoft no recomienda el despliegue selectivo como opción predeterminada, porque las dependencias sin resolver pueden romper una publicación. Desplegar todo lo que está en el alcance es más lento que desplegar un solo notebook modificado, pero es predecible, y de eso se trata.

El escenario de referencia de Microsoft usa una rama desplegada por entorno: las funcionalidades se fusionan en la rama predeterminada y se llevan a las ramas superiores mediante cherry-pick. Una variante habitual, la que usa esta guía, mantiene un único main protegido y promueve el mismo commit por QA, STAGING y PROD, con aprobaciones entre etapas. Ambas respetan la regla esencial: los workspaces desplegados nunca se editan a mano ni se sincronizan con Git.

Instalación

fabric-cicd es un paquete de Python:

pip install fabric-cicd

En un pipeline, fija la versión que validaste, por ejemplo en un archivo requirements-deploy.txt, para que una nueva versión nunca cambie el comportamiento del despliegue sin que lo sepas. Lee el registro de cambios antes de actualizar; los requisitos de autenticación, por ejemplo, han cambiado entre versiones.

Si prefieres la línea de comandos a un script de Python, la Fabric CLI ejecuta fabric-cicd internamente con fab deploy, usando un archivo config.yml y el mismo parameter.yml:

pip install ms-fabric-cli
fab deploy --config config.yml --target_env prod

Estructura del repositorio

fabric-cicd despliega desde un directorio que contiene los elementos confirmados mediante el control de código fuente de Fabric, más un parameter.yml opcional en su raíz. Mantén todo lo demás, como los scripts de despliegue y las definiciones de los pipelines, fuera de ese directorio.

.
├── .deploy/
│   └── deploy_workspace.py
├── pipelines/
│   ├── fabric-release.yml
│   └── templates/
│       └── deploy-fabric.yml
├── requirements-deploy.txt
└── workspace/
    ├── Ingest Orders.Notebook/
    │   ├── .platform
    │   └── notebook-content.py
    ├── Load Orders.DataPipeline/
    ├── Sales.Lakehouse/
    ├── Sales Warehouse.Warehouse/
    ├── Platform Settings.VariableLibrary/
    ├── Sales.SemanticModel/
    ├── Sales Overview.Report/
    └── parameter.yml

Cada elemento está en una carpeta con el nombre <nombre del elemento>.<tipo de elemento>. Se admiten subcarpetas del workspace, así que puedes agrupar los elementos igual que en Fabric. La conexión Git del workspace de desarrollo debe apuntar a esta carpeta workspace/, para que lo que los ingenieros confirman desde la interfaz sea exactamente lo que despliega el pipeline.

Decide pronto qué tipos de elementos gestiona el pipeline. Los proyectos en los que trabajo despliegan Notebook, DataPipeline, Lakehouse, Warehouse, VariableLibrary, SemanticModel y Report. Cada tipo que añades al alcance se convierte en algo que el pipeline crea, actualiza y puede eliminar, así que añade tipos de forma deliberada.

Autenticación

Las versiones actuales de fabric-cicd exigen una credencial explícita. El parámetro token_credential debe ser un objeto que implemente TokenCredential de azure-identity. Dos comportamientos antiguos ya no se admiten: el uso de DefaultAzureCredential como alternativa automática y la autenticación implícita dentro de un notebook de Fabric sin token_credential. Los scripts que dependían de cualquiera de ellos ahora fallan en la autenticación, de forma intencionada.

Dónde se ejecuta el despliegue Credencial Notas
Desarrollo local AzureCliCredential o AzurePowerShellCredential Usa la identidad de az login o Connect-AzAccount
Azure DevOps con una conexión de servicio AzureCliCredential o AzurePowerShellCredential Ejecuta el script dentro de una tarea AzureCLI@2 o AzurePowerShell@5; la plataforma gestiona el inicio de sesión
Pipeline con el secreto de una entidad de servicio ClientSecretCredential Lee el secreto desde una variable segura o Key Vault, nunca desde el repositorio
Agente autohospedado en Azure ManagedIdentityCredential No hay secretos que rotar; la identidad administrada del agente necesita acceso al workspace
Notebook de Fabric Una credencial explícita Los ejemplos de autenticación muestran un patrón con la sesión del notebook y otro con una entidad de servicio

En Azure DevOps prefiero AzureCliCredential dentro de una tarea AzureCLI@2 con una conexión de servicio. La plataforma del pipeline gestiona el secreto o la credencial federada, y el script de Python no contiene más lógica de autenticación que una línea.

Sea cual sea la identidad que ejecuta el despliegue, necesita permiso para crear y actualizar elementos en cada workspace de destino. También necesita acceso a las conexiones que usan los pipelines de datos; si no puede ver una conexión, el despliegue del pipeline falla.

El script de despliegue

El script es intencionadamente pequeño. Todo lo que varía según el entorno viene del pipeline: el workspace de destino y el nombre del entorno.

"""Deploy the Fabric items in ./workspace to one target workspace."""

import os
import sys
from pathlib import Path

from azure.identity import AzureCliCredential
from fabric_cicd import (
    FabricWorkspace,
    change_log_level,
    publish_all_items,
    unpublish_all_orphan_items,
)

# Stream output immediately in pipeline logs
sys.stdout.reconfigure(line_buffering=True, write_through=True)
sys.stderr.reconfigure(line_buffering=True, write_through=True)

if os.getenv("SYSTEM_DEBUG", "false").lower() == "true":
    change_log_level("DEBUG")

repo_root = Path(__file__).resolve().parent.parent

target_workspace = FabricWorkspace(
    workspace_id=os.environ["TARGET_WORKSPACE_ID"],
    environment=os.environ["TARGET_ENVIRONMENT"],  # DEV, QA, STAGING or PROD
    repository_directory=str(repo_root / "workspace"),
    item_type_in_scope=[
        "Lakehouse",
        "Warehouse",
        "VariableLibrary",
        "Notebook",
        "DataPipeline",
        "SemanticModel",
        "Report",
    ],
    token_credential=AzureCliCredential(),
)

publish_all_items(target_workspace)
unpublish_all_orphan_items(target_workspace)

El valor de environment selecciona los reemplazos de parameter.yml y el conjunto de valores activo de cada Variable Library. Debe coincidir exactamente con las claves usadas allí. fabric-cicd publica los tipos de elementos en su propio orden de dependencias (las Variable Libraries y los Warehouses antes que los elementos que los referencian), así que el orden de item_type_in_scope no importa.

DEV, QA, STAGING y PROD

Workspace Cómo cambia Quién lo edita
Workspaces de funcionalidad o de desarrollo Git Sync con una rama de funcionalidad Los ingenieros, desde la interfaz de Fabric
DEV (integración) Despliegue por pipeline desde main Nadie directamente
QA Despliegue por pipeline, después de DEV Nadie directamente
STAGING Despliegue por pipeline, con aprobación Nadie directamente
PROD Despliegue por pipeline del mismo commit, con aprobación Nadie directamente

No todos los equipos necesitan cuatro entornos desplegados. Lo que importa es la frontera: los únicos workspaces que se editan son los de desarrollo sincronizados con Git, y todos los demás entornos son destinos de despliegue.

Da a cada entorno su propio workspace, sus propios datos de Lakehouse y Warehouse y sus propias conexiones. Desplegar definiciones de elementos no mueve datos; un notebook de PROD que todavía apunta al Lakehouse de DEV es el error de despliegue más común, y el más peligroso.

Parametrizar los valores de cada entorno

Las definiciones confirmadas desde el workspace de desarrollo contienen identificadores de desarrollo: el Lakehouse predeterminado de cada notebook, el workspace al que pertenece, los ID del punto de conexión de análisis SQL en los pipelines y los modelos semánticos, los ID de las conexiones. parameter.yml le indica a fabric-cicd cómo reemplazarlos en cada entorno. El archivo está en la raíz del directorio del repositorio y se valida al comienzo de cada despliegue; un archivo no válido detiene la ejecución.

find_replace:
    # Default Lakehouse attached to notebooks
    - find_value: "your-dev-lakehouse-id"
      replace_value:
          _ALL_: "$items.Lakehouse.Sales.$id"
      item_type: "Notebook"

    # Workspace that owns the default Lakehouse
    - find_value: "your-dev-workspace-id"
      replace_value:
          _ALL_: "$workspace.$id"
      item_type: "Notebook"

    # Lakehouse SQL analytics endpoint used by pipelines and the semantic model
    - find_value: "your-dev-lakehouse-sql-endpoint-id"
      replace_value:
          _ALL_: "$items.Lakehouse.Sales.$sqlendpointid"
      item_type: ["DataPipeline", "SemanticModel"]

key_value_replace:
    # Run schedules only in production
    - find_key: $.schedules[?(@.jobType=="Execute")].enabled
      replace_value:
          DEV: false
          QA: false
          STAGING: false
          PROD: true
      file_path: "**/.schedules"

semantic_model_binding:
    default:
        connection_id:
            DEV: "your-dev-connection-id"
            QA: "your-qa-connection-id"
            STAGING: "your-staging-connection-id"
            PROD: "your-prod-connection-id"

Algunos detalles hacen que este archivo sea fiable:

  • Prefiere valores dinámicos a GUID codificados. $workspace.$id se resuelve como el workspace de destino y $items.Lakehouse.Sales.$id como el Lakehouse llamado Sales en ese workspace. $sqlendpointid devuelve el ID del punto de conexión de análisis SQL de un Lakehouse. Ya no mantienes una tabla de GUID de producción, y la misma entrada sirve para todos los entornos.
  • _ALL_ aplica un mismo valor a cualquier entorno. Debe ser la única clave de ese replace_value.
  • Filtra cada reemplazo. item_type, item_name y file_path limitan dónde se reemplaza un valor. Un reemplazo de GUID sin filtrar afecta a todos los archivos del repositorio.
  • Usa expresiones regulares solo con contexto. find_replace admite is_regex, por ejemplo para capturar el GUID que sigue a # META "default_lakehouse":. Nunca busques solo el formato de un GUID, o reemplazarás identificadores que no tienen relación.
  • Nombra los entornos de forma coherente. QA y qa son claves distintas. Si el entorno que recibe FabricWorkspace no aparece en una entrada, ese reemplazo se omite.

Conviene conocer algunos límites antes de depender de la parametrización. find_replace no se aplica a los elementos Lakehouse ni Warehouse. Las conexiones no están en el control de código fuente, así que deben existir en cada entorno antes del despliegue. Cuando se usa cualquier variable dinámica, fabric-cicd resuelve los puntos de conexión SQL de todos los Lakehouses y Warehouses del workspace de destino; si alguno todavía se está aprovisionando, el despliegue falla antes de publicar nada.

Las Variable Libraries complementan parameter.yml. Nombra cada conjunto de valores según un entorno (DEV, QA, PROD) y fabric-cicd activará el que coincida con el valor de environment. Guarda en las Variable Libraries la configuración de ejecución que leen los notebooks y los pipelines, y en parameter.yml las conexiones entre elementos, como los Lakehouses predeterminados y los ID de los puntos de conexión.

Qué ocurre en la CI

La CI se ejecuta en cada pull request hacia main. Nunca despliega en QA ni en PROD. Su función es impedir que una definición rota llegue a la rama desde la que se generan las publicaciones:

  • main protegido: los cambios solo llegan mediante pull requests, con al menos un revisor y una compilación correcta.
  • Comprobaciones de estructura: cada carpeta bajo workspace/ sigue el formato <nombre>.<tipo> y contiene un archivo .platform.
  • Validación de parámetros: parameter.yml se puede analizar, cada clave de entorno está escrita de forma coherente y cada variable dinámica hace referencia a un elemento que existe en el repositorio. fabric-cicd incluye en su repositorio un script debug_parameterization.py que valida el archivo sin desplegar.
  • Identificadores filtrados: haz fallar la compilación si un ID conocido de workspace o Lakehouse de desarrollo aparece en un archivo que parameter.yml no cubre.
  • Secretos: ningún secreto de cliente, clave ni cadena de conexión en las definiciones de los elementos.

Algunos equipos también despliegan cada commit fusionado en el workspace DEV compartido como primera etapa del CD. Es una prueba de integración útil: demuestra que el commit se despliega antes de que nadie le pida a QA que lo revise.

Qué ocurre en el CD

El pipeline de publicación despliega un mismo commit en cada entorno, uno tras otro. En Azure DevOps, una plantilla de etapa reutilizable mantiene todos los entornos idénticos salvo por sus entradas:

# pipelines/templates/deploy-fabric.yml
parameters:
  - name: environment
    type: string
  - name: serviceConnection
    type: string
  - name: workspaceId
    type: string
  - name: dependsOn
    type: object
    default: []

stages:
  - stage: Deploy_${{ parameters.environment }}
    dependsOn: ${{ parameters.dependsOn }}
    jobs:
      - deployment: Deploy
        environment: fabric-${{ parameters.environment }}
        pool:
          vmImage: ubuntu-latest
        strategy:
          runOnce:
            deploy:
              steps:
                - checkout: self
                - task: UsePythonVersion@0
                  inputs:
                    versionSpec: '3.12'
                - script: pip install -r requirements-deploy.txt
                  displayName: Install fabric-cicd
                - task: AzureCLI@2
                  displayName: Deploy to ${{ parameters.environment }}
                  inputs:
                    azureSubscription: ${{ parameters.serviceConnection }}
                    scriptType: bash
                    scriptLocation: inlineScript
                    inlineScript: python -u .deploy/deploy_workspace.py
                  env:
                    TARGET_ENVIRONMENT: ${{ parameters.environment }}
                    TARGET_WORKSPACE_ID: ${{ parameters.workspaceId }}
# pipelines/fabric-release.yml
trigger:
  branches:
    include:
      - main

pr: none

stages:
  - template: templates/deploy-fabric.yml
    parameters:
      environment: QA
      serviceConnection: your-qa-service-connection
      workspaceId: your-qa-workspace-id

  - template: templates/deploy-fabric.yml
    parameters:
      environment: STAGING
      serviceConnection: your-staging-service-connection
      workspaceId: your-staging-workspace-id
      dependsOn: [Deploy_QA]

  - template: templates/deploy-fabric.yml
    parameters:
      environment: PROD
      serviceConnection: your-prod-service-connection
      workspaceId: your-prod-workspace-id
      dependsOn: [Deploy_STAGING]

Las aprobaciones y comprobaciones se configuran en los entornos de Azure DevOps (fabric-STAGING, fabric-PROD), no en el YAML, de modo que nadie puede eliminarlas en una pull request. Los ID de los workspaces no son secretos, pero guardarlos en un grupo de variables por entorno evita editar el pipeline cuando se vuelve a crear un workspace. Una conexión de servicio distinta por entorno garantiza que la identidad de QA no pueda tocar PROD.

Como la plantilla es compartida, una corrección del proceso de despliegue llega a todos los entornos y a todos los repositorios de Fabric que la usan. Esa es la razón principal para centralizar las plantillas de pipeline en lugar de copiarlas entre proyectos.

Evitar la deriva de los workspaces

La deriva es la diferencia entre lo que dice el repositorio y lo que contiene un workspace. Un despliegue completo elimina la mayor parte en cada ejecución, pero solo para lo que está en el alcance:

  • Restringe los permisos. En los workspaces desplegados, las personas tienen el rol Viewer o roles limitados; la identidad de despliegue es la única entidad que modifica elementos.
  • Haz pasar las correcciones urgentes por Git. Una corrección hecha directamente en PROD se sobrescribe en la siguiente publicación. Hazla en una rama, fusiónala y despliégala.
  • Decide qué significa despublicar. unpublish_all_orphan_items() elimina los elementos del alcance que no están en el repositorio. La despublicación de Lakehouses y Warehouses está desactivada de forma predeterminada para proteger los datos. Usa item_name_exclude_regex para los elementos que se gestionan intencionadamente fuera de Git.
  • Conoce lo que no se despliega. Las conexiones, los recursos de los notebooks, los datos y esquemas de los Lakehouses (salvo que los defina un acceso directo) y el DDL de los Warehouses quedan fuera de fabric-cicd. Del Warehouse solo se despliega el elemento vacío; despliega su esquema con un DACPAC, dbt u otra herramienta de bases de datos.
  • Nunca sincronices con Git un workspace desplegado. Crearía una segunda vía, en competencia, para cambiar los mismos elementos.

Qué validar después del despliegue

Un pipeline en verde significa que las API aceptaron las definiciones. No demuestra que la plataforma funcione. Después de cada despliegue, comprueba:

  • Todos los elementos se desplegaron correctamente. Un fallo debe detener la etapa, no dejar un workspace actualizado a medias que parece terminado.
  • Los notebooks apuntan al Lakehouse de destino. Abre uno o consulta sus metadatos; el Lakehouse predeterminado y su workspace deben pertenecer al entorno de destino, nunca a DEV.
  • Los pipelines llaman a los elementos de destino y usan las conexiones del entorno.
  • Los modelos semánticos están vinculados y se actualizan. Ejecuta una actualización y confirma que lee el punto de conexión SQL de destino.
  • Los informes se abren sobre el modelo semántico desplegado.
  • Las Variable Libraries tienen el conjunto de valores activo esperado.
  • Las programaciones están activadas solo donde deben ejecutarse.
  • Una ejecución de prueba funciona: una pequeña ejecución de pipeline o notebook que recorre el camino principal y aparece en tu monitoreo de pipelines y notebooks.
  • La publicación queda registrada: ID del commit, entorno, aprobador y resultado.

La checklist de despliegue de CI/CD para Fabric, imprimible y en inglés, recoge los mismos pasos antes, durante y después de una publicación.

Errores y modos de fallo comunes

  • Depender de la autenticación predeterminada. Sin un token_credential explícito, las versiones actuales de fabric-cicd fallan. Los scripts antiguos que nunca lo pasaban dejan de funcionar después de una actualización.
  • Nombres de entorno que no coinciden. Prod en el pipeline y PROD en parameter.yml significa que no se aplica ningún reemplazo y los elementos de producción conservan los ID de desarrollo.
  • Un find_value que no coincide. Los archivos confirmados contienen un GUID distinto del de parameter.yml, a menudo porque alguien volvió a asociar un Lakehouse en el workspace de desarrollo.
  • Reemplazos sin filtrar que cambian ID en archivos que nunca debieron tocar.
  • Un punto de conexión SQL que aún se está aprovisionando en el workspace de destino, lo que hace fallar todo el despliegue cuando se usan variables dinámicas.
  • Falta de acceso a las conexiones por parte de la identidad de despliegue, lo que hace fallar los pipelines de datos.
  • Renombrar o eliminar un conjunto de valores de una Variable Library después del primer despliegue, lo que hace fallar los siguientes hasta que se corrige en la interfaz de Fabric.
  • Volver a crear demasiado pronto un elemento con el mismo nombre. Fabric reserva durante unos minutos los nombres de los elementos eliminados.
  • Limitación de solicitudes. Los workspaces grandes pueden recibir 429 Too Many Requests; vuelve a intentarlo más tarde o divide los despliegues muy grandes.
  • Despliegues selectivos como opción predeterminada, que dejan dependencias sin resolver.
  • Esperar que los datos o los esquemas del Warehouse se muevan con los elementos.

Cuando algo falle, activa el registro de depuración con change_log_level() (o define SYSTEM_DEBUG en Azure DevOps con el script anterior) y consulta la guía de solución de problemas. Define FABRIC_CICD_FILE_LOGGING_ENABLED si quieres el archivo detallado fabric_cicd.error.log.

Recomendaciones prácticas

  1. Haz de Git la única vía de entrada a un workspace desplegado. Los workspaces de desarrollo se sincronizan con Git; todos los demás son destinos de despliegue.
  2. Mantén el script de despliegue pequeño y genérico. El entorno, el ID del workspace y la credencial vienen del pipeline.
  3. Usa variables dinámicas ($workspace.$id, $items.<type>.<name>.$id, $sqlendpointid) en lugar de mantener GUID de producción.
  4. Filtra cada reemplazo por tipo de elemento, nombre de elemento o ruta de archivo.
  5. Promueve un mismo commit por QA, STAGING y PROD, con aprobaciones en los entornos del pipeline.
  6. Usa una identidad de despliegue y una conexión de servicio distintas por entorno.
  7. Fija la versión de fabric-cicd y actualízala de forma deliberada después de leer el registro de cambios.
  8. Despliega los esquemas del Warehouse y crea las conexiones con sus propias herramientas, antes que los elementos que dependen de ellos.
  9. Valida la plataforma después de cada publicación, no solo el resultado del pipeline.

Usado así, fabric-cicd convierte los despliegues de Fabric en algo aburrido: el mismo commit, el mismo script y las mismas comprobaciones en cada entorno. Para el diseño general de la plataforma en la que viven estos entornos, consulta Diseñar una arquitectura escalable de Microsoft Fabric.

Etiquetas

  • Microsoft Fabric
  • CI/CD
  • Git
  • DevOps
  • Python