Migrar para o mecanismo de implantação direta

Os Pacotes de Automação Declarativa foram originalmente criados com base no provedor Terraform do Databricks para gerenciar implantações. No entanto, as versões da CLI do Databricks 0.279.0 e superiores dão suporte a dois mecanismos de implantação diferentes: terraform e direto. O mecanismo de implantação direta oferece vantagens significativas e não depende do Terraform.

Novos pacotes criados usando a CLI do Databricks versão 1.3.0 e superior usam o mecanismo de implantação direta por padrão. Bundles que ainda utilizam o motor de implantação do Terraform são automaticamente migrados para o motor direto, portanto nenhuma configuração é necessária. Veja Usando a implantação direta.

Para evitar a migração automática, defina bundle.engine: terraform ou DATABRICKS_BUNDLE_ENGINE=terraform. Isso impede a migração automática para todas as versões da CLI do Databricks. Nas versões da CLI Databricks até a 1.19, o motor Terraform continua sendo utilizado. Na versão 1.20.0 da linha de comando Databricks em diante, isso gera um erro. Consulte a implantação direta de um novo pacote.

Vantagens de implantação direta

O novo mecanismo de implantação direta usa o SDK do Databricks Go e tem os seguintes benefícios:

• Implantações mais rápidas: as implantações de pacote são até 40% mais rápidas.
• Validação e planejamento mais avançados e detalhados: diferenças detalhadas de alterações usando bundle plan -o json relatórios por campo explicando o que desencadeou uma ação específica.
• Planos reutilizáveis: bundle deploy --plan plan.json executa um plano criado anteriormente, garantindo que apenas ações aprovadas cheguem à produção e implantações mais rápidas, já que a etapa de cálculo do plano é ignorada.
• Configuração simples: problemas com firewalls, proxies e registros de provedor personalizado são evitados.
• Mais recursos: há suporte para recursos adicionais, como catálogos, locais externos, pontos de extremidade de Pesquisa de IA e espaços do Genie.
• Pastas imutáveis: os recursos podem ser implantados em uma pasta imutável, de somente leitura, para proteção contra adulterações e consistência da implantação. Veja immutable_folder.

Comece a usar a implantação direta

O mecanismo de implantação direta é o padrão para novos pacotes criados com o Databricks CLI versão 1.3.0 ou superior. Na versão 1.14 ou superior da CLI do Databricks, bundles que usam o motor Terraform são automaticamente migrados para o motor direto na implantação.

Nas versões 1.8 da CLI do Databricks e superiores, você pode migrar um bundle para o motor direto definindo engine: direct. Consulte a implantação direta de um novo pacote.

Implantar um novo pacote diretamente

Para definir explicitamente o mecanismo de implantação direta, faça uma das seguintes opções:

• Defina bundle.engine em seu databricks.yml:

  bundle:
    engine: direct
  

• Defina a variável de DATABRICKS_BUNDLE_ENGINE ambiente e implante:

  DATABRICKS_BUNDLE_ENGINE=direct databricks bundle deploy -t my_target
  

Se a configuração e a variável de ambiente forem definidas, a configuração terá precedência.

Comparação do mecanismo de implantação

O novo mecanismo de implantação direta se comporta principalmente da mesma forma que o mecanismo de implantação do Terrform, mas há algumas diferenças.

Cálculo da diferença de estado do recurso

Ao contrário do Terraform, que mantém um único estado de recurso (uma combinação de configuração local e estado remoto), o novo mecanismo mantém essas configurações separadas e apenas registra a configuração local em seu arquivo de estado.

O cálculo de diferenciação de estado de recursos é feito em duas etapas:

1. A configuração do pacote local é comparada à configuração de instantâneo usada para a implantação mais recente. O estado remoto não desempenha nenhum papel.
2. O estado remoto é comparado com a configuração instantânea usada para a implantação mais recente.

O resultado é que:

• databricks.yml as alterações de recurso nunca são ignoradas e sempre dispararão uma atualização.
• Os campos de recurso não tratados pela implementação não disparam um erro de resultado inconsistente. Esses recursos são implantados com êxito pelo mecanismo direto, mas isso pode resultar em um descompasso. Os recursos implantados são atualizados durante o próximo plano ou implantação.

Configurações removidas

Os dois mecanismos manipulam as configurações que você remove da configuração do pacote de forma diferente:

• Com o mecanismo Terraform, a remoção de um campo definido de databricks.yml deixa o valor correspondente inalterado na plataforma. O Terraform gerencia apenas os campos que estão explicitamente presentes na configuração, portanto, um campo removido retém qualquer valor que ele tinha no momento da última implantação.
• Com o mecanismo direto, remover um campo definido do seu databricks.yml faz o valor voltar para o valor padrão do recurso. Como o mecanismo direto compara sua configuração local com o instantâneo anterior, um campo que não está mais presente é tratado como uma alteração e o recurso é atualizado para seu valor padrão na próxima implantação.

Para manter um valor, defina-o explicitamente em sua configuração em vez de depender do valor implantado anteriormente.

Pesquisa de substituição de recursos

As substituições de recursos estão disponíveis para resolver IDs de recurso, por exemplo, ${resources.jobs.my_job.id}. Consulte Substituições. A resolução de substituições de recursos no mecanismo de implantação direta é executada em duas etapas:

1. As referências que apontam para campos presentes na configuração local são resolvidas para o valor fornecido na configuração local.
2. As referências que não estão presentes na configuração local são resolvidas a partir do estado remoto. Esse é o estado buscado usando a solicitação apropriada GET para um determinado recurso.

O esquema usado para resolver uma ${resource.*} substituição está no arquivo out.fields.txt. Os campos marcados como ALL e STATE podem ser usados para resolução local. Os campos marcados como ALL ou REMOTE podem ser usados para resolução remota.

Compatibilidade de recursos

Os recursos a seguir exigem o mecanismo de implantação direta e não têm suporte com o mecanismo de implantação do Terraform:

• Políticas de cluster
• Catálogos do Unity
• Locais externos do Catálogo do Unity
• Segredos do Catálogo Unity
• Espaços Genie
• Pools da instância
• Execuções de trabalho
• Endpoints de Busca com IA
• Serviços MCP
• Serviços de provedores de modelos
• Serviços de modelos
• Cronogramas de snapshots do Postgres

Além disso, o lifecycle.started campo está disponível apenas no mecanismo de implantação direta e somente para apps, clusterse sql_warehouses. Quando definido como true, ele implanta o recurso no modo iniciado. Veja o ciclo de vida.