Tutorial: Automação de ponta a ponta no Fabric

Neste tutorial, você constrói um fluxo de lançamento completo e repetível para Microsoft Fabric usando infraestrutura como código. Você provisiona dois espaços de trabalho (dev e test) com Terraform, conecta o espaço de trabalho dev ao Git, cria um item em dev e depois o promove para test com a biblioteca Python fabric-cicd. Tudo roda sob um único princípio de serviço, então o mesmo fluxo funciona no seu laptop hoje e em um pipeline CI/CD amanhã.

Neste tutorial, você:

Dois aviões, duas ferramentas

Automatizar uma versão do Fabric tem duas preocupações distintas, e ajuda mantê-las separadas: o plano de controle estável (a infraestrutura em que seu conteúdo reside) e o plano de dados volátil (o conteúdo que você edita todos os dias). Associe a ferramenta de implantação à frequência com que cada elemento muda.

• O plano de controle armazena infraestrutura não volátil que você provisiona uma vez e raramente muda: capacidades, espaços de trabalho e suas configurações, domínios, conexões, configurações de locatário e fiação RBAC e Git. Este tutorial o provisiona com Terraform.
• A camada de dados abriga conteúdo volátil que evolui a cada sprint e circula pelo Git: notebooks, lakehouses e warehouses, modelos semânticos e relatórios, pipelines e dataflows, e valores da Biblioteca de Variáveis. Este tutorial move isso com fabric-cicd.

A ideia orientadora: provisionar a plataforma estável uma vez com o Terraform e então deixar que os elementos voláteis fluam continuamente por meio do Git e do fabric-cicd.

Essa é uma abordagem para automatizar o Fabric, e favorece equipes que já tratam infraestrutura como código e desejam uma configuração scriptável e controlada por código-fonte. O Fabric também oferece pipelines de implantação baseados em portais e integração com Git, que você pode conduzir a partir da interface sem precisar escrever Terraform ou Python. Para uma comparação das opções, veja opções de fluxo de trabalho CI/CD no Fabric.

Especificamente para a implantação do plano de dados, fabric-cicd é uma opção. Você também pode chamar diretamente as APIs REST do Fabric bulk (CRUD) se quiser controle total sobre as chamadas de criar, atualizar e excluir sem depender da biblioteca. Este tutorial usa o fabric-cicd porque ele faz a reconfiguração específica para cada ambiente para você.

Por que Terraform para o plano de controle

• Declarativo e idempotente. Você descreve o estado desejado dos seus espaços de trabalho uma vez; A Terraform cria o que falta e deixa o resto intacto.
• Detecção de deriva. terraform plan Mostra exatamente como o inquilino ao vivo difere da sua fonte de verdade, de modo que uma mudança fora de banda no portal se torna visível e reversível.
• Um fornecedor para vários recursos. O provedor Microsoft Fabric gerencia espaços de trabalho, capacidades, conexões, links Git e RBAC por meio das APIs REST do Fabric.

Por que usar o fabric-cicd para o plano de dados

• Implanta da forma que o Fabric espera. fabric-cicd lê a representação Git dos seus itens e os publica com a semântica correta de criação ou atualização, para que você não role manualmente as chamadas REST.
• Parametrização. Um arquivo parameter.yml remapeia valores específicos do ambiente, como o lakehouse padrão de um notebook ou a conexão de um modelo semântico para o destino correto em cada ambiente.
• Limpeza. Ele pode desfazer a publicação de itens que foram removidos do Git, mantendo cada ambiente como um espelho fiel da ramificação que rastreia.

O fluxo de ponta a ponta

Os dois planos se integram em uma automação única e contínua. Você provisiona a plataforma uma vez e, a partir daí, toda alteração de conteúdo segue o mesmo ciclo repetível — do seu editor, passando pelo Git, até o ambiente de teste — sem etapas manuais do portal entre elas.

A mesma entidade de serviço autentica todas as etapas, então o fluxo que você executa manualmente neste tutorial é exatamente o que um pipeline de CI/CD executa em seu nome: uma etapa de provisionamento (Terraform) e, depois, uma etapa de implantação (fabric-cicd) que é executada sempre que o branch monitorado muda. Cada estágio corresponde a uma etapa abaixo:

Pré-requisitos

