Pular para o conteúdo principal

Databricks Configuração do pacote ativo

Este artigo descreve a sintaxe dos arquivos de configuração do Databricks ativo Bundle, que definem os Databricks ativos Bundles. Veja o que são Databricks ativo Bundles?

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

databricks.yml​

Um pacote deve conter um (e somente um) arquivo de configuração chamado databricks.yml na raiz da pasta do projeto do pacote. databricks.yml é o principal arquivo de configuração que define um pacote, mas pode fazer referência a outros arquivos de configuração, como arquivos de configuração de recurso, no mapeamento include. A configuração do pacote é expressa em YAML. Para obter mais informações sobre o 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.

YAML
bundle:
  name: my_bundle

targets:
  dev:
    default: true

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

dica

Python O suporte para Databricks ativo Bundles permite que o senhor defina o recurso em Python. Consulte Configuração do pacote em Python.

Especificação​

A especificação YAML a seguir fornece a chave de configuração de nível superior para Databricks ativo Bundles. Para referência de configuração, consulte Referência de configuração.

YAML
# 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 ajudar você a entender como os pacotes funcionam e como estruturar a configuração.

nota

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

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

YAML
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 alvo com o nome prod que usa um URL workspace remoto diferente e credenciais de autenticação workspace, que são lidas da entrada correspondente host do arquivo .databrickscfg do chamador com o URL workspace especificado. Esse trabalho executa o mesmo Notebook, mas usa um clustering remoto diferente com o ID de clustering especificado.

nota

A Databricks recomenda que o senhor 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. A configuração do mapeamento host instrui a CLI do Databricks a encontrar um perfil correspondente no arquivo .databrickscfg e, em seguida, usar os campos desse perfil para determinar qual tipo de autenticação do Databricks deve ser usado. Se houver vários perfis com um campo host correspondente, o senhor deverá usar a opção --profile no bundle comando para especificar um perfil a ser usado.

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

YAML
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 o comando do pacote a seguir para validar, implantar e executar esse trabalho no destino dev. Para obter detalhes sobre o ciclo de vida de um pacote, consulte Develop Databricks ativo Bundles.

Bash
# 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:

Bash
# 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:

YAML
# databricks.yml

bundle:
  name: hello-bundle

include:
  - '*.yml'
YAML
# 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
YAML
# 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 referência de configuração, consulte Referência de configuração.

pacote​

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

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.

YAML
bundle:
  name: hello-bundle

Um mapeamento bundle também pode ser filho de um ou mais alvos no mapeamento de alvos de nível superior. Cada um desses mapeamentos bundle filho especifica quaisquer substituições nãodefault 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.

agrupamento​

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

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.

computar​

nota

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 clustering a ser usado como uma substituição para o clustering definido em outra parte do arquivo de configuração do pacote.

presente​

É possível recuperar e substituir os detalhes do controle de versão Git associados ao seu pacote, o que é útil para propagar metadados de implantação que podem ser usados posteriormente para identificar o recurso. Por exemplo, o senhor pode rastrear a origem do repositório de um Job implantado pelo site CI/CD.

Sempre que o senhor 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 default:

  • bundle.git.origin_url, que representa o URL de origem do repositório. Esse é o mesmo valor que o senhor obteria se executasse o comando git config --get remote.origin.url a partir do seu repositório clonado. Você pode usar substituições para se referir a esse valor com seus arquivos de configuração do pacote, como ${bundle.git.origin_url}.
  • bundle.git.branch, que representa a filial atual dentro do repositório. Esse é o mesmo valor que o senhor obteria se executasse o comando git branch --show-current a partir do seu repositório clonado. Você pode usar substituições para se referir a esse valor com seus arquivos de configuração do pacote, como ${bundle.git.branch}.

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

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

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

CLI​

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 databricks_cli_version suporta a especificação de restrições de versão. Se o valor databricks --version atual não estiver dentro dos limites especificados no mapeamento databricks_cli_version do pacote, ocorrerá um erro quando databricks bundle validate for executado no pacote. Os exemplos a seguir demonstram uma sintaxe comum de restrição de versão:

YAML
bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.0' # require Databricks CLI 0.218.0
YAML
bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.*' # allow all patch versions of Databricks CLI 0.218
YAML
bundle:
  name: my-bundle
  databricks_cli_version: '>= 0.218.0' # allow any version of Databricks CLI 0.218.0 or higher
YAML
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 configuração run_as especifica o user_name ou service_principal_name a ser usado para executar o pacote. Ele oferece a capacidade de separar a identidade usada para implantar um pacote de trabalho ou pipeline daquela usada para executar o trabalho ou pipeline.

Consulte Especificar uma identidade de execução para um Databricks ativo Bundles fluxo de trabalho.

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:

YAML
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:

YAML
include:
  - 'bundle*.yml'

