Pular para o conteúdo principal
Última atualização em

Converter um pipeline em um projeto de pacote

É possível converter um pipeline existente em um projeto de Pacotes de Automação Declarativa. Os Pacotes permitem definir e gerenciar a configuração de processamento de dados do Databricks em um único arquivo YAML controlado por código-fonte, o que oferece manutenção mais fácil e possibilita a implantação automatizada em ambientes de destino.

Para um tutorial que usa o comando databricks pipelines para criar um projeto de pipeline, implantar e executar um pipeline, consulte Desenvolver pipeline com Declarative Automation Bundles.

Visão geral do processo de conversão​

Diagrama mostrando os passos específicos na conversão de um pipeline existente em um pacote

Os passos que você toma para converter um pipeline existente em um pacote são:

  1. Certifique-se de ter acesso a um pipeline configurado anteriormente que você deseja converter em um pacote.
  2. Crie ou prepare uma pasta (de preferência em uma hierarquia controlada por fonte) para armazenar o pacote.
  3. Gere uma configuração para o pacote a partir do pipeline existente, usando o Databricks CLI.
  4. Revise a configuração do pacote gerado para garantir que esteja completa.
  5. Vincule o pacote ao pipeline original.
  6. implantou o pipeline em um workspace de destino usando a configuração do pacote.

Requisitos​

Antes de começar, você deve ter:

o passo 1: Configure uma pasta para seu projeto de pacote​

Você precisa ter acesso a um repositório Git que esteja configurado no Databricks como uma pasta Git. Você criará seu projeto de pacote neste repositório, que aplicará o controle de versão e o disponibilizará para outros colaboradores por meio de uma pasta Git no workspace Databricks correspondente. (Para obter mais detalhes sobre pastas Git, consulte Pastas Git do Databricks.)

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

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

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

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

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

  4. Inicialize um novo pacote executando:

    Bash
    databricks bundle init

    Responda às perguntas. Assim que for concluído, você terá um arquivo de configuração de projeto chamado databricks.yml no novo diretório raiz do seu projeto. Este arquivo é necessário para implantar seu pipeline a partir da linha de comando. Para obter mais detalhes sobre este arquivo de configuração, consulte Configuração de pacotes de automação declarativa.

o passo 2: Gerar a configuração pipeline​

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

Bash
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 do pacote e downloads todos os artefatos referenciados para a pasta src . O sinalizador --profile (ou -p ) é opcional, mas se você tiver um perfil de configuração específico Databricks (definido no seu arquivo .databrickscfg criado quando você instalou o Databricks CLI) que prefere usar em vez do perfil default , forneça-o neste comando. Para obter informações sobre perfis de configuração Databricks , consulte Perfis de configuraçãoDatabricks.

dica

Se você tiver um projeto de pipeline declarativo Spark (SDP) existente (que tenha um arquivo spark-pipeline.yml ), você pode copiar esse projeto pipeline para a pasta src do pacote e, em seguida, usar o comando databricks pipelines generate para gerar a configuração do pacote para ele. Veja o pipeline de geração do Databricks.

o passo 3: Revise os arquivos do 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 Notebook, são armazenados.

O comando também cria alguns arquivos adicionais:

  • *.pipeline.yml no subdiretório resources . Este arquivo contém a configuração e as definições específicas para seu pipeline.
  • Arquivos 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

o passo 4: Vincule o pipeline do pacote ao seu pipelineexistente​

Você deve vincular ou vincular a definição do pipeline no pacote ao seu pipeline existente para mantê-lo atualizado conforme você faz alterações. Para fazer isso, execute o comando bind de implantação do pacote CLI Databricks :

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

<pipeline-name> é o nome do pipeline. Este nome deve ser o mesmo que o valor das strings prefixadas do nome do arquivo para a configuração pipeline no seu novo diretório resources . Por exemplo, se você tiver um arquivo de configuração de pipeline chamado ingestion_data_pipeline.pipeline.yml na sua pasta resources , deverá fornecer ingestion_data_pipeline como nome do pipeline.

<pipeline-ID> é o ID do seu pipeline. É o mesmo que você copiou como parte dos requisitos destas instruções.

o passo 5: implemente seu pipeline usando seu novo pacote​

