Transformar um pipeline em um projeto de conjunto

Você pode converter um pipeline existente em um projeto de Pacotes de Automação Declarativa. 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 origem que fornece uma manutenção mais fácil e permite a implantação automatizada para ambientes de destino.

Para obter um tutorial que usa comandos databricks pipelines para criar um projeto de pipelines e, em seguida, implanta e executa um pipeline, consulte Desenvolver pipelines com Pacotes de Automação Declarativa.

Visão geral do processo de conversão

Diagrama mostrando as etapas específicas na conversão de um pipeline existente em um pacote

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

  1. Verifique se você tem acesso a um pipeline previamente configurado que quer converter em um pacote.
  2. Crie ou prepare uma pasta (de preferência em uma hierarquia com controle de versão) para armazenar o pacote.
  3. Gere uma configuração para o pacote do pipeline existente usando a CLI do Databricks.
  4. Examine a configuração do pacote gerado para garantir que ela esteja concluída.
  5. Vincule o pacote ao pipeline original.
  6. Implante o pipeline em um workspace de destino usando a configuração do pacote.

Requirements

Antes de começar, você deve ter:

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á a outros colaboradores por meio de uma pasta Git no workspace do Azure Databricks correspondente. (Para obter mais detalhes sobre pastas Git, consulte pastas git do Azure Databricks.)

  1. Vá para a raiz do repositório Git clonado em seu computador 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. Após a conclusão, você terá um arquivo de configuração de projeto chamado databricks.yml na nova pasta inicial do projeto. Esse arquivo é necessário para implantar o pipeline na linha de comando. Para obter mais detalhes sobre esse arquivo de configuração, consulte a configuração de Pacotes de Automação Declarativa.

Etapa 2: gerar a configuração do pipeline

Neste novo diretório na árvore de pastas do repositório Git clonado, execute o comando bundle generate da CLI do Databricks , fornecendo a ID do pipeline como <pipeline-id>:

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

Quando você executa o comando generate, ele cria um arquivo de configuração de pacote para seu pipeline na pasta resources e baixa todos os artefatos referenciados para a pasta src. O --profile (ou -p sinalizador) é opcional, mas se você tiver um perfil de configuração específico do Databricks (definido no .databrickscfg arquivo criado quando instalou a CLI do Databricks) que você 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 os perfis de configuração do Azure Databricks.

Dica

Se você tiver um projeto existente do Spark Declarative Pipelines (SDP) (ele tem um spark-pipeline.yml arquivo), poderá copiar esse projeto de pipeline para a src pasta do pacote e, em seguida, usar o databricks pipelines generate comando para gerar a configuração do pacote para ele. Consulte Pipelines do Databricks gerados.

Etapa 3: Examinar 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 arquivos de configuração de projeto.
  • src é a pasta do projeto em que os arquivos de origem, como consultas e notebooks, são armazenados.

O comando também cria alguns arquivos adicionais:

  • *.pipeline.yml dentro do subdiretório resources. Este arquivo contém as configurações específicas do seu pipeline.
  • Arquivos de origem, como consultas SQL, no subdiretório src, copiados do 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

Etapa 4: associar o pipeline de pacote ao pipeline existente

Você deve vincular ou associar a definição de pipeline no pacote ao pipeline existente para mantê-la atualizada à medida que fizer alterações. Para fazer isso, execute o comando bundle deployment bind da CLI do Databricks:

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

<pipeline-name> é o nome do pipeline. Esse nome deve ser o mesmo que o valor prefixado no nome do arquivo de configuração do pipeline dentro do novo diretório resources. Por exemplo, se você tiver um arquivo de configuração de pipeline chamado ingestion_data_pipeline.pipeline.yml na pasta resources, deverá fornecer ingestion_data_pipeline como o nome do pipeline.

<pipeline-ID> é a ID do seu pipeline. É a mesma ID que você copiou como parte dos requisitos para estas instruções.

Etapa 5: implantar seu pipeline usando seu novo pacote

Agora, implante o pacote de pipeline no workspace de destino usando o comando bundle deploy da CLI do Databricks:

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