sincronizar​

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 globos de arquivos e caminhos em um arquivo .gitignore na raiz do pacote, o mapeamento include pode conter uma lista de globos de arquivos, globos de caminho ou ambos, em relação à raiz do pacote, para incluir explicitamente.
  • Com base em qualquer lista de globos de arquivos e caminhos em um arquivo .gitignore na raiz do pacote, além da lista de globos de arquivos e caminhos no mapeamento include, o mapeamento exclude pode conter uma lista de globos de arquivos, globos 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:

YAML
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:

YAML
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:

YAML
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 sincroniza a pasta common localizada um nível acima da raiz do pacote e a própria raiz do pacote:

YAML
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/
    ...

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 é necessário para Python wheel builds. Para criar um arquivo Python wheel antes de implantá-lo, 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 à localização do arquivo de configuração do pacote. Para compilações do Python wheel, é o caminho para o arquivo setup.py do arquivo do Python wheel. Se o path não estiver incluído, o Databricks CLI tentará localizar o arquivo Python wheel do arquivo setup.py na raiz do pacote.
  • files é um mapeamento opcional que inclui um mapeamento secundário source, que você pode usar para especificar os artefatos criados. Os caminhos são relativos à localização do arquivo de configuração do pacote.
  • build é um conjunto opcional de comandos de compilação não default que você deseja executar localmente antes da implantação. Para compilações do Python wheel, a CLI do Databricks assume que pode encontrar uma instalação local do pacote Python wheel para executar compilações, e executa o comando python setup.py bdist_wheel por default durante a implantação de cada pacote. Para especificar vários comandos de compilação, separe cada comando com caracteres de e comercial duplo (&&).
  • dynamic_version permite que os pacotes atualizem a versão da roda com base na data e hora do arquivo da roda. O novo código pode então ser implantado sem a necessidade de atualizar a versão em setup.py ou pyproject.toml. Essa configuração só é válida quando type está definido como whl.

O exemplo de configuração a seguir cria uma roda usando o Poetry. Para obter um pacote de amostra completo que usa artifacts para criar uma roda, consulte Criar um arquivo Python wheel usando Databricks ativo Bundles.

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

Para obter um exemplo de configuração que cria um arquivo JAR e o Unity Catalog carrega para, consulte Bundle that upload a JAR file Unity Catalog to.

dica

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

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:

YAML
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>
nota

Supõe-se que as variáveis sejam do tipo string, a menos que type esteja definido como complex. Consulte 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.

important

Válido Databricks workspace caminhos começam com /Workspace ou, para artefatos, /Volumestambém é aceito. 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.

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 fluxos de trabalho, como por exemplo:

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

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

caminho_do_artefato​

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:

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

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

nota

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

caminho_do_arquivo​

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:

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

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

caminho_do_estado​

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 do site 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 alvos no mapeamento de alvos de nível superior.

important

O senhor deve codificar os valores dos seguintes mapeamentos workspace para a 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 do Databricks.
nota

Databricks recomenda que o senhor use o mapeamento host (ou as opções --profile ou -p ao executar o comando bundle validate, implantado, executado e destroy com o Databricks CLI) em vez do mapeamento profile, pois isso torna os arquivos de configuração do pacote mais portáteis. A configuração do mapeamento host instrui a CLI do Databricks a encontrar um perfil correspondente no arquivo .databrickscfg e, em seguida, usar os campos desse perfil para determinar qual tipo de autenticação do Databricks deve ser usado. Se houver vários perfis com um campo host correspondente no arquivo .databrickscfg, o senhor deverá usar o mapeamento profile (ou as opções de linha de comando --profile ou -p ) para instruir a CLI do Databricks sobre qual perfil usar. Para ver um exemplo, consulte a declaração de destino prod nos exemplos.

nota

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

  • 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 Autorização de acesso a Databricks recurso.

permissões​

O mapeamento de nível superior permissions especifica um ou mais níveis de permissão a serem aplicados a todos os recursos definidos no pacote. Se o senhor 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:

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

recurso​

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

As cargas úteis das solicitações de criação de operações estão documentadas em Databricks REST API Reference, e o comando databricks bundle schema gera todos os esquemas de objetos suportados. Além disso, o comando databricks bundle validate retorna avisos se forem encontradas propriedades de recurso desconhecidas nos arquivos de configuração do pacote.

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

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

Para obter mais informações sobre o recurso suportado nos pacotes, bem como sobre a configuração e os exemplos comuns, consulte Databricks ativo Bundles recurso e Bundle configuration examples.

alvos​

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 alvo também pode substituir os valores de qualquer variável de nível superior.

default​

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:

YAML
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 seguinte comando valida, implanta e executa my_job dentro dos alvos dev e prod:

Bash
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job
Bash
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.

YAML
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:

YAML
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 marca todos os recursos de produção:

YAML
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.

Última atualização em