Configuración de agrupación de recursos de Databricks

  • Artículo

En este artículo se describe la sintaxis de los archivos de configuración de agrupación de recursos de Databricks, que definen las agrupaciones de recursos de Databricks. Consulte ¿Qué son las agrupaciones de recursos de Databricks?

Un archivo de configuración de agrupación debe expresarse en formato YAML y debe contener como mínimo la asignación de agrupación de nivel superior. Cada agrupación debe contener como mínimo un archivo de configuración de agrupación (y solo uno) denominado databricks.yml. Si hay varios archivos de configuración de agrupación, el archivo databricks.yml debe hacer referencia a ellos mediante la asignación de include.

Para obtener más información sobre YAML, consulte la especificación y el tutorial oficiales de YAML.

Para crear y trabajar con archivos de configuración de agrupación, consulte Desarrollo de conjuntos de recursos de Databricks.

Información general

En esta sección se proporciona una representación visual del esquema del archivo de configuración de agrupación. Para obtener más información, consulte Asignaciones.

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

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

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

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

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

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  dashboards:
    <some-unique-programmatic-identifier-for-this-dashboard>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See REST API create request payload reference for jobs.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the REST API create request payload reference for models.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the REST API create request payload reference for Delta Live Tables (pipelines).
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"
  paths:
    - "<some-file-or-path-to-synchronize>"

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

Ejemplos

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 este archivo de configuración de agrupación local denominado databricks.yml. 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 de dicha área se leen del perfil de configuración local del autor de la llamada denominado DEFAULT.

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 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 profile para indicar a la CLI de Databricks qué perfil específico usar. Para obtener un ejemplo, consulte la declaración de destino prod más adelante en esta sección.

Esta técnica permite volver a usar, así como invalidar, las definiciones de trabajo y la configuración dentro del bloque 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

Aunque el siguiente archivo de configuración de agrupación es funcionalmente equivalente, no es modular, lo que no posibilita una buena reutilización. Además, esta declaración anexa una tarea al trabajo en lugar de invalidar el trabajo 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

En el ejemplo siguiente se agrega un destino con el nombre prod que usa una dirección URL de área de trabajo remota y unas credenciales de autenticación de área de trabajo diferentes, que se leen desde la entrada host coincidente del archivo .databrickscfg del autor de la llamada con la dirección URL del área de trabajo especificada. Este trabajo ejecuta el mismo cuaderno, pero usa un clúster remoto diferente con el id. de clúster especificado. 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

Para validar, implementar y ejecutar este trabajo dentro del 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, 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

A continuación se muestra el ejemplo anterior, pero se divide en archivos de componentes para una mayor modularización y una mejor reutilización en varios archivos de configuración de agrupación. Esta técnica no solo le permite reutilizar varias definiciones y configuraciones, sino también intercambiar cualquiera de estos archivos con otros archivos que proporcionan declaraciones 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

Asignaciones

En las secciones siguientes se describe la sintaxis del archivo de configuración de agrupación, por asignación de nivel superior.

bundle

Un archivo de configuración de agrupación solo debe contener una asignación bundle de nivel superior que asocie el contenido de la agrupación y la configuración del área de trabajo de Azure Databricks.

Esta asignación bundle debe contener una asignación name que especifique un nombre mediante programación (o lógico) para la agrupación. 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 name de la asignación bundle de nivel superior no se puede invalidar en el nivel de destino.

cluster_id

La asignación de bundle puede tener una asignación de cluster_id secundaria. Esta asignación permite especificar el id. de un clúster que se va a usar como invalidación para los clústeres definidos en otras partes del archivo de configuración de agrupación. Para obtener información sobre cómo recuperar el identificador de un clúster, consulta Dirección URL y id. del clúster.

La invalidación cluster_id está pensada para escenarios de solo desarrollo y solo se admite para el destino que tiene su asignación mode establecida en development. Para obtener más información sobre la asignación target, consulta 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 permite especificar el id. de un clúster que se va a usar como invalidación para los clústeres definidos en otras partes del archivo de configuración de agrupación.

git

Puede recuperar e invalidar los detalles del control de versiones de Git asociados a la agrupación. Esta acción es útil para anotar los recursos implementados. Por ejemplo, puede que desee incluir la dirección URL de origen del repositorio en la descripción de un modelo de Machine Learning que implemente.