• Uma capacidade do Fabric. Os dois espaços de trabalho deste tutorial estão atribuídos à mesma capacidade. Uma capacidade de teste funciona.
• Uma entidade de serviço (registro de aplicativo do Microsoft Entra) com um segredo do cliente. Essa identidade única fornece os espaços de trabalho e executa a implantação.
• A configuração de locatário Entidades de serviço podem usar APIs do Fabric deve estar habilitada para um grupo de segurança que contenha a entidade de serviço. Para mais informações, consulte Habilitar a autenticação da entidade de serviço para as APIs do Fabric.
• Uma organização, projeto e repositório Git do Azure DevOps que o principal do serviço pode acessar. O repositório já deve conter o branch (por exemplo, main) e a pasta que você definiu ado_directory_name (por exemplo, /workspace). A conexão Git usa PreferRemote, que lê essa pasta no branch quando ela se conecta, então ambas devem existir antes. Se a pasta não existir, terraform apply falhará com GitProviderResourceNotFound. Para criá-lo, faça o commit de um arquivo placeholder vazio (como .gitkeep) nesse caminho na branch antes de executar o Terraform.
• As seguintes ferramentas instaladas localmente:
  • Terraform 1.8 ou posterior.
  • Python 3.9 ou posterior (até 3.13).
  • O CLI do Azure.

Configurar a autenticação

Tanto o Terraform quanto o fabric-cicd autenticam como o principal do serviço. Exporte suas credenciais como variáveis de ambiente para que ambas as ferramentas possam captá-las:

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: Provisionar os espaços de trabalho com o Terraform

Nessa etapa, você define o plano de controle como código e o aplica. Crie uma pasta para sua configuração do Terraform e adicione os seguintes arquivos.

Configure o provedor

Crie provider.tf. Fixar a versão do provedor mantém todos os engenheiros em comportamento idêntico.

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

Declare as entradas

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

Defina os recursos

Crie main.tf. Essa configuração cria dois espaços de trabalho, uma conexão com o controle de código-fonte, o vínculo do Git na dev e atribuições de função.

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

Declare as saídas

Crie outputs.tf. O nome do espaço de trabalho de teste alimenta a etapa de implantação.

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
}

Aplicar a configuração

Forneça valores para as variáveis (por exemplo, em um terraform.tfvars arquivo que você mantém fora do Git), então execute:

terraform init
terraform plan
terraform apply

O Terraform reporta os recursos que criou e imprime os resultados.

Desafios de provisionamento que você deve conhecer

O provedor Fabric é poderoso, mas alguns comportamentos atrapalham as pessoas. Tenha isso em mente antes de rodar isso em produção:

• A conexão Git não pode ser importada. O fabric_workspace_git recurso não suporta terraform import. Trate isso como uma inicialização única e salve no estado remoto para que as execuções posteriores não tentem recriá-lo. Armazene seu estado em um backend compartilhado, como o Armazenamento do Azure, em vez de em um único laptop.
• Nomes do Git que diferenciam maiúsculas de minúsculas. A API do Fabric retorna nomes de projetos e repositórios do Azure DevOps em minúsculas. Se você passar em casos mistos, a Terraform relata que "o provedor produziu resultado inconsistente após a aplicação." Envolva-os em lower(), como mostrado acima.
• Escopo principal de serviço. A mesma identidade deve ser capaz de criar espaços de trabalho na capacidade e ser adicionada como membro do espaço de trabalho. Se o provisionamento falhar com um erro de autorização, verifique novamente a configuração de locatário e a atribuição de função de capacidade a partir dos pré-requisitos.
• Segredos fiquem fora do estado sempre que possível. O segredo da conexão usa o argumento client_secret_wo somente para gravação, para que não seja armazenado no estado em texto simples. Ainda assim, proteja seu arquivo de estado como informação sensível.

Passo 2: Verifique a conexão Git

O Terraform já conectou o espaço de trabalho do desenvolvedor ao Git no Step 1. Confirme:

1. No portal do Fabric, abra o espaço de trabalho releaseflow-dev.
2. Selecione configurações do Workspace>integração do Git.
3. Confirme que o espaço de trabalho está conectado à sua organização Azure DevOps, projeto, repositório, branch e à pasta que você definiu em ado_directory_name.

Passo 3: Criar conteúdo no dev e commitar

Agora adicione conteúdo ao espaço de trabalho do desenvolvedor e envie para o Git. Neste tutorial, você cria dois itens: uma casa do lago e um caderno que lê dela.

