Opastus: End-to-end -automaatio Fabric:ssa

Tässä opetusohjelmassa rakennat täydellisen, toistettavan julkaisuprosessin Microsoft Fabric:lle käyttäen infrastruktuuria koodina. Asetat kaksi työtilaa (dev ja test) Terraformilla, yhdistät dev-työtilan Gitiin, luot alkion devissä ja ylennät sen sitten testattavaksi fabric-cicd Python -kirjastolla. Kaikki toimii yhdellä palveluperiaatteen alla, joten sama prosessi toimii läppärilläsi tänään ja CI/CD-putkessa huomenna.

Tässä opetusohjelmassa:

Kaksi tasoa, kaksi työkalua

Fabric-julkaisun automatisoinnissa on kaksi erillistä huolenaihetta, ja se auttaa pitämään ne erillään: vakaa ohjaustaso (infrastruktuuri, jossa sisältösi sijaitsee) ja epävakaa datataso (sisältö, jota muokkaat päivittäin). Sovita käyttöönottotyökalu siihen, kuinka usein kukin asia muuttuu.

• Ohjaustaso sisältää ei-haihtuvaa infrastruktuuria, jonka luot kerran ja jota muutat harvoin: kapasiteetit, työtilat ja niiden asetukset, domainit, yhteydet, vuokralaisasetukset sekä RBAC- ja Git-johdotukset. Tämä opastus tarjoaa sille Terraformin.
• Datataso sisältää epävakaan sisällön, joka kehittyy jokaisessa sprintissä ja kulkee Gitin läpi: muistikirjoja, järvitaloja ja varastoja, semanttisia malleja ja raportteja, putkistoja ja datavirtoja sekä muuttuvien kirjastojen arvoja. Tämä opas liikuttaa sitä fabric-cicd-menetelmällä.

Ohjaava ajatus: varustaa vakaa alusta kerran Terraformilla, ja anna sitten haihtuvien esineiden virrata jatkuvasti Gitin ja fabric-cicdin kautta.

Tämä on yksi tapa automatisoida Fabric, ja se suosii tiimejä, jotka jo käsittelevät infrastruktuuria koodina ja haluavat skriptatolun, lähdekoodin ohjaaman kokoonpanon. Fabric tarjoaa myös portaalipohjaisia käyttöönottoputkia ja Git-integraatiota, joita voi ohjata käyttöliittymästä ilman, että tarvitsee kirjoittaa Terraformia tai Python. Vaihtoehtojen vertailua varten katso CI/CD-työnkulkuvaihtoehdot Fabric-sivustolla.

Datatason käyttöönotossa erityisesti fabric-cicd on yksi vaihtoehto. Voit myös kutsua Fabric bulk (CRUD) REST API:t suoraan, jos haluat täyden hallinnan luomis-, päivitys- ja poistokutsuihin ilman, että joudut olemaan riippuvaisia kirjastosta. Tämä opetusohjelma käyttää fabric-cicd-menetelmää, koska se hoitaa ympäristökohtaisen uudelleensidonnan puolestasi.

Miksi Terraform ohjaustasolle

• Deklaratiivinen ja idempotentti. Kuvailet työtilojesi toivottua tilaa kerran; Terraform luo puuttuvan ja jättää loput rauhaan.
• Driftin tunnistus. terraform plan Näyttää tarkalleen, miten elävä vuokralainen eroaa totuuden lähteestäsi, joten portaalin ulkoinen muutos tulee näkyväksi ja palautettavaksi.
• Yksi palveluntarjoaja monille resursseille. Microsoft Fabric -palveluntarjoaja hallinnoi työtiloja, kapasiteetteja, yhteyksiä, Git-linkkejä ja RBAC:ia Fabric REST -rajapintojen kautta.

Miksi fabric-cicd datatasolle

