Implementación de una aplicación de Databricks

Después de crear y desarrollar la aplicación de Azure Databricks, impleméntela para que sea accesible en el área de trabajo de Azure Databricks. La implementación compila la aplicación, instala dependencias y la ejecuta mediante la configuración definida en los archivos del proyecto. Puede implementar aplicaciones mediante la interfaz de usuario de Azure Databricks o la CLI de Databricks.

Lógica de implementación

Databricks Apps admite la implementación de aplicaciones que usan Python, Node.jso una combinación de ambos. Esto permite arquitecturas flexibles, como un front-end de Node.js con un back-end de Python.

Durante la implementación, el proceso de compilación comprueba si hay un package.json archivo en la raíz del directorio de la aplicación para determinar si se usa Node.js. Si está presente, incluye pasos de compilación específicos del nodo junto con los pasos de Python. La lógica de implementación sigue este patrón:

Si package.json está presente:

1. Ejecute npm install:
2. Instale Python dependencias:
   • Si requirements.txt existe, ejecute pip install -r requirements.txt
   • Si requirements.txt no existe y ambos pyproject.toml y uv.lock existen, ejecute uv sync para instalar dependencias.
3. Ejecutar npm run build (si se define un script build en package.json)
4. Ejecute el comando especificado en app.yamlo npm run start si no se especifica ningún comando.

Si package.json no está presente:

1. Instale Python dependencias:
   • Si requirements.txt existe, ejecute pip install -r requirements.txt
   • Si requirements.txt no existe y ambos pyproject.toml y uv.lock existen, ejecute uv sync para instalar dependencias.
2. Ejecute el comando especificado en app.yamlo python <my-app>.py si no se especifica ningún comando.

Preparación para la implementación

Antes de implementar la aplicación, compruebe que el proyecto incluye los componentes necesarios:

• Script principal : el archivo de punto de entrada, como app.py o app.js.
• Archivo opcional app.yaml : si la aplicación requiere un comando personalizado o variables de entorno, incluya un app.yaml archivo para configurar la ejecución. Vea Configurar la ejecución de la aplicación de Databricks con app.yaml.
• Dependencias : asegúrese de que todas las dependencias están disponibles. Consulte Administración de dependencias para una aplicación de Databricks.
• Secretos o valores de entorno : si usa la env sección de app.yaml, compruebe que los secretos a los que se hace referencia o los orígenes externos están configurados y accesibles correctamente. Consulte Incorporación de recursos a una aplicación de Databricks.

Además, asegúrese de que la entidad de servicio de la aplicación tiene acceso a la carpeta de código fuente.

Elección de un origen de implementación

Puede implementar aplicaciones de Databricks desde los orígenes siguientes:

• Carpeta del área de trabajo: suba archivos de la aplicación a una carpeta del área de trabajo y despliegue desde allí. Este es el método de implementación estándar. Consulte Implementación desde una carpeta del área de trabajo.
• Repositorio de Git : configure un repositorio de Git para una aplicación e implemente directamente sin cargar archivos en el área de trabajo. La aplicación lee el código de la referencia de Git configurada (rama, etiqueta o confirmación) cada vez que se implementa. Consulte Implementación desde un repositorio de Git.

Puede cambiar entre el área de trabajo y los orígenes de Git para la misma aplicación en cualquier momento. Consulte Actualizar o volver a implementar la aplicación.

Implementación de la aplicación

En las secciones siguientes se describe cómo implementar desde una carpeta del área de trabajo o directamente desde un repositorio de Git.

Implementación desde una carpeta del área de trabajo

Interfaz de usuario de Databricks

Para implementar una aplicación desde la interfaz de usuario de Azure Databricks:

1. Cargue los archivos de la aplicación en el área de trabajo de Azure Databricks. Para obtener instrucciones, consulte Importación de un archivo.
2. En el área de trabajo de Databricks, haga clic en el Conmutador de aplicaciones y seleccione Aplicaciones de Databricks.
3. Seleccione la aplicación en la columna Nombre .
4. Haga clic en Implementar y seleccione la carpeta del área de trabajo donde cargó los archivos de la aplicación.
5. Haga clic en Seleccionar y, a continuación, en Implementar.

CLI de Databricks

Para implementar una aplicación mediante la CLI:

1. Abra un terminal y vaya al directorio que contiene los archivos de la aplicación.

