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

Neste tutorial, constróis um fluxo de lançamento completo e repetível para o Microsoft Fabric usando infraestrutura como código. Provisionam-se dois espaços de trabalho (dev e test) com Terraform, liga-se o espaço de trabalho dev ao Git, cria-se um item em dev e, em seguida, promove-se para test com a biblioteca Python fabric-cicd. Tudo corre sob um único princípio de serviço, por isso o mesmo fluxo funciona hoje no teu portátil e amanhã num pipeline CI/CD.

Neste tutorial, irá aprender a:

Dois aviões, duas ferramentas

Automatizar um lançamento Fabric tem duas preocupações distintas, e ajuda mantê-las separadas: o plano de controlo estável (a infraestrutura onde o seu conteúdo reside) e o plano de dados volátil (o conteúdo que edita todos os dias). Ajusta a ferramenta de implementação à frequência com que cada coisa muda.

• O plano de controlo contém infraestruturas não volátils que se provisionam uma vez e raramente mudam: capacidades, espaços de trabalho e as suas definições, domínios, ligações, definições de inquilino, e cablagem RBAC e Git. Este tutorial aprovisiona-o com Terraform.
• O plano de dados contém conteúdo volátil que evolui em cada sprint e circula através do Git: notebooks, lakehouses e warehouses, modelos semânticos e relatórios, pipelines e fluxos de dados, e valores da Variable Library. Este tutorial usa o fabric-cicd.

A ideia orientadora: fornecer a plataforma estável uma vez com Terraform, depois deixar os itens voláteis fluírem continuamente através do Git e do fabric-cicd.

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

Para a implementação do plano de dados especificamente, o fabric-cicd é uma opção. Também pode chamar diretamente as APIs REST do Fabric bulk (CRUD) se quiser controlar totalmente as chamadas de criar, atualizar e eliminar sem depender da biblioteca. Este tutorial utiliza o fabric-cicd porque trata da reatribuição específica do ambiente por si só.

Porquê Terraform para o plano de controlo

• Declarativo e idempotente. Você descreve o estado desejado dos seus espaços de trabalho uma única vez; a Terraform cria o que falta e deixa o restante inalterado.
• Deteção de deriva. terraform plan Mostra exatamente como o inquilino ao vivo difere da sua fonte de verdade, de modo que uma alteração fora de banda no portal torna-se visível e reversível.
• Um fornecedor para vários recursos. O fornecedor Microsoft Fabric gere espaços de trabalho, capacidades, ligações, ligações Git e RBAC através das APIs REST do Fabric.

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

• Implementa-se da forma que o Fabric espera. O fabric-cicd lê a representação dos seus itens no Git e publica-os com a semântica correta de criação ou atualização, para que não tenha de criar manualmente chamadas REST.
• Parametrização. Um ficheiro parameter.yml reatribui valores específicos do ambiente, como definir o lakehouse predefinido de um notebook ou a ligação de um modelo semântico para o destino correto em cada ambiente.
• Limpeza. Pode despublicar itens que foram removidos do Git, mantendo cada ambiente um espelho fiel do ramo que acompanha.

O fluxo de ponta a ponta

Os dois planos unem-se num único processo de automatização contínuo. Provisiona-se a plataforma uma vez e, a partir daí, cada alteração de conteúdo segue o mesmo ciclo repetível — do seu editor, passando pelo Git, até ao ambiente de teste — sem passos manuais do portal pelo meio.

O mesmo princípio de serviço autentica todas as etapas, por isso o fluxo que executas manualmente neste tutorial é exatamente o que um pipeline CI/CD executa em teu nome: uma fase de provisão (Terraform), depois uma fase de implementação (fabric-cicd) que corre sempre que a ramificação rastreada muda. Cada fase corresponde a um passo abaixo:

Pré-requisitos

• Uma capacidade do Fabric. Ambos os espaços de trabalho neste tutorial estão atribuídos à mesma função. Uma capacidade de ensaio funciona.
• Um principal de serviço (registo da aplicação Microsoft Entra) com um segredo do cliente. Esta identidade única fornece os espaços de trabalho e executa a implementação.
• Os principais de serviço que definem o tenant podem usar APIs Fabric ativadas para um grupo de segurança que contenha o principal de serviço. Para mais informações, consulte Ativar a autenticação do principal de serviço para as APIs do Fabric.
• Uma organização, projeto e repositório Git do Azure DevOps ao qual o principal do serviço pode aceder. O repositório deve já conter o branch (por exemplo, main) e a pasta que definiste ado_directory_name (por exemplo, /workspace). A ligação ao Git usa PreferRemote, que lê essa pasta na ramificação quando se liga, pelo que ambos têm de existir previamente. Se a pasta não existir, terraform apply falha com GitProviderResourceNotFound. Para o criar, compromete um ficheiro provisório vazio (como .gitkeep) nesse caminho no ramo antes de executares o Terraform.
• As seguintes ferramentas instaladas localmente:
  • Terraform 1.8 ou posterior.
  • Python 3.9 ou posterior (até 3.13).
  • A CLI do Azure.

Configurar a autenticação

Tanto o Terraform como o fabric-cicd autenticam-se enquanto entidade de serviço. Exporte as suas credenciais como variáveis de ambiente para que ambas as ferramentas possam detetá-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

Neste passo, defines o plano de controlo como código e aplica-o. Crie uma pasta para a sua configuração do Terraform e adicione os seguintes ficheiros.

Configurar o fornecedor

Cria provider.tf. Fixar a versão do fornecedor 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
}

Declarar 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

Cria main.tf. Esta configuração cria duas áreas de trabalho, uma ligação ao controlo de versões, a ligação ao Git no ambiente de desenvolvimento e atribuições de funções.

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 as saídas