Siempre que ejecute un comando bundle, como validate, deploy o run, el comando bundle 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}.
  • bundle.git.commit, que representa la confirmación HEAD dentro del repositorio. Este es el mismo valor que obtendría si ejecutara el comando git rev-parse HEAD 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.commit}.

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 bundle de nivel superior 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 la agrupación. Esto puede evitar 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 de databricks --version actual no está dentro de los límites especificados en la asignación de databricks_cli_version de la agrupación, se produce un error cuando se ejecuta databricks bundle validate en la agrupación. 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

variables

El archivo de configuración de la agrupación puede contener una asignación de variables de primer nivel donde se definen 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 en una configuración de agrupación, use las 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

Las rutas de acceso válidas del área de trabajo de Databricks comienzan con /Workspace o /Volumes. Las rutas de acceso del área de trabajo personalizadas se prefijo automáticamente con /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.

root_path

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 forma predeterminada, para root_path, la CLI de Databricks usa la ruta de acceso predeterminada de /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, que usa sustituciones.

artifact_path

Esta asignación workspace también puede contener una asignación artifact_path para especificar una ruta de acceso raíz de artefacto 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:
  artifact_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

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

Nota:

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

file_path

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 forma predeterminada, para file_path, la CLI de Databricks usa la ruta de acceso predeterminada de ${workspace.root}/files, que usa sustituciones.

state_path

La asignación state_path tiene como valor predeterminado la ruta de acceso predeterminada de ${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 asignaciones 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 esta asignación workspace, deben especificarse en una asignación workspace como elemento secundario de uno o varios de los destinos de la asignación targets de nivel superior.

Importante

Debe codificar los valores de forma rígida para las siguientes asignaciones workspace para la autenticación de Azure Databricks. Por ejemplo, no se pueden especificar 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 se asigna al que creó al configurar 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 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 usa 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 valorclient_id y, a continuación, especificar el nombre del perfil con la asignación profile (o mediante 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). Consulte Autenticación del acceso a Azure Databricks con una entidad de servicio mediante OAuth (OAuth M2M).

    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 mediante 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).

  • 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 valorazure_workspace_resource_id y, a continuación, especificar el nombre del perfil con la asignación profile (o mediante 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). Consulte Autenticación de 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 mediante 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). Vea Autenticación de la entidad de servicio de MS 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 mediante 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).

  • Para la autenticación de identidades administradas de Azure, se usan las asignaciones azure_use_msi, azure_client_idy 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 mediante 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). Consulte Autenticación de 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 mediante 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).

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

  • La asignación auth_type especifica el tipo de autenticación de Azure Databricks que se va a usar, especialmente en los casos en los que la CLI de Databricks deduce un tipo de autenticación inesperado. Consulte Autenticación del acceso a los recursos de Azure Databricks.

permisos

La asignación de permissions de nivel superior 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, grupo y entidad de servicio, que se aplican a todos los trabajos, canalizaciones, experimentos y modelos definidos en resources del lote:

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

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 obligatorio. Para compilar un archivo wheel de Python antes de la implementación, esta asignación debe establecerse en whl.
  • path es una ruta de acceso relativa opcional desde la ubicación del archivo de configuración de la agrupación a la ubicación del archivo wheel de Python setup.py. Si path no se incluye, la CLI de Databricks intentará encontrar el archivo wheel de Python setup.py en la raíz de la agrupación.
  • files es una asignación opcional que incluye una asignación secundaria source, que se puede usar para especificar ubicaciones no predeterminadas que se van a incluir para obtener instrucciones de compilación complejas. Las ubicaciones se especifican como rutas de acceso relativas desde la ubicación del archivo de configuración de la agrupación.
  • 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. Para especificar varios comandos de compilación, separe cada uno de ellos con caracteres (&&) de doble &.

Para obtener más información, incluida una agrupación de ejemplo que usa artifacts, consulte Desarrollar un archivo wheel de Python usando agrupaciones de recursos de Databricks.

Sugerencia

Puede definir, combinar e invalidar la configuración de artefactos en agrupaciones mediante las técnicas descritas en Definición dinámica de la configuración de artefactos en agrupaciones de recursos de Databricks.

include

La matriz include especifica una lista de patrones globales de ruta de acceso que contienen archivos de configuración que se van a incluir dentro de 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 una asignación 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"

recursos

La asignación de resources especifica la información sobre los recursos de Azure Databricks que usa el paquete.

Esta asignación de resources puede aparecer como una asignación de nivel superior, o puede ser un elemento secundario de uno o más de los destinos de la asignación de nivel superior, e incluye cero o uno de los tipos de recursos compatibles. 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 útil de la 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 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.

