Compartir a través de

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?

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

Información general

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 cada mapeo de nivel superior, consulte Mapeos.

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

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
  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:
  clusters:
    <some-unique-programmatic-identifier-for-this-cluster>:
      # See the REST API create request payload reference for clusters.
  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.
  volumes:
    <some-unique-programmatic-identifier-for-this-volume>:
    # See the Unity Catalog volume 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 .databrickscfg coincidente del archivo host 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 bundle de la asignación name 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}.

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 Autorización del acceso desatendido a recursos de Azure Databricks con una entidad de servicio mediante 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 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 la Autorizació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 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 de paquete wheel de Python, es la ruta de acceso al archivo setup.py del archivo wheel de Python. Si no se incluye path, la CLI de Databricks intenta encontrar el archivo setup.py del archivo wheel de Python en la raíz del paquete.
  • 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 de 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 &.

La siguiente configuración de ejemplo crea una rueda mediante Poetry. Para obtener un paquete de ejemplo completo que usa artifacts para compilar un paquete wheel, consulte Desarrollo de un archivo wheel de Python mediante conjuntos de recursos de Databricks.

artifacts:
  default:
    type: whl
    build: poetry build
    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 y como se describe en Definición de la configuración del artefacto en Conjuntos 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.

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.

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