Configurações do Databricks Asset Bundle
Este artigo descreve a sintaxe dos arquivos de configuração do Databricks Asset Bundle, que definem o Databricks Asset Bundles. Consulte O que são Databricks Asset Bundles?
Um arquivo de configuração de pacote deve ser expresso no formato YAML e deve conter, no mínimo, o mapeamento de pacote de nível superior. Cada pacote deve conter pelo menos um (e apenas um) arquivo de configuração de pacote chamado databricks.yml
. Se houver vários arquivos de configuração de pacote, eles devem ser referenciados databricks.yml
pelo arquivo usando o include
mapeamento.
Para obter mais informações sobre o YAML, consulte a especificação oficial do YAML e o tutorial.
Para criar e trabalhar com arquivos de configuração de pacote, consulte Desenvolvimento de pacotes de ativos Databricks.
Descrição geral
Esta seção fornece uma representação visual do esquema do arquivo de configuração do pacote. Para obter detalhes, consulte Mapeamentos.
# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
name: string # Required.
databricks_cli_version: string
compute_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:
experiments:
<some-unique-programmatic-identifier-for-this-experiment>:
# See the Experiments API's create experiment request payload reference.
jobs:
<some-unique-programmatic-identifier-for-this-job>:
# See the Jobs API's create job request payload reference.
models:
<some-unique-programmatic-identifier-for-this-model>:
# See the Models API's create model request payload reference.
pipelines:
<some-unique-programmatic-identifier-for-this-pipeline>:
# See the Delta Live Tables API's create pipeline request payload reference.
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>"
# 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.
compute_id: string
default: true | false
mode: development
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
Nota
Para obter exemplos de configuração que demonstram recursos de pacote e casos de uso comuns de pacote, consulte Exemplos de configuração de pacote e o repositório de exemplos de pacote no GitHub.
O exemplo de configuração de pacote a seguir especifica um arquivo local chamado hello.py
que está no mesmo diretório que esse arquivo de configuração de pacote local chamado databricks.yml
. Ele executa este bloco de anotações como um trabalho usando o cluster remoto com a ID de cluster especificada. A URL do espaço de trabalho remoto e as credenciais de autenticação do espaço de trabalho são lidas a partir do perfil de configuração local do chamador chamado DEFAULT
.
O Databricks recomenda que você use o host
mapeamento em vez do mapeamento sempre que possível, pois isso torna os arquivos de configuração do default
pacote mais portáteis. A definição do host
mapeamento instrui a CLI do Databricks a encontrar um perfil correspondente em seu .databrickscfg
arquivo 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 correspondente host
em seu .databrickscfg
arquivo, você deverá usar o profile
para instruir a CLI do Databricks sobre qual perfil específico usar. Para obter um exemplo, consulte a declaração de prod
destino mais adiante nesta seção.
Essa técnica permite que você reutilize, bem como substitua as definições e configurações de trabalho dentro do resources
bloco :
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 seguinte arquivo de configuração do pacote 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 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 espaço de trabalho remoto diferente e credenciais de autenticação de espaço de trabalho, que são lidas da entrada correspondente host
do arquivo do chamador .databrickscfg
com a URL do espaço de trabalho especificado. Esse trabalho executa o mesmo bloco de anotações, mas usa um cluster remoto diferente com a ID de cluster especificada. Observe que você não precisa declarar o notebook_task
mapeamento dentro do prod
mapeamento, pois ele volta a usar o notebook_task
mapeamento dentro do mapeamento de nível resources
superior, se o notebook_task
mapeamento não for explicitamente substituído dentro do prod
mapeamento.
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 dev
destino:
# 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 prod
destino:
# 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 está 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 pacote. Essa técnica permite que você não apenas reutilize várias definições e configurações, mas também pode trocar qualquer um desses arquivos por outros arquivos que fornecem 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
- variáveis
- espaço de trabalho
- permissions (permissões)
- artefatos
- incluem
- Recursos
- sincronização
- Objetivos
pacote
Um arquivo de configuração de pacote deve conter apenas um mapeamento de nível bundle
superior que associe o conteúdo do pacote e as configurações do espaço de trabalho do Azure Databricks.
Esse bundle
mapeamento deve conter um name
mapeamento que especifique um nome programático (ou lógico) para o pacote. O exemplo a seguir declara um pacote com o nome hello-bundle
programático (ou lógico) .
bundle:
name: hello-bundle
Um bundle
mapeamento também pode ser filho de um ou mais dos destinos no mapeamento de destinos de nível superior. Cada um desses mapeamentos filho bundle
especifica quaisquer substituições não padrão no nível de destino. No entanto, o valor do name
mapeamento de nível bundle
superior não pode ser substituído no nível de destino.
compute_id
O bundle
mapeamento pode ter um mapeamento filho compute_id
. Esse mapeamento permite especificar a ID de um cluster a ser usada como uma substituição para todo e qualquer cluster definido em outro lugar no arquivo de configuração do pacote. Essa substituição destina-se a cenários somente de desenvolvimento antes da produção. O compute_id
mapeamento funciona apenas para o destino que tem seu mode
mapeamento definido como development
. Para obter mais informações sobre o compute_id
mapeamento, consulte o mapeamento de destinos .
Git
Você pode recuperar e substituir os detalhes do controle de versão do Git associados ao seu pacote. Isso é útil para anotar os recursos implantados. Por exemplo, talvez você queira incluir a URL de origem do repositório na descrição de um modelo de aprendizado de máquina implantado.
Sempre que você executa um bundle
comando como validate
, deploy
ou run
, o bundle
comando preenche a árvore de configuração do comando com as seguintes configurações padrão:
bundle.git.origin_url
, que representa o URL de origem do repositório. Este é o mesmo valor que você obteria se executasse o comandogit config --get remote.origin.url
do seu repositório clonado. Você pode usar substituições para fazer referência a esse valor com seus arquivos de configuração de pacote, como${bundle.git.origin_url}
.bundle.git.branch
, que representa a ramificação atual dentro do repo. Este é o mesmo valor que você obteria se executasse o comandogit branch --show-current
do seu repositório clonado. Você pode usar substituições para fazer referência a esse valor com seus arquivos de configuração de pacote, como${bundle.git.branch}
.bundle.git.commit
, que representa oHEAD
compromisso dentro do repo. Este é o mesmo valor que você obteria se executasse o comandogit rev-parse HEAD
do seu repositório clonado. Você pode usar substituições para fazer referência a esse valor com seus arquivos de configuração de pacote, como${bundle.git.commit}
.
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 executando o git clone
comando. 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 origin_url
configurações e branch
dentro do git
mapeamento do seu mapeamento de nível bundle
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 bundle
mapeamento pode conter um databricks_cli_version
mapeamento 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 suportados 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 suporta a databricks_cli_version
especificação de restrições de versão. Se o valor atual databricks --version
não estiver dentro dos limites especificados no mapeamento do databricks_cli_version
pacote, ocorrerá um erro quando databricks bundle validate
for executado no pacote. Os exemplos a seguir demonstram algumas 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
variáveis
O arquivo de configurações de pacotes pode conter um mapeamento de nível variables
superior para especificar as configurações de variáveis a serem usadas. Consulte Variáveis personalizadas.
espaço de trabalho
O arquivo de configuração do pacote pode conter apenas um mapeamento de nível workspace
superior para especificar quaisquer configurações não padrão do espaço de trabalho do Azure Databricks a serem usadas.
root_path
Esse workspace
mapeamento pode conter um root_path
mapeamento para especificar um caminho raiz não padrão a ser usado no espaço de trabalho para implantações e execuções de fluxo de trabalho, por exemplo:
workspace:
root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
Por padrão, para root_path
o Databricks CLI usa o caminho padrão de /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}
, que usa substituições.
artifact_path
Esse workspace
mapeamento também pode conter um artifact_path
mapeamento para especificar um caminho de artefato não padrão a ser usado no espaço de trabalho para implantações e execuções de fluxo de trabalho, por exemplo:
workspace:
artifact_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts
Por padrão, para artifact_path
o Databricks CLI usa o caminho padrão de ${workspace.root}/artifacts
, que usa substituições.
Nota
O artifact_path
mapeamento não suporta caminhos do sistema de arquivos Databricks (DBFS).
file_path
Esse workspace
mapeamento também pode conter um file_path
mapeamento para especificar um caminho de arquivo não padrão a ser usado no espaço de trabalho para implantações e execuções de fluxo de trabalho, por exemplo:
workspace:
file_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files
Por padrão, para file_path
o Databricks CLI usa o caminho padrão de ${workspace.root}/files
, que usa substituições.
state_path
O state_path
mapeamento assume como padrão o caminho padrão e representa o caminho dentro do espaço de trabalho para armazenar informações de estado do ${workspace.root}/state
Terraform sobre implantações.
Outros mapeamentos de espaço de trabalho
O workspace
mapeamento também pode conter os seguintes mapeamentos opcionais para especificar o mecanismo de autenticação do Azure Databricks a ser usado. Se eles não forem especificados nesse workspace
mapeamento, eles deverão ser especificados em um workspace
mapeamento como filho de um ou mais dos destinos no mapeamento de destinos de nível superior.
Importante
Você deve codificar valores para os mapeamentos a seguir workspace
para autenticação do Azure Databricks. Por exemplo, não é possível especificar variáveis personalizadas para os valores desses mapeamentos usando a ${var.*}
sintaxe.
O
profile
mapeamento (ou as opções ou-p
ao--profile
executar os comandos de validação, implantação, execução e destruição do pacote com a CLI do Databricks) especifica o nome de um perfil de configuração a ser usado com esse espaço de trabalho para autenticação do Azure Databricks. Esse perfil de configuração é mapeado para aquele que você criou quando configurou a CLI do Databricks.Nota
O Databricks recomenda que você use o
host
mapeamento (ou as--profile
opções 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, pois isso torna os arquivos de configuração doprofile
pacote mais portáteis. A definição dohost
mapeamento instrui a CLI do Databricks a encontrar um perfil correspondente em seu.databrickscfg
arquivo 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 correspondentehost
em seu.databrickscfg
arquivo, você deverá usar oprofile
mapeamento (ou as opções de--profile
-p
linha de comando) para instruir a CLI do Databricks sobre qual perfil usar. Para obter um exemplo, consulte aprod
declaração de destino nos exemplos.O
host
mapeamento especifica a URL para seu espaço de trabalho do Azure Databricks. Consulte URL por espaço de trabalho.Para autenticação OAuth máquina-a-máquina (M2M), o mapeamento
client_id
é usado. Como alternativa, você pode definir esse valor na variávelDATABRICKS_CLIENT_ID
de ambiente local . Ou você pode criar um perfil de configuração com oclient_id
valor e, em seguida, especificar o nome do perfil com oprofile
mapeamento (ou usando as--profile
opções ou-p
ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte Usar uma entidade de serviço para autenticar com o Azure Databricks (OAuth M2M).Nota
Não é possível especificar um valor secreto OAuth do Azure Databricks no arquivo de configuração do pacote. Em vez disso, defina a variável
DATABRICKS_CLIENT_SECRET
de ambiente local . Ou você pode adicionar oclient_secret
valor a um perfil de configuração e, em seguida, especificar o nome do perfil com oprofile
mapeamento (ou usando as--profile
opções ou-p
ao executar o pacote validar, implantar, executar e destruir comandos 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ávelDATABRICKS_AZURE_RESOURCE_ID
de ambiente local . Ou você pode criar um perfil de configuração com oazure_workspace_resource_id
valor e, em seguida, especificar o nome do perfil com oprofile
mapeamento (ou usando as--profile
opções ou-p
ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte 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
eazure_client_id
são usados. Como alternativa, você pode definir esses valores nas variáveisDATABRICKS_AZURE_RESOURCE_ID
de ambiente local ,ARM_TENANT_ID
, eARM_CLIENT_ID
, respectivamente. Ou você pode criar um perfil de configuração com osazure_workspace_resource_id
valores ,azure_tenant_id
e eazure_client_id
, em seguida, especificar o nome do perfil com oprofile
mapeamento (ou usando as--profile
opções ou-p
ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte Autenticação da entidade de serviço do MS Entra.Nota
Não é possível especificar um valor de segredo do cliente do Azure no arquivo de configuração do pacote. Em vez disso, defina a variável
ARM_CLIENT_SECRET
de ambiente local . Ou você pode adicionar oazure_client_secret
valor a um perfil de configuração e, em seguida, especificar o nome do perfil com oprofile
mapeamento (ou usando as--profile
opções ou-p
ao executar o pacote validar, implantar, executar e destruir comandos com a CLI do Databricks).Para autenticação de identidades gerenciadas do Azure, os mapeamentos
azure_use_msi
,azure_client_id
eazure_workspace_resource_id
são usados. Como alternativa, você pode definir esses valores nas variáveisARM_USE_MSI
de ambiente local ,ARM_CLIENT_ID
, eDATABRICKS_AZURE_RESOURCE_ID
, respectivamente. Ou você pode criar um perfil de configuração com osazure_use_msi
valores ,azure_client_id
e eazure_workspace_resource_id
, em seguida, especificar o nome do perfil com oprofile
mapeamento (ou usando as--profile
opções ou-p
ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte Autenticação de identidades gerenciadas do Azure.O
azure_environment
mapeamento 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 predefinido éPUBLIC
. Como alternativa, você pode definir esse valor na variávelARM_ENVIRONMENT
de ambiente local . Ou você pode adicionar oazure_environment
valor a um perfil de configuração e, em seguida, especificar o nome do perfil com oprofile
mapeamento (ou usando as--profile
opções ou-p
ao executar o pacote validar, implantar, executar e destruir comandos com a CLI do Databricks).O
azure_login_app_id
mapeamento não está operacional e está reservado para uso interno.O
auth_type
mapeamento 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. Consulte Autenticação para ferramentas e APIs do Azure Databricks.
Permissões
O mapeamento de nível permissions
superior especifica um ou mais níveis de permissão a serem aplicados a todos os recursos definidos no pacote. Se 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 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 no resources
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 de nível artifacts
superior especifica um ou mais artefatos que são criados automaticamente durante implantações de pacote e podem ser usados posteriormente em execuções de pacote. Cada artefato filho suporta os seguintes mapeamentos:
type
é obrigatório. Para construir um arquivo de roda Python antes da implantação, esse mapeamento deve ser definido comowhl
.path
é um caminho relativo opcional do local do arquivo de configuração do pacote para o local do arquivo de roda do Pythonsetup.py
. Sepath
não estiver incluída, a CLI do Databricks tentará encontrar o arquivo do arquivosetup.py
de roda Python na raiz do pacote.files
é um mapeamento opcional que inclui um mapeamento filhosource
, que você pode usar para especificar locais não padrão a serem incluídos para instruções de compilaçã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 padrão que você deseja executar localmente antes da implantação. Para compilações de roda Python, a CLI do Databricks assume que pode encontrar uma instalação local do pacote Pythonwheel
para executar compilações e executa o comandopython setup.py bdist_wheel
por padrão durante cada implantação de pacote. Para especificar vários comandos build, separe cada comando com caracteres duplos e (&&
).
Para obter mais informações, incluindo um pacote de exemplo que usa artifacts
o , consulte Desenvolver um arquivo de roda Python usando Databricks Asset Bundles.
Gorjeta
Você pode definir, combinar e substituir as configurações de artefatos em bundles usando as técnicas descritas em Definir configurações de artefato dinamicamente em Databricks Asset Bundles.
incluem
A include
matriz 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 para especificar todos e include
quaisquer arquivos de configuração a serem incluídos no pacote, além do databricks.yml
próprio arquivo.
Essa include
matriz pode aparecer apenas como um mapeamento de nível superior.
O exemplo a seguir em um arquivo de configuração de pacote inclui os três arquivos de configuração especificados. Esses arquivos estão no mesmo diretório que o arquivo de configuração do pacote:
include:
- "bundle.artifacts.yml"
- "bundle.resources.yml"
- "bundle.targets.yml"
O exemplo a seguir em um arquivo de configuração de pacote inclui todos os arquivos com nomes de arquivo que começam com bundle
e terminam com .yml
. Esses arquivos estão no mesmo diretório que o arquivo de configuração do pacote:
include:
- "bundle*.yml"
Recursos
O resources
mapeamento especifica informações sobre os recursos do Azure Databricks usados pelo pacote.
Esse resources
mapeamento 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 suportados. Cada mapeamento de tipo de recurso inclui uma ou mais declarações de recursos individuais, que devem ter um nome exclusivo. Essas declarações de recurso individuais usam a carga útil de solicitação da operação create do objeto correspondente, expressa em YAML, para definir o recurso. As propriedades suportadas para um recurso são os campos suportados do objeto correspondente.
As cargas úteis de solicitação de operação de criação são documentadas na Referência da API REST do Databricks e o databricks bundle schema
comando gera a saída de todos os esquemas de objeto suportados. Além disso, o databricks bundle validate
comando retorna avisos se propriedades de recursos desconhecidas forem encontradas nos arquivos de configuração do pacote.
A tabela a seguir lista os tipos de recursos suportados para pacotes e links para a documentação sobre suas cargas úteis correspondentes.
Tipo de recurso | Mapeamentos de recursos |
---|---|
emprego | Mapeamentos de trabalho: POST /api/2.1/jobs/create Para obter informações adicionais, consulte Tipos de tarefas de trabalho e substituir novas configurações de cluster de trabalho. |
gasoduto | Mapeamentos de pipeline: POST /api/2.0/pipelines/create |
experimentação | Mapeamentos de experimentos: POST /api/2.0/mlflow/experiments/create |
modelo | Mapeamentos de modelo: POST /api/2.0/mlflow/registered-models/create |
model_serving_endpoint | Modelo servindo mapeamentos de ponto final: POST /api/2.0/serving-endpoints/create |
registered_model (Catálogo Unity) | Mapeamentos de modelo do Unity Catalog: POST /api/2.1/unity-catalog/models/create |
esquema (Catálogo Unity) | Mapeamentos de esquema do Unity Catalog: POST /api/2.1/unity-catalog/schemas/create |
Todos os caminhos para pastas e arquivos referenciados por declarações de recursos são relativos ao local do arquivo de configuração do pacote no qual esses caminhos são especificados.
tarefa
O exemplo a seguir declara um trabalho com a chave de recurso de hello-job
:
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
gasoduto
O exemplo a seguir declara um pipeline com a chave de recurso de hello-pipeline
:
resources:
pipelines:
hello-pipeline:
name: hello-pipeline
clusters:
- label: default
num_workers: 1
development: true
continuous: false
channel: CURRENT
edition: CORE
photon: false
libraries:
- notebook:
path: ./pipeline.py
esquema
O schema
tipo de recurso permite definir esquemas do Unity Catalog para tabelas e outros ativos em seus fluxos de trabalho e pipelines criados como parte de um pacote. Um esquema, diferente de outros tipos de recursos, tem as seguintes limitações:
- O proprietário de um recurso de esquema é sempre o usuário de implantação e não pode ser alterado. Se
run_as
for especificado no pacote, ele será ignorado pelas operações no esquema. - Somente os campos suportados pela API de criação do objeto Schemas correspondente estão disponíveis para o
schema
recurso. Por exemplo, não é suportado,enable_predictive_optimization
pois só está disponível na API de atualização.
O exemplo a seguir declara um pipeline com a chave my-pipeline
de recurso que cria um esquema Unity Catalog com a chave my-schema
como destino:
resources:
pipelines:
my_pipeline:
name: test-pipeline-{{.unique_id}}
libraries:
- notebook:
path: ./nb.sql
development: true
catalog: main
target: ${resources.schemas.my_schema.id}
schemas:
my_schema:
name: test-schema-{{.unique_id}}
catalog_name: main
comment: This schema was created by DABs.
sincronização
O sync
mapeamento especifica uma lista de globs de arquivo ou caminho a serem incluídos em implantações de pacote ou a serem excluídos de implantações de pacote, dependendo das seguintes regras:
- Com base em qualquer lista de globs de arquivo e caminho em um
.gitignore
arquivo na raiz do pacote, oinclude
mapeamento pode conter uma lista de globs de arquivo, globs de caminho ou ambos, relativos à raiz do pacote, para incluir explicitamente. - Com base em qualquer lista de globs de arquivo e caminho em um
.gitignore
arquivo na raiz do pacote, além da lista de globs de arquivo e caminho noinclude
mapeamento, oexclude
mapeamento 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 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 e include
exclude
os padrões de arquivo e caminho seguem a sintaxe padrão padrão .gitignore
. Consulte Formato de padrão gitignore.
Por exemplo, se o seguinte .gitignore
ficheiro contiver as seguintes entradas:
.databricks
my_package/dist
E o arquivo de configuração do pacote contém o seguinte include
mapeamento:
sync:
include:
- my_package/dist/*.whl
Em seguida, todos os arquivos na my_package/dist
pasta com uma extensão de arquivo de *.whl
estão incluídos. Quaisquer outros arquivos na my_package/dist
pasta não estão incluídos.
No entanto, se o arquivo de configuração do pacote também contiver o seguinte exclude
mapeamento:
sync:
include:
- my_package/dist/*.whl
exclude:
- my_package/dist/delete-me.whl
Em seguida, todos os arquivos na my_package/dist
pasta com uma extensão de arquivo de *.whl
, exceto o arquivo chamado delete-me.whl
, são incluídos. Quaisquer outros arquivos na my_package/dist
pasta também não estão incluídos.
O sync
mapeamento também pode ser declarado no targets
mapeamento para um destino específico. Qualquer sync
mapeamento declarado em um destino é mesclado com qualquer declaração de mapeamento de nível sync
superior. Por exemplo, continuando com o exemplo anterior, o mapeamento a seguir include
no nível mescla targets
com o include
mapeamento no mapeamento de nível sync
superior:
targets:
dev:
sync:
include:
- my_package/dist/delete-me.whl
Quando você executa databricks bundle validate --output json
o , a parte relevante do gráfico resultante é a seguinte:
"sync": {
"include": [
"my_package/dist/*.whl",
"my_package/dist/delete-me.whl"
],
"exclude": [
"my_package/dist/delete-me.whl"
]
}
Objetivos
O targets
mapeamento especifica um ou mais contextos nos quais executar fluxos de trabalho do Azure Databricks. Cada destino é uma coleção exclusiva de artefatos, configurações de espaço de trabalho do Azure Databricks e detalhes do trabalho ou pipeline do Azure Databricks.
Este targets
mapeamento é opcional, mas altamente recomendado. Se for especificado, ele pode aparecer apenas como um mapeamento de nível superior. Se o targets
mapeamento não for especificado, as configurações no espaço de trabalho de nível superior, artefatos e mapeamentos de recursos serão sempre usados.
O targets
mapeamento consiste em um ou mais mapeamentos de destino, cada um com um nome programático (ou lógico) exclusivo.
Se um mapeamento de destino não especificar workspace
, artifacts
ou resources
mapeamentos filho, esse destino usará as configurações nos mapeamentos de nível workspace
superior , artifacts
e resources
.
Se um mapeamento de destino especificar um workspace
, artifacts
ou resources
mapeamento, e um , de nível workspace
superior , artifacts
ou resources
mapeamento também existir, todas as configurações conflitantes serão substituídas pelas configurações dentro do destino.
Um destino também pode substituir os valores de quaisquer variáveis de nível superior.
Para especificar que um destino é o padrão, a menos que especificado de outra forma, adicione o default
mapeamento, definido como true
. Por exemplo, esse destino chamado dev
é o destino padrão:
targets:
dev:
default: true
Para especificar que um destino é tratado como um destino de desenvolvimento, adicione o mode
mapeamento, definido como development
. Para especificar que um destino é tratado como destino de produção, adicione o mode
mapeamento, definido como production
. Por exemplo, esse destino nomeado prod
é tratado como um destino de produção:
targets:
prod:
mode: production
A especificação mode
fornece uma coleção de comportamentos padrão correspondentes para fluxos de trabalho de pré-produção e produção. Para obter detalhes, consulte Modos de implantação do Databricks Asset Bundle. Além disso, você pode especificar run_as
para cada destino, conforme descrito em Especificar uma identidade de execução para um fluxo de trabalho Databricks Asset Bundles.
O exemplo a seguir declara dois destinos. O primeiro destino tem um nome programático (ou lógico) de dev
e é o destino padrão. O segundo destino tem um nome programático (ou lógico) de prod
e não é o destino padrão. Este segundo destino usa um perfil de conexão do Azure Databricks nomeado PROD
para autenticação:
targets:
dev:
default: true
prod:
workspace:
host: https://<production-workspace-url>
Para validar, implantar e executar trabalhos ou pipelines no dev
destino, execute os seguintes comandos:
# 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 <job-or-pipeline-programmatic-name>
# 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 <job-or-pipeline-programmatic-name>
Para validar, implantar e executar esse trabalho no prod
destino, execute os seguintes comandos:
# 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 <job-or-pipeline-programmatic-name>
Variáveis personalizadas
Você pode usar variáveis personalizadas para tornar seus arquivos de configuração de pacote mais modulares e reutilizáveis. Por exemplo, você pode declarar uma variável que representa a ID de um cluster existente e, em seguida, desejar alterar o valor dessa variável para IDs de cluster diferentes para vários fluxos de trabalho executados em vários destinos sem alterar o código original dos arquivos de configuração do pacote.
As variáveis personalizadas são declaradas em seus arquivos de configuração de pacote dentro do variables
mapeamento. Para cada variável, defina uma descrição opcional, valor padrão, tipo ou pesquisa para recuperar um valor de ID, usando o seguinte formato:
variables:
<variable-name>:
description: <optional-description>
default: <optional-default-value>
type: <optional-type-value>
lookup:
<optional-object-type>: <optional-object-name>
Nota
As variáveis são assumidas como sendo do tipo string
, a menos que type
seja definido como complex
. Consulte Definir uma variável complexa.
Por exemplo, para declarar uma variável nomeada my_cluster_id
com o valor padrão de 1234-567890-abcde123
, e uma variável nomeada my_notebook_path
com o valor padrão de ./hello.py
:
variables:
my_cluster_id:
description: The ID of an existing cluster.
default: 1234-567890-abcde123
my_notebook_path:
description: The path to an existing notebook.
default: ./hello.py
Se você não fornecer um default
valor para uma variável como parte dessa declaração, deverá defini-lo ao executar comandos bundle, por meio de uma variável de ambiente ou em qualquer outro lugar dentro de seus arquivos de configuração de pacote, conforme descrito em Definir o valor de uma variável.
Nota
Seja qual for a abordagem escolhida para fornecer valores variáveis, use a mesma abordagem durante os estágios de implantação e execução. Caso contrário, você pode obter resultados inesperados entre o momento de uma implantação e uma execução de trabalho ou pipeline baseada nessa implantação existente.
Para fazer referência às variáveis personalizadas nos arquivos de configuração do pacote, use substituições. Para variáveis, use o formato ${var.<variable_name>}
. Por exemplo, para referenciar variáveis nomeadas my_cluster_id
e my_notebook_path
:
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: ${var.my_cluster_id}
notebook_task:
notebook_path: ${var.my_notebook_path}
Definir o valor de uma variável
Se você não tiver fornecido um default
valor para uma variável ou se quiser substituir temporariamente o default
valor de uma variável, forneça o novo valor temporário da variável usando uma das seguintes abordagens:
Forneça o valor da variável como parte de um
bundle
comando comovalidate
,deploy
ourun
. Para fazer isso, use a opção--var="<key>=<value>"
, onde<key>
é o nome da variável e<value>
é o valor da variável. Por exemplo, como parte dobundle validate
comando, para fornecer o valor de1234-567890-abcde123
para a variável nomeadamy_cluster_id
, e para fornecer o valor de./hello.py
para a variável chamadamy_notebook_path
, execute:databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py" # Or: databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
Forneça o valor da variável definindo uma variável de ambiente. O nome da variável de ambiente deve começar com
BUNDLE_VAR_
. Para definir variáveis de ambiente, consulte a documentação do seu sistema operacional. Por exemplo, para fornecer o valor de para a variável nomeadamy_cluster_id
, e para fornecer o valor de para a variável nomeadamy_notebook_path
, execute o seguinte comando antes de./hello.py
1234-567890-abcde123
chamar umbundle
comando comovalidate
,deploy
, ourun
:Para Linux e macOS:
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
Para Windows:
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
Ou, forneça o valor da variável como parte de um
bundle
comando comovalidate
,deploy
ourun
, por exemplo, para Linux e macOS:BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
Ou para Windows:
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
Forneça o valor da variável em seus arquivos de configuração de pacote. Para fazer isso, use um
variables
mapeamento dentro dotargets
mapeamento, seguindo este formato:variables: <variable-name>: <value>
Por exemplo, para fornecer valores para as variáveis nomeadas
my_cluster_id
emy_notebook_path
para dois destinos separados:targets: dev: variables: my_cluster_id: 1234-567890-abcde123 my_notebook_path: ./hello.py prod: variables: my_cluster_id: 2345-678901-bcdef234 my_notebook_path: ./hello.py
Nos exemplos anteriores, a CLI do Databricks procura valores para as variáveis my_cluster_id
e my_notebook_path
na seguinte ordem, parando quando encontra um valor para cada variável correspondente, ignorando quaisquer outros locais para essa variável:
- Dentro de quaisquer
--var
opções especificadas como parte dobundle
comando. - Dentro de qualquer conjunto de variáveis de ambiente que comece com
BUNDLE_VAR_
. - Dentro de quaisquer
variables
mapeamentos, entre os mapeamentos dentro detargets
seus arquivos de configuração de pacote. - Qualquer
default
valor para a definição dessa variável, entre os mapeamentos de nívelvariables
superior dentro dos arquivos de configuração do pacote.
Definir uma variável complexa
Para definir uma variável personalizada com um tipo complexo para seu pacote, defina type
como complex
em sua configuração de pacote.
Nota
O único valor válido para a type
configuração é complex
. Além disso, a validação do pacote falhará se type
estiver definida como complex
e o default
definido para a variável for um único valor.
No exemplo a seguir, as configurações de cluster são definidas dentro de uma variável complexa personalizada chamada my_cluster
:
variables:
my_cluster:
description: "My cluster definition"
type: complex
default:
spark_version: "13.2.x-scala2.11"
node_type_id: "Standard_DS3_v2"
num_workers: 2
spark_conf:
spark.speculation: true
spark.databricks.delta.retentionDurationCheck.enabled: false
resources:
jobs:
my_job:
job_clusters:
- job_cluster_key: my_cluster_key
new_cluster: ${var.my_cluster}
tasks:
- task_key: hello_task
job_cluster_key: my_cluster_key
Recuperar o valor de ID de um objeto
Para os alert
tipos de objeto , cluster_policy
, cluster
, dashboard
, instance_pool
job
, query
metastore
service_principal
pipeline
e , e , você warehouse
pode definir um lookup
para sua variável personalizada para recuperar a ID
variables:
<variable-name>:
lookup:
<object-type>: "<object-name>"
Se uma pesquisa for definida para uma variável, a ID do objeto com o nome especificado será usada como o valor da variável. Isso garante que a ID resolvida correta do objeto seja sempre usada para a variável.
Nota
Um erro ocorre se um objeto com o nome especificado não existir ou se houver mais de um objeto com o nome especificado.
Por exemplo, na configuração a seguir, ${var.my_cluster_id}
será substituído pela ID do cluster compartilhado 12.2.
variables:
my_cluster_id:
description: An existing cluster
lookup:
cluster: "12.2 shared"
resources:
jobs:
my_job:
name: "My Job"
tasks:
- task_key: TestTask
existing_cluster_id: ${var.my_cluster_id}
Substituições
Você pode usar substituições para tornar seus arquivos de configuração de pacote mais modulares e reutilizáveis.
Gorjeta
Você também pode usar referências de valor dinâmico para valores de parâmetros de trabalho para passar o contexto sobre uma execução de trabalho para tarefas de trabalho. Consulte Passar contexto sobre tarefas de trabalho em tarefas de trabalho.
Por exemplo, quando você executa o bundle validate --output json
comando, você pode ver um gráfico como este (as reticências indicam conteúdo omitido, para brevidade):
{
"bundle": {
"name": "hello-bundle",
"target": "dev",
"...": "..."
},
"workspace": {
"...": "...",
"current_user": {
"...": "...",
"userName": "someone@example.com",
"...": "...",
},
"...": "..."
},
"...": {
"...": "..."
}
}
No exemplo anterior, você pode fazer referência ao valor someone@example.com
em seu arquivo de configuração de pacote com a substituição ${workspace.current_user.userName}
.
Do mesmo modo, as seguintes substituições:
/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
Em um arquivo de configuração de pacote como o seguinte (as reticências indicam conteúdo omitido, para brevidade):
bundle:
name: hello-bundle
workspace:
root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
# ...
targets:
dev:
default: true
Resolveria para o seguinte gráfico quando você executar o bundle validate --output json
comando (as reticências indicam conteúdo omitido, para brevidade):
{
"bundle": {
"name": "hello-bundle",
"target": "dev",
"...": "..."
},
"workspace": {
"profile": "DEFAULT",
"current_user": {
"...": "...",
"userName": "someone@example.com",
"...": "...",
},
"root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
"...": "..."
},
"...": {
"...": "..."
}
}
Você também pode criar substituições para recursos nomeados. Por exemplo, para o pipeline configurado com o nome my_pipeline
, ${resources.pipelines.my_pipeline.target}
é a substituição para o valor do destino de my_pipeline
.
Para determinar substituições válidas, você pode usar a hierarquia de esquema documentada na referência da API REST ou a saída do bundle schema
comando.
Aqui estão algumas substituições comumente usadas:
${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}