Configurações do Pacote de Ativos do Databricks

Este artigo descreve a sintaxe dos arquivos de configuração do Pacote de Ativos do Databricks, que definem os Pacotes de Ativos do Databricks. Confira O que são Pacotes de Ativos do Databricks?

Para criar e trabalhar com pacotes, confira Desenvolvimento de Pacotes de Ativos do Databricks.

Visão geral

Um arquivo de configuração de pacote deve ser expresso no formato YAML e deve conter, no mínimo, o mapeamento do pacote de nível superior. Cada pacote deve conter no mínimo um (e somente um) arquivo de configuração de pacote denominado databricks.yml. Se existirem vários arquivos de configuração de pacote, eles deverão ser referenciados pelo arquivo databricks.yml usando o mapeamento include.

Para obter detalhes sobre cada mapeamento de nível superior, consulte Mapeamentos.

Para obter mais informações sobre o YAML, confira a especificação e o tutorial oficiais do YAML.

Especificação

A especificação YAML a seguir fornece chaves de configuração de nível superior para Pacotes de Ativos do Databricks. Para obter referência de configuração, consulte a referência de configuração .

# 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.
  volumes:
    <some-unique-programmatic-identifier-for-this-volume>:
    # See the Unity Catalog volume 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.

Exemplos

Observação

Para obter exemplos de configuração que demonstram recursos de pacote e casos comuns de uso de pacote, consulte Exemplos de configuração de pacote e o repositório de exemplos de pacote no GitHub.

A configuração do pacote de exemplo a seguir especifica um arquivo local denominado hello.py que está no mesmo diretório que esse arquivo de configuração de pacote local denominado databricks.yml. Ele executa esse notebook como um trabalho usando o cluster remoto com a ID de cluster especificada. A URL do workspace remoto e as credenciais de autenticação do workspace são lidas do perfil de configuração local do chamador nomeado DEFAULT.

O Databricks recomenda que você use o mapeamento host em vez do mapeamento default sempre que possível, pois isso torna os arquivos de configuração do pacote mais portáteis. Definir o mapeamento host instrui a CLI do Databricks a encontrar um perfil correspondente no arquivo .databrickscfg e a usar os campos desse perfil para determinar o tipo de autenticação do Databricks a ser usado. Se houver vários perfis com um campo host correspondente no arquivo .databrickscfg, você precisará usar o profile para instruir a CLI do Databricks sobre o perfil específico a ser usado. Para ver um exemplo, confira a declaração de destino prod mais adiante nesta seção.

Essa técnica permite que você reutilize, bem como substitua, as configurações e as definições de trabalho dentro do bloco 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

Embora o arquivo de configuração do pacote a seguir seja funcionalmente equivalente, ele não é modularizado, o que não permite uma boa reutilização. Além disso, essa declaração acrescenta uma tarefa ao trabalho, em vez de substituir o trabalho existente:

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

O exemplo a seguir adiciona um destino com o nome prod que usa uma URL de workspace remoto diferente e credenciais de autenticação de workspace, que são lidas do arquivo de .databrickscfg do chamador correspondendo à entrada host com a URL do workspace especificada. Esse trabalho executa o mesmo notebook, mas usa outro cluster remoto com a ID de cluster especificada. Observe que você não precisa declarar o mapeamento notebook_task dentro do mapeamento prod, pois ele volta a usar o mapeamento notebook_task no mapeamento resources de nível superior, caso o mapeamento notebook_task não seja substituído explicitamente no mapeamento 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

Para validar, implantar e executar esse trabalho no destino 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

Para validar, implantar e executar esse trabalho no destino prod em vez disso:

# 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

A seguir, o exemplo previamente apresentado, mas dividido em arquivos de componentes para obter ainda mais modularização e melhor reutilização em vários arquivos de configuração do pacote. Essa técnica permite que você não apenas reutilize várias definições e configurações, mas também troque um desses arquivos por outros arquivos que forneçam declarações completamente diferentes:

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

Mapeamentos

As seções a seguir descrevem a sintaxe do arquivo de configuração do pacote, por mapeamento de nível superior.

• bundle
• variables
• workspace
• permissions
• artifacts
• include
• resources
• sync
• targets

bundle

Um arquivo de configuração de pacote deve conter apenas um mapeamento bundle de nível superior que associe o conteúdo do pacote e as configurações do workspace do Azure Databricks.

