Condividi tramite

Configurazione del bundle di asset di Databricks

Questo articolo descrive la sintassi per i file di configurazione del bundle di asset di Databricks, che definiscono i bundle di asset di Databricks. Consulta Che cosa sono i pacchetti di risorse di Databricks?.

Per creare e usare bundle, vedere Sviluppare bundle di asset di Databricks.

databricks.yml

Un bundle deve contenere un file di configurazione (e solo uno) denominato databricks.yml nella radice della cartella del progetto bundle. databricks.yml è il file di configurazione principale che definisce un bundle, ma può fare riferimento ad altri file di configurazione, ad esempio i file di configurazione delle include risorse, nel mapping. La configurazione del bundle è espressa in YAML. Per altre informazioni su YAML, vedere la specifica YAML ufficiale.

Il più semplice databricks.yml definisce una distribuzione di destinazione e il nome del bundle, che si trova all'interno della mappatura di primo livello obbligatoria bundle.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Per informazioni dettagliate su tutti i mapping di primo livello, vedere Mapping.

Suggerimento

Il supporto python per i bundle di asset di Databricks consente di definire le risorse in Python. Vedere Configurazione del bundle in Python.

Specificazione

La specifica YAML seguente fornisce chiavi di configurazione di primo livello per i bundle di asset di Databricks. Per informazioni di riferimento sulla configurazione, vedere Informazioni di riferimento sulla configurazione.

# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_id: string
  deployment: Map
  git:
    origin_url: string
    branch: string

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are any additional configuration files to include.
include:
  - '<some-file-or-path-glob-to-include>'
  - '<another-file-or-path-glob-to-include>'

# These are any scripts that can be run.
scripts:
  <some-unique-script-name>:
    content: string

# These are any additional files or paths to include or exclude.
sync:
  include:
    - '<some-file-or-path-glob-to-include>'
    - '<another-file-or-path-glob-to-include>'
  exclude:
    - '<some-file-or-path-glob-to-exclude>'
    - '<another-file-or-path-glob-to-exclude>'
  paths:
    - '<some-file-or-path-to-synchronize>'

# These are the default artifact settings if not otherwise overridden in
# the targets top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    dynamic_version: boolean
    executable: string
    files:
      - source: string
    path: string
    type: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex
    lookup: Map
    type: string # The only valid value is "complex" if the variable is a complex variable, otherwise do not define this key.

# These are the default workspace settings if not otherwise overridden in
# the targets top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  resource_path: string
  root_path: string
  state_path: string

# These are the permissions to apply to resources defined
# in the resources mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    presets:
      <preset>: <value>
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

Esempi:

Questa sezione contiene alcuni esempi di base che consentono di comprendere il funzionamento dei bundle e come strutturare la configurazione.

Nota

Per esempi di configurazione che illustrano le funzionalità del bundle e i casi d'uso comuni del bundle, vedere Esempi di configurazione delbundle e il repository di esempi di bundle in GitHub.

La configurazione del bundle di esempio seguente specifica un file locale denominato hello.py che si trova nella stessa directory del file databricks.ymldi configurazione del bundle . Esegue questo notebook come attività utilizzando il cluster remoto con l'ID cluster assegnato. L'URL dell'area di lavoro remota e le credenziali di autenticazione dell'area di lavoro vengono lette dal profilo di configurazione locale del chiamante denominato DEFAULT.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

Nell'esempio seguente viene aggiunta una destinazione con il nome prod che usa un URL dell'area di lavoro remota e credenziali di autenticazione dell'area di lavoro diverse, che vengono lette dalla voce corrispondente del file del .databrickscfghost chiamante con l'URL dell'area di lavoro specificato. Questo processo esegue lo stesso notebook, ma usa un cluster remoto diverso con l'ID cluster specificato.

Nota

