Comparteix via

Configuración de agrupación de recursos de Databricks

En este artículo se describe la sintaxis de los archivos de configuración de Asset Bundle de Databricks, que definen Conjuntos de recursos de Databricks. Consulte ¿Qué son los conjuntos de recursos de Databricks?

Para crear y trabajar con agrupaciones, consulte Desarrollo de conjuntos de recursos de Databricks.

databricks.yml

Una agrupación debe contener un archivo de configuración (y solo uno) denominado databricks.yml en la raíz de la carpeta del proyecto de agrupación. databricks.yml es el archivo de configuración principal que define un paquete, pero puede hacer referencia a otros archivos de configuración, como los archivos de configuración de recursos, en la asignación include. La configuración de agrupación se expresa en YAML. Para obtener más información sobre YAML, consulte la especificación oficial de YAML.

La databricks.yml más sencilla define el nombre del paquete, que se encuentra dentro de la asignación de nivel superior bundle necesaria y una implementación de destino.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Para detalles sobre todas las asignaciones de nivel superior, consulte Asignaciones.

Sugerencia

La compatibilidad de Python con Conjuntos de recursos de Databricks le permite definir recursos en Python. Consulte Configuración de agrupación en Python.

Especificación

La siguiente especificación de YAML proporciona claves de configuración de nivel superior para Conjuntos de recursos de Databricks. Para obtener referencia de configuración, consulte Referencia de configuración.

# 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 scripts that can be run.
scripts:
  <some-unique-script-name>:
    content: string

# 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 # The only valid value is "complex" if the variable is a complex variable, otherwise do not define this key.

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

Ejemplos

Esta sección contiene algunos ejemplos básicos que le ayudarán a comprender cómo funcionan las agrupaciones y cómo estructurar la configuración.

Nota:

Para ver ejemplos de configuración que muestran las características de agrupación y los casos de uso comunes de agrupación, consulte Ejemplos de configuración de agrupación y el Repositorio de ejemplos de agrupación en GitHub.

La siguiente configuración de agrupación de ejemplo especifica un archivo local denominado hello.py que se encuentra en el mismo directorio que el archivo databricks.ymlde configuración de agrupación . Ejecuta este cuaderno como un trabajo mediante el clúster remoto con el id. de clúster especificado. La dirección URL del área de trabajo remota y las credenciales de autenticación del área de trabajo se leen del perfil de configuración local del llamador denominado 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

En el ejemplo siguiente se agrega un destino con el nombre prod que utiliza una URL de área de trabajo remota diferente y las credenciales de autenticación del área de trabajo, que se leen de la entrada coincidente .databrickscfg del archivo del llamador con la URL especificada del área de trabajo. Este trabajo ejecuta el mismo cuaderno, pero utiliza un clúster remoto diferente con el ID de clúster especificado.

Nota:

Databricks recomienda usar la asignación host en lugar de la asignación default siempre que sea posible, ya que esto hace que los archivos de configuración de agrupación sean más portátiles. Al establecer la asignación de host, se indica a la CLI de Databricks que busque un perfil coincidente en el archivo .databrickscfg y, a continuación, use los campos de ese perfil para determinar qué tipo de autenticación de Databricks se va a usar. Si existen varios perfiles con un campo coincidente host , debe usar la --profile opción en los comandos de agrupación para especificar un perfil que se va a usar.

Tenga en cuenta que no es necesario declarar la asignación notebook_task dentro de la asignación prod, ya que vuelve a usar la asignación notebook_task dentro de la asignación resources de nivel superior, si la asignación notebook_task no se invalida explícitamente dentro de la asignación 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 los siguientes comandos de agrupación para validar, implementar y ejecutar este trabajo dentro del dev destino. Para más información sobre el ciclo de vida de un paquete, consulte Desarrollar conjuntos de recursos 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, implementar y ejecutar este trabajo dentro del destino prod en su lugar:

# 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 una mayor modularización y mejor reutilización de definiciones y configuraciones en conjuntos, divida la configuración del lote en archivos independientes:

# 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

Asignaciones

En las siguientes secciones se describen las asociaciones de nivel superior de la configuración del paquete. Para obtener referencia de configuración, consulte Referencia de configuración.

paquete

