Compartir vía

Plantillas de proyecto de agrupación de recursos de Databricks

  • Artículo

Los conjuntos de recursos de Databricks describen los recursos de Databricks, como trabajos, canalizaciones y cuadernos como archivos de origen, lo que le permite incluir metadatos junto con estos archivos de origen para aprovisionar infraestructura y otros recursos, y proporcionar una definición de un extremo a otro de un proyecto, todos empaquetados como un único proyecto implementable. Consulte ¿Qué son los conjuntos de recursos de Databricks?

Las plantillas de agrupación permiten a los usuarios crear agrupaciones de forma coherente y repetible mediante el establecimiento de estructuras de carpetas, pasos de compilación y tareas, pruebas y otros atributos de infraestructura como código (IaC) de DevOps comunes en una canalización de implementación.

Por ejemplo, si ejecuta periódicamente trabajos de Databricks que requieren paquetes personalizados con un paso de compilación lento tras la instalación, puede acelerar el bucle de desarrollo mediante la creación de una plantilla de agrupación que especifique un entorno de contenedor personalizado.

Databricks proporciona un conjunto de plantillas de agrupación predeterminadas, pero también puede crear plantillas de agrupación personalizadas. A continuación, los usuarios pueden inicializar agrupaciones mediante el comando bundle init, especificando una plantilla predeterminada o la plantilla personalizada.

Creación de una agrupación mediante una plantilla

Para usar una plantilla de agrupación de Azure Databricks para crear la agrupación, use el comando cli de Databricksbundle init, especificando el nombre de la plantilla que se va a usar. Por ejemplo, el siguiente comando crea una agrupación mediante la plantilla de agrupación de Python predeterminada:

databricks bundle init default-python

Para utilizar una plantilla de paquete personalizada, pase la ruta de acceso local o la URL remota de la plantilla al comando CLI de Databricksbundle init.

Por ejemplo, el siguiente comando usa la plantilla dab-container-template creada en el Tutorial de plantilla de agrupación personalizada:

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Si no especifica una plantilla, el comando bundle init muestra un conjunto de plantillas predeterminadas disponibles entre las que puede elegir.

plantillas de paquetes predeterminadas

Azure Databricks proporciona las siguientes plantillas de agrupación predeterminadas:

Plantilla Descripción
default-python Plantilla para usar Python con Databricks. Esta plantilla crea una agrupación con un trabajo y una canalización de DLT. Consulte default-python.
default-sql Plantilla para usar SQL con Databricks. Esta plantilla contiene un archivo de configuración que define un trabajo que ejecuta consultas SQL en un almacén de SQL. Consulte default-sql.
dbt-sql Plantilla que aprovecha dbt-core para el desarrollo local y las agrupaciones para la implementación. Esta plantilla contiene la configuración que define un trabajo con una tarea dbt, así como un archivo de configuración que define perfiles de dbt para trabajos dbt implementados. Consulte dbt-sql.
mlops-stacks Plantilla de pila completa avanzada para iniciar nuevos proyectos de MLOps Stacks. Consulte mlops-stacks y Agrupaciones de recursos de Databricks para pilas de MLOps.

plantillas de paquetes personalizadas

Las plantillas de agrupación usan la sintaxis de plantillas de paquetes de Go, que proporcionan flexibilidad en las plantillas de agrupación personalizadas que puede crear. Consulte la documentación de la plantilla de paquete de Go.

Estructura del proyecto de plantilla

Como mínimo, un proyecto de plantilla de agrupación debe tener:

  • Un archivo databricks_template_schema.json en la raíz del proyecto que define una propiedad de solicitud de usuario para el nombre del proyecto de agrupación. Consulte Esquema de plantilla.
  • Un archivo databricks.yml.tmpl ubicado en una carpeta template que define la configuración de los conjuntos creados con la plantilla. Si el archivo databricks.yml.tmpl hace referencia a plantillas de configuración adicionales *.yml.tmpl, especifique la ubicación de estos en la asignación include. Consulte Plantillas de configuración de YML.

Además, la estructura de carpetas y los archivos incluidos del proyecto de plantilla de paquetes de la carpeta template se reflejan en los paquetes creados con la plantilla. Por ejemplo, si desea que la plantilla genere una agrupación con un cuaderno simple en la carpeta src y una definición de trabajo que ejecute el cuaderno en la carpeta resources, organizaría el proyecto de plantilla de la siguiente manera:

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      ├── databricks.yml.tmpl
      ├── resources
      │   └── {{.project_name}}_job.yml.tmpl
      └── src
          └── simple_notebook.ipynb

Sugerencia

El nombre del archivo de definición de trabajo de esta plantilla de agrupación usa una variable de plantilla. Para obtener información sobre las variables y los asistentes de plantilla, consulte Asistentes de plantillas y variables.

Esquema de plantilla