O sinalizador --target é necessário e deve ser definido como uma cadeia de caracteres que corresponda a um nome de workspace de destino configurado, como development ou production.

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

Promover entre ambientes com destinos

Um pacote define ambientes de implantação nomeados chamados destinos em databricks.yml, cada um apontando para seu próprio workspace, catálogo e valores de variáveis. Os destinos são como você promove o mesmo pipeline através de desenvolvimento, preparação e produção, implantando código-fonte idêntico para cada ambiente sucessivo sem editá-lo:

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 você define em cada destino altera o comportamento de implantação:

  • mode: development marca um destino como uma implantação pessoal, improvisada. Recursos recebem um [dev username] prefixo e os cronogramas são pausados por padrão, então seu trabalho não afeta mais ninguém.
  • mode: production desativa essas configurações de segurança padrão. Combinado com run_as, permite que você execute o pipeline como uma entidade de serviço, em vez de uma conta de indivíduo, para que as execuções não sejam interrompidas quando alguém sai da equipe ou muda de função. O Azure Databricks recomenda uma entidade de serviço para preparação e produção. service_principal_name assume a ID do aplicativo da entidade de serviço, e não seu respectivo nome de exibição. Você pode recuperar o ID da aplicação na página do principal do serviço nas configurações de administração do seu espaço de trabalho.

Para o conjunto completo de comportamentos dos modos, veja Modos de implantação dos Pacotes de Automação Declarativa e Especifique uma identidade para execução de um fluxo de trabalho dos Pacotes de Automação Declarativa.

Para promover, implante o mesmo pacote para cada alvo por turno, 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 nomes de catálogo ou caminhos de origem por ambiente dentro do seu código de transformação, passe os valores do destino para que a mesma fonte rodasse sem modificações em todos os lugares. Como você os define depende da sua língua de origem. Os parâmetros do pipeline se aplicam 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 parametrização do código do pipeline, veja Usar parâmetros em pipelines.

Configurar CI/CD

Como um pipeline convertido é definido inteiramente na forma de um bundle (YAML mais arquivos de origem no Git), configurar a integração contínua e a entrega contínua (CI/CD) para ele significa executar os comandos do bundle em um sistema de CI, como GitHub Actions ou Azure DevOps. Em cada pull request, uma boa linha de base executa:

  1. pytest em relação às funções de transformação testáveis por unidade. Consulte Testes unitários para pipelines.
  2. databricks bundle validate --target <env> para detectar erros de configuração.
  3. Opcionalmente, um databricks bundle run em um destino de rascunho para testar as expectativas em relação aos dados de exemplo.

O fluxo de trabalho do GitHub Actions a seguir faz a implantação no ambiente de preparação na mesclagem em main, usando a federação OpenID Connect (OIDC) em vez de um token previamente 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

Limite a implantação de produção com uma aprovação manual (por exemplo, um segundo trabalho que exija aprovação do ambiente do GitHub, ou uma etapa separada no Azure DevOps) para que a pessoa aprove explicitamente cada promoção. O trabalho de produção executa databricks bundle deploy --target prod usando uma entidade de serviço com escopo para o workspace de produção. Para mais informações, veja CI/CD sobre Azure Databricks.

Resolução de problemas

Questão Solução
Erro "databricks.yml não encontrado" ao executar bundle generate Atualmente, o bundle generate comando não cria o arquivo de configuração do pacote (databricks.yml) automaticamente. Você deve criar o arquivo usando databricks bundle init ou manualmente.
As configurações de pipeline existentes não correspondem aos valores na configuração YAML de pipeline gerada. A ID do pipeline não aparece no arquivo YML de configuração do pacote. Se você observar outras configurações ausentes, poderá aplicá-las manualmente.

Dicas para o sucesso

  • Sempre use o controle de versão. Se você não estiver usando pastas Git do Databricks, armazene seus subdiretórios e arquivos de projeto em um Git ou em outro repositório ou sistema de arquivos controlado por versão.
  • Teste seu pipeline em um ambiente de não 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:

  • Last updated on