Un archivo de configuración de paquete solo debe contener una asignación de nivel superior bundle que asocie el contenido del paquete con la configuración del espacio de trabajo de Azure Databricks.

Esta asignación bundle debe contener una asignación name que especifique un nombre programático (o lógico) para el paquete. En el ejemplo siguiente se declara una agrupación con el nombre programático (o lógico) hello-bundle.

bundle:
  name: hello-bundle

Una asignación bundle también puede ser un elemento secundario de uno o varios de los destinos de la asignación targets de nivel superior. Cada una de estas asignaciones bundle secundarias especifica cualquier invalidación no predeterminada en el nivel de destino. Sin embargo, el valor de bundle de la asignación name de nivel superior no se puede invalidar en el nivel de destino.

identificador_de_clúster

La asignación de bundle puede tener una asignación de cluster_id secundaria. Esta asignación le permite especificar el id. de un clúster que se usará como invalidación para los clústeres definidos en otra parte del archivo de configuración del conjunto. Para obtener información sobre cómo recuperar el identificador de un clúster, consulte Compute resource URL and ID (Dirección URL y identificador de recurso de proceso).

La invalidación cluster_id está pensada para escenarios de solo desarrollo y solo se admite para el destino que tiene su asignación de mode establecida en development. Para obtener más información sobre el mapeo target, ver destinos.

compute_id

Nota:

Esta configuración está en desuso. Use cluster_id en su lugar.

La asignación de bundle puede tener una asignación de compute_id secundaria. Esta asignación le permite especificar el id. de un clúster que se usará como invalidación para los clústeres definidos en otra parte del archivo de configuración del conjunto.

Git

Puede recuperar e invalidar los detalles del control de versiones de Git asociados a la agrupación, lo que resulta útil para propagar los metadatos de implementación que se pueden usar más adelante para identificar los recursos. Por ejemplo, puede realizar un seguimiento del origen del repositorio de un trabajo implementado por CI/CD.

Siempre que ejecute un bundle comando como validate, deploy o run, el bundle comando rellena el árbol de configuración del comando con la siguiente configuración predeterminada:

  • bundle.git.origin_url, que representa la dirección URL de origen del repositorio. Este es el mismo valor que obtendría si ejecutara el comando git config --get remote.origin.url desde el repositorio clonado. Puede usar sustituciones para hacer referencia a este valor con los archivos de configuración de agrupación, como ${bundle.git.origin_url}.
  • bundle.git.branch, que representa la rama actual dentro del repositorio. Este es el mismo valor que obtendría si ejecutara el comando git branch --show-current desde el repositorio clonado. Puede usar sustituciones para hacer referencia a este valor con los archivos de configuración de agrupación, como ${bundle.git.branch}.

Para recuperar o invalidar la configuración de Git, la agrupación debe estar dentro de un directorio asociado a un repositorio de Git, por ejemplo, un directorio local que se inicializa mediante la ejecución del comando git clone. Si el directorio no está asociado a un repositorio de Git, esta configuración de Git está vacía.

Puede invalidar las configuraciones origin_url y branch dentro de la asignación git de la asignación de nivel superior bundle, si es necesario, como se indica a continuación:

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

databricks_cli_version

La asignación de bundle puede contener una asignación de databricks_cli_version que restringe la versión de la CLI de Databricks requerida por el paquete. Esto puede evitar los problemas causados por el uso de asignaciones que no se admiten en una determinada versión de la CLI de Databricks.

La versión de la CLI de Databricks se ajusta al control de versiones semánticas y la asignación de databricks_cli_version admite la especificación de restricciones de versión. Si el valor actual databricks --version no está dentro de los límites especificados en la asignación del databricks_cli_version paquete, se produce un error cuando databricks bundle validate se ejecuta en el paquete. En los ejemplos siguientes se muestran algunas sintaxis comunes de las restricciones de versión:

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

La configuración de run_as especifica el user_name o service_principal_name que se utilizará para ejecutar el paquete. Proporciona la capacidad de separar la identidad utilizada para desplegar un trabajo de paquete o canalización de la que se utiliza para ejecutar el trabajo o la canalización.

Consulte Especificación de una identidad de ejecución para un flujo de trabajo de agrupaciones de recursos de Databricks.