• Otetaan käyttöön Fabric odotetulla tavalla. fabric-cicd lukee Git-esityksen kohteistasi ja julkaisee ne oikeilla luomis- tai päivitys-semantiikalla, joten et joudu pyörittämään REST-kutsuja käsin.
• Parametrisointi. Tiedosto parameter.yml sitoo ympäristökohtaiset arvot uudelleen, kuten ohjaamalla muistikirjan oletusjärvirakennuksen tai semanttisen mallin yhteyden oikeaan kohteeseen ympäristössä.
• Puhdistus. Se voi poistaa Gitistä poistettuja kohteita, pitäen jokaisen ympäristön uskollisena peilikuvana siitä haarasta, jota se seuraa.

Päästä päähän -kulku

Nämä kaksi tasoa yhdistyvät yhdeksi jatkuvaksi automaatioksi. Alusta toteutetaan kerran, ja siitä lähtien jokainen sisältömuutos seuraa samaa toistettavaa silmukkaa – editorista Gitin kautta testiympäristöön – ilman manuaalisia portaalin vaiheita välissä.

Sama palveluperiaate tunnistaa jokaisen vaiheen, joten tässä opastuaalissa käsin suoritettava flow on juuri se, mitä CI/CD-putki suorittaa puolestasi: provisionointivaihe (Terraform), sitten deploy-vaihe (fabric-cicd), joka käynnistyy aina, kun seurattava haara muuttuu. Jokainen vaihe kattaa alla olevan vaiheen:

Edellytykset

• A Fabric Capacity. Molemmat työtilat tässä tutoriaalissa on määritetty samaan kapasiteettiin. Kokeilukapasiteetti toimii.
• Palvelupäällikkö (Microsoft Entra -sovelluksen rekisteröinti) asiakassalaisuudella. Tämä yksittäinen identiteetti tarjoaa työtilat ja suorittaa käyttöönoton.
• Tenant-asetuksen palvelupäämiehet voivat käyttää Fabric-rajapintoja käytössä tietoturvaryhmälle, joka sisältää palvelupäähenkilön. Lisätietoja löytyy kohdasta Enable service principal authentication for Fabric APIs.
• Azure DevOps -organisaatio, projekti ja Git-repositorio, johon palvelupäähenkilö pääsee käsiksi. Repositoriossa täytyy jo olla haara (esimerkiksi main) ja kansio, jonka olet asettanut ado_directory_name (esim. /workspace). Git-yhteys käyttää PreferRemote, joka lukee kyseisen kansion haaralla yhdistämisen yhteydessä, joten molempien täytyy olla olemassa etukäteen. Jos kansio puuttuu, terraform apply epäonnistuu .GitProviderResourceNotFound Luodaksesi sen, commit tyhjä paikkamerkkitiedosto (esim .gitkeep. ) kyseiselle polulle haarassa ennen kuin suoritat Terraformin.
• Seuraavat työkalut asennettiin paikallisesti:
  • Terraform 1.8 tai uudempi.
  • Python 3.9 tai uudempi (versioon 3.13 asti).
  • Azure CLI.

Todennuksen määrittäminen

Sekä Terraform että fabric-cicd tunnistautuvat palvelun periaatteiksi. Vie sen tunnistetiedot ympäristömuuttujina, jotta molemmat työkalut voivat poimia ne:

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

Vaihe 1: Tarjoa työtilat Terraformilla

Tässä vaiheessa määrittelet ohjaustason koodiksi ja sovellat sitä. Luo kansio Terraform-konfiguraatiolle ja lisää seuraavat tiedostot.

Määritä palveluntarjoaja

Luo provider.tf. Provider-version kiinnittäminen pitää jokaisen insinöörin identtisessä toiminnassa.

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

Ilmoita syötteet

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

Määrittele resurssit

Luo main.tf. Tämä konfiguraatio luo kaksi työtilaa, lähdekoodin hallintayhteyden, Git-linkin kehityksessä sekä roolijaot.

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

Ilmoita ulostulot

Luo outputs.tf. Testityötilan nimi syöttää käyttöönoton vaiheen.

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
}

Sovella konfiguraatiota

Anna muuttujille arvot (esimerkiksi terraform.tfvars tiedostossa, jonka pidät poissa Gitistä), sitten suorita:

