Ta i bruk bundles¶

Denne guiden viser hvordan du oppretter, konfigurerer og deployer en bundle til flere Databricks-workspaces. Se Declarative Automation Bundles (konsept) for bakgrunn om targets, modes og wheel-strategier.

Forutsetninger¶

• Databricks CLI installert og autentisert mot workspacet ditt
• uv installert (for wheel-bygging)
• Tilgang til minst ett Databricks-workspace
• Klonet padda-golden-path-repoet

Opprette en ny bundle fra malen¶

Bruk Padda Asset Bundle Templates til å opprette en ny bundle:

databricks bundle init /sti/til/padda-golden-path/bundle-templates

Du blir spurt om Unity Catalog-navn, workspace-host for stage og prod, domene-navn, domene-beskrivelse og hvilken setup_type du vil bruke (default, minimal eller tailored). Med default eller tailored se bundle-templates/README.md for hva de ulike valgene betyr.

Med setup_type: default genererer malen omtrent denne strukturen:

my-domain/
  databricks.yml                       # Hovedkonfigurasjon med targets
  pyproject.toml                       # Python-prosjekt (uv, ruff, mypy)
  resources/
    example_job.yml                    # Jobb på klassisk compute
    example_serverless_job.yml         # Jobb på serverless compute
    example_pipeline_job.yml           # Eksempel-pipeline
  notebooks/
    example_job.py
    pipelines/example-pipeline/...
  src/
    my_domain/
      main.py                          # Python-kode pakket som wheel

Konfigurere targets for stage og prod¶

Sette workspace-host per target¶

Åpne databricks.yml og sett workspace.host for hvert target til riktig workspace-URL:

targets:
  stage:
    mode: development
    default: true
    workspace:
      host: https://stage-workspace.cloud.databricks.com

  prod:
    mode: production
    workspace:
      host: https://prod-workspace.cloud.databricks.com
      root_path: ~/.bundle/${bundle.name}/${bundle.target}

Sette variabler per target¶

Definer variabler i en variables-blokk på toppnivå, og sett verdiene eksplisitt for hvert target:

variables:
  catalog:
    description: Unity Catalog-katalog
  schema:
    description: Schema for tabeller

targets:
  stage:
    mode: development
    default: true
    workspace:
      host: https://stage-workspace.cloud.databricks.com
    variables:
      catalog: dev_catalog
      schema: default

  prod:
    mode: production
    workspace:
      host: https://prod-workspace.cloud.databricks.com
      root_path: ~/.bundle/${bundle.name}/${bundle.target}
    variables:
      catalog: prod_catalog
      schema: production

Referer til variablene i jobbdefinisjoner med ${var.catalog} og ${var.schema}.

Sette root_path, permissions og run_as for prod¶

production-mode krever et eksplisitt root_path (eller at du deployer som service principal). I tillegg anbefaler vi å definere eierskap med permissions og run_as, slik at produksjonsressursene ikke er knyttet til en enkelt utviklers konto. Begge tar service principalens application ID (en UUID), ikke visningsnavnet:

targets:
  prod:
    mode: production
    workspace:
      host: https://prod-workspace.cloud.databricks.com
      root_path: ~/.bundle/${bundle.name}/${bundle.target}
    run_as:
      service_principal_name: <application-id>
    permissions:
      - service_principal_name: <application-id>
        level: CAN_MANAGE

Deklarere volumes som bundle-ressurser¶

Hvis jobbene dine leser fra og skriver til Unity Catalog Volumes som er tett koblet til koden (input-opplastinger, mellomliggende output, sluttresultater), kan du deklarere volumene som bundle-ressurser i samme repo som jobbene. Da følger volume-definisjonen samme livssyklus som koden, og endringer kan reviewes i samme pull request.

resources:
  volumes:
    uploads:
      catalog_name: ${var.catalog}
      schema_name: bronze_default
      name: uploads
      volume_type: MANAGED

Volumes for team-spesifikk data hører hjemme i team-repoet sammen med koden, mens kataloger og delte schemas administreres i padda-iac. Se Ansvarsfordeling mellom bundles og padda-iac for full oversikt.