incluir

La matriz de include especifica una lista de los globs de ruta de acceso que contienen archivos de configuración que se van a incluir en la agrupación. Estos globs de ruta de acceso son relativos a la ubicación del archivo de configuración de agrupación en el que se especifican los globs de ruta de acceso.

La CLI de Databricks no incluye de forma predeterminada ningún archivo de configuración dentro de la agrupación. Debe usar la matriz include para especificar todos y cada uno de los archivos de configuración que se van a incluir en la agrupación, excepto el propio archivo databricks.yml.

Esta matriz include solo puede aparecer como un mapeo de nivel superior.

En el ejemplo siguiente de configuración se incluyen tres archivos de configuración. Estos archivos están en la misma carpeta que el archivo de configuración de agrupación:

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

La siguiente configuración de ejemplo incluye todos los archivos con nombres de archivo que comienzan con bundle y terminan con .yml. Estos archivos están en la misma carpeta que el archivo de configuración de agrupación:

include:
  - 'bundle*.yml'

Scripts

La scripts configuración especifica scripts que se pueden ejecutar mediante bundle run. Cada script nombrado en el mapeo scripts contiene comandos. Por ejemplo:

scripts:
  my_script:
    content: uv run pytest -m ${bundle.target}

Para obtener más información, consulte Ejecución de scripts.

sincronizar

La asignación sync permite configurar qué archivos forman parte de las implementaciones de agrupación.

incluir y excluir

Las asignaciones include y exclude dentro de la asignación de sync especifican una lista de archivos o carpetas que se van a incluir dentro de las implementaciones de agrupación, o excluirlas, en función de las reglas siguientes:

  • En función de cualquier lista de archivos y los globs de ruta de acceso en un archivo de .gitignore en la raíz de la agrupación, la asignación include puede contener una lista de patrones globales de archivo, patrones globs de ruta de acceso o ambos, en relación con la raíz de la agrupación de trabajos, para incluir explícitamente.
  • En función de cualquier lista de patrones globales de archivo y ruta de acceso de un archivo .gitignore en la raíz de la agrupación, además de la lista de patrones globales de archivo y ruta de acceso de la asignación include, la asignación exclude puede contener una lista de patrones globales de archivo, patrones globales de ruta de acceso o ambos, en relación con la raíz de la agrupación, para excluir explícitamente.

Todas las rutas de acceso a los archivos y carpetas especificados son relativas a la ubicación del archivo de configuración de agrupación en el que se especifican estas rutas de acceso.

La sintaxis de los patrones de archivo y ruta de acceso include y exclude siguen la sintaxis de patrón estándar .gitignore. Consulte formato de patrón de gitignore.

Por ejemplo, si el siguiente archivo .gitignore contiene las siguientes entradas:

.databricks
my_package/dist

Y el archivo de configuración de agrupación contiene la siguiente asignación include:

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

A continuación, se incluyen todos los archivos de la carpeta my_package/dist con una extensión de archivo de *.whl. No se incluye ningún otro archivo de la carpeta my_package/dist.

Sin embargo, si el archivo de configuración de agrupación también contiene la siguiente asignación exclude:

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

A continuación, se incluyen todos los archivos de la carpeta my_package/dist con una extensión de archivo de *.whl, excepto el archivo denominado delete-me.whl. No se incluye ningún otro archivo de la carpeta my_package/dist.

La asignación sync también se puede declarar en la asignación targets para un destino específico. Cualquier asignación sync declarada en un destino se combina con cualquier declaración de asignación sync de nivel superior. Por ejemplo, siguiendo con el ejemplo anterior, la siguiente asignación de include en el nivel targets se combina con la asignación de include en la asignación sync de nivel superior:

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

rutas

La asignación sync puede contener una asignación paths que especifica rutas de acceso locales para sincronizar con el área de trabajo. La asignación paths permite compartir archivos comunes entre agrupaciones y se puede usar para sincronizar archivos ubicados fuera de la raíz del lote. (La raíz de agrupación es la ubicación del archivo databricks.yml). Esto resulta especialmente útil cuando tienes un único repositorio que hospeda varios conjuntos y deseas compartir bibliotecas, archivos de código o configuración.