Agora, implante seu pacote pipeline no seu workspace de destino usando o comando bundle implantado Databricks CLI :

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

O sinalizador --target é obrigatório e deve ser definido como uma string que corresponda a um nome de workspace de destino configurado, como development ou production.

Se esse comando for bem-sucedido, você terá sua configuração pipeline em um projeto externo que pode ser carregado em outro espaço de trabalho e execução e facilmente compartilhado com outros usuários Databricks em sua account.

Promova entre ambientes com destinos​

Um bundle 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ável. Os destinos são a forma como você promove o mesmo pipeline através dos ambientes de desenvolvimento, staging e produção, implantando o código-fonte idêntico em cada ambiente sucessivo sem editá-lo:

YAML
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'

O mode que você define em cada destino altera seu comportamento de implantação:

  • mode: development marca um destino como uma implantação pessoal e temporária. Os recursos recebem um prefixo [dev username] e os agendamentos são pausados por default, para que seu trabalho não afete mais ninguém.
  • mode: production Desativa essas configurações de segurança default. Em conjunto com run_as, permite executar o pipeline como um Service Principal em vez de uma account individual, para que as execuções não sejam interrompidas quando alguém sai da equipe ou muda de função. A Databricks recomenda um Service Principal para ambientes de teste e produção. service_principal_name pega o ID do aplicativo do Service Principal, não seu nome de exibição. Você pode recuperar o ID do aplicativo na página do Service Principal nas configurações de administração do seu Workspace.

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

Para promover, implemente o mesmo pacote em cada destino, verificando em cada etapa:

Bash
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 origem seja executada sem modificações em todos os lugares. A forma de configurá-los depende do seu idioma de origem. Os parâmetros do pipeline aplicam-se somente ao código-fonte SQL. Para código-fonte Python, use o campo de pipeline configuration e leia os valores com spark.conf.get():

YAML
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 de código de pipeline, consulte Usar parâmetros com pipelines.

Configurar CI/CD​

Como um pipeline convertido é definido inteiramente como um pacote (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 pacote a partir de um sistema de CI, como o GitHub Actions ou o Azure DevOps. Em cada solicitação de pull request, uma boa linha de base é executada:

  1. pytest em relação às suas funções de transformação testáveis por unidade. Consulte Teste de unidade para pipelines.
  2. databricks bundle validate --target <env> para capturar erros de configuração.
  3. Opcionalmente, um databricks bundle run em um destino temporário para exercitar expectativas em relação aos dados de amostra.

O seguinte fluxo de trabalho do GitHub Actions é implantado no ambiente de staging após o merge para main, usando federação OpenID Connect (OIDC) em vez de um token armazenado:

YAML
# .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

Proteja a implantação de produção com uma aprovação manual (por exemplo, um segundo job que exija uma aprovação de ambiente do GitHub ou um estágio separado no Azure DevOps) para que uma pessoa aprove explicitamente cada promoção. O Job de produção executa databricks bundle deploy --target prod usando um Service Principal com escopo para o Workspace de produção. Para saber mais, consulte CI/CD no Databricks.

Solução de problemas​

Problema

soluções

Erro “databricks.yml não encontrado” ao executar bundle generate

Atualmente, o comando bundle generate 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 do pipeline existente não correspondem aos valores na configuração YAML do pipeline gerado

O ID do pipeline não aparece no arquivo YML de configuração do pacote. Se você notar alguma outra configuração ausente, poderá aplicá-la manualmente.

Problema

soluções

Erro “databricks.yml não encontrado” ao executar bundle generate

Atualmente, o comando bundle generate 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 do pipeline existente não correspondem aos valores na configuração YAML do pipeline gerado

O ID do pipeline não aparece no arquivo YML de configuração do pacote. Se você notar alguma outra configuração ausente, poderá aplicá-la manualmente.

Dicas para o sucesso​

  • Sempre use controle de versão. Se você não estiver usando as pastas Git do Databricks, armazene os subdiretórios e arquivos do seu projeto em um Git ou outro repositório ou sistema de arquivos com controle de versão.
  • Teste seu pipeline em um ambiente de não produção (como um ambiente de “desenvolvimento” ou “teste”) antes de transferi-lo para um ambiente de produção. É fácil introduzir uma configuração incorreta por acidente.

Recurso adicional​

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

Nesta página