Migración de dbx a agrupaciones

Artículo
10/09/2024

Importante

Databricks recomienda usar las agrupaciones de recursos de Databricks en lugar de dbx de Databricks Labs. Los artículos relacionados sobre dbx se han retirado y es posible que no se actualicen.

En este artículo se describe cómo migrar proyectos de dbxDatabricks Labs a conjuntos de recursos de Databricks. Consulte Introducción a dbx mediante Databricks Labs y ¿Qué son los conjuntos de recursos de Databricks?.

Antes de migrar, tenga en cuenta las siguientes limitaciones y comparaciones de características entre dbx de Databricks Labs y los conjuntos de recursos de Databricks.

Limitaciones

La siguiente funcionalidad admitida en dbx de Databricks Labs es limitada, no existe o requiere soluciones alternativas en conjuntos de recursos de Databricks.

La creación de artefactos JAR no se admite en agrupaciones.
No se admite la notación FUSE para las rutas de acceso del área de trabajo en agrupaciones (por ejemplo, /Workspace/<path>/<filename>). Sin embargo, puede indicar a los conjuntos que generen rutas de acceso al área de trabajo de estilo FUSE durante las implementaciones mediante notación como /Workspace/${bundle.file_path}/<filename>.

Comparaciones de características

Antes de migrar, tenga en cuenta cómo se implementan las siguientes características de dbx de Databricks Labs en conjuntos de recursos de Databricks.

Plantillas y proyectos

dbx proporciona compatibilidad con plantillasde Jinja. Puede incluir plantillas de Jinja en la configuración de implementación y pasar variables de entorno insertadas o a través de un archivo de variables. Aunque no se recomienda, dbx también proporciona compatibilidad experimental con funciones de usuario personalizadas.

Los paquetes proporcionan compatibilidad con las plantillas de Go para reutilizar la configuración. Los usuarios pueden crear agrupaciones basadas en plantillas precompiladas. Hay una paridad casi completa para plantillas, excepto para las funciones de usuario personalizadas.

Administración de compilaciones

dbx proporciona compatibilidad con la compilación a través pip wheel, Poesía y Flit. Los usuarios pueden especificar la opción de compilación en la build sección del archivo de deployment.yml un proyecto.

Las agrupaciones permiten a los usuarios compilar, implementar y ejecutar archivos Wheel de Python. Los usuarios pueden aprovechar la entradawhl integrada en el archivo databricks.yml de un conjunto.

Sincronización, implementación y ejecución de código

dbx habilita la carga de código por separado de la generación de recursos del área de trabajo, como los trabajos de Azure Databricks.

Las agrupaciones siempre cargan código y crean o actualizan los recursos del área de trabajo al mismo tiempo. Esto simplifica las implementaciones y evita las condiciones de bloqueo de los trabajos que ya están en curso.

Migración de un proyecto dbx a una agrupación

Después de tener en cuenta las limitaciones anteriores y las comparaciones de características entre dbx de Databricks Labs y los conjuntos de recursos de Databricks, está listo para migrar de dbx a los conjuntos.

Databricks recomienda que inicie una dbx migración del proyecto, mantenga dbx el proyecto en su carpeta original y que tenga una carpeta en blanco independiente en la que copie el contenido del proyecto original dbx. Esta carpeta independiente será la nueva agrupación. Puede encontrar problemas inesperados si comienza a convertir el dbx proyecto en su carpeta original a una agrupación y, a continuación, comete algunos errores o quiera empezar de nuevo desde el principio,

Paso 1: Instalación y configuración de la CLI de Databricks

Los conjuntos de recursos de Databricks están disponibles con carácter general en la CLI de Databricks, versión 0.218.0 y posteriores. Si ya ha instalado y configurado la versión 0.218.0 o posterior de la CLI de Databricks, vaya al paso 2.

Nota:

Las agrupaciones no son compatibles con las versiones 0.18 y posteriores de la CLI de Databricks.

