Databricks Configuração do pacote ativo

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

Para criar e trabalhar com pacotes, consulte Databricks ativo Bundles development.

Visão geral

Um arquivo de configuração de pacote deve ser expresso no formato YAML e conter, no mínimo, o mapeamento de pacote de nível superior. Cada pacote deve conter no mínimo um (e apenas um) arquivo de configuração de pacote configurável chamado databricks.yml. Se houver 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 saber mais sobre o YAML, consulte a especificação oficial e o tutorial do YAML.

Especificação

A especificação YAML a seguir fornece a chave de configuração de nível superior para Databricks ativo Bundles. Para referência de configuração, consulte 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 os recursos do pacote e os casos de uso comuns do pacote, consulte Exemplos de configuração do pacote e o repositório de exemplos do pacote no GitHub.

O exemplo de configuração de pacote configurável a seguir especifica um arquivo local chamado hello.py que está no mesmo diretório que esse arquivo de configuração de pacote configurável local chamado databricks.yml. Ele executa este notebook como um job usando o cluster remoto com o ID de cluster especificado. O URL do workspace remoto e as credenciais de autenticação do workspace são lidas a partir do perfil de configuração local do chamador chamado DEFAULT.

A 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 em seu arquivo .databrickscfg e, em seguida, usar os campos desse perfil para determinar qual tipo de autenticação do Databricks usar. Se existirem vários perfis com um campo host correspondente em seu arquivo .databrickscfg, você deverá usar o profile para instruir a CLI do Databricks sobre qual perfil específico deve ser usado. Para ver um exemplo, consulte a declaração de destino prod mais adiante nesta seção.

Essa técnica permite que você reutilize e substitua as definições e configurações do job no 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, esta declaração acrescenta uma tarefa ao job em vez de substituir o job atual:

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 alvo com o nome prod que usa um URL de workspace remoto diferente e credenciais de autenticação do workspace, que são lidas da entrada host correspondente do arquivo .databrickscfg do chamador com a URL de workspace especificada. Este job executa o mesmo notebook, mas usa um cluster remoto diferente com o ID de cluster especificado. Observe que você não precisa declarar o mapeamento notebook_task dentro do mapeamento prod, pois ele recai para o uso do mapeamento notebook_task dentro do mapeamento de nível superior resources, se o mapeamento notebook_task não for explicitamente sobrescrito dentro do 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 este job 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

Em vez disso, para validar, implantar e executar esse job no destino prod:

# 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

Veja a seguir o exemplo anterior, mas dividido em arquivos de componentes para ainda mais modularização e melhor reutilização em vários arquivos de configuração de pacotes. Essa técnica permite não só reutilizar várias definições e configurações, mas também trocar qualquer um desses arquivos por outros 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.

pacote

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

Esse mapeamento de bundle deve conter um mapeamento de name que especifica 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 alvos no mapeamento de destinos de nível superior. Cada um desses mapeamentos bundle filhos especifica quaisquer substituições não padrão no nível do destino. No entanto, o valor de name do mapeamento de bundle de nível superior não pode ser substituído no nível de destino.

agrupamento

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

A substituição cluster_id é destinada a cenários somente de desenvolvimento e só é compatível com o destino que tem seu mapeamento mode definido como development. Para obter mais informações sobre o mapeamento target, consulte os alvos.

compute_id

Observação

Essa configuração está obsoleta. Em vez disso, use o clustering.

O mapeamento bundle pode ter um mapeamento infantil compute_id. Esse mapeamento permite que o senhor especifique a ID de um cluster a ser usado 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 de controle da versão do Git associados ao seu pacote. Isso é útil para anotar seus recursos implantados. Por exemplo, talvez você queira incluir o URL de origem dr seu repositório na descrição de um modelo do machine learning que está sendo implantado.

Sempre que você executa um comando bundle, como validate, deploy ou run, o comando bundle preenche 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 repo. Esse é o mesmo valor que você obteria se executasse o comando git config --get remote.origin.url a partir de seu repo clonado. Você pode usar substituições para se referir a esse valor nos arquivos de configuração do pacote, como ${bundle.git.origin_url}.

• bundle.git.branch, que representa o ramo atual dentro do repositório. Esse é o mesmo valor que você obteria se executasse o comando git branch --show-current a partir de seu repo clonado. Você pode usar substituições para se referir a esse valor nos arquivos de configuração do pacote, como ${bundle.git.branch}.

Para recuperar ou substituir as configurações do Git, seu pacote deve 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 em branco.

Você pode substituir as configurações origin_url e branch dentro do mapeamento git do seu mapeamento de nível superior bundle , 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 de bundle pode conter um mapeamento de 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 são compatíveis com 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 de databricks_cli_version é compatível com a especificação das restrições de versão . Se o valor do databricks --version atual não estiver dentro dos limites especificados no mapeamento de databricks_cli_version do bundle, ocorrerá um erro quando databricks bundle validate for executado no bundle. Os exemplos a seguir demonstram alguma sintaxe comum de restrição de versão:

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

variáveis