Este mapeamento bundle precisa conter um mapeamento name que especifique um nome programático (ou lógico) para o pacote. O exemplo a seguir declara um pacote com o nome programático (ou lógico) hello-bundle.

bundle:
  name: hello-bundle

Um mapeamento bundle também pode ser filho de um ou mais dos destinos no mapeamento targets de nível superior. Cada um desses mapeamentos bundle filho especifica qualquer substituição não padrão no nível de destino. No entanto, o valor name do mapeamento bundle de nível superior não pode ser substituído no nível de destino.

cluster_id

O mapeamento bundle pode ter um mapeamento filho cluster_id. Esse mapeamento permite que você especifique a ID de um cluster a ser utilizada como uma substituição para clusters definidos em outro lugar no arquivo de configuração do pacote. Para obter informações sobre como recuperar a ID de um cluster, consulte URL e ID do cluster.

A substituição cluster_id destina-se a cenários somente de desenvolvimento e só tem suporte para o destino que tiver o mapeamento mode definido como development. Para obter mais informações sobre o mapeamento target, confira destino.

compute_id

Observação

Essa configuração está preterida. Em vez disso, use cluster_id.

O mapeamento bundle pode ter um mapeamento filho compute_id. Esse mapeamento permite que você especifique a ID de um cluster a ser utilizada como uma substituição para clusters definidos em outro lugar no arquivo de configuração do pacote.

git

Você pode recuperar e substituir os detalhes do controle de versão do Git associados ao pacote. Isso é útil para anotar os recursos implantados. Por exemplo, o ideal é incluir a URL de origem do repositório na descrição de um modelo de machine learning implantado.

Sempre que você executar um comando bundle como validate, deploy ou run, o comando bundle preencherá a árvore de configuração do comando com as seguintes configurações padrão:

• bundle.git.origin_url, que representa a URL de origem do repositório. Esse é o mesmo valor que você obterá se executar o comando git config --get remote.origin.url por meio do repositório clonado. Você pode utilizar substituições para se referir a esse valor nos arquivos de configuração do seu pacote, como ${bundle.git.origin_url}.
• bundle.git.branch, que representa o branch atual contido no repositório. Esse é o mesmo valor que você obterá se executar o comando git branch --show-current por meio do repositório clonado. Você pode utilizar substituições para se referir a esse valor nos arquivos de configuração do seu pacote, como ${bundle.git.branch}.

Para recuperar ou substituir as configurações do Git, seu pacote precisa estar dentro de um diretório associado a um repositório Git, por exemplo, um diretório local que é inicializado pela execução do comando git clone. Se o diretório não estiver associado a um repositório Git, essas configurações do Git estarão vazias.

Você pode substituir as configurações origin_url e branch contidas no mapeamento git do mapeamento bundle de nível superior, se necessário, da seguinte maneira:

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

databricks_cli_version

O mapeamento bundle pode conter um mapeamento databricks_cli_version que restringe a versão da CLI do Databricks exigida pelo pacote. Isso pode evitar problemas causados pelo uso de mapeamentos que não têm suporte em uma determinada versão da CLI do Databricks.

A versão da CLI do Databricks está em conformidade com o controle de versão semântico e o mapeamento databricks_cli_version dá suporte à especificação de restrições de versão. Se o valor databricks --version atual não estiver dentro dos limites especificados no mapeamento do pacote databricks_cli_version, ocorrerá um erro quando databricks bundle validate for executado no pacote. Os exemplos a seguir demonstram alguma sintaxe de restrição de versão comum:

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

variables

O arquivo de configurações de pacotes configuráveis pode conter um mapeamento de nível superior variables em que as variáveis personalizadas são definidas. Para cada variável, defina uma descrição opcional, um valor padrão, se a variável personalizada é um tipo complexo ou uma pesquisa para recuperar um valor de ID usando o seguinte formato:

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>

Observação

Presume-se que as variáveis sejam do tipo string, a menos que type esteja definida como complex. Consulte Definir uma variável complexa.

Para referenciar uma variável personalizada na configuração do pacote, use a substituição ${var.<variable_name>}.

Para obter mais informações sobre variáveis personalizadas e substituições, consulte Substituições e variáveis em pacotes de ativos do Databricks.

workspace

O arquivo de configuração do pacote pode conter apenas um mapeamento workspace de nível superior para especificar quaisquer configurações não padrão do workspace do Azure Databricks a serem usadas.

Importante

