Condividi tramite

Configurazione del bundle di asset di Databricks

  • Articolo

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

Per creare e usare pacchetti, vedere sviluppo di pacchetti di asset Databricks.

Panoramica

Un file di configurazione del bundle deve essere espresso in formato YAML e deve contenere almeno il mapping di primo livello del bundle. Ogni bundle deve contenere almeno un file di configurazione bundle (e uno soltanto) denominato databricks.yml. Se sono presenti più file di configurazione bundle, è necessario fare riferimento al file databricks.yml usando il mapping include.

Per informazioni dettagliate su ogni mappatura di primo livello, vedere le mappature .

Per altre informazioni su YAML, vedere la specifica e l'esercitazione ufficiali di YAML.

Specificazione

Il seguente YAML fornisce la specifica di configurazione per gli Asset Bundle di Databricks.

# 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
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex

# These are the default workspace settings if not otherwise overridden in
# the following "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. Non-operational and 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
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines 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 default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

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

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

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  clusters:
    <some-unique-programmatic-identifier-for-this-cluster>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <some-unique-programmatic-identifier-for-this-dashboard>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See REST API create request payload reference for jobs.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the REST API create request payload reference for models.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the REST API create request payload reference for Delta Live Tables (pipelines).
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema request payload reference.

# 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 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.
    cluster_id: string
    default: true | false
    mode: development
    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:

Nota

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

La configurazione del bundle di esempio seguente specifica un file locale denominato hello.py nella stessa directory del file di configurazione del bundle locale denominato databricks.yml. Esegue questo notebook come processo usando il cluster remoto con l'ID cluster specificato. 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.

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 mapping host indica all'interfaccia della riga di comando di Databricks di trovare un profilo corrispondente nel file .databrickscfg 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 profile per indicare all'interfaccia della riga di comando di Databricks quale profilo specifico usare. Per un esempio, consultare dichiarazione di destinazione prod più avanti in questa sezione.

Questa tecnica consente di riutilizzare e di eseguire l'override delle definizioni e delle impostazioni del processo all'interno del blocco resources:

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

Anche se il file di configurazione del bundle seguente è funzionalmente equivalente, non è modularizzato, cosa che non permette di riutilizzarlo. Inoltre, questa dichiarazione aggiunge un'attività al processo anziché l'override del processo esistente:

bundle:
  name: hello-bundle

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

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 .databrickscfg del file host del 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. 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

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

# 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

Di seguito è riportato l'esempio precedente, ma suddiviso in file di componenti per una maggiore modularizzazione e un riutilizzo migliore tra più file di configurazione bundle. Questa tecnica consente di non solo riutilizzare varie definizioni e impostazioni, ma è anche possibile scambiare uno di questi file con altri file che forniscono dichiarazioni completamente diverse:

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.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

bundle.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 la sintassi del file di configurazione del bundle in base al mapping di primo livello.

bundle

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 mapping bundle può anche essere figlio di una o più destinazioni nel mapping di destinazioni generale. Ognuno di questi mapping figlio bundle specifica tutte le sostituzioni non predefinite a livello di destinazione. Tuttavia, il valore bundle del mapping di primo livello name non può essere sottoposto a override 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 del cluster.

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 sul mapping target, vedere Destinazioni.

compute_id

Nota

Questa impostazione è deprecata. Usare cluster_id al suo posto.

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. Ciò è utile per annotare le risorse distribuite. Ad esempio, è possibile includere l'URL di origine del repository nella descrizione di un modello di Machine Learning distribuito.

Ogni volta che si esegue un comando bundle come validate, deploy o run, il comando bundle 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}.
  • bundle.git.commit, che rappresenta il commit HEAD all'interno del repository. Si tratta dello stesso valore che si otterrebbe se è stato eseguito il comando git rev-parse HEAD dal repository clonato. È possibile usare le sostituzioni per fare riferimento a questo valore con i file di configurazione del bundle, come ${bundle.git.commit}.

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 versionamento semantico e il mapping databricks_cli_version supporta la specifica dei vincoli di versione. Se il valore corrente databricks --version non rientra nei limiti specificati nel mapping databricks_cli_version del 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

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 o /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 l'interfaccia della riga di comando di Databricks usa il percorso predefinito di /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, che usa le sostituzioni.