2. Cargue los archivos de la aplicación en el área de trabajo de Azure Databricks mediante el comando sync. Reemplace la ruta de acceso por la ubicación del área de trabajo donde desea cargar los archivos.

   databricks sync --watch . /Workspace/Users/my-email@org.com/my-app
   

   La --watch marca mantiene el proceso de sincronización en ejecución y carga automáticamente los cambios al modificar archivos localmente. Para excluir archivos o directorios específicos de la sincronización, agréguelos a un .gitignore archivo en el directorio de la aplicación local. Los archivos comunes que se van a excluir son node_modules/, .env, __pycache__/, .DS_Storey cualquier archivo de datos grande o artefactos de compilación.

3. Compruebe la carga viendo los archivos del área de trabajo. Haga clic en el selector de aplicaciones >Análisis e IA; luego, haga clic en Espacio de trabajo y vaya al directorio que creó para su aplicación.

4. Implemente la aplicación mediante la ejecución del comando siguiente. Reemplace el nombre de la aplicación y la ruta de acceso del código fuente por los valores.

   databricks apps deploy my-app-name \
      --source-code-path /Workspace/Users/my-email@org.com/my-app
   

   La CLI muestra el progreso de la implementación y confirma cuándo se está ejecutando la aplicación.

Implementación desde un repositorio de Git

Para implementar una aplicación desde un repositorio de Git, agregue el repositorio en el nivel de aplicación y, a continuación, especifique la referencia de Git al implementarla. El repositorio de Git debe contener los archivos de la aplicación, incluidas app.yaml, las dependencias y el punto de entrada. Se admiten todos los principales proveedores de Git, incluidos GitHub, GitLab y Bitbucket. También puede implementar aplicaciones respaldadas por Git mediante la interfaz de usuario, la CLI, la API o los conjuntos de automatización declarativos.

Interfaz de usuario de Databricks

Para configurar e implementar una aplicación desde Git:

1. Cargue los archivos de la aplicación en un repositorio de Git.
2. En el área de trabajo de Databricks, haga clic en el Conmutador de aplicaciones y seleccione Aplicaciones de Databricks.
3. Seleccione una aplicación existente para editar o haga clic en + Crear aplicación y, a continuación, en Crear una aplicación personalizada. Consulte Creación de una aplicación personalizada de Databricks.
4. En el paso Configurar Git , escriba la dirección URL del repositorio de Git (por ejemplo, https://github.com/org/repo) y seleccione un proveedor de Git.
5. Para una nueva aplicación, escriba la referencia Git (rama, etiqueta o confirmación) y, para los repositorios de GitHub, habilite opcionalmente Auto deploy on push events. Consulte Habilitación de implementaciones automáticas de Git.
6. Haga clic en Crear aplicación o en Guardar para volver a la página de información general de la aplicación.
7. En el caso de los repositorios privados, la entidad de servicio de la aplicación debe tener configurada una credencial de Git. En la página de información general de la aplicación, haga clic en Configurar credenciales de Git. Debe tener CAN MANAGE permisos en la aplicación para agregar una credencial de Git. Los repositorios públicos no requieren una credencial de Git. Para obtener instrucciones para cada proveedor, consulte Conexión del proveedor de Git a Databricks.

A continuación, implemente la aplicación:

1. En la página de información general de la aplicación, haga clic en Implementar.
2. Seleccione Desde Git.
3. En Referencia de Git, escriba el nombre de rama, la etiqueta o la confirmación SHA (por ejemplo, main, v1.0.0o un hash de confirmación).
4. En Tipo de referencia, especifique el tipo de referencia, como una rama, etiqueta o confirmación.
5. (Opcional) En Ruta de acceso del código fuente, escriba una ruta de acceso a un directorio específico dentro del repositorio. La aplicación trata ese directorio como directorio de nivel superior y no puede acceder a los archivos fuera de él. Si no especifica una ruta de acceso, Databricks usa la raíz del repositorio.
6. (Opcional) Para desplegar automáticamente con cada commit en esa rama, habilite Despliegue automático en eventos push. Debe establecer una rama para vigilar. Opcionalmente, puede incluir una ruta de acceso de código fuente para establecer una ruta de acceso distinta de la raíz del repositorio. Consulte Habilitación de implementaciones automáticas de Git.
7. Haga clic en Implementar.

CLI de Databricks

Para implementar una aplicación desde Git mediante la CLI:

1. Cargue los archivos de la aplicación en un repositorio de Git.

2. Configure el repositorio de Git en la aplicación al crear la aplicación o agréguelo a una aplicación existente. Los proveedores admitidos incluyen gitHub, gitHubEnterprise, gitLab, gitLabEnterpriseEditionbitbucketCloud, bitbucketServer, , azureDevOpsServicesy awsCodeCommit.

   Para crear una nueva aplicación con un repositorio de Git configurado, use el comando create :

   databricks apps create my-app \
      --json '{"git_repository": {"url": "https://github.com/org/repo", "provider": "gitHub"}}'
   

   Para agregar o actualizar un repositorio de Git en una aplicación existente, use el comando create-update :

   databricks apps create-update my-app \
      --json '{"update_mask": "git_repository", "git_repository": {"url": "https://github.com/org/repo", "provider": "gitHub"}}'
   

3. En el caso de los repositorios privados, configure una credencial de Git para la entidad de servicio de la aplicación. Debe tener CAN MANAGE permisos en la aplicación para agregar una credencial de Git. Los repositorios públicos no requieren una credencial de Git.

   Para agregar una credencial de Git a la entidad de servicio de la aplicación mediante la interfaz de línea de comandos (CLI), ejecute:

   databricks git-credentials create --json '{
     "git_provider": "gitHub",
     "git_email": "your-email@example.com",
     "personal_access_token": "YOUR_TOKEN",
     "principal_id": YOUR_SP_ID,
     "name": "GitHub credentials for SP"
   }'
   

   Reemplace por YOUR_SP_ID el identificador de entidad de servicio de la aplicación. Para obtener instrucciones para obtener un token de acceso personal para cada proveedor, consulte Conexión del proveedor de Git a Databricks.