Os caminhos válidos do workspace do Databricks começam com /Workspace ou /Volumes. Os caminhos de workspace personalizados são prefixados automaticamente com /Workspace, portanto, se você usar qualquer substituição de caminho de workspace em seu caminho personalizado, como ${workspace.file_path}, não será necessário anexar /Workspace ao caminho.

root_path

Esse mapeamento workspace pode conter um mapeamento root_path para especificar um caminho raiz não padrão a ser usado no workspace para implantações e execuções de fluxo de trabalho, por exemplo:

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

Por padrão, para root_path, a CLI do Databricks usa o caminho padrão /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, que usa substituições.

artifact_path

Esse mapeamento workspace também pode conter um mapeamento artifact_path para especificar um caminho de artefato não padrão a ser usado no workspace para implantações e execuções de fluxo de trabalho, por exemplo:

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

Por padrão, para artifact_path, a CLI do Databricks usa o caminho padrão ${workspace.root}/artifacts, que usa substituições.

Observação

O mapeamento de artifact_path não dá suporte a caminhos do Sistema de Arquivos do Databricks (DBFS).

file_path

Esse mapeamento workspace também pode conter um mapeamento file_path para especificar um caminho de arquivo não padrão a ser usado no workspace para implantações e execuções de fluxo de trabalho, por exemplo:

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

Por padrão, para file_path, a CLI do Databricks usa o caminho padrão ${workspace.root}/files, que usa substituições.

state_path

O mapeamento state_path usa como padrão o caminho padrão ${workspace.root}/state e representa o caminho no seu workspace para armazenar informações de estado do Terraform sobre as implantações.

Outros mapeamentos de workspace

O mapeamento workspace também pode conter os mapeamentos opcionais a seguir para especificar o mecanismo de autenticação do Azure Databricks a ser usado. Se eles não forem especificados no mapeamento workspace, precisarão ser especificados em um mapeamento workspace como filho de um ou mais dos destinos no mapeamento targets de nível superior.

Importante

Você precisa embutir os valores em código referentes aos mapeamentos workspace a seguir para a autenticação do Azure Databricks. Por exemplo, você não pode especificar variáveis personalizadas para os valores desses mapeamentos usando a sintaxe ${var.*}.

• O mapeamento profile (ou as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks) especifica o nome de um perfil de configuração a ser usado com esse workspace para autenticação do Azure Databricks. Esse perfil de configuração é mapeado para aquele que você criou ao configurar a CLI do Databricks.

  Observação

  O Databricks recomenda que você use o host mapeamento (ou as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks) em vez do mapeamentoprofile, pois isso torna seus arquivos de configuração de pacote mais portáteis. Definir o mapeamento host instrui a CLI do Databricks a encontrar um perfil correspondente no arquivo .databrickscfg e a usar os campos desse perfil para determinar o tipo de autenticação do Databricks a ser usado. Se houver vários perfis com um campo correspondente host no arquivo .databrickscfg, é necessário usar o mapeamento profile (ou as opções --profile ou -p da linha de comando) para instruir a CLI do Databricks sobre o perfil que deve ser usado. Para ver um exemplo, confira a declaração de destino prod nos exemplos.

• O mapeamento host especifica a URL do seu workspace do Azure Databricks. Confira URL por workspace.

• Para a autenticação M2M (máquina a máquina) do OAuth, o mapeamento client_id é usado. Como alternativa, você pode definir esse valor na variável de ambiente local DATABRICKS_CLIENT_ID. Ou você pode criar um perfil de configuração com o valor client_id e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usar as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks). Confira Autorizar acesso autônomo aos recursos do Azure Databricks com uma entidade de serviço usando o OAuth.

  Observação

  Você não pode especificar um valor de segredo do OAuth do Azure Databricks no arquivo de configuração do pacote. Em vez disso, defina a variável de ambiente local DATABRICKS_CLIENT_SECRET. Ou você pode adicionar o valor client_secret a um perfil de configuração e especificar o nome do perfil com o mapeamento profile (ou usar as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks).

• Para a autenticação da CLI do Azure, o mapeamento azure_workspace_resource_id é usado. Como alternativa, você pode definir esse valor na variável de ambiente local DATABRICKS_AZURE_RESOURCE_ID. Ou você pode criar um perfil de configuração com o valor azure_workspace_resource_id e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usar as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks). Confira Autenticação da CLI do Azure.