Håndtere Python wheels¶

Ditt eget prosjekt: artifacts-seksjonen¶

Hvis prosjektet ditt har en pyproject.toml, legg til en artifacts-seksjon som bygger wheelet automatisk ved deploy:

artifacts:
  python_artifact:
    type: whl
    build: uv build --wheel

targets:
  stage:
    mode: development
    default: true
    presets:
      artifacts_dynamic_version: true

Referer til wheelet i jobbdefinisjonen. På serverless compute deklareres avhengigheter i en environments-blokk på jobb-nivå, og tasken peker på environment via environment_key:

resources:
  jobs:
    my_job:
      name: my_job
      tasks:
        - task_key: my_task
          timeout_seconds: 600
          python_wheel_task:
            package_name: my_project
            entry_point: main
            parameters:
              - "--input-dir=${var.input_dir}"
              - "--output-dir=${var.output_dir}"
          environment_key: default
      environments:
        - environment_key: default
          spec:
            client: "5"
            dependencies:
              - ../dist/*.whl

spec.client angir versjonen av serverless-environmentet — bruk siste versjon.

Flere tasks i samme jobb kan dele én environment_key, eller bruke ulike environments hvis de trenger forskjellige avhengigheter.

Tredjepartsbiblioteker¶

Workspacene har ikke tilgang til internett, så clusteret kan ikke hente avhengigheter fra PyPI (se Hvorfor clustere ikke har internett for bakgrunn). For tredjepartsbiblioteker (for eksempel openpyxl) som du ikke bygger selv, anbefaler vi å vendore wheels inn i bundlen: last dem ned lokalt før deploy og pakk dem sammen med ditt eget prosjekt.

Last ned avhengighetene til dist/deps/ før deploy:

mkdir -p dist/deps
uvx pip download openpyxl==3.1.5 -d dist/deps

Legg dist/deps/*.whl til som ekstra avhengighet på samme environments-blokk som ditt eget prosjekt:

environments:
  - environment_key: default
    spec:
      client: "5"
      dependencies:
        - ../dist/*.whl
        - ../dist/deps/*.whl

Bygge og deploye¶

Velge CLI-profil¶

Databricks CLI bruker profiler i ~/.databrickscfg for å holde styr på flere workspace-tilganger. En typisk konfigurasjon for et team med stage og prod ser slik ut:

[MY_TEAM_STAGE]
host = https://stage-workspace.cloud.databricks.com
auth_type = databricks-cli

[MY_TEAM_PROD]
host = https://prod-workspace.cloud.databricks.com
auth_type = databricks-cli

Logg inn én gang per profil:

databricks auth login --host https://stage-workspace.cloud.databricks.com --profile MY_TEAM_STAGE

I bundle-kommandoer velger du profil med -p:

databricks bundle validate -t stage -p MY_TEAM_STAGE

Validere konfigurasjonen¶

Kjør validate før du deployer for å fange opp feil i YAML-syntaks, manglende variabler og ugyldig konfigurasjon:

databricks bundle validate -t stage -p MY_TEAM_STAGE

Deploye til stage¶

databricks bundle deploy -t stage -p MY_TEAM_STAGE

Verifiser i Databricks-workspacet at jobben dukker opp under Workflows. I development-mode får jobben et prefiks med brukernavnet ditt, for eksempel [dev ola.nordmann] my_job.

Kjøre en jobb manuelt¶

databricks bundle run -t stage -p MY_TEAM_STAGE my_job

Deploye til prod¶

databricks bundle deploy -t prod -p MY_TEAM_PROD

Feilsøking¶

Trenger du hjelp?¶

• Spør i #dig-dataspeilet-support på Slack
• Opprett en issue i padda-golden-path
• Se Declarative Automation Bundles (konsept) for bakgrunn om targets, modes og wheel-strategier
• Se Declarative Automation Bundles (referanse) for konfigurasjonsoversikt og tilgjengelige eksempler