Databricks Asset Bundles (DABs)

Databricks Asset Bundles (DABs) são a abordagem oficial de infraestrutura como código para Databricks. Permitem definir jobs, pipelines, clusters, notebooks, permissões e configurações em arquivos YAML versionados no Git, com suporte a múltiplos ambientes (dev, staging, prod).

Substituem abordagens ad-hoc de deploy via scripts REST e complementam/substituem Terraform para recursos específicos do Databricks.

Estrutura de um projeto DAB

meu-projeto/
├── databricks.yml              ← arquivo raiz do bundle
├── src/
│   ├── notebooks/
│   │   └── ingestao.py
│   ├── jobs/
│   │   └── pipeline_vendas.yml
│   └── pipelines/
│       └── dlt_pedidos.yml
├── resources/
│   └── clusters.yml
└── tests/
    └── test_transformacoes.py

databricks.yml: arquivo raiz

bundle:
  name: pipeline-vendas
 
workspace:
  host: https://adb-1234567890.1.azuredatabricks.net
 
# Variáveis substituíveis por ambiente
variables:
  env:
    default: dev
  catalog:
    default: dev_catalog
  schema:
    default: vendas
 
# Targets = ambientes de deploy
targets:
  dev:
    mode: development          # cria recursos com prefixo [dev <user>]
    default: true
    workspace:
      host: https://adb-dev.azuredatabricks.net
    variables:
      catalog: dev_catalog
 
  staging:
    mode: development
    workspace:
      host: https://adb-staging.azuredatabricks.net
    variables:
      catalog: staging_catalog
 
  prod:
    mode: production           # sem prefixo, permissões restritas
    workspace:
      host: https://adb-prod.azuredatabricks.net
    variables:
      catalog: gold
    run_as:
      service_principal_name: [email protected]
 
# Incluir recursos de outros arquivos YAML
include:
  - resources/jobs/*.yml
  - resources/pipelines/*.yml
  - resources/clusters/*.yml

Definindo um Job

# resources/jobs/pipeline_vendas.yml
resources:
  jobs:
    pipeline_vendas:
      name: "Pipeline Vendas [${var.env}]"
      description: "Ingestão e transformação do pipeline de vendas"
 
      schedule:
        quartz_cron_expression: "0 0 6 * * ?"   # 06:00 todo dia
        timezone_id: "America/Sao_Paulo"
        pause_status: UNPAUSED
 
      email_notifications:
        on_failure:
          - [email protected]
 
      tasks:
        - task_key: ingestao
          description: "Ingere dados brutos do CRM"
          notebook_task:
            notebook_path: ./src/notebooks/ingestao.py
            base_parameters:
              catalog: "${var.catalog}"
              schema: "${var.schema}"
          job_cluster_key: cluster_padrao
          timeout_seconds: 1800
 
        - task_key: transformacao
          depends_on:
            - task_key: ingestao
          python_wheel_task:
            package_name: pipeline_vendas
            entry_point: transformar
          job_cluster_key: cluster_padrao
 
        - task_key: qualidade
          depends_on:
            - task_key: transformacao
          notebook_task:
            notebook_path: ./src/notebooks/qualidade.py
          job_cluster_key: cluster_padrao
 
      job_clusters:
        - job_cluster_key: cluster_padrao
          new_cluster:
            spark_version: "15.4.x-scala2.12"
            node_type_id: Standard_D8ds_v5
            num_workers: 4
            data_security_mode: SINGLE_USER
 
      permissions:
        - level: CAN_VIEW
          group_name: time-bi
        - level: CAN_MANAGE_RUN
          group_name: engenharia-dados

Definindo um Pipeline DLT

# resources/pipelines/dlt_pedidos.yml
resources:
  pipelines:
    dlt_pedidos:
      name: "DLT Pedidos [${var.env}]"
      catalog: "${var.catalog}"
      schema: "${var.schema}"
      channel: CURRENT
 
      libraries:
        - notebook:
            path: ./src/pipelines/bronze_pedidos.py
        - notebook:
            path: ./src/pipelines/silver_pedidos.py
 
      clusters:
        - label: default
          num_workers: 2
 
      development: ${bundle.target == 'dev'}   # modo dev no target dev
      continuous: false                         # triggered (não contínuo)

Comandos CLI

# Instalar a CLI v2
pip install databricks-cli
 
# Autenticar (OAuth ou PAT)
databricks configure --token
 
# Validar o bundle sem fazer deploy
databricks bundle validate
 
# Deploy no target padrão (dev)
databricks bundle deploy
 
# Deploy em ambiente específico
databricks bundle deploy --target prod
 
# Executar um job após deploy
databricks bundle run pipeline_vendas
 
# Executar pipeline DLT
databricks bundle run dlt_pedidos
 
# Destruir recursos deployados (cuidado em prod)
databricks bundle destroy --target dev

Modo development vs. production

Aspecto	development	production
Prefixo nos recursos	[dev <user>] nome	nome (sem prefixo)
Clusters	Podem ter autotermination reduzido	Configuração completa
run_as	Usuário atual	Service principal
Pause de schedule	Automático (não dispara em dev)	Conforme configurado

CI/CD com DABs (GitHub Actions)

# .github/workflows/deploy.yml
name: Deploy Databricks Bundle
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Install Databricks CLI
        run: pip install databricks-cli
 
      - name: Deploy to Production
        env:
          DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
          DATABRICKS_TOKEN: ${{ secrets.DATABRICKS_TOKEN }}
        run: databricks bundle deploy --target prod

Variáveis e substituição

# No databricks.yml
variables:
  catalog:
    description: "Catalog de destino"
    default: dev_catalog
  env:
    default: dev
 
# Referenciar variável
table_name: "${var.catalog}.vendas.pedidos"
 
# Sobrescrever via CLI
databricks bundle deploy --var="catalog=gold" --target prod
 
# Bundle context variables (built-in)
# ${bundle.name}       → nome do bundle
# ${bundle.target}     → target atual (dev/prod/...)
# ${workspace.current_user.userName}

Ver também: databricks | databricks-jobs | databricks-lakeflow-pipelines | databricks-clusters | databricks-unity-catalog