• Para a autenticação de segredo do cliente do Azure com entidades de serviço, os mapeamentos azure_workspace_resource_id, azure_tenant_id e azure_client_id são usados. Como alternativa, você pode definir esses valores nas variáveis de ambiente local DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_ID e ARM_CLIENT_ID, respectivamente. Ou você pode criar um perfil de configuração com os valores azure_workspace_resource_id, azure_tenant_id e azure_client_id e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usar as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks). Confira Autenticação da entidade de serviço do MS Entra.

  Observação

  Você não pode especificar um valor de segredo do cliente do Azure no arquivo de configuração do pacote. Em vez disso, defina a variável de ambiente local ARM_CLIENT_SECRET. Ou você pode adicionar o valor azure_client_secret a um perfil de configuração e especificar o nome do perfil com o mapeamento profile (ou usar as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks).

• Para autenticação de identidades gerenciadas do Azure, os mapeamentos azure_use_msi, azure_client_id e azure_workspace_resource_id são utilizados. Como alternativa, você pode definir esses valores nas variáveis de ambiente local ARM_USE_MSI, ARM_CLIENT_ID e DATABRICKS_AZURE_RESOURCE_ID, respectivamente. Ou você pode criar um perfil de configuração com os valores azure_use_msi, azure_client_id e azure_workspace_resource_id e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usar as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks). Consulte Autenticação de identidades gerenciadas do Azure.

• O mapeamento azure_environment especifica o tipo de ambiente do Azure (como Público, UsGov, China e Alemanha) para um conjunto específico de pontos de extremidade de API. O valor padrão é PUBLIC. Como alternativa, você pode definir esse valor na variável de ambiente local ARM_ENVIRONMENT. Ou você pode adicionar o valor azure_environment a um perfil de configuração e especificar o nome do perfil com o mapeamento profile (ou usar as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com a CLI do Databricks).

• O mapeamento azure_login_app_id não está operacional e é reservado para uso interno.

• O mapeamento auth_type especifica o tipo de autenticação do Azure Databricks a ser usado, especialmente nos casos em que a CLI do Databricks infere um tipo de autenticação inesperado. Confira Autorizar acesso aos recursos do Azure Databricks.

permissions

O mapeamento permissions de nível superior especifica um ou mais níveis de permissão a serem aplicados a todos os recursos definidos no pacote. Se você quiser aplicar permissões a um recurso específico, consulte Definir permissões para um recurso específico.

Os níveis de permissão de nível superior permitidos são CAN_VIEW, CAN_MANAGE e CAN_RUN.

O exemplo a seguir em um arquivo de configuração do pacote define níveis de permissão para um usuário, grupo e entidade de serviço, que são aplicados a todos os trabalhos, pipelines, experimentos e modelos definidos em resources no pacote:

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

O mapeamento artifacts de nível superior especifica um ou mais artefatos que são criados automaticamente durante as implantações de pacote e podem ser usados posteriormente nas execuções de pacote. Cada artefato filho dá suporte aos seguintes mapeamentos:

• type é necessário para builds de pacote wheel do Python. Para criar um arquivo de roda do Python antes de implantar, defina-o como whl. Para criar outros artefatos, essa configuração não precisa ser especificada.
• path é um caminho opcional. Os caminhos são relativos ao local do arquivo de configuração do pacote. Para compilações de pacote wheel do Python, é o caminho para o arquivo setup.py do arquivo de wheel do Python. Se path não estiver incluído, a CLI do Databricks tentará localizar o arquivo de wheel setup.py do Python na raiz do pacote.
• files é um mapeamento opcional que inclui um mapeamento filho source, o qual você pode usar para especificar os artefatos construídos. Os caminhos são relativos ao local do arquivo de configuração do pacote.
• build é um conjunto opcional de comandos de build não padrão que você deseja executar localmente antes da implantação. Para builds de wheels do Python, a CLI do Databricks pressupõe que possa encontrar uma instalação local do pacote wheel do Python para executar os builds e executa o comando python setup.py bdist_wheel por padrão durante cada implantação de pacote. Para especificar vários comandos de build, separe cada comando com caracteres de E comercial duplo (&&).

A configuração de exemplo a seguir cria uma roda usando o Poetry. Para obter um pacote de exemplo completo que usa artifacts para criar um pacote wheel, confira Desenvolver um arquivo de wheel do Python usando Pacotes de Ativos do Databricks.

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

Para obter uma configuração de exemplo que compila um JAR e o carrega no Catálogo do Unity, consulte Pacote que carrega um arquivo JAR para o Catálogo do Unity.