Cria outputs.tf. O nome do espaço de trabalho de teste alimenta a etapa de implementaçã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, num terraform.tfvars ficheiro que mantém fora do Git) e depois execute:

terraform init
terraform plan
terraform apply

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

Desafios do provisionamento a ter em conta

O provedor Fabric é poderoso, mas alguns comportamentos confundem os utilizadores. Tenha isto em consideração antes de executar isto em produção:

• A ligação Git não pode ser importada. O fabric_workspace_git recurso não suporta terraform import. Trata-o como uma inicialização única e persiste-o no estado remoto para que as execuções futuras não tentem recriá-lo. Guarde o seu estado num backend partilhado, como o Armazenamento do Azure, em vez de num único portátil.
• Nomes do Git que distinguem maiúsculas de minúsculas. A API do Fabric devolve os nomes de projetos e de repositórios do Azure DevOps em minúsculas. Se passar em casos mistos, a Terraform reporta "o fornecedor produziu resultados inconsistentes após a aplicação." Envolva-os em lower(), como mostrado acima.
• Âmbito principal do 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, volte a verificar a definição do tenant e a atribuição da função de capacidade indicada nos pré-requisitos.
• Os segredos mantêm-se fora do estado sempre que possível. O segredo da ligação usa o argumento client_secret_wo só de escrita, pelo que não é armazenado no estado em texto simples. Ainda assim, proteja o seu ficheiro de estado como informação sensível.

Passo 2: Verificar a ligação Git

O Terraform já ligou o espaço de trabalho de desenvolvimento ao Git no Step 1. Confirme:

1. No portal do Fabric, abra o espaço de trabalho releaseflow-dev.
2. Selecione Definições do Espaço de Trabalho>Integração com Git.
3. Confirme que o espaço de trabalho está ligado à sua organização, projeto, repositório, branch e à pasta que definiu ado_directory_nameem Azure DevOps.

Passo 3: Criar conteúdo em desenvolvimento e commitá-lo

Agora adiciona conteúdo ao espaço de trabalho de desenvolvimento e envia-o para o Git. Neste tutorial crias dois itens: uma casa do lago e um caderno que lê dela.

1. Em releaseflow-dev, crie uma casa de lago chamada demoLakehouse.
2. Cria um caderno chamado demoNotebook. Anexe demoLakehouse como o seu lakehouse predefinido e adicione uma célula que leia uma tabela ou escreva um pequeno exemplo de DataFrame.
3. Execute o notebook uma vez para confirmar que funciona no lakehouse de desenvolvimento.
4. Abra Controlo de código-fonte na área de trabalho, selecione ambos os itens e Confirme-os no seu ramo.

Depois do commit, o seu repositório contém uma demoLakehouse.Lakehouse pasta e uma demoNotebook.Notebook pasta sob o diretório que configurou.

Passo 4: Implementar de desenvolvimento para teste com o fabric-cicd

O espaço de trabalho de testes continua vazio. Utilize o fabric-cicd para publicar os itens do Git no ambiente de teste, voltando a associar 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-o:

pip install -r requirements.txt

Adicionar um ficheiro de parâmetros

O bloco de notas armazenado no Git aponta para o lakehouse dev e o espaço de trabalho dev. Quando implementas para testar, essas referências têm de mudar para que o caderno leia e escreva dados de teste. O Fabric-CICD faz isto com um parameter.yml ficheiro.

Cria parameter.yml ao lado do teu script de implementação. Substitua os dois GUIDs provisórios pelo ID real do dev lakehouse e pelo ID do espaço de trabalho de desenvolvimento que aparecem no conteúdo comprometido do teu caderno:

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 no momento da implementação para os GUIDs na área de trabalho de destino.

Escrever o script de implementaçã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 espaço de trabalho de teste que o Terraform apresentou como test_workspace_name. Clone o seu repositório (ou reutilize a cópia local que o programador comprometeu) para que as pastas de itens fiquem disponíveis localmente, depois execute:

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

fabric-cicd cria o lakehouse e o bloco de notas em teste, aplica as regras find_replace e comunica cada item publicado.

Passo 5: Verificar a promoção

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

1. No portal do Fabric, abra o espaço de trabalho releaseflow-test.
2. Confirma que o demoLakehouse e o demoNotebook já existem.
3. Abra demoNotebook e confirme que o lakehouse predefinido é o testdemoLakehouse, e não o de desenvolvimento.
4. Passa o caderno. Deve ler e escrever a casa do lago de teste.

Agora tens um ciclo de vida repetível: mudas itens no dev, compromete-te com o Git e reexecutas deploy.py para promover para testar.

Automate in Azure DevOps

Tudo o que executaste localmente usa o mesmo princípio de serviço que um pipeline usa, por isso passar para CI/CD é principalmente uma questão de colocar estes comandos em estágios de pipeline: um estágio executa terraform apply (plano de controlo), um estágio posterior executa deploy.py (plano de dados). Para uma explicação detalhada e controlada no Azure Pipelines da fase de implementação do fabric-cicd, 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 aplica-se a uma parte maior 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 ligação de cada ambiente.
• Adiciona um VariableLibrary e permite que o fabric-cicd ative o conjunto de valores correspondente ao --environment que passas.
• Adicione um passo pós-implementação (por exemplo, atualizar um modelo semântico ou executar um caderno de testes de fumo) após publish_all_items.

Limpeza de recursos

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

terraform destroy

Alternativamente, apague 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 CI/CD no Fabric
• Tutorial: CI/CD usando Azure DevOps e a biblioteca fabric-cicd
• Tutorial: CI/CD usando a API Fabric bulk
• Tutorial: Gestão do ciclo de vida de aplicações no Fabric
• Fornecedor Microsoft Fabric Terraform
• Documentação da biblioteca Fabric-CICD