Configuración de la app

Dos archivos controlan cómo se inicia tu app de AppKit y a qué se conecta: app.yaml (comportamiento en runtime y variables de entorno) y databricks.yml (recursos de Databricks). A cada app se le asigna una URL fija al crearla, que no se puede modificar.

Archivos de configuración

app.yaml controla el comportamiento en runtime (comando de inicio y variables de entorno):

command: ["npm", "run", "start"]
env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres
  - name: WAREHOUSE_ID
    valueFrom: sql-warehouse

El command es una secuencia (array), no una cadena de shell. No se admite la expansión de variables de entorno en command, salvo para DATABRICKS_APP_PORT.

databricks.yml declara los recursos de Databricks, las variables y los destinos de despliegue:

resources:
  apps:
    my-app:
      resources:
        - name: postgres
          postgres:
            branch: ${var.postgres_branch}
            database: ${var.postgres_database}
            permission: CAN_CONNECT_AND_CREATE

Las variables como ${var.postgres_branch} se resuelven a partir de la sección variables de databricks.yml o de los flags de la CLI en el momento del despliegue.

Para ver la referencia completa de app.yaml específica de AppKit, incluidos los resource bindings de plugins, consulta Configuración de AppKit.

Manifiesto de plugins

Cada app de AppKit cuenta con un archivo appkit.plugins.json que declara qué plugins están activos y qué recursos de Databricks necesitan. Este archivo se genera automáticamente al ejecutar:

npx @databricks/appkit plugin sync --write

Esto se ejecuta automáticamente durante npm run dev y npm run build. Haz commit del archivo junto con tu código. La CLI y el pipeline de despliegue lo usan para aprovisionar recursos.

Recursos

Las apps acceden a los servicios de Databricks mediante recursos declarados. Cada recurso tiene un name en databricks.yml. Usa ese nombre como valor de valueFrom en app.yaml.

Las plantillas de AppKit usan nombres convencionales para los recursos gestionados por plugins:

Encontrarás otros tipos de recursos (tablas de Unity Catalog, conexiones, índices de AI Search (antes Vector Search), experimentos de MLflow, entre otros) en la documentación oficial de recursos.

Secrets

Ninguno de los dos archivos de configuración contiene el valor del secret. databricks.yml declara un recurso que apunta a un secret scope y a una clave que tú defines, y app.yaml hace referencia a ese recurso por su nombre. La plataforma inyecta el valor descifrado en runtime.

1. Almacena el valor del secret con la Databricks CLI:

   databricks secrets create-scope my-app-secrets
   databricks secrets put-secret my-app-secrets MY_SECRET --string-value "..."

2. Declara el recurso de tipo secret en databricks.yml:

   resources:
     apps:
       my-app:
         resources:
           - name: my-secret # etiqueta para este recurso (definida por el usuario)
             secret:
               scope: my-app-secrets # nombre del secret scope de Databricks
               key: MY_SECRET # clave dentro de ese scope
               permission: READ

3. Vincúlalo a una variable de entorno en app.yaml:

   env:
     - name: MY_SECRET
       valueFrom: my-secret # hace referencia al nombre del recurso anterior, no al valor del secret

En runtime, MY_SECRET contiene el valor descifrado del secret. Ninguno de los dos archivos contiene el valor en sí.

Variables de entorno

La plataforma inyecta estas variables automáticamente en runtime:

Las variables personalizadas se definen en app.yaml, dentro de env. Usa value para texto sin formato y valueFrom para nombres de recursos. Nunca incluyas secrets en value.

Modelo de autenticación

Cada app cuenta con un service principal dedicado. Databricks inyecta DATABRICKS_CLIENT_ID y DATABRICKS_CLIENT_SECRET automáticamente en runtime y elimina el service principal cuando se elimina la app.

La autorización de usuario (Public Preview) reenvía el token del usuario autenticado mediante la cabecera HTTP x-forwarded-access-token. Los ámbitos (por ejemplo, sql, genie, files) se configuran en la interfaz del workspace. Los plugins integrados de Genie y Model Serving de AppKit lo usan automáticamente. Consulta contexto de ejecución para ver la implementación en AppKit, o autorización de apps para conocer todos los detalles de la plataforma.

Compute

Los tamaños de compute son MEDIUM (el predeterminado), LARGE y XLARGE (la disponibilidad varía según el workspace). Define el tamaño en la interfaz del workspace o con la opción --compute-size en databricks apps create y databricks apps update. Consulta la documentación de Databricks Apps para conocer las vCPU, la RAM y las DBU de cada tamaño.

Restricciones

• No hay sistema de archivos persistente (usa Lakebase Postgres, DBSQL o UC Volumes para la persistencia)
• Los archivos de más de 10 MB hacen que falle el despliegue
• SIGTERM concede 15 segundos antes de SIGKILL
• Runtime: Ubuntu 22.04, Node 22, Python 3.11

Consulta Mejores prácticas para ver las pautas sobre la gestión del apagado, el manejo seguro de los secrets y las redes.

Estados de la aplicación

Qué sigue

Consulta Desarrollo de apps para conocer la configuración local, los flags de despliegue y la API completa de plugins, o explora el catálogo de plantillas para ver patrones completos.