Un proyecto de plantilla de agrupación personalizado debe contener en la raíz del proyecto un databricks_template_schema.json [archivo JSON](https://json-schema.org/specification.html). Este archivo define los campos usados por la CLI de Databricks cuando se ejecuta el comando bundle init, como el texto de aviso.

El siguiente archivo de databricks_template_schema.json básico define una variable de entrada project_name para el proyecto de agrupación, que incluye el mensaje de aviso y un valor predeterminado. A continuación, define un mensaje de operación correcta para la inicialización del proyecto de agrupación que usa el valor de la variable de entrada dentro del mensaje.

{
  "properties": {
    "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
    }
  },
  "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

Campos de esquema de plantilla

El archivo databricks_template_schema.json admite la definición de variables de entrada para recopilar información del usuario durante la inicialización del paquete dentro del campo properties, así como para definir campos adicionales que personalicen la inicialización.

Las variables de entrada se definen en el campo properties del esquema de plantilla. Cada variable de entrada define los metadatos necesarios para presentar un indicador al usuario durante la inicialización del paquete. A continuación, se puede acceder al valor de la variable mediante la sintaxis de variable de plantilla, como {{.project_name}}.

También puede establecer los valores de algunos campos para personalizar el proceso de inicialización del paquete.

Los campos de esquema admitidos se enumeran en la tabla siguiente.

Campo de esquema Descripción
properties Definiciones de variable de entrada de plantilla de agrupación. Databricks recomienda definir al menos una variable de entrada que sea el nombre del proyecto de agrupación.
properties.<variable_name> Nombre de la variable de entrada.
properties.<variable_name>.default Valor predeterminado que se va a usar si el usuario no proporciona un valor con --config-file como parte del comando bundle init o en la línea de comandos cuando se le solicite.
properties.<variable_name>.description Mensaje de solicitud de usuario asociado a la variable de entrada.
properties.<variable_name>.enum Lista de valores posibles para la propiedad, como "enum": ["azure", "aws", "gcp"]. Si se define este campo, la CLI de Databricks presenta los valores de una lista en la línea de comandos para pedir al usuario que seleccione un valor.
properties.<variable_name>.order Entero que define el orden relativo de las propiedades de entrada. Esto controla el orden en el que se muestran las indicaciones de estas variables de entrada en la línea de comandos.
properties.<variable_name>.pattern Patrón regexp que se va a usar para validar la entrada del usuario, por ejemplo, "pattern": "^[^ .\\\\/]{3,}$". Para ver la sintaxis regexp admitida, consulte https://github.com/google/re2/wiki/Syntax.
properties.<variable_name>.pattern_match_failure_message Mensaje que se muestra al usuario si el valor especificado por el usuario no coincide con el patrón especificado, por ejemplo, Project name must be at least 3 characters long and cannot contain the following characters: \"\\\", \"/\", \" \" and \".\".".
properties.<variable_name>.skip_prompt_if Omita la solicitud de la variable de entrada si esta configuración ya satisface el esquema. En ese caso, se usa el valor predeterminado de la propiedad en su lugar. Para obtener un ejemplo, consulte la plantilla mlops-stacks. Solo se admiten comparaciones de const.
properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const Si el valor de <previous_variable_name> coincide con la constante configurada en skip_prompt_if, se omitirá la solicitud de <variable_name>.
welcome_message Primer mensaje que se va a generar antes de pedir al usuario que escriba.
success_message Mensaje que se va a imprimir después de inicializar correctamente la plantilla.
min_databricks_cli_version La versión mínima del SemVer de esta CLI de Databricks que requiere la plantilla. databricks bundle init produce un error si la versión de la CLI es menor que esta versión.
version Reservado para uso futuro. Versión del esquema. Esto se usa para determinar si el esquema es compatible con la versión actual de la CLI.

Plantillas de configuración de YML

Una plantilla de agrupación personalizada debe contener un archivo databricks.yml.tmpl en una carpeta template del proyecto de plantilla de agrupación que se usa para crear el proyecto de agrupación databricks.yml. Rellene este archivo de plantilla con la plantilla de configuración básica YAML.

En el ejemplo siguiente, las plantillas de configuración para databricks.yml y el *_job.yml asociado, establecen el nombre del lote y dos entornos de destino, y definen un trabajo que ejecuta el cuaderno en la agrupación, para los conjuntos creados con esta plantilla. Estas plantillas de configuración aprovechan las sustituciones de paquetes y los auxiliares de plantillas de paquetes. Consulte sustituciones de paquetes y asistentes de plantilla de paquete.

# databricks.yml
# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

# {{.project_name}}_job.yml
# The main job for {{.project_name}}

resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

Asistentes y variables de plantilla

Los asistentes de plantilla son funciones proporcionadas por Databricks que puede usar dentro de los archivos de plantilla para obtener información específica del usuario en tiempo de ejecución o interactuar con el motor de plantillas. También puede definir sus propias variables de plantilla.

Los siguientes asistentes de plantilla están disponibles para los proyectos de plantilla de agrupación de Databricks. Para obtener información sobre el uso de plantillas y variables de Go, consulte plantillas de Go.

Ayudante Descripción
{{url}} Un alias para https://pkg.go.dev/net/url#Parse. Esto permite el uso de todos los métodos de url.URL.
{{regexp}} Un alias para https://pkg.go.dev/regexp#Compile. Esto permite el uso de todos los métodos de regexp.Regexp.
{{random_int}} Devuelve, como int, un número pseudoaleatorio no negativo en el intervalo medio abierto (0,n).
{{uuid}} Devuelve, como una cadena, un UUID que es un identificador único universal de 128 bits (16 bytes) tal como se define en RFC 4122.Este identificador es estable durante la ejecución de la plantilla y se puede usar para rellenar el campo bundle.uuid en databricks.yml por autores de plantillas.
{{bundle_uuid}} Un identificador único para la agrupación. Varias invocaciones de esta función devolverán el mismo UUID.
{{pair}} Un par clave-valor. Esto se usa con el asistente de map para generar mapas que se usarán dentro de una plantilla.
{{map}} Convierte una lista de pares en un objeto de mapa. Esto resulta útil para pasar varios objetos a plantillas definidas en el directorio de biblioteca. Dado que la sintaxis de la plantilla de texto de Go para invocar una plantilla solo permite especificar un único argumento, esta función se puede usar para solucionar esa limitación.
Por ejemplo, en la línea siguiente, se puede hacer referencia a {{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}}, $arg1 y $arg2 desde dentro de my_template como .foo y .bar.
{{smallest_node_type}} Devuelve el tipo de nodo más pequeño.
{{path_separator}} Carácter separador de ruta para el sistema operativo. Esto es / para sistemas basados en Unix y \ para Windows.
{{workspace_host}} La dirección URL del host del área de trabajo en la que el usuario está autenticado actualmente.
{{user_name}} Nombre completo del usuario que inicializa la plantilla.
{{short_name}} Nombre corto del usuario que inicializa la plantilla.
{{default_catalog}} Devuelve el catálogo de áreas de trabajo predeterminado. Si no hay ningún valor predeterminado o si el catálogo de Unity no está habilitado, devuelve una cadena vacía.
{{is_service_principal}} Si el usuario actual es o no una entidad de servicio.
{{ skip <glob-pattern-relative-to-current-directory> }} Hace que el motor de plantillas omita la generación de todos los archivos y directorios que coinciden con el patrón glob de entrada. Para obtener un ejemplo, consulte la plantilla mlops-stacks.

Para definir sus propias variables, cree un archivo de plantilla en la carpeta library del proyecto de plantilla y use la sintaxis de plantillas de Go para definir variables. Por ejemplo, el siguiente contenido de un archivo de library/variables.tmpl define las variables cli_version y model_name. Cuando esta plantilla se usa para inicializar una agrupación, el valor de la variable model_name se construye mediante el campo input_project_name definido en el archivo de esquema de plantilla. El valor de este campo es la entrada del usuario después de un aviso.

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

Para ver un ejemplo completo, consulte el archivo de variables de plantilla de mlops-stacks.

Prueba la plantilla del paquete

Por último, asegúrese de probar la plantilla. Cree una nueva carpeta de proyecto de agrupación y, a continuación, use la CLI de Databricks para inicializar una nueva agrupación mediante la plantilla:

databricks bundle init basic-bundle-template

En el símbolo del sistema What is your bundle project name?, escriba my_test_bundle.

Una vez creada la agrupación de pruebas, se genera el mensaje de confirmación del archivo de esquema. Si examina el contenido de la carpeta my_test_bundle, debería ver lo siguiente:

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

Y ahora se han personalizado el archivo databricks.yml y el trabajo.

# databricks.yml
# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

# my_test_bundle_job.yml
# The main job for my_test_bundle

resources:
    jobs:
        my_test_bundle_job:
        name: my_test_bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

Uso compartido de la plantilla

Si desea compartir esta plantilla de agrupación con otros usuarios, puede almacenarla en el control de versiones con cualquier proveedor que Git admita y al que los usuarios tengan acceso. Para ejecutar el comando bundle init con una dirección URL de Git, asegúrese de que el archivo databricks_template_schema.json se encuentra en la ubicación raíz con respecto a esa dirección URL de Git.

Sugerencia

Puede colocar el archivo databricks_template_schema.json en una carpeta diferente, en relación con la raíz del lote. A continuación, puede usar la opción bundle init del comando --template-dir para hacer referencia a esa carpeta, que contiene el archivo databricks_template_schema.json.

Pasos siguientes