Las rutas de acceso especificadas deben ser relativas a los archivos y directorios anclados en la carpeta donde se establece la asignación paths. Si uno o varios valores de ruta de acceso atraviesan el directorio a un antecesor de la raíz del lote, la ruta de acceso raíz se determina dinámicamente para asegurarse de que la estructura de carpetas permanece intacta. Por ejemplo, si la carpeta raíz del lote se denomina my_bundle , esta configuración en databricks.yml sincroniza la carpeta common que se encuentra un nivel por encima de la raíz de la agrupació y la propia raíz de la agrupación:

sync:
  paths:
    - ../common
    - .

Una implementación de este conjunto da como resultado la siguiente estructura de carpetas en el área de trabajo:

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

artefactos

La asignación artifacts de nivel superior especifica uno o varios artefactos que se compilan automáticamente durante las implementaciones de agrupación y se pueden usar más adelante en ejecuciones de agrupación. Cada artefacto secundario admite las siguientes asignaciones:

  • type es necesario para las compilaciones de ruedas de Python. Para compilar un archivo de rueda de Python antes de la implementación, establézcalo en whl. Para compilar otros artefactos, no es necesario especificar esta configuración.
  • path es una ruta de acceso opcional. Las rutas de acceso son relativas a la ubicación del archivo de configuración del paquete. En el caso de las compilaciones wheel de Python, es la ruta de acceso al archivo setup.py del archivo wheel de Python. Si path no se incluye, la CLI de Databricks intenta encontrar el archivo wheel de Python de setup.py en la raíz del lote.
  • files es un mapeo opcional que incluye un mapeo secundario source, que puede utilizar para especificar los artefactos creados. Las rutas de acceso son relativas a la ubicación del archivo de configuración del paquete.
  • build es un conjunto opcional de comandos de compilación no predeterminados que desea ejecutar localmente antes de la implementación. En el caso de las compilaciones de paquetes wheel de Python, la CLI de Databricks supone que puede encontrar una instalación local del paquete wheel de Python para ejecutar compilaciones y ejecuta el comando python setup.py bdist_wheel de forma predeterminada durante cada implementación de agrupación. Especifique varios comandos de compilación en líneas independientes.
  • dynamic_version permite que los conjuntos actualicen la versión de la rueda en función de la marca de tiempo del archivo wheel. A continuación, se puede implementar código nuevo sin tener que actualizar la versión en setup.py o pyproject.toml. Esta configuración solo es válida cuando type se establece en whl.

La siguiente configuración de ejemplo ejecuta pruebas y crea una rueda. Para ver un tutorial completo de agrupación que usa artifacts para crear una rueda, consulte Creación de un archivo de rueda de Python mediante Conjuntos de recursos de Databricks.

artifacts:
  default:
    type: whl
    build: |-
      # run tests
      python -m pytest tests/ -v

      # build the actual artifact
      python setup.py bdist_wheel

    path: .

Para obtener una configuración de ejemplo que compila un JAR y lo carga en Unity Catalog, consulte Agrupación que carga un archivo JAR en Unity Catalog.

Sugerencia

Puede definir, combinar e invalidar la configuración de artefactos en agrupaciones, tal como se describe en Invalidación con la configuración de destino.

Variables

El archivo de configuración de agrupaciones puede contener una asignación variables de nivel superior donde se definen las variables personalizadas. En cada variable, establezca una descripción opcional, un valor predeterminado, si la variable personalizada es un tipo complejo o una búsqueda para recuperar un valor de identificador, y use este 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>

Nota:

Se supone que las variables son del tipo string, a menos que type se establezca en complex. Consulte Definición de una variable compleja.

Para hacer referencia a una variable personalizada dentro de la configuración de un paquete, use la sustitución ${var.<variable_name>}.

Para obtener más información sobre las variables y sustituciones personalizadas, vea Sustituciones y variables en Agrupaciones de recursos de Databricks.

área de trabajo

El archivo de configuración de agrupación solo puede contener una asignación workspace de nivel superior para especificar cualquier configuración de área de trabajo de Azure Databricks no predeterminada que se va a usar.

Importante