1. Em releaseflow-dev, crie uma casa de lago chamada demoLakehouse.
2. Crie um caderno chamado demoNotebook. Anexe demoLakehouse como seu lakehouse padrão e adicione uma célula que leia uma tabela ou escreva um pequeno DataFrame de exemplo.
3. Execute o notebook uma vez para confirmar se funciona contra o Lakehouse do desenvolvedor.
4. Abra o Controle de código-fonte no espaço de trabalho, selecione ambos os itens e faça o commit deles na sua branch.

Após o commit, seu repositório contém uma demoLakehouse.Lakehouse pasta e uma demoNotebook.Notebook pasta sob o diretório que você configurou.

Passo 4: Implantar do dev para testar com fabric-cicd

O espaço de trabalho de teste ainda está vazio. Use o fabric-cicd para publicar os itens do Git no ambiente de teste, revinculando o notebook ao lakehouse de teste durante o processo.

Instalar fabric-cicd

Crie requirements.txt:

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

Instale:

pip install -r requirements.txt

Adicionar um arquivo de parâmetros

O notebook armazenado no Git aponta para o dev lakehouse e o workspace dev. Quando você faz o deploy no ambiente de teste, essas referências devem ser alteradas para que o notebook leia e grave dados de teste. O fabric-cicd faz isso com um parameter.yml arquivo.

Crie parameter.yml ao lado do seu script de implantação. Substitua os dois GUIDs provisórios pelo ID real do dev lakehouse e pelo dev workspace ID que aparecem no conteúdo do seu notebook comprometido:

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"

Os tokens $items.Lakehouse.demoLakehouse.$id e $workspace.$id são resolvidos pelo fabric-cicd durante a implantação para os GUIDs no workspace de destino.

Escreva o script de implantação

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

Executar a implantação

Aponte o script para o nome do workspace de teste que o Terraform imprimiu como test_workspace_name. Clone seu repositório (ou reutilize a cópia local que o desenvolvedor comprometeu) para que as pastas de itens fiquem disponíveis localmente, então execute:

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

O Fabric-CICD cria a casa do lago e o caderno no test, aplica as find_replace regras e reporta cada item publicado.

Passo 5: Verifique a promoção

Confirme que o teste recebeu uma cópia corretamente rebound do conteúdo:

1. No portal do Fabric, abra o espaço de trabalho releaseflow-test.
2. Confirme que demoLakehouse e demoNotebook já existem.
3. Abra o demoNotebook e confirme que o lakehouse padrão é o testdemoLakehouse, não o de desenvolvimento.
4. Execute o bloco de anotações. Ele deve ler e escrever o teste da casa do lago.

Agora você tem um ciclo de vida repetível: altere itens no ambiente de desenvolvimento, faça commit no Git e execute novamente deploy.py para promover para o ambiente de teste.

Automate in Azure DevOps

Tudo que você rodou localmente usa o mesmo princípio de serviço que um pipeline usa, então migrar para CI/CD é basicamente uma questão de colocar esses comandos em estágios do pipeline: um estágio executa terraform apply (plano de controle), um estágio posterior executa deploy.py (plano de dados). Para ver um passo a passo completo da etapa de implantação do fabric-cicd no Azure Pipelines, com controles de aprovação, incluindo grupos de variáveis e aprovações, consulte Tutorial: CI/CD com Azure DevOps e a biblioteca fabric-cicd.

Estenda este tutorial

Este tutorial inclui um caderno e uma casa de lago. O mesmo padrão se aplica a outras partes do plano de dados:

• Adicione SemanticModel e Report a ITEM_TYPES e adicione uma regra semantic_model_binding em parameter.yml para apontar os modelos para a conexão de cada ambiente.
• Adicione um VariableLibrary e deixe o fabric-cicd ativar o conjunto de valores que corresponde ao --environment que você passa.
• Adicione uma etapa pós-implantação (por exemplo, atualizar um modelo semântico ou executar um notebook de teste de fumaça) após publish_all_items.

Limpar os recursos

Para evitar consumir capacidade, remova os espaços de trabalho que você criou. Da sua pasta Terraform:

terraform destroy

Alternativamente, exclua os releaseflow-dev espaços de trabalho e releaseflow-test do portal Fabric.

Conteúdo relacionado

• O que é CI/CD no Microsoft Fabric?
• Opções de fluxo de trabalho de CI/CD no Fabric
• Tutorial: CI/CD usando Azure DevOps e a biblioteca fabric-cicd
• Tutorial: CI/CD usando a API em massa do Fabric
• Tutorial: Gerenciamento do ciclo de vida de aplicações no Fabric
• Provedor Microsoft Fabric Terraform
• Documentação da biblioteca Fabric-CICD