terraform init
terraform plan
terraform apply

Terraform raportoi luomansa resurssit ja tulostaa tulokset.

Provisiointihaasteet, joista kannattaa tietää

Fabric-palveluntarjoaja on voimakas, mutta muutamat käyttäytymismallit saavat ihmiset hämmentymään. Pidä nämä mielessä ennen kuin käynnistät tämän tuotannossa:

• Git-yhteyttä ei voi tuoda. Resurssi fabric_workspace_git ei tue terraform import. Käsittele sitä kertakäyttöisenä käynnistystilanteena ja pidä se etätilassa, jotta myöhemmissä ajoissa et yritä luoda sitä uudelleen. Tallenna tilasi jaetussa taustajärjestelmässä, kuten Azure-tallennus, sen sijaan että käyttäisit sitä yhdellä kannettavalla.
• Kirjainkoon sensitiiviset Git-nimet. Fabric API palauttaa Azure DevOps -projektin ja repositorioiden nimet pienkirjaimina. Jos läpäiset ne sekakäyttöisessä tapauksessa, Terraform raportoi "palveluntarjoaja tuotti epäjohdonmukaisen tuloksen käytön jälkeen." Kääri ne , lower()kuten yllä on esitetty.
• Palvelun pääasiallinen laajuus. Saman identiteetin täytyy pystyä luomaan työtiloja kapasiteetille ja lisätä työtilan jäseneksi. Jos provisionointi epäonnistuu valtuutusvirheen vuoksi, tarkista vuokralaisasetus ja kapasiteetin roolien määritys edellytyksistä.
• Salaisuudet pysyvät poissa osavaltiosta aina kun mahdollista. Yhteyden salaisuus käyttää kirjoitusargumenttia client_secret_wo , joten sitä ei tallenneta selväkieliseen tilaan. Suojaa kuitenkin osavaltion tiedostosi arkaluontoisena.

Vaihe 2: Varmista Git-yhteys

Terraform on jo yhdistänyt kehitystyötilan Gitiin vaiheessa 1. Vahvista se:

1. Fabric-portaalissa avaa työtilareleaseflow-dev.
2. Valitse Workspace-asetukset>Git-integraatio.
3. Varmista, että työtila on yhdistetty Azure DevOps -organisaatioosi, projektiisi, varastoosi, haaraan ja kansioon, jonka olet asettanut ado_directory_name.

Vaihe 3: Kirjoita sisältöä kehityksessä ja sitoudu siihen

Lisää nyt sisältöä dev-työtilaan ja työnnä se Gitille. Tässä tutoriaalissa luot kaksi esinettä: järvimajan ja muistikirjan, joka lukee siitä.

1. Luo releaseflow-devjärvenrakennus nimeltä demoLakehouse.
2. Luo muistikirja nimeltä demoNotebook. Liitä demoLakehouse sen oletusjärvitaloksi ja lisää solu, joka lukee taulukon tai kirjoittaa pienen näytedatakehyksen.
3. Aja muistikirja kerran varmistaaksesi, että se toimii kehittäjärvitaloa vastaan.
4. Avoimen lähdekoodin hallinta työtilassa, valitse molemmat kohteet ja sitoudu haaraan.

Commitin jälkeen arkistossasi on kansio demoLakehouse.Lakehouse ja demoNotebook.Notebook kansio sen kansion alla, jonka olet konfiguroinut.

Vaihe 4: Deploy kehityksestä testaukseen fabric-cicd:llä

Testityötila on edelleen tyhjä. Käytä fabric-cicd:ää julkaistakseni Gitin kohteet testissä ja sitomalla vihkon uudelleen testijärvenrakennukseen matkan varrella.

Asenna fabric-cicd

Luo requirements.txt:

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

Asenna se:

pip install -r requirements.txt

Lisää parametritiedosto