O arquivo de configurações de pacotes pode conter um mapeamento variables de nível superior em que variáveis personalizadas são definidas. Para cada variável, defina uma descrição opcional, o valor default, 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

As variáveis são consideradas do tipo string, a menos que type seja definido como complex. Veja Definir uma variável complexa.

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

Para obter mais informações sobre variáveis e substituições personalizadas, consulte Substituições e variáveis em Databricks ativo Bundles.

workspace

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

Importante

Válido Databricks workspace caminhos começam com /Workspace ou /Volumes. Os caminhos personalizados do workspace são automaticamente prefixados com /Workspace, portanto, se o senhor usar qualquer substituição de caminho do workspace em seu caminho personalizado, como ${workspace.file_path}, não precisará acrescentar /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 fluxos de trabalho, como por exemplo:

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

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

artifact_path

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

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

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

Observação

O mapeamento artifact_path não oferece suporte aos caminhos do Databricks File System (DBFS).

file_path

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

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

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

state_path

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

Outros mapeamentos de workspace

O mapeamento workspace também pode conter os seguintes mapeamentos opcionais para especificar o mecanismo de autenticação do Databricks a ser usado. Se eles não estiverem especificados nesse mapeamento workspace, eles devem ser especificados em um mapeamento workspace como filhos de um ou mais dos destinos no mapeamento de destinos de nível superior.

Importante

Você deve codificar os valores dos seguintes mapeamentos workspace para autenticação do 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, implantar, executar e destruir do pacote com a CLI do Databricks) especifica o nome de um perfil de configuração a ser usado com esse workspace para autenticação do Databricks. Esse perfil de configuração é mapeado para aquele que você criou quando configurou a CLI da Databricks.

  Observação

  A Databricks recomenda que você use o mapeamento host (ou as opções --profile ou -p ao executar os comandos de validação, implantação, execução e destruição do pacote com a CLI do Databricks) em vez do mapeamento profile, 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 em seu arquivo .databrickscfg e, em seguida, usar os campos desse perfil para determinar qual tipo de autenticação do Databricks usar. Se existirem vários perfis com um campo host correspondente em seu arquivo .databrickscfg, você deverá usar o mapeamento profile (ou as opções de linha de comando --profile ou -p) para instruir a CLI do Databricks sobre qual perfil usar. Para ver um exemplo, consulte a declaração de destino prod nos exemplos.

• O mapeamento host especifica a URL para seu workspace do Databricks. Consulte Nomes de instâncias, URLs e IDs de workspace.

• Para autenticação OAuth máquina a máquina (M2M), use o mapeamento client_id. Como alternativa, o senhor pode definir esse valor na variável de ambiente local DATABRICKS_CLIENT_ID. Ou o senhor 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 usando as opções --profile ou -p ao executar o comando bundle validate, implantado, executado e destroy com o Databricks CLI). Consulte Autenticar o acesso ao Databricks com uma entidade de serviço usando OAuth (OAuth M2M).

  Observação

  Você não pode especificar um valor secreto do Databricks OAuth no arquivo de configuração do pacote. Em vez disso, defina a variável de ambiente local DATABRICKS_CLIENT_SECRET. Como alternativa, você pode adicionar o valor client_secret a um perfil de configuração e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar os comandos bundle validate, deploy, run e destroy com a CLI do Databricks).

• Para a autenticação da conta de serviço do Google Cloud, o mapeamento google_service_account é usado. Como alternativa, você pode definir esse valor na variável de ambiente local DATABRICKS_GOOGLE_SERVICE_ACCOUNT. Ou você pode criar um perfil de configuração com o valor google_service_account e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar os comandos de validação, implantação, execução e destruição do pacote com a CLI do Databricks). Veja Autenticação do Google Cloud ID.

• O mapeamento auth_type especifica o tipo de autenticação do Databricks a ser usado, especialmente nos casos em que a CLI do Databricks infere um tipo de autenticação inesperado. Consulte a seção Autenticar acesso a Databricks recurso.

permissões

O mapeamento de 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 de pacote define os 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

artefatos

O mapeamento artifacts de nível superior especifica um ou mais artefatos que são criados automaticamente durante as implantações de pacotes e podem ser usados posteriormente em execuções de pacotes. Cada artefato filho suporta os seguintes mapeamentos:

• type é obrigatório. Para criar um Python wheel antes da implantação, esse mapeamento deve ser definido como whl.

• path é um caminho relativo opcional do local do arquivo de configuração do pacote para o local do arquivo setup.py do arquivo Python wheel. Se path não estiver incluído, a CLI do Databricks tentará localizar o arquivo setup.py do arquivo Python wheel na raiz do pacote.

• files é um mapeamento opcional que inclui um mapeamento secundário de source, que você pode usar para especificar locais não padrão a serem incluídos em instruções de criação complexas. Os locais são especificados como caminhos relativos a partir do local do arquivo de configuração do pacote.

• build é um conjunto opcional de comandos de compilação não default que você deseja executar localmente antes da implantação. Para compilações do Python wheel, a CLI do Databricks assume que pode encontrar uma instalação local do pacote Python wheel para executar compilações, e executa o comando python setup.py bdist_wheel por default durante a implantação de cada pacote. Para especificar vários comandos de compilação, separe cada comando com caracteres de e comercial duplo (&&).