4. Implemente la aplicación especificando la referencia de Git. Puede especificar un branch, tago commit (estos son mutuamente excluyentes). Opcionalmente, incluya source_code_path para implementar desde un subdirectorio dentro del repositorio.

   databricks apps deploy my-app \
      --json '{"git_source": {"branch": "main"}}'
   

   Para implementar una etiqueta o confirmación específicas:

   databricks apps deploy my-app \
      --json '{"git_source": {"tag": "v1.0.0"}}'
   

   databricks apps deploy my-app \
      --json '{"git_source": {"commit": "abc123def456"}}'
   

   Para realizar la implementación desde un subdirectorio dentro del repositorio:

   databricks apps deploy my-app \
      --json '{"git_source": {"branch": "main", "source_code_path": "apps/my-app"}}'
   

   La CLI muestra el progreso de la implementación y confirma cuándo se está ejecutando la aplicación.

En el caso de las referencias de rama o etiqueta, Azure Databricks implementa la confirmación más reciente de esa rama o etiqueta. En el caso de las referencias SHA de commit, Azure Databricks siempre implementa ese commit específico. Si la credencial de Git de la entidad de servicio no es válida o ha expirado, se produce un error en la implementación.

Habilitación de implementaciones automáticas de Git

Al habilitar implementaciones automáticas, Azure Databricks crea un webhook en el repositorio de GitHub y vuelve a implementar la aplicación cada vez que la rama configurada recibe una nueva confirmación. La aplicación implementada permanece sincronizada con el repositorio sin pasos manuales. Los repositorios están limitados a 20 webhooks (250 para GitHub Enterprise).

Las implementaciones automáticas requieren la siguiente configuración:

• La aplicación Azure Databricks GitHub debe estar instalada en el repositorio.
• El repositorio debe ser privado. Databricks no admite implementaciones automáticas desde repositorios públicos.
• La entidad de servicio de la aplicación debe tener una credencial de Git con acceso al repositorio. Consulte Conexión del proveedor de Git a Databricks.

Para habilitar implementaciones automáticas, configure GitHub como proveedor de Git y habilite Auto deploy on push events. Puede hacerlo en cualquiera de los siguientes lugares:

• El paso Configurar Git del Asistente para crear aplicaciones personalizadas. Consulte Creación de una aplicación personalizada de Databricks.
• La notificación de implementación automática en una aplicación existente o mediante la reconfiguración de la configuración de la aplicación. Siga los pasos descritos en Implementación desde un repositorio de Git.

La referencia de Git debe ser un nombre de rama. Las etiquetas no son compatibles con las implementaciones automáticas.

Para deshabilitar los despliegues automáticos, haga clic en el distintivo Despliegue automático de una aplicación existente y deshabilite Despliegue automático en eventos push. También puede volver a configurar la configuración en Configuración de la aplicación.