También se admiten rutas de acceso válidas del área de trabajo de Databricks con /Workspace o para artefactos /Volumes. Las rutas de acceso del área de trabajo personalizadas tienen asignado automáticamente el prefijo /Workspace, por lo que si usa cualquier sustitución de ruta de acceso del área de trabajo en la ruta de acceso personalizada, como ${workspace.file_path}, no es necesario anteponer /Workspace a la ruta de acceso.

ruta raíz

Esta asignación workspace puede contener una asignación root_path para especificar una ruta de acceso raíz no predeterminada que se usará en el área de trabajo tanto para las implementaciones como para las ejecuciones de flujo de trabajo, por ejemplo:

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

De manera predeterminada, para root_path, la CLI de Databricks usa la ruta de acceso predeterminada /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, que usa substitutions.

ruta_del_artifacto

Esta asignación workspace también puede contener una asignación artifact_path para especificar una ruta de artefactos no predeterminada que se usará tanto para las implementaciones como para las ejecuciones de flujo de trabajo en el área de trabajo, por ejemplo:

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

De manera predeterminada, para artifact_path, la CLI de Databricks usa la ruta de acceso predeterminada ${workspace.root}/artifacts, que usa substitutions.

Nota:

La asignación artifact_path no admite rutas de acceso del sistema de archivos de Databricks (DBFS).

ruta_de_archivo

Esta asignación workspace también puede contener una asignación file_path para especificar una ruta de acceso de archivo no predeterminada que se usará en el área de trabajo tanto para las implementaciones como para las ejecuciones de flujo de trabajo, por ejemplo:

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

De manera predeterminada, para file_path, la CLI de Databricks usa la ruta de acceso predeterminada ${workspace.root}/files, que usa substitutions.

ruta_de_estado

La asignación state_path tiene como valor predeterminado la ruta de acceso predeterminada ${workspace.root}/state y representa la ruta de acceso dentro del área de trabajo para almacenar información de estado de Terraform sobre las implementaciones.

Otras mapeos de áreas de trabajo

La asignación workspace también puede contener las siguientes asignaciones opcionales para especificar el mecanismo de autenticación de Azure Databricks que se va a usar. Si no se especifican dentro de este mapeo workspace, deben especificarse en un mapeo workspace como hijo de uno o varios de los destinos del mapeo targets de nivel superior.

Importante

