Compartilhar via

Configurações do Pacote de Ativos do Databricks

  • Artigo

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

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

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

Para criar e trabalhar com arquivos de configuração de pacote, confira 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, confira 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
  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:
  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>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    cluster_id: string
    default: true | false
    mode: development
    presets:
      <preset>: <value>
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

Exemplos

Observação

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

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

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

Essa técnica permite que você reutilize, bem como substitua, as configurações e as definições de trabalho dentro do bloco resources:

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

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

bundle:
  name: hello-bundle

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

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

bundle:
  name: hello-bundle

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

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

Para validar, implantar e executar esse trabalho no destino dev:

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

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

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

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

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

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

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

bundle.targets.yml:

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

Mapeamentos

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

bundle

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

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

bundle:
  name: hello-bundle

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

cluster_id

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

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

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 associados ao pacote. Isso é útil para anotar os recursos implantados. Por exemplo, o ideal é incluir a URL de origem do repositório na descrição de um modelo de machine learning implantado.

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

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

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

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

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

databricks_cli_version

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

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

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

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

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

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

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.

espaço 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.

root_path

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

workspace:
  root_path: /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 /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, que usa substituições.

artifact_path

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

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

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

Observação

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

file_path

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

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

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

state_path

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

Outros mapeamentos de workspace

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

Importante

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

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

    Observação

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

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

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

    Observação

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

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

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

    Observação

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

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

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

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

  • O mapeamento auth_type especifica o tipo de autenticação do Azure Databricks a ser usado, especialmente nos casos em que a CLI do Databricks infere um tipo de autenticação inesperado. Consulte Autenticar o acesso a 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

artifacts

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

  • type é obrigatório. Para criar um arquivo wheel do Python antes da implantação, esse mapeamento deve ser definido como whl.
  • path é um caminho opcional e relativo do local do arquivo de configuração do pacote para o local do arquivo wheel setup.py do Python. Se path não estiver incluído, a CLI do Databricks tentará localizar o arquivo wheel setup.py do Python na raiz do pacote.
  • files é um mapeamento opcional que inclui um mapeamento filho source, que você pode usar para especificar locais não padrão a serem incluídos para instruções de build 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 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 compilação, separe cada comando com caracteres de dois caracteres e (&&).

Para obter mais informações, incluindo um pacote de amostras que usa artifacts, confira Desenvolver um arquivo wheel do Python usando os Pacotes 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 as configurações de artefato dinamicamente nos 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"

O exemplo de configuração a seguir inclui todos os arquivos com nomes 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"

recursos

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

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

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

A tabela a seguir lista os tipos de recursos com suporte para pacotes e links para documentação em seus conteúdos correspondentes.

Tipo de recurso Mapeamentos de recursos
clusters Mapeamentos de clusters: POST /api/2.1/jobs/create
job Mapeamentos de trabalho: POST /api/2.1/jobs/create

Para obter informações adicionais, confira tipos de tarefa de trabalho e substituir configurações de novo cluster de trabalho.
pipeline Mapeamentos de pipeline: POST /api/2.0/pipelines/create
experimento 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 Mapeamentos de ponto de extremidade do serviço de modelos: POST /api/2.0/serving-endpoints/create
registered_model (Catálogo do Unity) Mapeamentos de modelo do Catálogo do Unity: POST /api/2.1/unity-catalog/models/create
esquema (Catálogo do Unity) Mapeamentos de esquema do Catálogo do Unity: POST /api/2.1/unity-catalog/schemas/create

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

clusters

O recurso clusters permite que você crie clusters para todas as finalidades. 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"

trabalho

O exemplo a seguir declara um trabalho com a chave de recurso do 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 do 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 você defina esquemas do Catálogo do Unity para tabelas e outros ativos em seus fluxos de trabalho e pipelines criados como parte de um pacote. Um esquema, diferentemente de outros tipos de recursos, tem as seguintes limitações:

  • O proprietário de um recurso de esquema é sempre o usuário da implantação e não pode ser alterado. Se estiver especificado no pacote, run_as será ignorado pelas operações no esquema.
  • Somente os campos compatíveis com a API de criação do objeto de esquemas correspondente estão disponíveis para o recurso schema. Por exemplo, enable_predictive_optimization não tem suporte, já que está disponível somente na API de atualização.

O exemplo a seguir declara um pipeline com a chave de recurso my_pipeline, que cria um esquema do Catálogo do Unity tendo 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.

O mapeamento de concessões de nível superior não é compatível com os Pacotes de Ativos do Databricks. Portanto, para definir concessões para um esquema, defina as concessões para o esquema dentro do 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"

sync

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

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 de implantações de pacotes, 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 arquivos e pastas especificados são relativos ao local do arquivo de configuração do pacote no qual eles são especificados.

A sintaxe dos padrões de arquivosinclude e exclude e caminho 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 espaço de trabalho. 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 é particularmente útil quando você tem um único repositório que hospeda vários pacotes e deseja compartilhar bibliotecas, arquivos de código ou configuração.

Os caminhos especificados devem 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 espaço de trabalho:

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

targets

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

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

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

As configurações no espaço de trabalho de nível superior, artefatos e mapeamentos de recursos 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 conjunto de mapeamento mode a development. Para especificar que um destino é tratado como um destino de produção, adicione o conjunto de mapeamentos mode a 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.