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?
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 saber mais sobre o YAML, consulte a especificação oficial e o tutorial do YAML.
Para criar e trabalhar com arquivos de configuração de pacotes, consulte Desenvolvimento de pacotes de ativos do Databricks.
Visão geral
Esta seção fornece uma representação visual do esquema do arquivo de configuração do pacote. Para obter detalhes, consulte Mapeamentos.
# 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:
dashboards:
<some-unique-programmatic-identifier-for-this-dashboard>:
# See the REST API create request payload reference for dashboards.
experiments:
<some-unique-programmatic-identifier-for-this-experiment>:
# See the REST API create request payload reference for experiments.
jobs:
<some-unique-programmatic-identifier-for-this-job>:
# See REST API create request payload reference for jobs.
models:
<some-unique-programmatic-identifier-for-this-model>:
# See the REST API create request payload reference for models.
pipelines:
<some-unique-programmatic-identifier-for-this-pipeline>:
# See the REST API create request payload reference for Delta Live Tables (pipelines).
schemas:
<some-unique-programmatic-identifier-for-this-schema>:
# See the Unity Catalog schema request payload reference.
# These are any additional files or paths to include or exclude.
sync:
include:
- "<some-file-or-path-glob-to-include>"
- "<another-file-or-path-glob-to-include>"
exclude:
- "<some-file-or-path-glob-to-exclude>"
- "<another-file-or-path-glob-to-exclude>"
paths:
- "<some-file-or-path-to-synchronize>"
# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
<some-unique-programmatic-identifier-for-this-target>:
artifacts:
# See the preceding "artifacts" syntax.
bundle:
# See the preceding "bundle" syntax.
cluster_id: string
default: true | false
mode: development
presets:
<preset>: <value>
resources:
# See the preceding "resources" syntax.
sync:
# See the preceding "sync" syntax.
variables:
<preceding-unique-variable-name>: <non-default-value>
workspace:
# See the preceding "workspace" syntax.
run_as:
# See the preceding "run_as" syntax.
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 comandogit 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 comandogit 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}
.bundle.git.commit
, que representa o commitHEAD
dentro do repo. Esse é o mesmo valor que você obteria se executasse o comandogit rev-parse HEAD
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.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 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 mapeamentoprofile
, pois isso torna os arquivos de configuração do pacote mais portáteis. Definir o mapeamentohost
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 campohost
correspondente em seu arquivo.databrickscfg
, você deverá usar o mapeamentoprofile
(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 destinoprod
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 localDATABRICKS_CLIENT_ID
. Ou o senhor pode criar um perfil de configuração com o valorclient_id
e, em seguida, especificar o nome do perfil com o mapeamentoprofile
(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 valorclient_secret
a um perfil de configuração e, em seguida, especificar o nome do perfil com o mapeamentoprofile
(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 localDATABRICKS_GOOGLE_SERVICE_ACCOUNT
. Ou você pode criar um perfil de configuração com o valorgoogle_service_account
e, em seguida, especificar o nome do perfil com o mapeamentoprofile
(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 comowhl
.path
é um caminho relativo opcional do local do arquivo de configuração do pacote para o local do arquivosetup.py
do arquivo Python wheel. Sepath
não estiver incluído, a CLI do Databricks tentará localizar o arquivosetup.py
do arquivo Python wheel na raiz do pacote.files
é um mapeamento opcional que inclui um mapeamento secundário desource
, 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 Pythonwheel
para executar compilações, e executa o comandopython 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 (&&
).
Para obter mais informações, incluindo um pacote de amostra que usa artifacts
, consulte Desenvolva um arquivo Python wheel usando o Pacote de Ativos do Databricks.
Dica
Você pode definir, combinar e substituir as configurações de artefatos em pacotes usando as técnicas descritas em Definir configurações de artefatos dinamicamente nos Pacote de Ativos do Databricks.
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 inclui zero ou um dos tipos de recursos compatíveis. 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 recursos individuais usam o pauload de solicitação de operação de criação do objeto correspondente, expressa em YAML, para definir o recurso. As propriedades compatíveis com um recurso são os campos compatíveis com o 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.
A tabela a seguir lista os tipos de recursos compatíveis com pacotes e links para documentação sobre seus payloads correspondentes.
Tipo de recurso |
Mapeamentos de recursos |
---|---|
Mapeamentos de cluster: POST /api/2.1/clusters/create |
|
experimento |
Mapeamentos de experimentos: POST /api/2.0/mlflow/experiments/create |
Mapeamentos de jobs: POST /api/2.1/jobs/create Para obter informações adicionais, consulte os tipos de tarefas do job e substitua as novas configurações do cluster de job. |
|
pipeline mapeamentos: POST /api/2.0/pipelines |
|
modelo |
Mapeamentos de modelos: POST /api/2.0/mlflow/registered-models/create |
model_serving_endpoint |
servindo o modelo endpoint mappings: POST /api/2.0/serving-endpoint |
registered_model (Unity Catalog) |
Mapeamentos de modelos do Unity Catalog: POST /api/2.1/unity-catalog/models |
esquema (Unity Catalog) |
Mapeamentos de esquema do Unity Catalog: POST /api/2.1/unity-catalog/schemas |
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.
agrupamento
O recurso cluster permite que o senhor crie o clusters todo-propósito. O exemplo a seguir cria um cluster chamado my_cluster
e o define como o cluster a ser usado para executar o Notebook em my_job
:
bundle:
name: clusters
resources:
clusters:
my_cluster:
num_workers: 2
node_type_id: "i3.xlarge"
autoscale:
min_workers: 2
max_workers: 7
spark_version: "13.3.x-scala2.12"
spark_conf:
"spark.executor.memory": "2g"
jobs:
my_job:
tasks:
- task_key: test_task
existing_cluster_id: ${resources.clusters.my_cluster.id}
notebook_task:
notebook_path: "./src/my_notebook.py"
painel
O recurso de dashboard permite que o senhor gerencie AI/BI dashboards em um pacote. Para obter informações sobre AI/BI dashboards, consulte Dashboards.
O exemplo a seguir inclui e implanta a amostra do painel de análise de viagens de táxi de Nova York no site Databricks workspace.
resources:
dashboards:
nyc_taxi_trip_analysis:
display_name: "NYC Taxi Trip Analysis"
file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
warehouse_id: ${var.warehouse_id}
Se o senhor usar a interface do usuário para modificar o painel, as modificações feitas por meio da interface do usuário não serão aplicadas ao arquivo JSON do painel no pacote local, a menos que o atualize explicitamente usando bundle generate
. Você pode usar a opção --watch
para pesquisar e recuperar continuamente as alterações no painel. Consulte Gerar um arquivo de configuração de pacote.
Além disso, se o senhor tentar implantar um pacote que contenha um arquivo JSON de dashboard diferente do arquivo workspace remoto, ocorrerá um erro. Para forçar a implantação e substituir o painel no site remoto workspace pelo local, use a opção --force
. Veja implantado a bundle.
job
O exemplo a seguir declara um job com a chave de recurso 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
pipeline
O exemplo a seguir declara um pipeline com a chave de recurso 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 tipo de recurso schema permite que o senhor defina Unity Catalog esquemas para tabelas e outros ativos em seu fluxo de trabalho e pipeline criados como parte de um pacote. Um esquema, diferente de outros tipos de recurso, 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 compatíveis com a API de criação do objeto dos esquemas correspondente estão disponíveis para o recurso
schema
. Por exemplo,enable_predictive_optimization
não é compatível, pois só está disponível na API de atualização.
O exemplo a seguir declara um pipeline com a chave de recurso my_pipeline
que cria um esquema do 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.
Um mapeamento de concessões de nível superior não é suportado pelo Databricks ativo Bundles, portanto, se o senhor quiser definir concessões para um esquema, defina as concessões para o esquema no mapeamento schemas
:
schemas:
my_schema:
name: test-schema
grants:
- principal: users
privileges:
- CAN_MANAGE
- principal: my_team
privileges:
- CAN_READ
catalog_name: main
comment: "my schema with grants"
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 deinclude
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 mapeamentoinclude
, o mapeamentoexclude
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.