Compartir a través de

Plantillas de proyecto de agrupación de recursos de Databricks

  • Artículo

En este artículo se describe la sintaxis de las plantillas de Agrupaciones de recursos de Databricks. Las agrupaciones permiten la administración mediante programación de flujos de trabajo de Azure Databricks. Consulte ¿Qué son las agrupaciones 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 del entorno de desarrollo.

Por ejemplo, si ejecuta de forma rutinaria 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 admita entornos de contenedor personalizados.

Las plantillas de agrupación definen la estructura de directorios del lote que se creará y incluyen una databricks.yml.tmpl plantilla de archivo de configuración, así como un databricks_template_schema.json archivo que contiene variables de solicitud de usuario.

Utilizar una plantilla de agrupación predeterminada

Para usar una plantilla de agrupación predeterminada de Azure Databricks para crear la agrupación, utilice el comando bundle init de la CLI de Databricks y especifica el nombre de la plantilla predeterminada 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

Si no especifica una plantilla predeterminada, el bundle init comando presenta el conjunto de plantillas disponibles desde las que puede elegir.

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 Delta Live Tables. 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 los conjuntos 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 Paquetes de recursos de MlOps para pilas de MLOps.

Uso de una plantilla de agrupación personalizada

Para usar una plantilla de agrupación que no sea la predeterminadas de Azure Databricks, pase la ruta de acceso local o la dirección URL remota de la plantilla al comando bundle init de la CLI de Databricks.

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

Creación de una plantilla de agrupación personalizada

Las plantillas de agrupación usan la sintaxis de plantillas de paquetes de Go. Consulte la documentación de la plantilla de paquete de Go.

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 variable de solicitud de usuario para el nombre del proyecto de agrupación.
  • Un archivo databricks.yml.tmpl ubicado en una carpeta template que define la configuración de los conjuntos creados con la plantilla. Si el databricks.yml.tmpl archivo hace referencia a plantillas de configuración adicionales *.yml.tmpl, especifique la ubicación de estos en la include asignación.

Opcionalmente, puede agregar subcarpetas y archivos a la template carpeta que desea reflejar en agrupaciones creadas por la plantilla.

Definición de variables de solicitud de usuario

El primer paso para crear una plantilla de agrupación básica es crear una carpeta de proyecto de plantilla y un archivo denominado databricks_template_schema.json en la raíz del proyecto. Este archivo contiene las variables para las que los usuarios proporcionan valores de entrada cuando usan la plantilla para crear una agrupación mediante bundle init. Este archivo sigue la especificación del esquema JSON.

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

Agregue el siguiente código al archivo databricks_template_schema.json y, a continuación, guarde el archivo:

{
   "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."
}

En este archivo:

  • project_name es el único nombre de variable de entrada.
  • default es un valor predeterminado opcional para la variable relacionada, si el usuario no proporciona un valor con --config-file como parte del comando bundle init o invalida al usuario en el símbolo del sistema.
  • description es la solicitud del usuario para la variable de entrada relacionada, si el usuario no proporciona un valor con --config-file como parte del comando bundle init.
  • order es un orden opcional en el que aparece cada solicitud de usuario, si el usuario no proporciona un valor con --config-file como parte del comando bundle init. Si no se proporciona order, se mostrarán las indicaciones del usuario en el orden en que se muestran, de principio a fin.
  • success_message es un mensaje opcional que se muestra tras la creación correcta del proyecto.

Compilación de la estructura de carpetas

A continuación, cree la carpeta necesaria template y compile la estructura de carpetas dentro de ella. Esta estructura se reflejará mediante agrupaciones creadas con esta plantilla. Además, coloque los archivos que desee incluir en esas carpetas. Esta plantilla de agrupación básica almacena archivos en una src carpeta e incluye un cuaderno simple.

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

Agregue al archivo simple_notebook.ipynb lo siguiente:

print("Hello World!")

Rellenar archivos de plantilla de configuración

Ahora cree el archivo necesario databricks.yml.tmpl en la carpetatemplate:

touch basic-bundle-template/template/databricks.yml.tmpl

Rellene este archivo con la plantilla de configuración básica YAML. Esta plantilla de configuración establece el nombre del lote, un trabajo mediante el archivo de cuaderno especificado y dos entornos de destino para agrupaciones creadas con esta plantilla. También aprovecha las sustituciones de agrupación, que es muy recomendable. Consulte las sustituciones de agrupación.

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

bundle:
  name: {{.project_name}}

# 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

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 -}}

Prueba de la plantilla de agrupación

Por último, pruebe 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:

mkdir my-test-bundle
cd my-test-bundle
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
   └── src
      └── simple_notebook.ipynb

Y el archivo databricks.yml ahora está personalizado:

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

bundle:
  name: my-test-bundle

# 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

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

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