Instale o actualice a la CLI de Databricks versión 0.218.0 o posterior. Consulte Instalación o actualización de la CLI de Databricks.
Configure la CLI de Databricks para la autenticación con las áreas de trabajo de Azure Databricks de destino, por ejemplo, mediante la autenticación de Tokens de acceso personal de Azure Databricks. Para ver otros tipos de autenticación de Azure Databricks, consulte Autenticación para la CLIde Databricks.

Paso 2: Crear el archivo de configuración de agrupación

Si usa un IDE como Visual Studio Code, PyCharm Professional o IntelliJ IDEA Ultimate que proporciona compatibilidad con archivos YAML y archivos de esquema JSON, puede usar el IDE no solo para crear el archivo de configuración de agrupación, sino para comprobar la sintaxis y el formato del archivo y proporcionar sugerencias de finalización de código, como se indica a continuación.

Visual Studio Code

Agregue compatibilidad con el servidor de lenguaje YAML a Visual Studio Code, por ejemplo, instalando la extensión YAML desde Visual Studio Code Marketplace.
Genere el archivo de esquema JSON de configuración del conjunto de recursos de Databricks mediante la CLI de Databricks para ejecutar el comando bundle schema y redirigir la salida a un archivo JSON. Por ejemplo, genere un archivo denominado bundle_config_schema.json dentro del directorio actual, como se indica a continuación:
```
databricks bundle schema > bundle_config_schema.json
```
Use Visual Studio Code para crear o abrir un archivo de configuración de agrupación en el directorio actual. Por convención, este archivo se denomina databricks.yml.
Agregue el siguiente comentario al principio del archivo de configuración de agrupación:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Nota:

En el comentario anterior, si el archivo de esquema JSON de configuración del conjunto de recursos de Databricks está en una ruta de acceso diferente, reemplace bundle_config_schema.json por la ruta de acceso completa al archivo de esquema.
Use las características del servidor de lenguaje YAML que agregó anteriormente. Para más información, consulte la documentación del servidor de lenguaje YAML.

PyCharm Professional

Genere el archivo de esquema JSON de configuración del conjunto de recursos de Databricks mediante la CLI de Databricks para ejecutar el comando bundle schema y redirigir la salida a un archivo JSON. Por ejemplo, genere un archivo denominado bundle_config_schema.json dentro del directorio actual, como se indica a continuación:
```
databricks bundle schema > bundle_config_schema.json
```
Configure PyCharm para reconocer el archivo de esquema JSON de configuración de agrupación y, a continuación, complete la asignación de esquema JSON siguiendo las instrucciones de Configuración de un esquema JSON personalizado.
Use PyCharm para crear o abrir un archivo de configuración de agrupación. Por convención, este archivo se denomina databricks.yml. A medida que escribe, PyCharm comprueba si hay sintaxis y formato de esquema JSON y proporciona sugerencias de finalización de código.

IntelliJ IDEA Ultimate

Genere el archivo de esquema JSON de configuración del conjunto de recursos de Databricks mediante la CLI de Databricks para ejecutar el comando bundle schema y redirigir la salida a un archivo JSON. Por ejemplo, genere un archivo denominado bundle_config_schema.json dentro del directorio actual, como se indica a continuación:
```
databricks bundle schema > bundle_config_schema.json
```
Configure IntelliJ IDEA para reconocer el archivo de esquema JSON de configuración de agrupación y, a continuación, complete la asignación de esquema JSON siguiendo las instrucciones de Configurar un esquema JSON personalizado.
Use IntelliJ IDEA para crear o abrir un archivo de configuración de agrupación. Por convención, este archivo se denomina databricks.yml. A medida que escribe, IntelliJ IDEA comprueba si hay sintaxis y formato de esquema JSON y proporciona sugerencias de finalización de código.

Paso 3: Convertir la configuración del proyecto dbx en databricks.yml

Convierta la configuración del archivo dbx de su proyecto .dbx/project.json en la configuración equivalente de la agrupación databricks.yml de su archivo. Para obtener más información, consulte Conversión de la configuración del proyecto dbx en databricks.yml.

Paso 4: convertir la configuración de implementación de dbx en databricks.yml

Convierta la configuración en la carpeta dbx proyecto conf en la configuración equivalente de la agrupacióndatabricks.yml del archivo. Para más información, consulte Conversión de la configuración de implementación de dbx a databricks.yml.