artifact_path

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 l'interfaccia della riga di comando di Databricks usa il percorso predefinito di ${workspace.root}/artifacts, che usa le sostituzioni.

Nota

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

file_path

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 l'interfaccia della riga di comando di Databricks usa il percorso predefinito di ${workspace.root}/files, che usa le sostituzioni.

state_path

Il mapping state_path viene impostato per impostazione predefinita sul percorso predefinito di ${workspace.root}/state e rappresenta il percorso all'interno dell'area di lavoro per archiviare le informazioni sullo stato di Terraform sulle 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 mapping workspace, devono essere specificati in un mapping workspace come figlio di una o più destinazioni nel mapping delle destinazioni di primo livello.

Importante

È necessario impostare valori hardcoded 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 mapping host indica all'interfaccia della riga di comando di Databricks di trovare un profilo corrispondente nel file .databrickscfg 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 destinazione prod negli esempi.

  • Il mapping host specifica l'URL per l'area di lavoro di Azure Databricks. Vedere URL nuovi 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 ed eliminazione del bundle con l'interfaccia della riga di comando di Databricks. Consultare Autenticare l'accesso ad Azure Databricks con un'entità servizio usando OAuth (OAuth M2M).

    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 usando 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.

  • 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 ed eliminazione del bundle con l'interfaccia della riga di comando di Databricks. Vedere Autenticazione con 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 usando 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 Autenticazione dell’entità servizio di 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 usando 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.

  • 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 usando 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 Panoramica dell'autenticazione delle 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 usando 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.

  • 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. Consultare Autenticare 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 bundle definisce i livelli di autorizzazione per un utente, un gruppo e un'entità servizio, che vengono applicati a tutti i processi, pipeline, esperimenti e modelli definiti nel bundle resources:

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

artifacts

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

  • type è obbligatorio. Per compilare un file wheel Python prima della distribuzione, questo mapping deve essere impostato su whl.
  • path è un percorso relativo facoltativo dal percorso del file di configurazione del bundle al percorso del file wheel Python setup.py. Se path non è incluso, l'interfaccia della riga di comando di Databricks tenterà di trovare il file setup.py del file wheel python nella radice del bundle.
  • files è un mapping facoltativo che include un mapping figlio source , che è possibile usare per specificare percorsi non predefiniti da includere per istruzioni di compilazione complesse. I percorsi vengono specificati come percorsi relativi dal 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. Per specificare più comandi di compilazione, separare ogni comando con caratteri doppia e commerciale (&&).

La configurazione di esempio seguente crea una ruota usando Poetry:

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

Per un pacchetto di esempio completo che usa artifacts, vedere Sviluppare un file wheel Python usando i pacchetti di asset Databricks.

Suggerimento

È possibile definire, combinare ed eseguire l'override delle impostazioni per gli artefatti nei bundle, come descritto in Definire le impostazioni degli artefatti nei Bundle 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"

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 comando databricks bundle schema 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 altre informazioni sulle risorse supportate nei bundle, oltre a configurazioni ed esempi comuni, vedere risorse di Aggregazioni di asset di Databricks e esempi di configurazione del bundle .

sync

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

exclude e include

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

  • In base a qualsiasi elenco di file e glob di percorso in un file .gitignore nella radice del bundle, il mapping include può contenere un elenco di GLOB di file, GLOB di percorso o entrambi, relativamente alla radice del bundle, per includere in modo esplicito.
  • In base a qualsiasi elenco di file e glob di percorso in un .gitignore file nella radice del bundle, oltre all'elenco di file e percorsi glob nel include mapping, il exclude mapping può contenere un elenco di glob di file, glob 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 Formato di modello gitignore.

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

.databricks
my_package/dist

Il file di configurazione del bundle contiene il mapping seguente 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 il seguente mapping 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 attraversano la directory a un predecessore della radice del bundle, il percorso radice viene determinato in modo dinamico per garantire che la struttura di 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/
    ...

destinazioni

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 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 mapping targets, 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 all'interno delle dev destinazioni 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.