Imponer implementaciones solo desde Git

Los administradores del área de trabajo pueden requerir que todas las aplicaciones de un área de trabajo se implementen desde repositorios de Git. Vaya a Configuración>Aplicaciones> y active Permitir solo implementaciones de aplicaciones desde Git. Esta opción está desactivada de forma predeterminada.

Al aplicar implementaciones de Git:

• Los usuarios deben configurar un repositorio de Git antes de crear una aplicación.
• Los usuarios solo pueden implementar desde Git, no desde carpetas del área de trabajo.
• Databricks deshabilita las plantillas de aplicación en el área de trabajo.
• Los usuarios no pueden quitar un repositorio de Git de las aplicaciones que tienen una.
• Las aplicaciones existentes siguen ejecutándose, pero los usuarios no pueden implementarlas ni iniciarlas de nuevo a menos que la aplicación tenga un repositorio de Git.

Comportamiento posterior a la implementación

Una vez que se complete la implementación, Azure Databricks inicia la aplicación según lo definido en command en su archivo app.yaml o, de forma predeterminada, ejecuta python app.py. La página de información general de la aplicación muestra el estado actual y proporciona acceso a los registros, el historial de implementación y la información del entorno.

Para ver la salida de la aplicación implementada, haga clic en el vínculo de la aplicación.

Vaya a la pestaña Registros para depurar y supervisar en tiempo de ejecución. Consulte Registro y supervisión de aplicaciones de Databricks.

Actualizar o volver a implementar la aplicación

Vuelva a implementar la aplicación después de realizar cambios en el código fuente o la configuración. La reimplementación aplica las actualizaciones más recientes sin volver a crear la aplicación. Puede volver a implementar desde el área de trabajo o el repositorio de Git en cualquier momento.

Redistribuir desde una carpeta del espacio de trabajo

Para volver a desplegar desde una carpeta del área de trabajo:

1. Actualice los archivos de la aplicación en la carpeta del área de trabajo.
2. Seleccione la aplicación y haga clic en Implementar.
3. Si la ruta de acceso del código fuente ha cambiado o cambia de un origen de Git, haga clic en la flecha situada junto a Implementar y seleccione Implementar con otro origen.

Reimplementación desde un repositorio de Git

Para volver a implementar desde un repositorio de Git:

1. Inserte los cambios en el repositorio de Git.
2. En el área de trabajo de Azure Databricks, seleccione la aplicación y haga clic en Deploy. Si la referencia de Git ha cambiado o va a cambiar de un origen del área de trabajo, haga clic en la flecha situada junto a Implementar y seleccione Implementar con otro origen.

Para actualizar el repositorio de Git mediante la CLI o la API, use el comando create-update . Al quitar el repositorio de Git de la aplicación, se obliga la implementación desde el área de trabajo.

Solución de problemas de implementación

Si la aplicación no se puede implementar o no se ejecuta según lo previsto, pruebe los pasos de solución de problemas siguientes:

• Compruebe los registros de los mensajes de error o la salida en tiempo de ejecución.
• Valide la app.yaml sintaxis y la configuración.
• Compruebe que los secretos y las variables de entorno en la sección env se resuelven correctamente.
• Confirme que todas las dependencias necesarias se incluyen o instalan.
• Si su área de trabajo utiliza Private Link o políticas de red de salida restringida, verifique que los dominios necesarios estén en la lista de permitidos. Las entradas de la lista de salida permitidas que faltan son una causa común de errores de implementación en entornos de Private Link. Consulte Implementar aplicaciones en entornos de Private Link.

Para las implementaciones del repositorio de Git:

• En el caso de los repositorios privados, compruebe que la entidad de servicio de la aplicación tiene configurada una credencial de Git.
• Compruebe que la dirección URL del repositorio de Git es correcta y que la referencia de Git (rama, etiqueta o confirmación) existe en el repositorio.
• Si un administrador del área de trabajo aplica implementaciones solo de Git, no puede implementar ni iniciar una aplicación a menos que tenga configurado un repositorio de Git.
• Si implementa desde la CLI, la API o los conjuntos de automatización declarativa, cree primero la aplicación y luego agregue la credencial de Git al principal de servicio de la aplicación.

Pasos siguientes

• Registro y supervisión de aplicaciones de Databricks
• Configuración de permisos para una aplicación de Databricks
• Configuración de la ejecución de aplicaciones de Databricks con app.yaml