Configurações do Pacote de Ativos do Databricks

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

Para criar e trabalhar com pacotes, consulte Desenvolver Pacotes de Ativos do Databricks.

databricks.yml

Um pacote deve conter um (e apenas um) arquivo de configuração nomeado databricks.yml na raiz da pasta do projeto do pacote. databricks.yml é o arquivo de configuração principal que define um pacote, mas pode referenciar outros arquivos de configuração, como arquivos de configuração de recursos, no include mapeamento. A configuração do pacote é expressa no YAML. Para obter mais informações sobre YAML, consulte a especificação oficial do YAML.

O databricks.yml mais simples define o nome do pacote, que está dentro do pacote de mapeamento de nível superior necessário e uma implantação de destino.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Para obter detalhes sobre todos os mapeamentos de nível superior, consulte Mapeamentos.

Dica

O suporte do Python para Pacotes de Ativos do Databricks permite que você defina recursos no Python. Consulte a configuração do pacote em Python.

Especificação

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

# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_id: string
  deployment: Map
  git:
    origin_url: string
    branch: string

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

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

# 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 default artifact settings if not otherwise overridden in
# the targets top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    dynamic_version: boolean
    executable: string
    files:
      - source: string
    path: string
    type: string

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

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

# These are the permissions to apply to resources 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 resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# 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.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    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

Esta seção contém alguns exemplos básicos para ajudá-lo a entender como os pacotes funcionam e como estruturar a configuração.

Observação

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

A configuração do pacote de exemplo a seguir especifica um arquivo local chamado hello.py que está no mesmo diretório que o arquivo databricks.ymlde configuração do pacote. Ele executa esse notebook 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 do perfil de configuração local do chamador nomeado DEFAULT.

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

O exemplo a seguir adiciona um destino com o nome prod, que utiliza uma URL de espaço de trabalho remoto diferente e credenciais de autenticação de espaço de trabalho. Estas credenciais são obtidas a partir da entrada correspondente .databrickscfg no arquivo host do chamador, que está associada à URL de espaço de trabalho especificada. Esse trabalho executa o mesmo notebook, mas usa outro cluster remoto com a ID de cluster especificada.

Observação

O Databricks recomenda que você use o mapeamento host em vez do mapeamento default sempre que possível, pois isso torna os arquivos de configuração do pacote mais portáteis. Definir o 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 houver vários perfis com um campo correspondente host , você deverá usar a opção --profile em comandos de pacote para especificar um perfil a ser usado.

Observe que você não precisa declarar o mapeamento notebook_task dentro do mapeamento prod, pois ele volta a usar o mapeamento notebook_task no mapeamento resources de nível superior, caso o mapeamento notebook_task não seja substituído explicitamente no mapeamento prod.

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Use os comandos de pacote a seguir para validar, implantar e executar esse trabalho dentro do dev destino. Para obter detalhes sobre o ciclo de vida de um pacote, consulte Desenvolver Pacotes de Ativos do Databricks.

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

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

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

Para obter mais modularização e melhor reutilização de definições e configurações entre pacotes, divida a configuração do pacote em arquivos separados:

# databricks.yml

bundle:
  name: hello-bundle

include:
  - '*.yml'

# hello-job.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

# 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 os mapeamentos de nível superior da configuração do pacote. Para obter referência de configuração, consulte a referência de configuração .

• pacote
• run_as
• incluir
• sincronizar
• artefatos
• variáveis
• área de trabalho
• permissões
• recursos
• targets

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 workspace do Azure Databricks.

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

bundle:
  name: hello-bundle

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

cluster_id

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

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

compute_id

Observação

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

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

Git

Você pode recuperar e substituir os detalhes do controle de versão do Git associados ao pacote, o que é útil para propagar metadados de implantação que podem ser usados posteriormente para identificar recursos. Por exemplo, você pode rastrear a origem do repositório de um trabalho implantado por CI/CD.

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

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

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

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

databricks_cli_version

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

A versão da CLI do Databricks está em conformidade com o controle de versão semântico e o mapeamento databricks_cli_version dá suporte à especificação de restrições de versão. Se o valor 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 alguma sintaxe de restrição de versão comum:

bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.0' # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.*' # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: '>= 0.218.0' # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: '>= 0.218.0, <= 1.0.0' # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

run_as

A run_as configuração especifica o user_name ou service_principal_name a ser usado para executar o pacote. Ele fornece a capacidade de separar a identidade usada para desenvolver um trabalho de pacote ou pipeline da que é usada para executar o trabalho ou pipeline.

Consulte Especificar uma identidade de execução para um fluxo de trabalho do Pacotes de Ativos do Databricks.

include

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

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

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

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

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

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

include:
  - 'bundle*.yml'

sincronizar

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

incluir e excluir

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

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

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

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

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

.databricks
my_package/dist

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

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

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

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

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

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

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

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

Caminhos

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

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

sync:
  paths:
    - ../common
    - .

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

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

artefatos

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

• type é necessário para builds de roda do Python. Para criar um arquivo de roda do Python antes de implantar, defina-o como whl. Para criar outros artefatos, essa configuração não precisa ser especificada.
• path é um caminho opcional. Os caminhos são relativos ao local do arquivo de configuração do pacote. Para builds de roda do Python, é o caminho para o arquivo de roda do Python setup.py. Se path não estiver incluído, a CLI do Databricks tentará localizar o arquivo setup.py do arquivo de roda do Python na raiz do pacote.
• files é um mapeamento opcional que inclui um mapeamento filho source, o qual você pode usar para especificar os artefatos comilados. Os caminhos são relativos ao local do arquivo de configuração do pacote.
• build é um conjunto opcional de comandos de build não padrão que você deseja executar localmente antes da implantação. Para builds de wheels do Python, a CLI do Databricks pressupõe que possa encontrar uma instalação local do pacote wheel do Python para executar os builds e executa o comando python setup.py bdist_wheel por padrão durante cada implantação de pacote. Para especificar vários comandos de build, separe cada comando com caracteres de E comercial duplo (&&).
• dynamic_version permite que os pacotes atualizem a versão do wheel com base no carimbo de data/hora do arquivo wheel. Em seguida, o novo código pode ser implantado sem precisar atualizar a versão em setup.py ou pyproject.toml. Essa configuração só é válida quando type está definido como whl.

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

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

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

Dica

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

Variáveis

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

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

Observação

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

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

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

área de trabalho

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

Importante

Os caminhos de workspace válidos do Databricks iniciam com /Workspace ou, quanto aos artefatos, /Volumes também tem suporte. Os caminhos de espaço de trabalho personalizados são prefixados automaticamente com /Workspace, portanto, se você usar qualquer substituição de caminho de espaço de trabalho em seu caminho personalizado, como ${workspace.file_path}, não será necessário anexar /Workspace ao caminho.

caminho raiz

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

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

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

artifact_path

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

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

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

Observação

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

caminho_do_arquivo

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

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

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

state_path

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

Outros mapeamentos de workspace

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

Importante

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

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

  Observação

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

• O mapeamento host especifica a URL do seu workspace do Azure Databricks. Confira URL por espaço de trabalho.

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

  Observação

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

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

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

  Observação

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

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

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

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

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

Permissões

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

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

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

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

Recursos

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

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

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

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

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

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

destinos

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

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

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

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

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

padrão

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

targets:
  dev:
    default: true

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

Os seguintes comandos validam, implantam e executam my_job nos destinos dev e prod:

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

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

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

modo e predefinições

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

Dica

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

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

targets:
  prod:
    mode: production

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

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

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