Paso 5: validar la actualización

Antes de implementar artefactos o ejecutar un trabajo de Azure Databricks, una canalización de Delta Live Tables o una canalización de MLOps, debe asegurarse de que el archivo de configuración de agrupación sea sintácticamente correcto. Para ello, ejecute el comando bundle validate desde la raíz del lote:

databricks bundle validate

Para obtener información sobre bundle validate, consulte Validar un lote.

Paso 6: implementar la agrupación

Para implementar los artefactos locales especificados en el área de trabajo remota, ejecute el comando bundle deploy desde la raíz del lote. Si no se especifica ninguna opción de comando, se usa el destino predeterminado declarado en el archivo de configuración de agrupación:

databricks bundle deploy

Para implementar los artefactos en el contexto de un destino específico, especifique la opción -t (o --target) junto con el nombre del destino tal como se declara en el archivo de configuración de agrupación. Por ejemplo, para un destino declarado con el nombre development:

databricks bundle deploy -t development

Para obtener información sobre bundle deploy, consulte Implementación de un lote.

Sugerencia

Puede vincular trabajos y canalizaciones definidos por agrupación a trabajos y canalizaciones existentes en el área de trabajo de Azure Databricks para mantenerlos sincronizados. Consulte Enlazar recursos de agrupación.

Paso 7: ejecutar las pruebas

Para ejecutar un trabajo o una canalización específicos, ejecute el comando bundle run desde la raíz del lote. Debe especificar el trabajo o la canalización declarados en el archivo de configuración de agrupación. Si no se especifica la opción -t, se usa el destino predeterminado declarado en el archivo de configuración de agrupación. Por ejemplo, para ejecutar un trabajo denominado hello_job en el contexto del destino predeterminado:

databricks bundle run hello_job

Para ejecutar un trabajo denominado hello_job en el contexto de un destino declarado con el nombre development:

databricks bundle run -t development hello_job

Para obtener información sobre bundle run, consulte Ejecución de un trabajo o una canalización.

(Opcional) Paso 8: configuración del paquete para CI/CD con GitHub

Si usa GitHub para CI/CD, puede usar Acciones de GitHub para ejecutar los comandos databricks bundle deploy y databricks bundle run automáticamente, en base a los eventos específicos de flujo de trabajo de GitHub y otros criterios. Consulte Ejecución de un flujo de trabajo de CI/CD con una agrupación de recursos de Databricks y Acciones de GitHub.

Conversión de la configuración del proyecto dbx en databricks.yml

Para dbx, la configuración del proyecto está de forma predeterminada en un archivo denominado project.json en la carpeta del proyecto.dbx. Consulte Referencia del archivo de proyecto.

En el caso de las agrupaciones, las configuraciones de agrupación están de forma predeterminada en un archivo denominado databricks.yml dentro de la carpeta raíz del lote. Consulta Configuración de agrupaciones de recursos de Databricks.

Para un archivo conf/project.json con el siguiente contenido de ejemplo:

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

El archivo correspondiente databricks.yml es el siguiente:

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

Los objetos siguientes del archivo anterior conf/project.jsoneste ejemplo no se admiten en los archivos databricks.yml y no tienen ninguna alternativa:

inplace_jinja_support
storage_type

Los siguientes objetos permitidos adicionales en los archivos conf/project.json no se admiten en los archivos databricks.yml y no tienen ninguna solución alternativa:

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

Conversión de la configuración de implementación de dbx en databricks.yml

Para dbx, la configuración de implementación se encuentra de forma predeterminada en un archivo dentro de la carpeta del proyectoconf. Consulte Referencia del archivo de implementación. El archivo de configuración de implementación tiene de forma predeterminada uno de los siguientes nombres de archivo:

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

En el caso de las agrupaciones, la configuración de implementación se encuentra de forma predeterminada en un archivo denominado databricks.yml dentro de la carpeta raíz del lote. Consulta Configuración de agrupaciones de recursos de Databricks.

Para un archivo conf/deployment.yml con el siguiente contenido de ejemplo:

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"