Databricks consiglia di usare il mapping host invece del mapping default laddove possibile, in quanto rende i file di configurazione del bundle più portabili. L'impostazione del host mapping indica all'interfaccia della riga di comando di Databricks di trovare un profilo corrispondente nel .databrickscfg file e quindi usare i campi del profilo per determinare il tipo di autenticazione di Databricks da usare. Se esistono più profili con un campo corrispondente host , è necessario usare l'opzione --profile nei comandi bundle per specificare un profilo da usare.

Si noti che non è necessario dichiarare il mapping notebook_taskall'interno del mapping prod, perché esegue il fallback per usare il mapping notebook_task all'interno del mapping di primo livello resources, se il mapping notebook_task non viene sottoposto esplicitamente a override all'interno del mapping prod.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Usare i comandi bundle seguenti per convalidare, distribuire ed eseguire questo processo all'interno della dev destinazione. Per informazioni dettagliate sul ciclo di vita di un bundle, vedere Sviluppo dei Bundle di Asset di Databricks.

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

Per convalidare, distribuire ed eseguire questo processo all'interno della destinazione prod invece:

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

Per una maggiore modularizzazione e un migliore riutilizzo delle definizioni e delle impostazioni tra bundle, suddividere la configurazione del bundle in file separati:

# databricks.yml

bundle:
  name: hello-bundle

include:
  - '*.yml'

# hello-job.yml

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

# targets.yml

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Mapping

Le sezioni seguenti descrivono le mappature di alto livello della configurazione del bundle. Per informazioni di riferimento sulla configurazione, vedere Informazioni di riferimento sulla configurazione.

pacchetto

Un file di configurazione del bundle deve contenere un solo mapping di primo livello bundle che associa il contenuto del bundle e le impostazioni dell'area di lavoro di Azure Databricks.

Questo mapping bundle deve contenere un mapping name che specifica un nome programmatico (o logico) per il bundle. Nell'esempio seguente viene dichiarato un bundle con il nome programmatico (o logico) hello-bundle.

bundle:
  name: hello-bundle

Un bundle mapping può anche essere figlio di una o più destinazioni nella mappatura destinazioni principale. Ognuna di queste mappature figlio bundle specifica eventuali sostituzioni non predefinite al livello di destinazione. Tuttavia, il valore del mapping di primo livello di bundle non può essere sovrascritto a livello di destinazione.

cluster_id

Il mapping bundle può avere un mapping figlio cluster_id. Questo mapping consente di specificare l'ID di un cluster da usare come override per i cluster definiti altrove nel file di configurazione del bundle. Per informazioni su come recuperare l'ID di un cluster, vedere URL e ID della risorsa di calcolo.

L'override cluster_id è destinato agli scenari di solo sviluppo ed è supportato solo per la destinazione con il relativo mapping mode impostato su development. Per altre informazioni sulla mappatura target, vedere destinazioni.

compute_id

Nota

Questa impostazione è deprecata. Usare cluster_id invece.

Il mapping bundle può avere un mapping figlio compute_id. Questo mapping consente di specificare l'ID di un cluster da usare come override per i cluster definiti altrove nel file di configurazione del bundle.

Git

È possibile recuperare ed eseguire l'override dei dettagli del controllo della versione Git associati al bundle, utile per propagare i metadati di distribuzione che possono essere usati in un secondo momento per identificare le risorse. Ad esempio, è possibile tracciare l'origine del repository di un processo distribuito da CI/CD.

Ogni volta che si esegue un bundle comando come validate, deploy o run, il bundle comando popola l'albero di configurazione del comando con le impostazioni predefinite seguenti:

  • bundle.git.origin_url, che rappresenta l'URL di origine del repository. Si tratta dello stesso valore che si otterrebbe se è stato eseguito il comando git config --get remote.origin.url dal repository clonato. È possibile usare le sostituzioni per fare riferimento a questo valore con i file di configurazione del bundle, come ${bundle.git.origin_url}.
  • bundle.git.branch, che rappresenta il ramo corrente all'interno del repository. Si tratta dello stesso valore che si otterrebbe se è stato eseguito il comando git branch --show-current dal repository clonato. È possibile usare le sostituzioni per fare riferimento a questo valore con i file di configurazione del bundle, come ${bundle.git.branch}.