En la tabla siguiente se enumeran los tipos de recursos admitidos para agrupaciones y vínculos a documentación sobre sus cargas correspondientes.

Tipo de recurso Asignaciones de recursos
cluster Asignaciones de clústeres: POST /api/2.1/clusters/create
salpicadero Asignaciones de paneles: POST /api/2.0/preview/sql/dashboards
experimento Asignaciones de experimentos: POST /api/2.0/mlflow/experiments/create
trabajo Asignaciones de trabajos: POST /api/2.1/jobs/create

Para más información, consulte tipos de tareas e invalidar la configuración del nuevo clúster de tareas.
pipeline Asignaciones de canalización: POST /api/2.0/pipelines
model Asignaciones de modelos: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint Asignaciones de puntos de conexión de servicio de modelos: POST /api/2.0/serving-endpoints
registered_model (Unity Catalog) Asignaciones de modelos del catálogo de Unity: POST /api/2.1/unity-catalog/models
schema (Unity Catalog) Asignaciones de esquemas del catálogo de Unity: POST /api/2.1/unity-catalog/schemas

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

cluster

El recurso de clúster permite crear clústeres de uso completo. En el ejemplo siguiente se crea un clúster denominado my_cluster y se establece que como clúster que se va a usar para ejecutar el cuaderno en 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"

dashboard

El recurso de panel permite administrar paneles de INTELIGENCIA ARTIFICIAL o BI en un lote. Para obtener información sobre los paneles de IA/BI, consulte Paneles.

En el ejemplo siguiente se incluye e implementa el panel de análisis de carreras de taxi de Nueva York en el área de trabajo de Databricks.

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: "NYC Taxi Trip Analysis"
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

Si usa la interfaz de usuario para modificar el panel, las modificaciones realizadas a través de la interfaz de usuario no se aplican al archivo JSON del panel en el lote local a menos que lo actualice explícitamente mediante bundle generate. Puede usar la --watch opción para sondear y recuperar continuamente los cambios en el panel. Consulte Generación de un archivo de configuración de agrupación.

Además, si intenta implementar una agrupación que contiene un archivo JSON de panel diferente al del área de trabajo remota, se producirá un error. Para forzar la implementación y sobrescribir el panel en el área de trabajo remota con la local, use la --force opción . Consulte Implementación de una agrupación.

trabajo

En el ejemplo siguiente se declara un trabajo con la clave de recurso de 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

En el ejemplo siguiente se declara una canalización con la clave de recurso de 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

schema

El tipo de recurso de esquema permite definir esquemas de catálogo de Unity para tablas y otros recursos en los flujos de trabajo y canalizaciones creados como parte de una agrupación. Un esquema, diferente de otros tipos de recursos, tiene las siguientes limitaciones:

  • El propietario de un recurso de esquema siempre es el usuario de implementación y no se puede cambiar. Si se especifica run_as en la agrupación, se omitirán las operaciones en el esquema.
  • Solo los campos admitidos por la API de creación de objetos de esquema correspondiente están disponibles para el recurso schema. Por ejemplo, enable_predictive_optimization no se admite, ya que solo está disponible en la API de actualización.

En el ejemplo siguiente se declara una canalización con la clave de recurso my_pipeline que crea un esquema de Unity Catalog con la clave 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.

Una asignación de concesiones de primer nivel no se admite por las agrupaciones de recursos de Databricks, por lo que si desea establecer concesiones para un esquema, defina las concesiones para el esquema dentro de la asignación 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

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

excluir e incluir

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

  • 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, la asignación include 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 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 de trabajos, 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 sigue 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 suben al directorio hasta un antecesor de la raíz de la agrupación, 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/
    ...

destinos

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 targets asignación consta de una o varias asignaciones de destino, de manera que, cada una de las cuales, debe tener un nombre programático (o lógico) único.

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

La configuración del área de trabajo de nivel superior, los artefactos y las asignaciones de recursos se usan si no se especifican en una asignación de 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.

default

Para especificar un valor predeterminado de destino para los comandos de agrupación, establece 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 los procedimientos recomendados de CI/CD, Conjunto de recursos de Databricks proporciona modos de implementación para destinos que establecen 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 conjuntos de recursos de Databricks: Azure 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, agrega la asignación mode establecida en development. Para especificar que un destino se trata como destino de producción, agrega 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 algunos de los comportamientos mediante la asignación presets. Para obtener una lista de los valores preestablecidos disponibles, consulta Valores preestablecidos personalizados. En el ejemplo siguiente se muestra un destino de producción personalizado que se antepone y etiqueta 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á.