Converter um pipeline num projeto de pacote

Pode converter um pipeline existente num projeto Declarative Automation Bundles . Os pacotes permitem que você defina e gerencie sua configuração de processamento de dados do Azure Databricks em um único arquivo YAML controlado pela fonte que fornece manutenção mais fácil e permite a implantação automatizada em ambientes de destino.

Para um tutorial que utiliza comandos databricks pipelines para criar um projeto de pipelines, e depois desdobra e executa um pipeline, veja Desenvolver pipelines com Pacotes de Automação Declarativa.

Visão geral do processo de conversão

As etapas que você executa para converter um pipeline existente em um pacote são:

1. Certifique-se de que tem acesso a uma pipeline configurada anteriormente que deseja converter num pacote.
2. Crie ou prepare uma pasta (de preferência em uma hierarquia controlada pelo código-fonte) para armazenar o pacote.
3. Gerar uma configuração para o bundle a partir do pipeline existente, usando a CLI Databricks.
4. Analise a configuração do pacote gerado para garantir que ela esteja completa.
5. Vincule o pacote ao pipeline original.
6. Implante o pipeline em um espaço de trabalho de destino usando a configuração do pacote.

Requerimentos

Antes de começar, você deve ter:

• A CLI do Databricks instalada na sua máquina de desenvolvimento local. A versão 0.218.0 ou superior do Databricks CLI é necessária para utilizar Pacotes de Automação Declarativa.
• A ID de um pipeline declarativo existente que você gerenciará com um pacote. Para saber como obter essa ID, consulte Obter uma definição de pipeline existente usando a interface do usuário.
• Autorização para o espaço de trabalho do Azure Databricks onde é executado o pipeline existente. Para configurar autenticação e autorização para as suas chamadas de CLI Databricks, consulte Autorizar acesso aos recursos Azure Databricks.
• Para o conjunto completo de privilégios necessários para criar, executar, atualizar e visualizar pipelines e os seus resultados, consulte Gerir identidades, permissões e privilégios para pipelines.

Etapa 1: configurar uma pasta para seu projeto de pacote

Você deve ter acesso a um repositório Git configurado no Azure Databricks como uma pasta Git. Você criará seu projeto de pacote neste repositório, que aplicará o controle do código-fonte e o disponibilizará para outros colaboradores por meio de uma pasta Git no espaço de trabalho correspondente do Azure Databricks. (Para obter mais detalhes sobre pastas Git, consulte Pastas Git do Azure Databricks.)

1. Vá para a raiz do repositório Git clonado em sua máquina local.

2. Em um local apropriado na hierarquia de pastas, crie uma pasta especificamente para seu projeto de pacote. Por exemplo:

   mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle
   

3. Altere o diretório de trabalho atual para esta nova pasta. Por exemplo:

   cd ~/source/my-pipelines/ingestion/events/my-bundle
   

4. Inicialize um novo pacote executando:

   databricks bundle init
   

   Responda às instruções. Quando ele for concluído, você terá um arquivo de configuração do projeto chamado databricks.yml na nova pasta base do seu projeto. Esse arquivo é necessário para implantar seu pipeline a partir da linha de comando. Para mais detalhes sobre este ficheiro de configuração, consulte Configuração dos Pacotes de Automação Declarativa.

Etapa 2: Gerar a configuração do pipeline

A partir deste novo diretório na árvore de pastas do seu repositório Git clonado, execute o comando Databricks CLI bundle generat, fornecendo o ID do seu pipeline como <pipeline-id>:

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

Quando executa o comando generate, ele cria um ficheiro de configuração de pacote para o seu pipeline na pasta do pacote resources e baixa os artefatos referenciados para a pasta src. A --profile (ou -p flag) é opcional, mas se tiver um perfil de configuração Databricks específico (definido no ficheiro .databrickscfg criado quando instalou a CLI Databricks) que prefere usar em vez do perfil padrão, forneça-o neste comando. Para obter informações sobre perfis de configuração do Databricks, consulte Perfis de configuração do Azure Databricks.

Etapa 3: Revise os arquivos de projeto do pacote

Quando o comando bundle generate for concluído, ele terá criado duas novas pastas:

• resources é o subdiretório do projeto que contém os arquivos de configuração do projeto.
• src é a pasta do projeto onde os arquivos de origem, como consultas e blocos de anotações, são armazenados.

O comando também cria alguns arquivos adicionais:

• *.pipeline.yml sob o subdiretório resources. Este arquivo contém a configuração e as definições específicas para seu pipeline.
• Ficheiros de origem, como consultas SQL no subdiretório src, copiados do seu pipeline existente.

├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

Passo 4: Ligar o fluxo de agrupamento ao fluxo de trabalho existente

Você deve vincular ou vincular a definição de pipeline no pacote ao pipeline existente para mantê-lo atualizado à medida que faz alterações. Para isso, execute o comando de vinculação de deployment bundle da CLI Databricks:

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> é o nome do gasoduto. Esse nome deve ser o mesmo que o valor da cadeia de caracteres prefixada do nome do arquivo para a configuração do pipeline no novo diretório resources. Por exemplo, se você tiver um arquivo de configuração de pipeline chamado ingestion_data_pipeline.pipeline.yml em sua pasta resources, deverá fornecêingestion_data_pipeline como o nome do pipeline.