Per recuperare o eseguire l'override delle impostazioni Git, il bundle deve trovarsi all'interno di una directory associata a un repository Git, ad esempio una directory locale inizializzata eseguendo il comando git clone. Se la directory non è associata a un repository Git, queste impostazioni Git sono vuote.

Se necessario, è possibile eseguire l'override delle impostazioni origin_url e branch all’interno del mapping git del mapping di primo livello bundle, come indicato di seguito:

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

databricks_cli_version

Il mapping bundle può contenere un mapping databricks_cli_version che vincola la versione dell'interfaccia della riga di comando di Databricks richiesta dal bundle. Ciò può impedire problemi causati dall'uso di mapping non supportati in una determinata versione dell'interfaccia della riga di comando di Databricks.

La versione dell'interfaccia della riga di comando di Databricks è conforme al controllo delle versioni semantiche e il databricks_cli_version mapping supporta la specifica dei vincoli di versione. Se il valore corrente databricks --version non rientra nei limiti specificati nel mapping del databricks_cli_version bundle, si verifica un errore quando databricks bundle validate viene eseguito nel bundle. Gli esempi seguenti illustrano una sintassi comune dei vincoli di versione:

bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.0' # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.*' # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: '>= 0.218.0' # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: '>= 0.218.0, <= 1.0.0' # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

run_as

L'impostazione run_as specifica il componente user_name o service_principal_name da usare per eseguire il bundle. Consente di separare l'identità usata per distribuire un job bundle o una pipeline da quella usata per eseguire il job o la pipeline.

Consultare Specificare un'identità di esecuzione per un flusso di lavoro dei pacchetti di asset di Databricks.

includere

La matrice include specifica un elenco di GLOB di percorso che contengono file di configurazione da includere all'interno del bundle. Questi glob di percorso sono relativi al percorso del file di configurazione del bundle in cui vengono specificati i glob del percorso.

L'interfaccia della riga di comando di Databricks non include alcun file di configurazione per impostazione predefinita all'interno del bundle. È necessario usare la matrice include per specificare tutti i file di configurazione da includere all'interno del bundle, ad eccezione del file databricks.yml stesso.

Questa matrice include può essere visualizzata solo come mapping di primo livello.

La configurazione di esempio seguente include tre file di configurazione. Questi file si trovano nella stessa cartella del file di configurazione del bundle:

include:
  - 'bundle.artifacts.yml'
  - 'bundle.resources.yml'
  - 'bundle.targets.yml'

La configurazione di esempio seguente include tutti i file con nomi file che iniziano con bundle e terminano con .yml. Questi file si trovano nella stessa cartella del file di configurazione del bundle:

include:
  - 'bundle*.yml'

Scripti

L'impostazione scripts specifica gli script che possono essere eseguiti tramite bundle run. Ogni script denominato nel scripts mapping contiene contenuto con i comandi. Per esempio:

scripts:
  my_script:
    content: uv run pytest -m ${bundle.target}

Per altre informazioni, vedere Eseguire script.

sincronizza

Il mapping sync consente di configurare i file che fanno parte delle distribuzioni di bundle.

include ed escludere

I mapping include e exclude all'interno del mapping sync specificano un elenco di file o cartelle da includere o escludere dalle distribuzioni di bundle, a seconda delle regole seguenti:

  • Basato su qualsiasi elenco di file e glob di percorso in un .gitignore file posizionato nella radice del bundle, il include mapping può contenere un elenco di glob di file, glob di percorso, o entrambi, relativo alla radice del bundle, per includere in modo esplicito.
  • Basato su qualsiasi elenco di modelli di file e modelli di percorso in un .gitignore file nella radice del bundle, oltre all'elenco di modelli di file e modelli di percorso nel include mapping, il exclude mapping può contenere un elenco di modelli di file, modelli di percorso o entrambi, rispetto alla radice del bundle, per escludere in modo esplicito.