Dica

Você pode definir, combinar e substituir as configurações de artefatos em pacotes, conforme descrito em Definir as configurações de artefato em Pacotes de Ativos do Databricks.

include

A matriz include especifica uma lista de globs de caminho que contêm os arquivos de configuração a serem incluídos no pacote. Esses globs de caminho são relativos ao local do arquivo de configuração do pacote no qual os globs de caminho são especificados.

A CLI do Databricks não inclui nenhum arquivo de configuração por padrão no pacote. Você precisa usar a matriz include para especificar todo e qualquer arquivo de configuração a ser incluído no pacote, além do próprio arquivo databricks.yml.

Esta matriz include só pode aparecer como um mapeamento de nível superior.

O exemplo de configuração a seguir inclui três arquivos de configuração. Esses arquivos estão na mesma pasta que o arquivo de configuração do pacote:

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

A configuração de exemplo a seguir inclui todos os arquivos com nomes de arquivos que começam com bundle e terminam com .yml. Esses arquivos estão na mesma pasta que o arquivo de configuração do pacote:

include:
  - "bundle*.yml"

resources

O mapeamento resources especifica informações sobre os recursos do Azure Databricks usados pelo pacote.

Esse mapeamento resources pode aparecer como um mapeamento de nível superior ou pode ser filho de um ou mais dos destinos no mapeamento de destinos de nível superior e inclui zero ou um dos tipos de recursos com suporte. Cada mapeamento de tipo de recurso inclui uma ou mais declarações de recurso individuais, que devem ter um nome exclusivo. Essas declarações individuais de recursos usam o conteúdo da solicitação da operação de criação do objeto correspondente, expressa em YAML, para definir o recurso. As propriedades com suporte para um recurso são os campos com suporte do objeto correspondente.

Os conteúdos de solicitação da operação de criação são documentados na Referência da API REST do Databricks e o comando databricks bundle schema exibe todos os esquemas de objeto com suporte. Além disso, o comando databricks bundle validate retornará avisos se forem encontradas propriedades de recurso desconhecidas em arquivos de configuração de pacote.

A configuração de exemplo a seguir define um recurso de trabalho:

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

Para obter mais informações sobre os recursos com suporte em pacotes, bem como configuração e exemplos comuns, consulte Recursos de Pacotes de Ativos do Databricks e Exemplos de configuração de pacote.

sync

O mapeamento sync permite que você configure quais arquivos fazem parte das implantações do pacote.

include e exclude

Os mapeamentos de include e exclude no mapeamento de sync especificam uma lista de arquivos ou pastas a serem incluídos ou excluídos de implantações de pacote, dependendo das seguintes regras:

• Com base em qualquer lista de globs de arquivo e de caminho em um arquivo .gitignore na raiz do pacote, o mapeamento include pode conter uma lista de globs de arquivo, globs de caminho ou ambos, em relação à raiz do pacote, para inclusão explícita.
• Com base em qualquer lista de globs de arquivo e de caminho em um arquivo .gitignore na raiz do pacote, além da lista de globs de arquivo e de caminho no mapeamento include, o mapeamento exclude pode conter uma lista de globs de arquivo, globs de caminho ou ambos, em relação à raiz do pacote, para exclusão explícita.

Todos os caminhos para pastas e arquivos especificados são relativos ao local do arquivo de configuração do pacote no qual esses caminhos são especificados.

A sintaxe dos padrões de caminho e de arquivo include e exclude segue a sintaxe padrão de padrões .gitignore. Consulte Formato de padrão gitignore.

Por exemplo, se o seguinte arquivo .gitignore contiver as seguintes entradas:

.databricks
my_package/dist

E o arquivo de configuração do pacote contém o seguinte mapeamento include:

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

Em seguida, todos os arquivos da pasta my_package/dist com a extensão de arquivo igual *.whl são incluídos. Os outros arquivos da pasta my_package/dist não estão incluídos.

Entretanto, se o arquivo de configuração do pacote também contiver o seguinte mapeamento exclude:

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

Em seguida, todos os arquivos da pasta my_package/dist com a extensão de arquivo *.whl, exceto o arquivo nomeado delete-me.whl, são incluídos. Os outros arquivos da pasta my_package/dist também não estão incluídos.