Gitissä oleva muistikirja osoittaa dev-järvitaloon ja kehitystyötilaan. Kun otat käyttöön testiin, viittaukset täytyy muuttua niin, että muistikirja lukee ja kirjoittaa testidataa. Fabric-CICD tekee tämän tiedoston parameter.yml avulla.

Luo parameter.yml käyttöönottoskriptisi viereen. Korvaa kaksi väliaikaista GUID:tä varsinaisilla dev lakehouse ID:llä ja dev workspace ID:llä, jotka näkyvät sitoutuneessa muistikirjan sisällössä:

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"

Ja-tokenit $items.Lakehouse.demoLakehouse.$id$workspace.$id ratkaistaan fabric-cicd:llä julkaisuhetkellä GUID-tiedostoihin kohdetyötilassa .

Kirjoita käyttöönottoskripti

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

Suorita käyttöönotto

Osoita skriptillä testityötilan nimi, jonka Terraform tulosti muodossa test_workspace_name. Kloonaa repositio (tai käytä uudelleen kehittäjän tekemää paikallista kopiota), jotta item folderit ovat saatavilla paikallisesti, ja suorita sitten:

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

Fabric-CICD luo Lakehousen ja Notebookin testissä, soveltaa sääntöjä find_replace ja raportoi jokaisen julkaistun kohteen.

Vaihe 5: Varmista ylennys

Varmista, että testi sai oikein palautetun kopion sisällöstä:

1. Fabric-portaalissa avaa työtilareleaseflow-test.
2. Vahvista, että demoLakehouse ja demoNotebook ovat nyt olemassa.
3. Avaa demoNotebook ja varmista, että sen oletusjärvitalo on testidemoLakehouse, ei dev-testi.
4. Käynnistä muistikirja. Sen pitäisi lukea ja kirjoittaa testijärvimajoitus.

Nyt sinulla on toistettava elinkaari: vaihda esineitä kehityksessä, sitoudu Git-ohjelmaan ja aja deploy.py uudelleen ylennystä varten testattavaksi.

Automate in Azure DevOps

Kaikki paikallisesti ajamasi käyttää samaa palveluperiaatetta kuin putkisto, joten siirtyminen CI/CD:hen on lähinnä komentojen sijoittamista putkistovaiheisiin: yksi vaihe ( terraform apply ohjaustaso), myöhempi vaihe ( deploy.py datataso). Täydellisen, portatun Azure Pipelines -läpikäynnin fabric-cicd-käyttöönoton vaiheesta, mukaan lukien muuttujaryhmät ja hyväksynnät, löydät ohjeesta Tutorial: CI/CD using Azure DevOps and the fabric-cicd-kirjasto.

Laajenna tätä opetusta

Tässä tutoriaalissa sijoitetaan muistikirja ja järvimajoitus. Sama kuvio skaalautuu laajemmalle datatasolle:

• Lisää SemanticModel ja ReportITEM_TYPES ja lisää sääntö semantic_model_bindingparameter.yml osoittamaan malleja kunkin ympäristön yhteydessä.
• Lisää a VariableLibrary ja anna fabric-cicd:n aktivoida arvojoukko, joka vastaa läpäisemistäsi --environment .
• Lisää käyttöönoton jälkeinen vaihe (esimerkiksi semanttisen mallin päivittäminen tai savutestivihko) jälkeen publish_all_items.

Resurssien puhdistaminen

Jotta kapasiteetti ei kulu, poista luomasi työtilat. Terraform-kansiostasi:

terraform destroy

Vaihtoehtoisesti poista releaseflow-dev ja releaseflow-test työtilat Fabric-portaalista.

Liittyvä sisältö

• Mitä on CI/CD Microsoft Fabric:ssa?
• CI/CD-työnkulun asetukset Fabricissa
• Opastus: CI/CD käyttäen Azure DevOps:ia ja fabric-cicd-kirjastoa
• Opas: CI/CD käyttäen Fabric bulk API:ta
• Opas: Sovelluksen elinkaaren hallinta Fabric:ssa
• Microsoft Fabric Terraform -palveluntarjoaja
• Fabric-CICD-kirjaston dokumentaatio