Tutti i percorsi dei file e delle cartelle specificati sono relativi al percorso del file di configurazione del bundle in cui sono specificati.

La sintassi per i modelli di file include e exclude di percorso segue la sintassi standard del modello .gitignore. Vedere Gitignore Pattern Format( Formato modello gitignore).

Ad esempio, se il seguente file .gitignore contiene le voci seguenti:

.databricks
my_package/dist

Il file di configurazione del bundle contiene la seguente mappatura include:

sync:
  include:
    - my_package/dist/*.whl

Vengono quindi inclusi tutti i file nella cartella my_package/dist con estensione di file di *.whl. Tutti gli altri file nella cartella my_package/dist non sono inclusi.

Tuttavia, se il file di configurazione del bundle contiene anche la seguente mappatura exclude:

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

Vengono quindi inclusi tutti i file nella cartella my_package/dist con estensione di file di *.whl, ad eccezione del file denominato delete-me.whl. Anche tutti gli altri file nella cartella my_package/dist non sono inclusi.

Il mapping sync può anche essere dichiarato nel mapping targets per una destinazione specifica. Qualsiasi mapping sync dichiarato in una destinazione viene unito a qualsiasi dichiarazione di mapping di primo livello sync. Ad esempio, continuando con l'esempio precedente, il seguente mapping include al livello targets viene unito al mapping include nel mapping di primo livello sync:

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

Percorsi

Il mapping sync può contenere un mapping paths che specifica i percorsi locali da sincronizzare con l'area di lavoro. Il mapping paths consente di condividere file comuni tra bundle e può essere usato per sincronizzare i file che si trovano all'esterno della radice del bundle. (La radice del bundle è il percorso del file databricks.yml.) Ciò è particolarmente utile quando si dispone di un singolo repository che ospita più bundle e si vuole condividere librerie, file di codice o configurazione.

I percorsi specificati devono essere relativi a file e directory ancorati nella cartella in cui è impostato il mapping paths. Se uno o più valori di percorso salgono nella directory fino a un antenato della radice del pacchetto, il percorso radice viene determinato in modo dinamico per garantire che la struttura delle cartelle rimanga intatta. Ad esempio, se la cartella radice del bundle è denominata my_bundle, questa configurazione in databricks.yml sincronizza la cartella common che si trova a un livello sopra la radice del bundle e la radice del bundle stessa:

sync:
  paths:
    - ../common
    - .

Una distribuzione di questo bundle comporta la struttura di cartelle seguente nell'area di lavoro:

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

artefatti

Il mapping di primo livello artifacts specifica uno o più artefatti creati automaticamente durante le distribuzioni di *bundle* e che possono essere usati in un secondo momento nelle esecuzioni del *bundle*. Ogni artefatto figlio supporta i mapping seguenti:

  • type è necessario per le compilazioni con rotellina Python. Per compilare un file wheel Python prima della distribuzione, impostare questo su whl. Per costruire altri artefatti, questa impostazione non deve essere specificata.
  • path è un percorso facoltativo. I percorsi sono relativi al percorso del file di configurazione del bundle. Per le compilazioni con rotellina Python, si tratta del percorso del file della setup.py rotellina Python. Se path non è incluso, il client CLI di Databricks tenta di trovare il file wheel Python setup.py nella radice del bundle.
  • files è un mapping facoltativo che include un mapping figlio source, il quale è possibile utilizzare per specificare gli artefatti costruiti. I percorsi sono relativi al percorso del file di configurazione del bundle.
  • build è un set facoltativo di comandi di compilazione non predefiniti da eseguire in locale prima della distribuzione. Per le compilazioni con il wheel Python, l'interfaccia della riga di comando di Databricks presuppone che sia possibile trovare un'installazione locale del pacchetto Python wheel per eseguire le compilazioni ed esegue il comando python setup.py bdist_wheel per impostazione predefinita durante ogni distribuzione del bundle. Specificare più comandi di compilazione in righe separate.
  • dynamic_version consente ai bundle di aggiornare la versione del wheel in base al timestamp del file wheel. ** Il nuovo codice può quindi essere distribuito senza dover aggiornare la versione in setup.py o pyproject.toml. Questa impostazione è valida solo se type è impostata su whl.

L'esempio di configurazione seguente esegue test e compila una rotellina. Per un'esercitazione completa sull'aggregazione usata artifacts per creare una rotellina, vedere Creare un file con rotellina Python usando i bundle di asset di Databricks.

artifacts:
  default:
    type: whl
    build: |-
      # run tests
      python -m pytest tests/ -v

      # build the actual artifact
      python setup.py bdist_wheel

    path: .

Per un esempio di configurazione che compila un file JAR e lo carica in Unity Catalog, vedere Bundle che carica un file JAR in Unity Catalog.

Suggerimento

È possibile definire, combinare ed eseguire l'override delle impostazioni per gli artefatti nei bundle, come descritto in Eseguire l'override con le impostazioni di destinazione.

variabili

Il file di impostazioni bundle può contenere un mapping di primo livello variables in cui sono definite variabili personalizzate. Per ogni variabile, impostare una descrizione facoltativa, un valore predefinito, se la variabile personalizzata è un tipo complesso o una ricerca per recuperare un valore ID, usando il formato seguente:

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

Nota

Si presuppone che le variabili siano di tipo string, a meno che non type sia impostato su complex. Vedere Definire una variabile complessa.

Per fare riferimento a una variabile personalizzata all'interno della configurazione del bundle, usare la sostituzione ${var.<variable_name>}.

Per altre informazioni sulle variabili e le sostituzioni personalizzate, vedere Sostituzioni e variabili nei bundle di asset di Databricks.

area di lavoro

Il file di configurazione del bundle può contenere un solo mapping di primo livello workspace per specificare le impostazioni dell'area di lavoro di Azure Databricks non predefinite da usare.

Importante

I percorsi validi dell'area di lavoro di Databricks iniziano con /Workspace, mentre per gli artefatti è supportato anche /Volumes. I percorsi dell'area di lavoro personalizzati sono preceduti automaticamente da /Workspace, quindi se si usa una sostituzione del percorso dell'area di lavoro nel percorso personalizzato, ${workspace.file_path}ad esempio , non è necessario anteporre /Workspace al percorso.

root_path

Questo mapping workspace può contenere un mapping root_path per specificare un percorso radice non predefinito da usare all'interno dell'area di lavoro sia per le distribuzioni che per le esecuzioni del flusso di lavoro, ad esempio:

workspace:
  root_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

Per impostazione predefinita, per root_path la CLI di Databricks usa il percorso predefinito di /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, che utilizza sostituzioni.

percorso_artifatto

Questo mapping workspace può contenere anche un mapping artifact_path per specificare un percorso di artefatto non predefinito da usare all'interno dell'area di lavoro per le distribuzioni e le esecuzioni del flusso di lavoro, ad esempio:

workspace:
  artifact_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

Per impostazione predefinita, per artifact_path la CLI di Databricks usa il percorso predefinito di ${workspace.root}/artifacts, che utilizza sostituzioni.

Nota

Il mapping artifact_path non supporta i percorsi di Databricks File System (DBFS).

percorso del file

Questo mapping workspace può contenere anche un mapping file_path per specificare un percorso di file non predefinito da usare all'interno dell'area di lavoro per le distribuzioni e le esecuzioni del flusso di lavoro, ad esempio:

workspace:
  file_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files

Per impostazione predefinita, per file_path la CLI di Databricks usa il percorso predefinito di ${workspace.root}/files, che utilizza sostituzioni.

stato_percorso

Il mapping state_path predefinito punta al percorso base ${workspace.root}/state e rappresenta il percorso all'interno dell'area di lavoro per archiviare le informazioni sullo stato di Terraform relative alle distribuzioni.

Altri mapping dell'area di lavoro

Il mapping workspace può contenere anche i mapping facoltativi seguenti per specificare il meccanismo di autenticazione di Azure Databricks da usare. Se non vengono specificati all'interno di questo workspace mapping, devono essere specificati in un workspace mapping come figlio di una o più destinazioni nel mapping delle destinazioni di primo livello.

Importante

È necessario codificare a mano i valori per i seguenti mapping workspace per l'autenticazione di Azure Databricks. Ad esempio, non è possibile specificare variabili personalizzate per questi valori di mapping usando la ${var.*} sintassi .

  • Il mapping profile (o le opzioni --profile o -p quando si eseguono i comandi del bundle convalida, distribuisci, esegui ed elimina con l'interfaccia della riga di comando di Databricks) specifica il nome di un profilo di configurazione da usare con questa area di lavoro per l'autenticazione di Azure Databricks. Questo profilo di configurazione viene mappato a quello creato durante la configurazione dell'interfaccia della riga di comando di Databricks.

    Nota

    Databricks consiglia di usare il mapping host (o le --profile opzioni o -p quando si eseguono i comandi del bundle convalida, distribuisci, esegui ed elimina con l'interfaccia della riga di comando di Databricks) anziché il mapping profile, in quanto rende i file di configurazione del bundle più portatili. L'impostazione del host mapping indica all'interfaccia della riga di comando di Databricks di trovare un profilo corrispondente nel .databrickscfg file e quindi usare i campi del profilo per determinare il tipo di autenticazione di Databricks da usare. Se all'interno del file host esistono più profili con un campo corrispondente .databrickscfg, è necessario usare il mapping profile (o le opzioni della riga di comando --profile o -p ) per indicare all'interfaccia della riga di comando di Databricks il profilo da usare. Per un esempio, vedere la dichiarazione di prod destinazione negli esempi.

  • Il mapping host specifica l'URL per l'area di lavoro di Azure Databricks. Vedere URL per area di lavoro.

  • Per l'autenticazione da computer a computer (M2M) OAuth, viene usato il mapping client_id. In alternativa, è possibile impostare questo valore nella variabile di ambiente locale DATABRICKS_CLIENT_ID. In alternativa, è possibile creare un profilo di configurazione con il valore client_id e quindi specificare il nome del profilo con il mapping profile oppure usando le opzioni --profile o -p quando si eseguono i comandi di convalida, distribuzione, esecuzione e eliminazione del bundle con la CLI di Databricks. Vedere Autorizzare l'accesso dell'entità servizio ad Azure Databricks con OAuth.

    Nota

    Non è possibile specificare un valore del segreto OAuth di Azure Databricks nel file di configurazione del bundle. Invece, impostare la variabile di ambiente DATABRICKS_CLIENT_SECRET. In alternativa, è possibile aggiungere il valore client_secret a un profilo di configurazione e quindi specificare il nome del profilo con il mapping profile, oppure utilizzando le opzioni --profile o -p quando si eseguono i comandi di convalida, distribuzione, esecuzione ed eliminazione del bundle con il CLI di Databricks.

  • Per l'autenticazione con l’interfaccia della riga di comando di Azure, viene usato il mapping azure_workspace_resource_id. In alternativa, è possibile impostare questo valore nella variabile di ambiente locale DATABRICKS_AZURE_RESOURCE_ID. In alternativa, è possibile creare un profilo di configurazione con il valore azure_workspace_resource_id e quindi specificare il nome del profilo con il mapping profile oppure usando le opzioni --profile o -p quando si eseguono i comandi di convalida, distribuzione, esecuzione e eliminazione del bundle con la CLI di Databricks. Vedere Eseguire l'autenticazione con l'interfaccia della riga di comando di Azure.

  • Per l'autenticazione dei segreti client di Azure con le entità servizio, vengono usati i mapping azure_workspace_resource_id, azure_tenant_id e azure_client_id. In alternativa, è possibile impostare questi valori rispettivamente nelle variabili di ambiente locali DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_ID e ARM_CLIENT_ID. In alternativa, è possibile creare un profilo di configurazione con i valori azure_workspace_resource_id, azure_tenant_id e azure_client_id, e quindi specificare il nome del profilo con il mapping profile oppure utilizzando le opzioni --profile o -p quando si eseguono i comandi di convalida, distribuzione, esecuzione ed eliminazione del bundle con l'interfaccia della riga di comando di Databricks. Consultare Effettuare l'autenticazione con i principali di servizio Microsoft Entra.

    Nota

    Non è possibile specificare un valore del segreto client di Azure nel file di configurazione del bundle. Invece, impostare la variabile di ambiente ARM_CLIENT_SECRET. In alternativa, è possibile aggiungere il valore azure_client_secret a un profilo di configurazione e quindi specificare il nome del profilo con il mapping profile, oppure utilizzando le opzioni --profile o -p quando si eseguono i comandi di convalida, distribuzione, esecuzione ed eliminazione del bundle con il CLI di Databricks.

  • Per l'autenticazione delle identità gestite di Azure, vengono usati i mapping azure_use_msi, azure_client_id e azure_workspace_resource_id . In alternativa, è possibile impostare questi valori rispettivamente nelle variabili di ambiente locali ARM_USE_MSI, ARM_CLIENT_ID e DATABRICKS_AZURE_RESOURCE_ID. In alternativa, è possibile creare un profilo di configurazione con i valori azure_use_msi, azure_client_id e azure_workspace_resource_id, e quindi specificare il nome del profilo con il mapping profile oppure utilizzando le opzioni --profile o -p quando si eseguono i comandi di convalida, distribuzione, esecuzione ed eliminazione del bundle con l'interfaccia della riga di comando di Databricks. Vedere Eseguire l'autenticazione con le identità gestite di Azure.

  • Il mapping azure_environment specifica il tipo di ambiente di Azure (ad esempio Public, UsGov, Cina e Germania) per un set specifico di endpoint API. Il valore predefinito è PUBLIC. In alternativa, è possibile impostare questo valore nella variabile di ambiente locale ARM_ENVIRONMENT. In alternativa, è possibile aggiungere il valore azure_environment a un profilo di configurazione e quindi specificare il nome del profilo con il mapping profile, oppure utilizzando le opzioni --profile o -p quando si eseguono i comandi di convalida, distribuzione, esecuzione ed eliminazione del bundle con il CLI di Databricks.

  • Il mapping azure_login_app_id non è operativo ed è riservato per l'uso interno.

  • Il mapping auth_type specifica il tipo di autenticazione di Azure Databricks da usare, in particolare nei casi in cui l'interfaccia della riga di comando di Databricks deduce un tipo di autenticazione imprevisto. Vedere Autorizzare l'accesso alle risorse di Azure Databricks.

autorizzazioni

Il mapping di primo livello permissions specifica uno o più livelli di autorizzazione da applicare a tutte le risorse definite nel bundle. Per applicare autorizzazioni a una risorsa specifica, vedere Definire le autorizzazioni per una risorsa specifica.

I livelli di autorizzazione di primo livello consentiti sono CAN_VIEW, CAN_MANAGE e CAN_RUN.

L'esempio seguente in un file di configurazione del bundle definisce i livelli di autorizzazione per un utente, un gruppo e un'entità servizio, che vengono applicati a tutte le risorse definite nel resources bundle:

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

risorse

Il mapping resources specifica informazioni sulle risorse di Azure Databricks usate dal bundle.

Questo mapping resources può essere visualizzato come mapping di primo livello oppure può essere figlio di una o più destinazioni nel mapping di livello superiore e include zero o uno dei tipi di risorse supportati . Ogni mapping dei tipi di risorsa include una o più dichiarazioni di risorse singole, che devono avere un nome univoco. Queste singole dichiarazioni di risorse usano il payload di richiesta dell'operazione di creazione dell'oggetto corrispondente, espresso in YAML, per definire la risorsa. Le proprietà supportate per una risorsa sono i campi supportati dell'oggetto corrispondente.

I payload della richiesta di operazione di creazione sono documentati in Informazioni di riferimento sull'API REST di Databricks e il databricks bundle schema comando restituisce tutti gli schemi di oggetti supportati. Inoltre, il comando databricks bundle validate restituisce avvisi se le proprietà sconosciute delle risorse vengono trovate nei file di configurazione del bundle.

La seguente configurazione di esempio definisce una risorsa attività:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

Per ulteriori informazioni sulle risorse supportate nei bundle, così come configurazioni ed esempi comuni, vedere risorse dei bundle di asset di Databricks e esempi di configurazione del bundle.

obiettivi

Il mapping targets specifica uno o più contesti in cui eseguire i flussi di lavoro di Azure Databricks. Ogni destinazione è una raccolta univoca di artefatti, impostazioni dell'area di lavoro di Azure Databricks e dettagli del processo o della pipeline di Azure Databricks.

Il mapping targets è costituito da uno o più mapping di destinazione, che devono avere un nome univoco a livello di codice (o logico).

Questo mapping targets è facoltativo ma altamente consigliato. Se viene specificato, può essere visualizzato solo come mapping di primo livello.

Le impostazioni nell'area di lavoro di primo livello, gli artefatti e i mapping delle risorse vengono usate se non sono specificate in un targets mapping, ma tutte le impostazioni in conflitto vengono sostituite dalle impostazioni all'interno di una destinazione.

Una destinazione può anche eseguire l'override dei valori di qualsiasi variabile di primo livello.

impostazione predefinita

Per specificare un valore predefinito di destinazione per i comandi bundle, impostare il mapping default su true. Ad esempio, questa destinazione denominata dev è la destinazione predefinita:

targets:
  dev:
    default: true

Se una destinazione predefinita non è configurata o se si desidera convalidare, distribuire ed eseguire processi o pipeline all'interno di una destinazione specifica, usare l'opzione -t dei comandi bundle.

I comandi seguenti convalidano, distribuiscono ed eseguono my_job nei target dev e prod:

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

Nell'esempio seguente vengono dichiarate due destinazioni. La prima destinazione ha il nome dev ed è la destinazione predefinita usata quando non viene specificata alcuna destinazione per i comandi bundle. La seconda destinazione ha il nome prod e viene usata solo quando questa destinazione viene specificata per i comandi bundle.

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

modalità e set di impostazioni

Per semplificare lo sviluppo e le procedure consigliate per CI/CD, i bundle di asset di Databricks offrono modalità di distribuzione per le destinazioni che impostano comportamenti predefiniti per i flussi di lavoro di pre-produzione e produzione. Alcuni comportamenti sono configurabili anche. Per informazioni dettagliate, vedere Modalità di distribuzione del bundle di asset di Databricks.

Suggerimento

Per impostare le identità di esecuzione per i bundle, è possibile specificare run_as per ogni destinazione, come descritto in Specificare un'identità di esecuzione per un flusso di lavoro dei bundle di asset di Databricks.

Per specificare che una destinazione viene considerata come destinazione di sviluppo, aggiungere il mapping mode impostato su development. Per specificare che una destinazione viene considerata come destinazione di produzione, aggiungere il mapping mode impostato su production. Ad esempio, questa destinazione denominata prod viene considerata come destinazione di produzione:

targets:
  prod:
    mode: production

È possibile personalizzare alcuni dei comportamenti usando il mapping presets. Per un elenco dei set di impostazioni disponibili, vedere Impostazioni predefinite personalizzate. L'esempio seguente mostra una destinazione di produzione personalizzata che prefissa e contrassegna tutte le risorse di produzione:

targets:
  prod:
    mode: production
    presets:
      name_prefix: 'production_' # prefix all resource names with production_
      tags:
        prod: true

Se mode e presets sono impostati, i set di impostazioni sostituiscono il comportamento della modalità predefinita. Le impostazioni delle singole risorse sostituiscono i set di impostazioni. Ad esempio, se una pianificazione è impostata su UNPAUSED, ma il set di impostazioni trigger_pause_status è impostato su PAUSED, la pianificazione verrà annullata.

  • Last updated on