Configuração do app

Dois arquivos controlam como seu app AppKit é iniciado e a que ele se conecta: app.yaml (comportamento de runtime e variáveis de ambiente) e databricks.yml (recursos do Databricks). Cada app recebe uma URL fixa no momento da criação, que não pode ser alterada.

Arquivos de configuração

O app.yaml controla o comportamento em runtime (comando de inicialização e variáveis de ambiente):

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

O command é uma sequência (array), e não uma string de shell. Não há suporte para expansão de variáveis de ambiente em command, exceto para DATABRICKS_APP_PORT.

databricks.yml declara os recursos, as variáveis e os destinos de implantação do Databricks:

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

Variáveis como ${var.postgres_branch} são resolvidas a partir da seção variables do databricks.yml ou de flags da CLI no momento do deploy.

Para a referência completa do app.yaml específico do AppKit, incluindo vinculações de recursos de plugins, consulte Configuração do AppKit.

Manifesto de plugins

Cada app do AppKit possui um appkit.plugins.json que declara quais plugins estão ativos e quais recursos do Databricks eles exigem. Esse arquivo é gerado automaticamente ao executar:

npx @databricks/appkit plugin sync --write

Isso é executado automaticamente durante npm run dev e npm run build. Faça o commit dele junto com o seu código. A CLI e o pipeline de implantação o utilizam para provisionar recursos.

Recursos

Os apps acessam serviços do Databricks por meio de recursos declarados. Cada recurso tem um name em databricks.yml. Use esse nome como o valor de valueFrom no app.yaml.

Os templates do AppKit usam nomes convencionais para recursos gerenciados por plugins:

Outros tipos de recursos (tabelas do Unity Catalog, conexões, índices do AI Search (antigo Vector Search), experimentos do MLflow, entre outros) estão listados na documentação oficial de recursos.

Secrets

Nenhum dos arquivos de configuração contém o valor do secret. O databricks.yml declara um recurso que aponta para um secret scope e uma chave definidos por você, e o app.yaml referencia esse recurso pelo nome. A plataforma injeta o valor descriptografado em runtime.

1. Armazene o valor do secret com a Databricks CLI:

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

2. Declare o recurso de secret no databricks.yml:

   resources:
     apps:
       my-app:
         resources:
           - name: my-secret # rótulo deste recurso (definido pelo usuário)
             secret:
               scope: my-app-secrets # nome do secret scope do Databricks
               key: MY_SECRET # chave dentro desse scope
               permission: READ

3. Vincule-o a uma variável de ambiente no app.yaml:

   env:
     - name: MY_SECRET
       valueFrom: my-secret # referencia o nome do recurso acima, não o valor do secret

Em runtime, MY_SECRET contém o valor descriptografado do secret. Nenhum dos dois arquivos contém o valor em si.

Variáveis de ambiente

A plataforma injeta estas variáveis automaticamente em runtime:

Variáveis personalizadas ficam no app.yaml, em env. Use value para texto simples e valueFrom para nomes de recursos. Nunca coloque secrets em value.

Modelo de autenticação

Cada app recebe um service principal dedicado. O Databricks injeta DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET automaticamente em runtime e exclui o service principal quando o app é excluído.

A autorização de usuário (Public Preview) encaminha o token do usuário autenticado pelo cabeçalho HTTP x-forwarded-access-token. Os escopos (por exemplo, sql, genie, files) são configurados na interface do workspace. Os plugins nativos do AppKit para Genie e Model Serving já usam esse mecanismo automaticamente. Consulte contexto de execução para ver a implementação no AppKit ou autorização de apps para os detalhes completos da plataforma.

Compute

Os tamanhos de compute são MEDIUM (padrão), LARGE e XLARGE (a disponibilidade varia conforme o workspace). Defina o tamanho na interface do workspace ou pela flag --compute-size nos comandos databricks apps create e databricks apps update. Consulte a documentação do Databricks Apps para ver os valores de vCPU, RAM e DBU de cada tamanho.

Restrições

• Sem sistema de arquivos durável (use Lakebase Postgres, DBSQL ou UC Volumes para persistência)
• Arquivos maiores que 10 MB fazem a implantação falhar
• O SIGTERM dá 15 segundos antes do SIGKILL
• Runtime: Ubuntu 22.04, Node 22, Python 3.11

Consulte Boas práticas para orientações sobre tratamento de encerramento, boas práticas com secrets e rede.

Status do app

Próximos passos

Consulte Desenvolvimento de apps para configuração local, flags de deploy e a API completa de plugins, ou explore o catálogo de templates para ver padrões completos.