Debe codificar de forma rígida los siguientes valores de workspace asignaciones para la autenticación de Azure Databricks. Por ejemplo, no se pueden especificar las variables personalizadas para los valores de estas asignaciones mediante la sintaxis ${var.*}.

  • La asignación profile (o las opciones --profile o -p al ejecutar los comandos de validación, implementación, ejecución y destrucción del conjunto con la CLI de Databricks) especifica el nombre de un perfil de configuración que se usará con esta área de trabajo para la autenticación de Azure Databricks. Este perfil de configuración corresponde al que usted creó cuando configuró la CLI de Databricks.

    Nota:

    Databricks recomienda usar la asignación host (o las opciones --profile o -p al ejecutar los comandos de validación, implementación, ejecución y destrucción del conjunto con la CLI de Databricks) en lugar de la asignación profile, ya que esto hace que los archivos de configuración en conjunto sean más portátiles. Al establecer la asignación de host, se indica a la CLI de Databricks que busque un perfil coincidente en el archivo .databrickscfg y, a continuación, use los campos de ese perfil para determinar qué tipo de autenticación de Databricks se va a usar. Si existen varios perfiles con un campo host coincidente en el archivo .databrickscfg, debe usar la asignación profile (o las opciones de línea de comandos --profile o -p) para indicar a la CLI de Databricks qué perfil usar. Para obtener un ejemplo, vea la declaración de destino prod en los ejemplos.

  • La asignación host especifica la dirección URL del área de trabajo de Azure Databricks. Consulte Dirección URL por área de trabajo.

  • Para la autenticación de máquina a máquina (M2M) de OAuth, se emplea la asignación client_id. Como alternativa, puede establecer este valor en la variable de entorno local DATABRICKS_CLIENT_ID. O bien, puede crear un perfil de configuración con el valor client_id y, a continuación, especificar el nombre del perfil con la asignación profile (o mediante la opción --profile o -p al ejecutar los comandos de validación, implementación, ejecución y destrucción del paquete con la CLI de Databricks). Consulte Autorización del acceso de la entidad de servicio a Azure Databricks con OAuth.

    Nota:

    No se puede especificar un valor de secreto de OAuth de Azure Databricks en el archivo de configuración de agrupación. En su lugar, establezca la variable de entorno local DATABRICKS_CLIENT_SECRET. O bien, puede agregar el valor client_secret a un perfil de configuración y, a continuación, especificar el nombre del perfil con la asignación profile (o usando las opciones --profile o -p al ejecutar los comandos de validar, implementar, ejecutar y destruir del paquete con la CLI de Databricks).

  • Para la autenticación de la CLI de Azure, se usa la asignación azure_workspace_resource_id. Como alternativa, puede establecer este valor en la variable de entorno local DATABRICKS_AZURE_RESOURCE_ID. O bien, puede crear un perfil de configuración con el valor azure_workspace_resource_id y, a continuación, especificar el nombre del perfil con la asignación profile (o mediante la opción --profile o -p al ejecutar los comandos de validación, implementación, ejecución y destrucción del paquete con la CLI de Databricks). Consulte Autenticación con la CLI de Azure.

  • Para la autenticación de secretos de cliente de Azure con entidades de servicio, se usan las asignaciones azure_workspace_resource_id, azure_tenant_id y azure_client_id. Como alternativa, puede establecer estos valores en las variables de entorno local DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_ID y ARM_CLIENT_ID, respectivamente. O bien, puede crear un perfil de configuración con los valores azure_workspace_resource_id, azure_tenant_id y azure_client_id y, a continuación, especificar el nombre del perfil con la asignación profile (o utilizando las opciones --profile o -p al ejecutar los comandos bundle validate, deploy, run y destroy con la CLI de Databricks). Consulte Autenticación con entidades de servicio de Microsoft Entra.

    Nota:

    No se puede especificar un valor de secreto de cliente de Azure en el archivo de configuración de agrupación. En su lugar, establezca la variable de entorno local ARM_CLIENT_SECRET. O bien, puede agregar el valor azure_client_secret a un perfil de configuración y, a continuación, especificar el nombre del perfil con la asignación profile (o usando las opciones --profile o -p al ejecutar los comandos de validar, implementar, ejecutar y destruir del paquete con la CLI de Databricks).

  • Para la autenticación de identidades administradas de Azure, se usan las asignaciones azure_use_msi, azure_client_id y azure_workspace_resource_id. Como alternativa, puede establecer estos valores en las variables de entorno local ARM_USE_MSI, ARM_CLIENT_ID y DATABRICKS_AZURE_RESOURCE_ID, respectivamente. O bien, puede crear un perfil de configuración con los valores azure_use_msi, azure_client_id y azure_workspace_resource_id y, a continuación, especificar el nombre del perfil con la asignación profile (o utilizando las opciones --profile o -p al ejecutar los comandos bundle validate, deploy, run y destroy con la CLI de Databricks). Consulte Autenticación con identidades administradas de Azure.

  • La asignación azure_environment especifica el tipo de entorno de Azure (como Public, UsGov, China y Alemania) para un conjunto específico de puntos de conexión de API. El valor predeterminado es PUBLIC. Como alternativa, puede establecer este valor en la variable de entorno local ARM_ENVIRONMENT. O bien, puede agregar el valor azure_environment a un perfil de configuración y, a continuación, especificar el nombre del perfil con la asignación profile (o usando las opciones --profile o -p al ejecutar los comandos de validar, implementar, ejecutar y destruir del paquete con la CLI de Databricks).

  • La asignación azure_login_app_id no es operativa y está reservada para uso interno.

Permisos

La asignación de nivel superior permissions especifica uno o varios niveles de permisos que se aplicarán a todos los recursos definidos en la agrupación. Si quiere aplicar permisos a un recurso específico, vea Definición de permisos para un recurso específico.

Los niveles de permisos de nivel superior permitidos son CAN_VIEW, CAN_MANAGE y CAN_RUN.

En el ejemplo siguiente de un archivo de configuración de agrupación se definen los niveles de permisos de un usuario, un grupo y una entidad de servicio, que se aplican a todos los recursos definidos en resources en la agrupación:

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

La asignación de resources especifica información sobre los recursos de Azure Databricks utilizados por la agrupación.