O exemplo de configuração a seguir cria uma roda usando o Poetry:

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

Para obter um exemplo completo de pacote que usa artifacts, consulte Desenvolver um arquivo Python wheel usando Databricks ativo Bundles.

Dica

O senhor pode definir, combinar e substituir as configurações de artefatos em pacotes, conforme descrito em Definir configurações de artefatos em Databricks ativo Bundles.

incluir

A matriz include especifica uma lista de globs de caminho que contêm 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ê deve 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 .

Essa 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 do arquivo de configuração do pacote:

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

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

include:
  - "bundle*.yml"

recursos

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

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

Os payloads de solicitação de operação de criação estão documentadas na Referência da API REST do Databricks, e o comando databricks bundle schema exibe todos os esquemas de objetos compatíveis. Além disso, o comando databricks bundle validate retorna avisos se propriedades de recursos desconhecidas forem encontradas em arquivos de configuração de pacotes.

O exemplo de configuração 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 o recurso suportado nos pacotes, bem como sobre a configuração e os exemplos comuns, consulte Databricks ativo Bundles recurso e Bundle configuration examples.

sincronização

O mapeamento sync permite que você configure quais arquivos fazem parte de suas implantações de pacotes.

incluir e excluir

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

• Com base em qualquer lista de globs de arquivo e caminho em um arquivo .gitignore na raiz do pacote, o mapeamento de include pode conter uma lista de globs de arquivo, globs de caminho ou ambos, em relação à raiz do pacote, para incluir explicitamente.

• Com base em qualquer lista de globs de arquivo e caminho em um arquivo .gitignore na raiz do pacote, mais a lista de globs de arquivo e 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 excluir explicitamente.

Todos os caminhos para arquivos e pastas especificados são relativos à localização do arquivo de configuração do pacote no qual eles são especificados.

A sintaxe para padrões de arquivos e caminhos em include e exclude segue a sintaxe padrão de padrões em .gitignore . Consulte Formato do 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 na pasta my_package/dist com uma extensão de arquivo *.whl são incluídos. Quaisquer outros arquivos na pasta my_package/dist não estão incluídos.

No entanto, 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 na pasta my_package/dist com uma extensão de arquivo de *.whl, exceto o arquivo chamado delete-me.whl, são incluídos. Quaisquer outros arquivos na pasta my_package/dist também não estão incluídos.

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

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

caminhos

O mapeamento sync pode conter um mapeamento paths que especifica caminhos locais para sincronizar 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 é a localização do arquivo databricks.yml.) Isso é especialmente útil quando o senhor tem um único repositório que hospeda vários pacotes e deseja compartilhar biblioteca, arquivos de código ou configuração.

Os caminhos especificados devem ser relativos aos arquivos e 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 tiver o nome 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
    - .

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

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

destinos

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

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

Este mapeamento targets é opcional, mas altamente recomendado. Se for especificado, ele poderá aparecer apenas como um mapeamento de nível superior.

As configurações nos mapeamentos de nível superior workspacede nível superior, artefatos e mapeamentos de recurso são usados se não forem especificados em um mapeamento targets, mas quaisquer configurações conflitantes são substituídas pelas configurações em um destino.

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

padrão

Para especificar um destino default para o comando do pacote, defina o mapeamento default como true. Por exemplo, esse alvo chamado dev é o alvo default:

targets:
  dev:
    default: true

Se um destino default não estiver configurado ou se o senhor quiser validar, implantar e executar um trabalho ou pipeline em um destino específico, use a opção -t do comando bundle.

O comando a seguir valida, implanta e executa my_job dentro dos alvos 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 alvos. O primeiro alvo tem o nome dev e é o alvo default usado quando nenhum alvo é especificado para o comando do pacote. O segundo alvo tem o nome prod e é usado somente quando esse alvo é especificado para o comando do pacote.

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

modo e predefinições

Para facilitar o desenvolvimento e CI/CD as práticas recomendadas, o Databricks ativo Bundles oferece modos de implantação para alvos que definem default comportamentos para o fluxo de trabalho de pré-produção e produção. Alguns comportamentos também são configuráveis. Para obter detalhes, consulte Databricks ativo Bundle deployment modes.

Dica

Para definir identidades de execução para pacotes, o senhor pode especificar run_as para cada destino, conforme descrito em Especificar uma identidade de execução para um Databricks ativo Bundles fluxo de trabalho.

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

targets:
  prod:
    mode: production

Você pode personalizar alguns dos comportamentos usando o mapeamento presets. Para obter uma lista das predefinições disponíveis, consulte Predefinições personalizadas. O exemplo a seguir mostra um alvo de produção personalizado que prefixa e tags todos os recursos de produção:

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

Se ambos mode e presets estiverem definidos, as predefinições substituirão o comportamento do modo default. As configurações dos recursos individuais substituem as predefinições. Por exemplo, se um programar estiver definido como UNPAUSED, mas a predefinição trigger_pause_status estiver definida como PAUSED, o programar não será pausado.