<pipeline-ID> é o ID do seu pipeline. É o mesmo que copiaste como parte dos requisitos para estas instruções.

Etapa 5: Implementar o seu pipeline usando o seu novo pacote

Agora, implemente o seu pipeline bundle no seu espaço de trabalho alvo usando o comando deploy bundle da CLI Databricks:

databricks bundle deploy --target <target-name> --profile <profile-name>

O sinalizador --target é obrigatório e deve ser definido como uma cadeia de caracteres que corresponda a um nome de espaço de trabalho de destino configurado, como development ou production.

Se esse comando for bem-sucedido, agora você tem sua configuração de pipeline em um projeto externo que pode ser carregado em outros espaços de trabalho e executado, e facilmente compartilhado com outros usuários do Azure Databricks em sua conta.

Promover entre ambientes com alvos

Um conjunto define ambientes de implementação nomeados chamados alvos em databricks.yml, cada um apontando para o seu próprio espaço de trabalho, catálogo e valores de variáveis. Os targets são a forma como promoves o mesmo pipeline através do desenvolvimento, staging e produção, implementando código fonte idêntico em cada ambiente sucessivo sem o editar:

bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

A mode que define em cada destino altera o respetivo comportamento de implementação:

• mode: development marca um destino como uma implementação pessoal e ad hoc. Os recursos recebem um prefixo [dev username] e os agendamentos ficam em pausa por predefinição, para que o teu trabalho não afete ninguém.
• mode: production desativa essas predefinições de segurança. Combinado com run_as, permite-lhe gerir o pipeline como um principal de serviço em vez de uma conta individual, por isso as execuções não falham quando alguém sai da equipa ou muda de função. O Azure Databricks recomenda um principal de serviço para teste e produção. service_principal_name recebe o ID da aplicação do principal de serviço, não o seu nome de visualização. Podes recuperar o ID da aplicação na página do principal do serviço nas definições de administrador do teu espaço de trabalho.

Para o conjunto completo de comportamentos de modos, consulte Declarative Automation Bundles modos de implementação e Especifique uma identidade de execução para um fluxo de trabalho de Declarative Automation Bundles.

Para promover, implante o mesmo pacote em cada alvo por sua vez, verificando em cada etapa:

databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

Em vez de codificar diretamente nomes de catálogo ou caminhos-fonte por ambiente dentro do teu código de transformação, passa os valores do destino para que a mesma fonte corra sem alterações em todo o lado. A forma como os defines depende da tua língua de origem. Os parâmetros do pipeline aplicam-se apenas ao código-fonte SQL. Para código-fonte em Python, use o campo pipeline configuration e leia os valores com spark.conf.get():

resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

Para saber mais sobre a parametrização do código do pipeline, consulte Utilizar parâmetros com pipelines.

Configurar CI/CD

Como um pipeline convertido é definido inteiramente como um bundle (YAML mais ficheiros-fonte no Git), configurar a integração contínua e a entrega contínua (CI/CD) para esse pipeline significa executar os comandos do bundle num sistema de CI, como o GitHub Actions ou o Azure DevOps. Em cada pull request, uma boa linha de base apresenta-se:

1. pytest contra as tuas funções de transformação testáveis por unidade. Veja Testes unitários para pipelines.
2. databricks bundle validate --target <env> para detetar erros de configuração.
3. Opcionalmente, um databricks bundle run num destino temporário para testar expectativas em relação a dados de exemplo.

O seguinte fluxo de trabalho GitHub Actions é implementado para staging na fusão para main, usando a federação OpenID Connect (OIDC) em vez de um token armazenado:

# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate bundle
        run: databricks bundle validate --target staging

      - name: Deploy bundle
        run: databricks bundle deploy --target staging

Bloqueie a implementação de produção atrás de uma aprovação manual (por exemplo, um segundo trabalho que exija aprovação do GitHub Environment, ou uma fase separada no Azure DevOps) para que uma pessoa aprove explicitamente cada promoção. O trabalho de produção é executado databricks bundle deploy --target prod utilizando uma entidade de serviço com âmbito no espaço de trabalho de produção. Para mais informações, consulte CI/CD no Azure Databricks.

Solução de problemas

Dicas para o sucesso

• Use sempre o controle de versão. Se você não estiver usando pastas do Databricks Git, armazene seus subdiretórios e arquivos do projeto em um Git ou outro repositório ou sistema de arquivos controlado por versão.
• Teste seu pipeline em um ambiente que não seja de produção (como um ambiente de "desenvolvimento" ou "teste") antes de implantá-lo em um ambiente de produção. É fácil introduzir uma configuração incorreta por acidente.

Recursos adicionais

Para obter mais informações sobre como usar pacotes para definir e gerenciar o processamento de dados, consulte:

• O que são os Pacotes de Automação Declarativa?
• Desenvolver pipelines com Pacotes de Automação Declarativa. Este tópico aborda a criação de um pacote para um novo pipeline em vez de um existente, com arquivos de origem controlados por versão para processamento que você fornece.