Esta asignación de resources puede aparecer como una asignación de nivel superior o puede ser un elemento secundario de uno o varios de los destinos de la asignación de nivel superior, e incluye cero o uno de los tipos de recursos admitidos. Cada asignación de tipos de recursos incluye una o varias declaraciones de recursos individuales, que deben tener un nombre único. Estas declaraciones de recursos individuales usan la carga de solicitud de la operación de creación del objeto correspondiente, expresada en YAML, para definir el recurso. Las propiedades admitidas para un recurso son los campos admitidos del objeto correspondiente.

Las cargas de solicitud de operación de creación se documentan en la Referencia de la API de REST de Databricks, y el comando databricks bundle schema genera todos los esquemas de objetos admitidos. Además, el comando databricks bundle validate devuelve advertencias si se encuentran propiedades de recursos desconocidas en los archivos de configuración de agrupación.

La siguiente configuración de ejemplo define un recurso de trabajo:

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 obtener más información sobre los recursos admitidos en conjuntos, así como ejemplos y configuraciones comunes, consulte Recursos de conjuntos de recursos de Databricks y Ejemplos de configuración de agrupación.

objetivos

La asignación targets especifica uno o varios contextos en los que ejecutar flujos de trabajo de Azure Databricks. Cada instancia target es una colección única de artefactos, configuraciones del área de trabajo de Azure Databricks y detalles del trabajo o la canalización de Azure Databricks.

La asignación targets consta de una o varias asignaciones de destino, que deben tener un nombre de programación único (o lógico).

Esta asignación targets es opcional, pero muy recomendable. Si se especifica, solo puede aparecer como una asignación de nivel superior.

Las configuraciones de las asignaciones de nivel superior workspace, artifacts y resources se usan si no se especifican en una asignación targets, pero la configuración en conflicto se invalida mediante la configuración dentro de un destino.

Un destino también puede invalidar los valores de cualquier variable de nivel superior.

predeterminado

Para especificar un valor predeterminado de destino para los comandos de agrupación, establezca la asignación default en true. Por ejemplo, este destino denominado dev es el destino predeterminado:

targets:
  dev:
    default: true

Si un destino predeterminado no está configurado, o si deseas validar, implementar y ejecutar trabajos o canalizaciones dentro de un destino específico, usa la opción -t de los comandos de agrupación.

Los siguientes comandos validan, implementan y ejecutan my_job dentro de los destinos dev y 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

En el ejemplo siguiente declara dos destinos. El primer destino tiene el nombre dev y es el destino predeterminado que se usa cuando no se especifica ningún destino para los comandos de agrupación. El segundo destino tiene el nombre prod y solo se usa cuando se especifica este destino para los comandos de agrupación.

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

modo y valores preestablecidos

Para facilitar un desarrollo sencillo y las mejores prácticas de CI/CD, Databricks Asset Bundles proporciona modos de implementación para entornos que definen comportamientos predeterminados para flujos de trabajo de preproducción y producción. Algunos comportamientos también son configurables. Para obtener más información, consulte Modos de implementación de paquetes de activos de Databricks.

Sugerencia

Para configurar identidades de ejecución para agrupaciones, puede especificar run_as para cada destino, como se describe en Especificación de una identidad de ejecución para un flujo de trabajo de Conjuntos de recursos de Databricks.

Para especificar que un destino se trata como destino de desarrollo, agregue la asignación mode establecida en development. Para especificar que un destino se trata como destino de producción, agregue la asignación mode establecida en production. Por ejemplo, este destino denominado prod se trata como destino de producción:

targets:
  prod:
    mode: production

Puedes personalizar ciertos comportamientos utilizando la asignación presets. Para obtener una lista de los valores preestablecidos disponibles, consulta Valores preestablecidos personalizados. El siguiente ejemplo muestra un objetivo de producción personalizado que añade prefijos y etiquetas a todos los recursos de producción.

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

Si se establecen mode y presets, los valores preestablecidos invalidan el comportamiento del modo predeterminado. La configuración de recursos individuales invalida los valores preestablecidos. Por ejemplo, si una programación se establece en UNPAUSED, pero el valor preestablecido trigger_pause_status se establece en PAUSED, la programación se despausará.

  • Last updated on