O mapeamento sync também pode ser declarado no mapeamento targets para um destino específico. Qualquer mapeamento sync declarado em um destino é mesclado com quaisquer declarações de mapeamento sync de nível superior. Por exemplo, continuando com o exemplo anterior, o seguinte mapeamento include no nível targets é mesclado com o mapeamento include no mapeamento sync de nível superior:

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

paths

O mapeamento sync pode conter um mapeamento paths que especifica caminhos locais para sincronização com o workspace. O mapeamento paths permite que você compartilhe arquivos comuns entre pacotes e pode ser usado para sincronizar arquivos localizados fora da raiz do pacote. (A raiz do pacote é o local do arquivo databricks.yml.) Isso é especialmente útil quando você tem apenas um repositório que hospeda vários pacotes e deseja compartilhar bibliotecas, arquivos de código ou configuração.

Os caminhos especificados precisam ser relativos aos arquivos e aos diretórios ancorados na pasta em que o mapeamento paths está definido. Se um ou mais valores de caminho percorrerem o diretório até um ancestral da raiz do pacote, o caminho raiz será determinado dinamicamente para garantir que a estrutura da pasta permaneça intacta. Por exemplo, se a pasta raiz do pacote for nomeada como my_bundle, essa configuração em databricks.yml sincronizará a pasta common localizada um nível acima da raiz do pacote e a própria raiz do pacote:

sync:
  paths:
    - ../common
    - .

Uma implantação desse pacote resulta na seguinte estrutura de pastas no workspace:

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

targets

O mapeamento targets especifica um ou mais contextos nos quais os fluxos de trabalho do Azure Databricks devem ser executados. Cada destino é uma coleção exclusiva de artefatos, configurações de workspace do Azure Databricks e de detalhes de pipeline ou de trabalho do Azure Databricks.

O mapeamento targets consiste em um ou mais mapeamentos de destino, e cada um precisa ter um nome programático (ou lógico) exclusivo.

O mapeamento targets é opcional, mas altamente recomendado. Se especificado, ele só poderá aparecer como um mapeamento de nível superior.

As configurações nos mapeamentos de workspace, artefatos e recursos de nível superior serão usadas se não forem especificadas em um mapeamento targets, mas quaisquer configurações conflitantes serão substituídas pelas configurações em um destino.

Um destino também pode substituir os valores de qualquer variável de nível superior.

default

Para especificar um padrão de destino para comandos de pacote, defina o mapeamento default como true. Por exemplo, este destino chamado dev é o destino padrão:

targets:
  dev:
    default: true

Se um destino padrão não estiver configurado ou se você quiser validar, implantar e executar trabalhos ou pipelines em um destino específico, use a opção -t dos comandos de pacote.

Os seguintes comandos validam, implantam e executam my_job nos destinos 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

O exemplo a seguir declara dois destinos. O primeiro destino tem o nome dev e é o destino padrão usado quando nenhum destino é especificado para comandos de pacote. O segundo destino tem o nome prod e é usado somente quando esse destino é especificado para comandos de pacote.

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

modo e predefinições

Para facilitar o desenvolvimento e as práticas recomendadas de CI/CD, os Pacotes de Ativos do Databricks fornece modos de implantação para destinos que definem comportamentos padrão para fluxos de trabalho de pré-produção e produção. Alguns comportamentos também são configuráveis. Para ver detalhes, confira Modos de implantação do Pacote de Ativos do Databricks.

Dica

Para definir identidades de execução para pacotes, você pode especificar run_as para cada destino, conforme descrito em Especificar uma identidade de execução para um fluxo de trabalho de Pacotes de Ativos do Databricks.

Para especificar que um destino seja tratado como um destino de desenvolvimento, adicione o mapeamento mode, definido como development. Para especificar que um destino seja tratado como um destino de desenvolvimento, adicione o mapeamento mode, definido como production. Por exemplo, este destino chamado prod é tratado como um destino de produção:

targets:
  prod:
    mode: production

Você pode personalizar alguns dos comportamentos usando o mapeamento presets. Para obter uma lista de predefinições disponíveis, consulte Predefinições personalizadas. O seguinte exemplo mostra uma meta de produção personalizada que prefixa e marca todos os recursos de produção:

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

Se mode e presets estiverem definidos, as predefinições substituirão o comportamento do modo padrão. As configurações de recursos individuais substituem as predefinições. Por exemplo, se uma agenda estiver definida como UNPAUSED, mas a predefinição trigger_pause_status estiver definida como PAUSED, a agenda não será pausada.