O conteúdo do Databricks Voices é criado e publicado por funcionários do Databricks que desejam compartilhar seus próprios aprendizados e conhecimento do Databricks. Este conteúdo complementa a documentação oficial do produto Databricks encontrada em outras seções deste site.
Azure DevOps com Pacotes de Automação Declarativa: Guia de Integração Passo a Passo
O estabelecimento de um processo confiável de Integração Contínua/Implantação Contínua (CI/CD) é fundamental para gerenciar com eficácia o ciclo de vida de suas cargas de trabalho de dados e AI no Azure Databricks. No entanto, com inúmeras opções de configuração e uma plataforma em constante evolução, a grande pergunta é: "Por onde devo começar?" Este blog abrangente elimina a complexidade para descrever uma abordagem de CI/CD recomendada para o Azure Databricks.
Focamos nas práticas recomendadas mais recentes que suportam uma governança robusta com o mínimo de sobrecarga administrativa, mesmo quando suportamos várias equipes em uma infraestrutura compartilhada. Ela é adaptada para desenvolvedores que gostam de trabalhar na interface de usuário do workspace do Databricks, embora também ofereça compatibilidade total com IDEs como Visual Studio Code.
A abordagem recomendada usa Pacotes de Automação Declarativa (DABs; anteriormente conhecidos como Pacotes de Ativos do Databricks) para implantação. Os pacotes se integram perfeitamente às pastas Git do Databricks para controle de versão, ao Azure DevOps para automação e às conexões de serviço do Azure DevOps para conectividade Databricks. No final do blog, comparo as abordagens de conexão de serviço do DevOps e do Databricks OIDC para integrar o DevOps e o Databricks para sua referência.
Por fim, seguiremos uma estratégia de ramificação baseada em tronco simples, mas eficaz no DevOps. O teste será implantado automaticamente depois que as solicitações pull da ramificação de recursos forem aprovadas e merge na principal. A implantação de produção da ramificação principal dependerá de uma implantação de teste bem-sucedida e exigirá o passo de aprovação adicional, que implementaremos.
Este blog cobre uma ampla variedade de tópicos, mas, ao orientá-lo para as escolhas ideais, você economizará tempo e esforço significativos a longo prazo. O conteúdo está dividido em três partes:
- Alinhando seus requisitos de infraestrutura e governança
- Configuração de um processo de desenvolvimento de pacote com versão
- Configuração de um pipeline do Azure DevOps para implantação em staging e produção
Parte 1: alinhe seus requisitos de infraestrutura e governança
Cada organização precisa decidir qual nível de separação e organização é necessário para workspaces do Databricks, ambientes de implantação, Unity Catalog, projetos DevOps e repositórios Git. Não existe uma resposta certa para todas as organizações, e só podemos tocar nas considerações antes de passar para o tópico do artigo.
tópico | Consideração | Para este artigo |
|---|---|---|
Ambientes | Três é comum, mas alguns podem usar dois e outros quatro ou mais. | Usaremos: dev , staging e prod . |
Workspace do Databricks | Geralmente, os Workspace estão alinhados com os ambientes. As organizações maiores também podem organizar unidades de negócio em Workspace separados. Uma vantagem de três Workspace é que o administrador do Workspace pode habilitar livremente recursos de prévia e outras configurações no Workspace "dev" e ter certeza de que não afetará as cargas de trabalho de staging e prod. | Vamos mostrar como várias equipes independentes podem usar dois Workspace ( |
Catálogos | Existem muitas estratégias para organizar seus dados no Unity Catalog. | Vamos nomear nossos catálogos de |
Projetos do Azure DevOps | Organizações menores usam um único projeto para simplificar a configuração, enquanto organizações maiores podem exigir vários projetos para ter limites rígidos entre repository e aprovadores. | Usaremos um projeto chamado |
Repository do Git | Há prós e contras para um único "mono repo" versus múltiplos repos baseados em equipe ou domínio. | Como já selecionamos um projeto DevOps baseado em equipe, usaremos seu único repo default . |
Nota: Encorajo-o a seguir o exemplo e a estratégia organizacional descritos neste blog para ver como todo o processo funciona em conjunto de forma eficaz. Depois, você pode considerar o que aprendeu, como as necessidades de governança e organização da sua empresa podem diferir e fazer as alterações necessárias. Depois de fazer essas escolhas, vejamos nossa estratégia organizacional visualmente.
Dentro da nossa organização “corporativa” (BU1), a Equipe 2 lida com dados de RH, e todo o resto é tratado pela Equipe 1. Essas duas equipes trabalharão de forma independente em nossos Workspace bu1-dev e bu1-prod compartilhados. Para que isso funcione bem, é importante observar que um ou mais indivíduos devem ter a confiança de ambas as equipes para atuar como Administradores do workspace. Se isso puder ser organizado, o gerenciamento da infraestrutura será simplificado; caso contrário, as equipes 1 e 2 devem ser separadas em seus próprios Workspace de dev/prod.
No futuro, outra divisão (BU2) pode ser adquirida que compartilhe o mesmo diretório Entra ID, mas opte por ter Workspace e infraestrutura de DevOps separados. Não tem problema, e é por isso que prefixaremos nossos nomes de catálogo no Unity Catalog (por exemplo, bu1_dev, bu2_dev).
Alinharemos com a abordagem “mono repo” dentro de cada projeto DevOps e organizaremos ainda mais nosso código usando Pacotes de Automação Declarativa. Neste blog, usaremos um único pacote “Hello World” para ilustrar como funcionam os processos recomendados de desenvolvimento e CI/CD. Na prática, você terá muitos pacotes para um determinado domínio de dados (por exemplo, finanças) e todos eles podem ser versionados no mesmo repo. Usaremos um único pipeline DevOps para implantações de staging e produção, mas você pode escolher uma estratégia de pipeline diferente.
Criar um grupo de variáveis para cada estágio
Os pacotes do Databricks e as pastas do Git funcionam perfeitamente em conjunto com o Azure DevOps e o prepararam para o sucesso em seu processo de CI/CD. Vamos lá.
Configuração Inicial do Azure DevOps
Isso é bastante simples e envolve a criação do projeto Azure DevOps da equipe e a inicialização do repo. Você não precisa criar nenhuma Branch — usaremos a main Branch integrada e criaremos nossas recurso Branch no Databricks usando a interface de integração com Git integrada.
Crie seu projeto, inicialize a branch principal e, em seguida, vá para o repo e copie a URL do repository para sua área de transferência para o próximo o passo.
Criar uma account vinculada para acessar o repo
No workspace do Databricks, cada desenvolvedor cria sua própria credencial de account vinculada ao Azure DevOps (Microsoft Entra) , permitindo que eles autentiquem no repositório Git. Faça isso agora no seu workspace “dev” na página Configurações > Usuário > Contas vinculadas . Você não precisa fazer isso no seu workspace prod porque não há integração com o Git necessária lá (o DevOps enviará o código para prod).
Criar uma pasta Git que aponta para o repo
Em seu diretório Home , cada desenvolvedor cria sua própria pasta Git que aponta para o repo da equipe. Este o passo é feito por cada desenvolvedor apenas uma vez. Clique em Criar > Pasta Git .
Cole o URL do repo do seu projeto do Azure DevOps (ainda deve estar na sua área de transferência) e clique em Criar pasta Git .
Você notará que as pastas do Git têm propriedades especiais na interface do usuário do Workspace, incluindo estes dois botões.
Clique em Abrir no editor e observe que uma nova tab do navegador será aberta com a sua pasta Git em um novo modo de autoria "focado". Discutiremos isso em um momento.
Não usaremos esta view agora, então feche a tab do navegador que acabamos de abrir.
Agora, clique no botão de Branch Git conforme mostrado abaixo.
Na interface do usuário de integração Git, clique em Criar Branch , atribua um nome à sua ramificação de recurso (por exemplo, features/initial_work_on_hello_world) e, em seguida, clique em Criar .
Clique no botão “X” no canto superior direito da caixa de diálogo de integração do Git para fechá-la. Usando suas credenciais do Microsoft Entra, a integração do Databricks Git criou a branch em seu Azure DevOps Repo e mudou você para ela na IU do Workspace, como mostrado abaixo.
Navegando pela UI do Workspace
A partir de abril de 2026, existem duas prévias de UI que afetam o comportamento dos menus mostrados neste artigo. Peça ao administrador do seu workspace que acesse Previews e pesquise “tree”. Por default, a nova pré-visualização de contexto de “autoria” (a primeira abaixo) está habilitada, e a nova view em árvore para o navegador de arquivos não está. Recomendamos habilitar ambos para que você possa seguir o artigo e porque ambos facilitam o trabalho com pastas Git e pacotes de ativos. Aqui estão os links de documentação para referência:
Criar e implantar seu primeiro pacote para “Dev”
Na sua pasta Git, clique em Criar e escolha Pacote .
Existem diferentes abordagens para organizar sua cópia de desenvolvimento dos pacotes na sua pasta Git. Uma lista simples de pacotes, conforme mostrado abaixo, funciona bem. Você também pode criar pastas na pasta Git e organizar seus pacotes dentro delas.
Para os fins deste blog, digite um nome como hello_world para o nome do pacote e escolha a opção Projeto vazio . Depois de clicar em Criar , você verá uma lista de recursos complementares para o seu pacote. Escolha Adicionar uma nova definição de job , digite um título de job como Update Event Table .
Não clique no botão Adicionar e implantar; em vez disso, clique na seta para baixo e escolha Apenas adicionar, implantar depois . Se você clicou acidentalmente em Adicionar e implantar, tudo bem, mas você tem um Job implantado no dev que ainda não tem nada para fazer.
Adicione algum código e configure seu job
Vamos adicionar algum código ao nosso projeto para ver o processo de CI/CD em ação. Para os propósitos deste blog, você pode fazer o download do notebook Hello_World.ipynb deste local e, em seguida, importá-lo para sua pasta de pacotes conforme mostrado abaixo.
Certifique-se de importá-lo para a pasta de pacote de ativos hello_world (não a pasta recurso), como mostrado abaixo.
Ainda no arquivo job.yml , descomente as linhas 8 a 19 no arquivo YAML do Job usando a combinação de teclas Alternar comentário de linha key (você pode obter uma lista de atalhos de teclado no menu de contexto, como mostrado abaixo). Após descomentar as linhas, faça as duas alterações mostradas em amarelo. Esteja ciente de que os caminhos diferenciam maiúsculas de minúsculas. Você renomeou a primeira tarefa em seu job e a apontou para o notebook que você acabou de importar.
Abra o notebook Hello_World e observe algumas coisas. A primeira célula define um widget chamado “catalog” sem default. O notebook que você importou renderizou o widget de catálogo na parte superior, mas ele está vazio para que você possa preencher o catálogo no qual deseja gravar. Para este laboratório, criaremos um catálogo chamado bu1_dev.
Insira seu valor para o campo de widget “catalog” como mostrado abaixo. Observe que também há um widget chamado “job_run_id” que não tem valor default.
Vá em frente e faça a execução do notebook agora clicando no botão Execução de tudo na parte superior. Você deve usar o compute Serverless para este artigo para não ter que esperar um cluster começar.
Observe na saída e no Catalog Explorer que uma linha foi inserida, incluindo o horário e o usuário que fez a execução do código.
No workspace, clique no botão implantar do pacote (o “foguete”), aguarde até que a lista Recursos do pacote termine de carregar e, em seguida, clique no botão Implantar .
Clique em Implantar novamente para confirmar que a definição do seu Job atualizado deve ser implantada.
Parabéns! Você verá uma mensagem informando que foi implantado com sucesso no seu destino de desenvolvimento.
Clique em workspace na navegação lateral para ver o que foi implantado e onde.
O Databricks implanta o pacote de ativos na sua pasta Home/.bundle. Isso é representado pelo ambiente de implantação de dev destacado em azul abaixo. Neste ponto, nada está no controle de versão do Azure DevOps.
Clique em Jobs e pipelines na navegação lateral.
A implantação do seu pacote também criou um Job. Observe que o título do Job tem [dev your_user_id] prefixado.
Abra o Job e clique na tab Tarefas . Revise as informações abaixo.
As mensagens (1) e (4) indicam que este job foi criado por uma implantação de pacote e que você não deve editar esse job na interface do usuário (você pode editá-lo, mas suas edições serão apagadas na próxima vez que você implantar seu pacote). O nome da sua tarefa de notebook (2) corresponde ao que você editou no arquivo Update Event Table.job.yml. O caminho do notebook (3) que você especificou no arquivo job.yml está sendo usado. O job está definido para ser executado como você (5). Atualmente, nenhum parâmetro de job (6) é exibido – trabalharemos nisso em seguida. Há um botão Desconectar da fonte (7) na interface do usuário.
Implantação vinculada à origem é um recurso opcional da implantação de pacote e está habilitado por default para a implantação de dev. Este é um recurso conveniente porque o seu job de dev referencia o notebook do seu Home/bu1-team1/hello_world folder no workspace. Uma cópia não é enviada para a pasta de implantação do pacote para dev (Home/.bundle/hello_world). O que é conveniente sobre a implantação vinculada à origem no dev é que você pode fazer correções iterativas em seu notebook e executar seu Job novamente a partir da interface do usuário de Jobs sem precisar reimplantar seu pacote de ativos .
Volte para a tab Execuções e clique no botão Execução agora . Use o compute de Job Serverless para que você não precise esperar um cluster de Job começar.
O job falhará porque o notebook não consegue encontrar um valor para a variável de catálogo. Ao executar o notebook manualmente, você digitou um valor no widget de catálogo, mas quando o notebook foi executado por um job, o widget de catálogo estava vazio e também não havia valor default especificado na primeira célula.
Não queremos um valor default para o catálogo porque pretendemos executar uma execução deste notebook em ambientes de desenvolvimento, preparação e produção. Queremos enviar nomes específicos de catálogos ao job com base no ambiente em que ele está sendo executado. Vamos configurar isso em seguida.
Parametrizando o nome do catálogo passado para o seu notebook
Nesta seção, você trabalhará em dois arquivos, que você fará o download em breve. Mas vamos primeiro entender como eles funcionam juntos:
-
Configuração de pacote (databricks.yml) - Você definirá uma variável personalizada catalog_var e alguns valores específicos do ambiente para ela ( bu1_dev , bu1_stg e bu1_prd ). Isso também envolverá a definição de nossos alvos de ambiente de implantação (dev, stage e prod).
-
Configuração de job (job.yml) - Você definirá um catálogo de parâmetros de job para aceitar o valor da variável de pacote durante a implantação, e configuraremos um base_parameter de tarefa de job para que o parâmetro de job esteja disponível para o nosso notebook. Para obter mais informações sobre esses tópicos, clique nos links atrás dos termos acima. Visualmente, o cabeamento da variável/parâmetro parece com isso:
Como você pode ver, o arquivo de configuração do pacote (databricks.yml) contém informações gerais de configuração nas linhas 1 a 12 e alvos de ambiente a partir da linha 14. Cada destino (dev, staging e prod) define as características do pacote para esse ambiente. Isso inclui como acessar o workspace do Databricks, quais nomes/valores de variáveis passar e qual modo de implantação usar para o ambiente.
Definimos uma variável de pacote catalog_var e a definimos como bu1_dev ao implantar no ambiente de destino “dev”. Vamos defini-lo como bu1_stg para o ambiente de staging, e assim por diante. Esses destinos ambientais são definidos por você. Você pode ter quantos quiser e nomeá-los como quiser. No entanto, o nome do destino do pacote deve corresponder ao valor especificado no seu pipeline do Azure DevOps para os passos de validação e implantação do pacote, conforme você verá.
A configuração do modo de implantação tem dois valores: desenvolvimento e produção. O destino de desenvolvimento usa o modo de desenvolvimento, enquanto o de teste (staging) e o de produção (prod) usam o modo de produção. O modo de desenvolvimento prefixa seus jobs implantados com [dev <your_user_name>] para que sejam mais fáceis de distinguir caso você e seus colegas estejam trabalhando em cópias separadas do mesmo pacote/pipeline em desenvolvimento. O modo de desenvolvimento também permite a implantação vinculada à origem conforme descrito anteriormente, facilitando a iteração na fiação do pacote e no código do notebook. Aqui está uma referência completa para o comportamento da configuração mode: do pacote.
Para economizar seu tempo, aqui está o código completo para o exemplo que estamos seguindo. Copie-os para seus arquivos Event Table Job.yml e databricks.yml.
Home/bu1-team1/hello_world/recurso/Update Event Table.job.yml
Especifique seu email na linha realçada abaixo.
Observe que o código inclui um segundo parâmetro para capturar o ID de execução do job para que possamos gravá-lo na tabela de eventos. A sintaxe {{job.run_id}} captura o ID de execução dinamicamente. Estamos anexando isso à strings job_run_id_, que você verá quando esse parâmetro for gravado na tabela. Você pode alterar a definição do parâmetro e remover o prefixo, se desejar. Como esse parâmetro é definido dinamicamente pelo job, você não precisa criar uma variável de bundle para ele como fez com catalog_var.
resources:
jobs:
Update_Event_Table:
name: Update Event Table
queue:
enabled: true
parameters:
- name: catalog
default: ${var.catalog_var}
- name: job_run_id
default: 'job_run_id_{{job.run_id}}'
tasks:
- task_key: notebook_task_1
notebook_task:
notebook_path: ../Hello_World.ipynb
base_parameters:
catalog: ${var.catalog_var}
job_run_id: 'job_run_id_{{job.run_id}}'
email_notifications:
on_failure:
- your_email@example.com
trigger:
periodic:
interval: 1
unit: DAYS
Home/bu1-team1/hello_world/databricks.yml
Edite os URLs do workspace para corresponderem ao seu ambiente e altere os nomes dos catálogos, se necessário. Vale observar que estamos usando o mesmo workspace para dev e staging neste blog, mas você pode usar três workspaces separados para dev/staging/prod, se desejar. Basta fazer as edições abaixo.
# Declarative Automation Bundle (DAB) configuration; more info here:
# https://docs.databricks.com/en/dev-tools/bundles/settings.html
bundle:
name: 'hello_world'
include:
- resources/*.yml
- resources/*/*.yml
# Define custom variables; more info here:
# https://docs.databricks.com/en/dev-tools/bundles/reference#variables
variables:
catalog_var:
description: Custom variable containing the target catalog
default: ''
targets:
# TODO - adjust the catalog names and workspace URLs to match your deployment
# The "dev" target used by the bundle deploy feature
dev:
mode: development
default: true
variables:
catalog_var: bu1_dev
workspace:
host: https://adb-###########.#.azuredatabricks.net
# The "staging" target used by Azure DevOps
staging:
mode: production
variables:
catalog_var: bu1_stg
workspace:
host: https://adb-###########.#.azuredatabricks.net
root_path: /Workspace/devops/staging/bu1-team1/.bundle/${bundle.name}
# The "prod" target used by Azure DevOps
prod:
mode: production
variables:
catalog_var: bu1_prd
workspace:
host: https://adb-###########.#.azuredatabricks.net
root_path: /Workspace/devops/prod/bu1-team1/.bundle/${bundle.name}
Depois de atualizar as URLs do workspace em seu arquivo databricks.yml, clique no botão recarregar em seu navegador da Web.
Isso é necessário porque temos a fonte do arquivo com texto de espaço reservado (##########) para o URL do workspace, e a interface do usuário do pacote o vê assim que você faz a edição. Isso o confunde na próxima etapa, pois ele pensará que não há destinos válidos para implantação. Portanto, depois de fazer suas edições e recarregar a interface do usuário do workspace em seu navegador da Web, continue para a próxima etapa.
Clique no botão implantar do pacote e clique no menu suspenso Destino .
Observe a mensagem informando que não há suporte à implantação em outros Workspace. Na verdade, isso significa que o recurso de implantação do pacote foi projetado apenas para implantação local, no workspace em que você está.
Usaremos apenas o botão de implantação de pacote para enviar o pacote localmente para nosso destino de desenvolvimento. Usaremos o Azure DevOps para implantar nossos pacotes nos ambientes de preparação e produção.
Pressione a key Escape (ESC) para fechar o menu suspenso e clique no botão Implantar .
Clique em Implantar novamente e analise as mensagens de saída abaixo.
Depois que seu DAB for implantado no dev, vá para sua página de Job e clique no botão de execução para começar seu Job. Depois de começar, você pode clicar em seu Job e vê-lo sendo executado.
Quando terminar, clique no seu job e observe que os parâmetros de catálogo e ID de execução de job foram criados e populados conforme esperado, e seu código adicionou outra linha à tabela bu1_dev.default.test_events.
Com seu código funcionando no dev, vamos enviá-lo para o Git.
Clique no botão Workspace (a “pasta”) e reserve alguns minutos para se familiarizar com a nova interface do usuário do Workspace. Clique no botão “Todos os arquivos” e volte ao botão “Pasta” ao lado dele. Observe que isso simplesmente alterna se você está na pasta do pacote DAB. Além disso, observe as tabs de arquivos abertos à direita. É bom poder ter vários arquivos abertos ao mesmo tempo, mesmo em pastas/subpastas diferentes, e alternar entre eles sem ter que navegar pela estrutura de pastas à esquerda.
Quando estiver pronto, clique no botão Git ao lado da sua pasta de pacote.
Vá em frente e adicione alguns comentários e clique em commit e enviar para o seu primeiro projeto DAB!
Na mensagem na parte superior da tela, clique no link criar uma solicitação pull para criar sua solicitação pull aqui, para maior comodidade. Isso o levará diretamente ao Azure DevOps, onde você poderá preencher os detalhes da sua Pull request!
Clique em Criar para criar seu PR e pare por aqui.
Vamos configurar o pipeline de implantação do Azure DevOps. Dessa forma, quando entrarmos no DevOps para aprovar e fazer merge do seu PR, devemos ver nosso novo pipeline de DevOps implantar automaticamente seu código inicial de hello world no staging.
Parte 3 - Criando o Pipeline de Implantação do Azure DevOps para CI/CD
Como uma revisão, nossos requisitos de CI/CD são:
-
Os PRs de desenvolvedor aprovados devem ser mesclados no main e implantados automaticamente no staging. Aqui, o código merge pode ser testado no contexto mais amplo da plataforma de dados, potencialmente junto com outras alterações aprovadas aguardando a promoção para prod.
-
Então, após aprovação adicional, a ramificação principal é implantada em prod.
Começaremos configurando o processo de staging, que envolve a criação de uma conexão de serviço DevOps, mapeando-a para uma Service Principal (SP) do Databricks gerenciada por ID do Entra, criando uma pasta de implantação de Workspace para staging e concedendo as permissões de SP na pasta e no catálogo bu1_stg no Unity Catalog. Repetiremos esse processo para prod. Em seguida, criaremos os grupos de variáveis do DevOps, o aprovador/portão de ambiente de prod e o pipeline para reunir tudo. Depois disso, podemos testar!
Aqui está uma visão geral dos passos que você realizará duas vezes (uma vez para staging e uma vez para prod), exceto onde indicado:
Passo | Onde | O quê | Por que |
|---|---|---|---|
1 | Azure DevOps > Configurações do projeto | Criar a Conexão de Serviço | Facilita uma conexão segura e flexível entre DevOps e Azure Databricks para implantar pacotes em staging e prod. Para uma comparação com a abordagem baseada em OIDC mais recente do Databricks, consulte o tópico no final deste artigo. |
2 | Portal do Azure | Criar o registro de aplicativo | |
3 | Workspace do Databricks > Configurações | Criar o Service Principal | Este será o proprietário dos recursos implantados pelo DevOps; você precisa dar a este principal acesso de escrita à pasta de implantação e privilégios no Unity Catalog. |
4 | Workspace do Databricks > Pastas | Crie seu SP e quaisquer permissões de grupo de administração na pasta | Ao implantar em pastas baseadas em equipe, você tem a capacidade de definir permissões para que cada equipe possa view seu próprio código implantado, se necessário. |
5 | Workspace do Databricks > Catálogo | Forneça ao SP e a outros grupos permissões apropriadas no Unity Catalog. | Tabelas e esquemas criados pelo SP são de propriedade do SP. |
6 | Azure DevOps > Biblioteca | Criar um grupo de variáveis para cada estágio | Eles mantêm a variável |
7 | Azure DevOps > Ambientes | Você criará isso apenas para "prod" | Isso será usado para configurar o portão de aprovação para a implantação de produção. |
8 | Azure DevOps > Repo | Crie uma pasta raiz chamada "/.cicd" ou similar para o código do pipeline. | Isso fornece separação entre o código do pipeline e o código do pacote. Considere exigir aprovadores especiais para alterações de código em arquivos nesta pasta raiz. |
9 | Azure DevOps > Pipelines | Criar um pipeline de lançamento para seu projeto hello_world | Isso implantará seu código em staging e prod após as aprovações necessárias. |
10 | Teste! | Verifique as mensagens escritas na tabela de eventos nos catálogos de preparação e produção | Você pode considerar como organizar seus pacotes e pipelines de implantação. Um pipeline pode implantar vários pacotes, ou você pode mantê-los em uma relação 1:1 para um controle mais refinado. |
Crie a conexão de serviço de staging e o registro do aplicativo
Vá para Configurações do projeto > Pipelines > Conexões de serviço do seu projeto DevOps e clique em Criar conexão de serviço .
Escolha a opção Azure Resource Manager e clique em Próximo .
Importante! Para Tipo de identidade , você verá duas opções.
Escolha a opção Registro de aplicativo ou identidade gerenciada (manual) destacada abaixo ( não escolha a marcada como recomendada).
Isso permite que você nomeie claramente o Registro de Aplicativo do Azure que suporta a Conexão de Serviço do seu DevOps. Isso é importante porque o nome do registro do aplicativo Azure é sincronizado com o nome do Service Principal do Databricks, e é isso que sua equipe de dados procurará ao conceder permissões em seus recursos do Unity Catalog e Workspace.
Se você escolher a outra opção, o nome do Registro do Aplicativo será gerado automaticamente pelo Azure como <devops_org>-<project>-<GUID>, sem qualquer indicação de que seja para testes ou para produção. Você não pode renomeá-lo e isso tornará difícil atribuir permissões posteriormente. A abordagem manual que recomendamos neste artigo envolve mais alguns os passos, mas é sua melhor opção.
Nota: Ambas as abordagens envolvem a criação de um registro de Aplicativo em seu portal do Azure, portanto, se você não tiver permissões para fazer isso, receberá um erro e precisará trabalhar nesses os passos com alguém que tenha.
Depois de escolher Registro de aplicativo ou identidade gerenciada (manual) , preencha o Nome da conexão de serviço (por exemplo, bu1-team1-staging-svc-conn), a descrição e o ID do diretório (tenant) na seção Parte 1: informações básicas e clique em Avançar .
Isso levará você à Parte 2: Detalhes do registro do aplicativo .
Dica: para encontrar sua ID de tenant, clique no círculo da sua ID de usuário na barra de banner do portal DevOps e clique no link Trocar diretório . A ID do tenant será a string em Diretorio atual.
Neste ponto, você precisará manter a tela da Parte 2 aberta e abrir o Portal do Azure em outra tab. Você pode seguir os passos abaixo e vê-los ilustrados na imagem abaixo.
- Crie o Registro de Aplicativo (por exemplo,
bu1-team1-cicd-staging-app) no portal do Azure. - Copie o ID do Aplicativo (anteriormente chamado de ID do cliente) e adicione-o ao campo Conexão de serviço do DevOps Parte 2 rotulado como ID do aplicativo (cliente) .
- Enquanto estiver lá, preencha seu ID da inscrição . Você pode obter o ID da inscrição pesquisando Inscrições no Portal do Azure.
- Insira seu Nome da inscrição - não clique no botão Verificar e salvar ainda.
- De volta ao Portal do Azure na sua página de Registro de Aplicativo, clique em Gerenciar à esquerda.
- Em seguida, clique em Certificados e segredos .
- Clique na tab Credenciais federadas .
- Clique em Adicionar Credencial .
- Escolha Outro emissor .
- Copie a URL do Emissor da sua conexão de serviço em Parte 2 e cole-a no campo Emissor .
- Copie o Identificador de assunto e cole-o no campo Valor .
- Insira um nome para sua credencial (por exemplo,
bu1-team1-cicd-staging-fed-credential). - Clique em Adicionar .
- De volta à tela de conexão de serviço, marque a caixa Conceder permissão de acesso a todos os pipelines . Isso está ok porque significa que todos os pipelines de DevOps em nosso projeto de DevOps
bu1-team1. Se você estiver organizando as coisas de forma diferente, você sempre pode conceder acesso a esta conexão mais tarde.
Não clique em Verificar e salvar ainda! Você precisa dar ao seu Registro de Aplicativo permissão para ler sua inscrição. Se você clicou de qualquer maneira, observe atentamente a mensagem de erro. Você verá que seu trabalho da Parte 1 foi salvo como um rascunho. Você pode voltar e concluir a Parte 2 depois de seguir os passos necessários.
Acesse o Portal do Azure e localize sua inscrição. Acesse Controle de acesso (IAM) e clique em Adicionar atribuição de função . Clique em Leitor em Nome e, em seguida, clique em Avançar . Mantenha a opção Atribuir acesso a definida como Usuário, grupo ou Service Principal e clique no link Selecionar membros . Encontre seu Service Principal (observação: o registro do aplicativo criado anteriormente criou um Service Principal em segundo plano com o mesmo nome, por exemplo, bu1-team1-cicd-staging-app), selecione-o e clique em Selecionar .
Clique em Revisar + Atribuir .
Agora volte ao Azure DevOps e à tela Editar conexão de serviço Parte 2 e clique no botão Verificar e salvar .
Parabéns! Esses são muitos passos, mas são necessários porque você precisa estabelecer uma relação de confiança entre seu projeto do Azure DevOps e seu Registro de Aplicativo/Service Principal do Portal do Azure; esses serviços nem todos confiam um no outro por default.
Agora vamos configurar a confiança entre nosso Registro de Aplicativo/Service Principal do Azure e o Service Principal do Databricks que fará a execução dos recursos que o Azure DevOps implantou em seu Workspace.
Criar o Service Principal do Databricks para Tarefas de CI/CD
Acesse seu workspace de preparo (neste artigo, usamos o workspace bu1-dev). Acesse Configurações do Workspace > Identidade e acesso > Service Principal e clique em Gerenciar . Clique em Adicionar Service Principal e, em seguida, clique no botão Adicionar novo .
Em Gerenciamento, escolha Gerenciado pelo Microsoft Entra ID e, em seguida, copie o ID do aplicativo do seu registro no aplicativo Azure.
A IU mostrada abaixo para a opção Gerenciado por Microsoft Entra ID mostra um campo para inserir o nome do service principal. Embora este campo permita que você insira e salve um valor, ele não será mantido, como você verá quando for pesquisar esse service principal na IU de permissões em todo o Databricks.
Dê a ele qualquer nome como bu1-team1-cicd-staging-sp (mas você verá que ele será alterado de volta para o nome do seu Registro de Aplicativo em breve) e clique em Adicionar .
Nota: é possível usar uma única Conexão de Serviço do Azure DevOps, Registro de Aplicativo Azure e Databricks Service Principal para todos os seus processos de CI/CD (incluindo implantações de staging e produção). No entanto, você notará que temos incluído o termo “staging” nos nomes desses recursos de CI/CD que criamos, para que você possa adicionar posteriormente as versões “prod” e ter uma governança mais precisa sobre seu processo de CI/CD.
Clique no seu Databricks SP após ele ser criado. Ele precisará dos direitos de acesso ao Workspace e acesso ao SQL , dependendo do seu código. Recomendo usar jobs Serverless, especialmente durante o desenvolvimento, para acelerar os testes de CI/CD por tentativa e erro. Se você usa jobs Serverless, não precisa atribuir o direito Permitir criação de cluster irrestrita .
Explore a tab Permissões . Isso permite que você decida quem pode gerenciar e usar o SP, não o que esse SP pode fazer em seu Workspace. Você pode considerar se uma equipe no ambiente de staging precisa fazer manualmente uma execução de um Job novamente por algum motivo. Nesse caso, dê a essa equipe a permissão USE.
Explore a tab Integração do Git . Esse recurso permite que sua entidade de serviço se conecte a um repo do Git, o que é necessário quando o Job é configurado para extrair o código do Notebook do Git durante a execução. Mas não estamos usando essa abordagem neste blog. Estamos configurando o DevOps para enviar o código do Notebooks e os recursos do pacote para cada ambiente. Deixe a integração do Git não configurada para a entidade de serviço.
Criar a pasta de implantação de staging
No workspace, crie um local de preparo onde o pipeline do Azure DevOps implantará seu código. Em seguida, clique com o botão direito nesta pasta e escolha o menu Compartilhar (Permissões) . Pesquise seu SP e conceda permissões de Pode gerenciar , conforme mostrado abaixo (lembre-se, como mencionado anteriormente, você está pesquisando o Registro de Aplicativo que criou no portal do Azure, que está sincronizado com o nome da Service Principal do Databricks que você acabou de criar).
Se você quiser que sua equipe de desenvolvimento veja o que foi implantado aqui, conceda-lhes permissões de View. Geralmente, desenvolvedores, equipes de QA e administradores não devem ter acesso de gravação à pasta de implantação de destino do pacote de preparação.
Atribuindo permissões do Unity Catalog à sua Service Principal
Existem algumas estratégias para criar e gerenciar permissões em catálogos e esquemas. Neste blog, criamos os catálogos manualmente e atribuímos permissões de Editor de Dados ao nosso SP. Também concedemos a permissão Gerenciar para que nosso SP possa remover tabelas e gerenciar permissões se fizermos isso em nosso código de job. Sinta-se à vontade para reavaliar e evoluir suas escolhas conforme necessário.
Dê permissão ao seu SP para criar ativos de dados em seu catálogo de estágios conforme mostrado abaixo.
Vá para o esquema default em seu catálogo de staging e observe que muitas dessas permissões são herdadas conforme o esperado. Veja as permissões em seu esquema bu1_stg.default. Observe que seu SP pode ler e gravar neste esquema, embora ele não seja o proprietário (você é o proprietário, pois ele foi criado quando você criou o catálogo).
Criar seu pipeline do Azure DevOps (bu1-team1-hello-world-pipeline.yml)
Queremos que o nosso pipeline de CI/CD tenha duas etapas:
-
DeployStaging - A execução é automática quando o código de uma Branch de recurso é aprovado e é feito merge na Branch principal.
-
DeployProd - execução após DeployStaging e após uma aprovação que você pode configurar. Usaremos grupos de variáveis do DevOps para armazenar as URLs do workspace e um ambiente do DevOps para definir o processo de aprovação que protege nosso deployment de produção.
Vá para o seu projeto DevOps > Pipelines > Biblioteca e clique no botão + Grupo de variáveis . Nomeie-o como stagingVariables (você fará referência a isso no primeiro estágio do seu pipeline) e adicione uma variável para DATABRICKS_HOST junto com uma URL apontando para o hostname do seu workspace de preparação (bu1-dev no exemplo deste artigo). Em seguida, clique em Salvar .
Repita o processo para outro grupo de variáveis chamado prodVariables , que você referenciará no segundo estágio do seu pipeline.
Vá para o seu projeto DevOps > Ambientes e clique no botão Criar ambiente . Nomeie-o como prod (você fará referência a isso na segunda etapa do seu pipeline), deixe Recurso definido como Nenhum e clique em Criar .
Em seguida, clique na tab Aprovações e verificações e clique na verificação de Aprovações . Para este artigo, vamos apenas escolher dois aprovadores, mas você pode configurar isso conforme necessário para sua organização.
Você não precisa criar um ambiente de staging, pois planejamos implantar automaticamente após o merge para main sem condições ou aprovações.
Vá para a página do seu projeto DevOps > Repos > Arquivos e crie uma nova pasta (por exemplo, .cicd ) e seu pipeline Hello World dentro dela.
Copie o YAML seguinte para ele e edite o valor azureSubscription nas linhas 33 e 102 para coincidir com o nome das suas Conexões de Serviço DevOps (sim, é confuso que precise do nome da conexão de serviço, mas ele pede o nome da inscrição). Revise os comentários e faça os outros ajustes necessários.
- Você também pode fazer download do arquivo deste link - https://github.com/databricks-solutions/databricks-dab-examples/blob/main/knowledge-base/azure-devops-cicd-example/bu1-team1-hello-world-pipeline.yml
# This triggers the pipeline on a commit to the 'main' branch
trigger:
branches:
include:
- main
# Prevents the pipeline from triggering on Pull Requests; only on merges
pr: none
stages:
# -----------------------------------------------
# Stage 1: Deploy to Staging (automatic on merge)
# -----------------------------------------------
# TODO - In the bundle validate/deploy steps below, change "workingDirectory"
# to the folder containing your databricks.yml and edit the target values if
# your choice differs from "staging" used in the example below.
- stage: DeployStaging
displayName: 'Deploy to Staging'
variables:
- group: stagingVariables
condition: |
eq(variables['Build.SourceBranch'], 'refs/heads/main')
jobs:
- job: deployStagingJob
pool:
vmImage: ubuntu-latest
steps:
- task: UsePythonVersion@0
inputs:
versionSpec: 3.11
- task: AzureCLI@2
displayName: 'Get Databricks Token (Staging)'
inputs:
# TODO - Change azureSubscription value to the name of your DevOps "staging" Service Connection
azureSubscription: bu1-team1-staging-svc-conn
scriptType: 'bash'
scriptLocation: 'inlineScript'
failOnStandardError: true
# Set the token as a pipeline variable for subsequent steps; note that the "echo"
# line does not print the token to the pipeline logs. The resource ID is the well-known
# Azure AD application ID for Databricks (same for all tenants).
inlineScript: |
set -e
DATABRICKS_TOKEN=$(az account get-access-token --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d --query "accessToken" -o tsv)
echo "##vso[task.setvariable variable=DATABRICKS_TOKEN]$DATABRICKS_TOKEN"
# Clone the repository so the bundle files are available to the pipeline agent
- checkout: self
displayName: 'Checkout repository'
# Install Python dependencies here if your bundle requires them
# For example:
# - script: pip install -r requirements.txt
# displayName: 'Install Python dependencies'
- script: |
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh
databricks --version
displayName: 'Install Databricks CLI'
- script: databricks bundle validate -t staging
displayName: 'Validate bundle for the "staging" environment'
env:
DATABRICKS_HOST: $(DATABRICKS_HOST)
DATABRICKS_TOKEN: $(DATABRICKS_TOKEN)
workingDirectory: $(Build.SourcesDirectory)/hello_world
- script: databricks bundle deploy -t staging
displayName: 'Deploy bundle to the "staging" environment'
env:
DATABRICKS_HOST: $(DATABRICKS_HOST)
DATABRICKS_TOKEN: $(DATABRICKS_TOKEN)
workingDirectory: $(Build.SourcesDirectory)/hello_world
# -----------------------------------------------
# Stage 2: Deploy to Production (requires approval in Azure DevOps)
# -----------------------------------------------
# TODO - In the bundle validate/deploy steps below, change "workingDirectory"
# to the folder containing your databricks.yml and edit the target values if
# your choice differs from "prod" used in the example below.
- stage: DeployProd
displayName: 'Deploy to Prod'
dependsOn: DeployStaging
condition: succeeded()
variables:
- group: prodVariables
jobs:
# A "deployment:" job (rather than a regular "job:") is required to
# connect to an Azure DevOps Environment and enable the approval gate.
- deployment: deployProdJob
displayName: 'Deploy to Prod'
pool:
vmImage: ubuntu-latest
# Setup the approval gate. The value for "environment" must match
# the Azure DevOps Environment name where approvals are configured.
environment: 'prod'
strategy:
runOnce:
deploy:
steps:
- checkout: self
- task: UsePythonVersion@0
displayName: 'Use Python 3.11'
inputs:
versionSpec: 3.11
- task: AzureCLI@2
displayName: 'Get Databricks Token (Prod)'
inputs:
# TODO - Change azureSubscription value to the name of your DevOps "prod" Service Connection
azureSubscription: bu1-team1-prod-svc-conn
scriptType: 'bash'
scriptLocation: 'inlineScript'
failOnStandardError: true
# Set the token as a pipeline variable for subsequent steps; note that the "echo"
# line does not print the token to the pipeline logs. The resource ID is the well-known
# Azure AD application ID for Databricks (same for all tenants).
inlineScript: |
set -e
DATABRICKS_TOKEN=$(az account get-access-token --resource 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d --query "accessToken" -o tsv)
echo "##vso[task.setvariable variable=DATABRICKS_TOKEN]$DATABRICKS_TOKEN"
# Install Python dependencies here if your bundle requires them
# For example:
# - script: pip install -r requirements.txt
# displayName: 'Install Python dependencies'
- script: |
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh
databricks --version
displayName: 'Install Databricks CLI'
- script: databricks bundle validate -t prod
displayName: 'Validate bundle for the "prod" environment'
env:
DATABRICKS_HOST: $(DATABRICKS_HOST)
DATABRICKS_TOKEN: $(DATABRICKS_TOKEN)
workingDirectory: $(Build.SourcesDirectory)/hello_world
- script: databricks bundle deploy -t prod
displayName: 'Deploy bundle to the "prod" environment'
env:
DATABRICKS_HOST: $(DATABRICKS_HOST)
DATABRICKS_TOKEN: $(DATABRICKS_TOKEN)
workingDirectory: $(Build.SourcesDirectory)/hello_world
Clique em Commit para salvá-lo na ramificação principal do seu repo.
Antes de criar o pipeline de DevOps e apontá-lo para este arquivo, vamos aprovar e fazer merge da solicitação pull inicial do Hello World DABs para que haja algum código para implantar.
No seu projeto Azure DevOps, clique em Repos > Pull requests e selecione a pull request que você criou anteriormente na UI de integração do Databricks Git.
Clique em Concluir e escolha suas opções de merge antes de clicar no botão Concluir merge .
Você pode verificar se o código do seu pacote agora está na branch principal.
Agora vamos criar o pipeline. Vá para o menu projeto > Pipelines > Pipelines e clique em Criar Pipeline . Escolha Azure Repos Git .
Escolha o repository da sua equipe e clique em Arquivo YAML do Azure Pipelines existente .
Insira o caminho para o arquivo do seu pipeline e clique em Continuar .
Antes de executar o pipeline, você precisa:
- Repita os passos anteriores para criar sua conexão de serviço de produção (
bu1-team1-prod-svc-conn), sua entidade de serviço do Databricks e a pasta de implantação no workspace de produção e as permissões para o catálogo de produção, ou - Comente todas as linhas do Estágio 2 em seu pipeline para evitar erros de validação.
Implantado em preparação
Quando tiver decidido, clique em execução.
Você não precisa definir nem alterar nada na próxima tela exibida.
Seu Job de implantação em staging entrará em execução. Na primeira vez em que estiver em execução, você verá uma mensagem solicitando permissão para acessar o grupo de variáveis de staging. Dê permissão a ele.
Quando a implantação de preparo terminar, vá encontrar seu Job e faça sua execução.
Verifique se os dados foram adicionados pelo service principal. Dependendo da parte da IU, você verá o ID ou nome do aplicativo do Registro de Aplicativo, conforme mostrado abaixo.
Embora a implantação do código, a execução do job e a escrita de dados na tabela tenham sido realizadas pelo SP do Registro de Aplicativo do Azure, foi o administrador do Workspace que o habilitou nas configurações do Workspace e o proprietário do Unity Catalog que lhe concedeu direitos de editor no esquema.
Implantando para produção
Quando você estiver pronto, clique no botão Revisar e aprove a execução do estágio de implantação de produção.
O seu pacote deve ser implantado no workspace de produção. Encontre o Job e execução, verifique o catálogo prod para ver se ele foi executado.
Parabéns! Se você chegou até aqui, agora é um campeão de CI/CD do Azure Databricks.
Comparando duas abordagens para a federação de identidades de Workload: conexões de serviço mediadas pelo Azure AD versus integração com OIDC do Databricks
A abordagem adotada para integrar o Azure DevOps e o Databricks neste blog usa conexões de serviço do Azure DevOps apoiadas por registro de aplicativos. Este é um padrão bem estabelecido para federar com segurança sua carga de trabalho de pipeline entre os dois serviços de cloud. Mas o Databricks introduziu recentemente uma abordagem alternativa baseada em OIDC. Como eles se comparam e qual é a melhor opção?
Ambas as abordagens usam protocolos seguros baseados em tokens (OIDC e OAuth). A diferença é o emissor. No blog, uso o recurso de conexão de serviço do DevOps, o que significa que o pipeline do DevOps (via tarefa AzureCLI@2) obtém um access token do Azure AD e o passa para a CLI do Databricks como DATABRICKS_TOKEN. Isso funciona bem quando seu pipeline também precisa acessar outros recursos do Azure (Storage, Key Vault, etc.) por meio do mesmo Service Principal.
O Databricks também oferece suporte a uma alternativa mais recente: federação de tokens OAuth (também chamada de federação de identidade de carga de trabalho ou OIDC). Com essa abordagem, o pipeline do Azure DevOps se autentica diretamente no Databricks — sem intermediário do Azure AD, sem conexões de serviço e sem etapa de recuperação de token explícita. Você cria uma política de federação no Service Principal do Databricks que confia no emissor OIDC da sua organização do Azure DevOps, e a CLI do Databricks gerencia a troca de token automaticamente usando o System.AccessToken integrada do pipeline.
Isso resulta em um pipeline mais simples (sem tarefa AzureCLI@2, sem conexões de serviço do Azure), mas ele só se autentica no Databricks — se você precisar acessar outros recursos do Azure, ainda precisará usar a outra abordagem de conexão de serviço mostrada neste blog. Para saber mais, consulte dev-tools/auth/provider-azure-devops.md na documentação da Databricks.
Aspecto | Abordagem 1: Autenticação mediada pelo Azure AD (este blog) | Abordagem 2: Federação OIDC nativa do Databricks (opção alternativa) |
|---|---|---|
Link do doc | Conectar ao Azure usando registro de aplicativo com federação de identidade de carga de trabalho | Habilitar a federação de identidade de carga de trabalho para Azure DevOps Pipelines |
Maturidade | Padrão bem estabelecido | Mais recente (Federação OAuth do Databricks) |
Protocolos usados | OIDC, OAuth 2.0, token do portador | OIDC → Databricks OAuth 2.0 |
Intermediário de autenticação | Azure AD (broker de tokens) | Nenhum (OIDC direto) |
Aquisição de tokens | Explícito | Automático pelo Databricks SDK ou Databricks CLI |
Azure CLI no pipeline | Obrigatório | Não necessário |
Conexões de serviço Azure | Necessário (um por env) | Não necessário |
Política de federação | No Azure AD (confia no Azure DevOps) | No SP do Databricks (confia no Azure DevOps) |
Complexidade | Dois saltos; 8 os passos de pipeline por estágio | Um hop; 2-3 os passos de pipeline por estágio |
Acesso aos recursos do Azure | O mesmo SP pode acessar outros recursos do Azure (key vault, e assim por diante). | Autentica apenas no Databricks |
Melhor quando |
|
|
O que é diferente | Ignora completamente o Azure AD. Uma política de federação é criada diretamente no Service Principal do Databricks que confia no emissor OIDC do Azure DevOps ( | |
Requer |
|