Configurar versões de ambiente para pipelines

Uma versão de ambiente define a versão da linguagem Python e o conjunto de bibliotecas Python pré-instaladas disponíveis para o código Python do seu pipeline. Todas as dependências externas que você adicionar ao pipeline são adicionadas em camadas sobre esta base.

As versões de ambiente separam o runtime Python do pipeline da versão do Databricks Runtime em que o pipeline é executado. Enquanto uma versão do ambiente está definida, as atualizações do Databricks Runtime não alteram sua versão de linguagem Python ou versões de biblioteca pré-instaladas. O runtime de Python também é consistente com trabalhos sem servidor e notebooks que usam a mesma versão de ambiente. Para encontrar a versão atual do Databricks Runtime para pipelines do Lakeflow, consulte as notas de versão dos pipelines do Lakeflow e o processo de atualização de versão.

Databricks migra automaticamente os pipelines elegíveis para uma versão de ambiente. Veja Migração automática.

Requirements

As versões de ambiente têm os seguintes requisitos:

• O pipeline deve usar o Catálogo do Unity. Não há suporte para pipelines de metastore do Hive.

Versões de ambiente com suporte

Os pipelines do Lakeflow dão suporte às versões de ambiente 3 e 4 na computação clássica e sem servidor. Para obter a versão do idioma Python e a lista completa de bibliotecas de Python pré-instaladas disponíveis em cada versão, consulte a referência de versão environment.

Migração automática

O Databricks migra automaticamente os pipelines elegíveis para uma determinada versão do ambiente. A migração ocorre na próxima atualização de um pipeline, não requer etapas manuais e inclui estas salvaguardas:

• O comportamento é verificado antes da migração. O Databricks escaneia seu pipeline em busca de padrões de código que se comportariam de forma diferente no Spark Connect e compara o plano de saída do pipeline antes e depois da migração. Veja a compatibilidade de versões do ambiente.
• Uma migração falhada reverte automaticamente. Se uma atualização migrada falhar por qualquer motivo, ela é interrompida antes que qualquer dado seja escrito, e o pipeline automaticamente retorna ao tempo de execução anterior na próxima atualização. Nenhuma ação é necessária.
• Suas configurações explícitas são sempre respeitadas. Se você mesmo definir environment_version, o Databricks nunca o substitui.

Após a migração bem-sucedida de um pipeline, ele será executado na versão de ambiente definida. Você pode ver a versão selecionada nas configurações do pipeline, a GetPipeline resposta da API e o runtime_details log de eventos.

O que não é migrado automaticamente

Um pipeline não é migrado automaticamente caso qualquer uma das seguintes condições se aplique:

• Ele apresenta avisos de incompatibilidade do Spark Connect não resolvidos da sua atualização mais recente.
• Não é um pipeline do Unity Catalog.
• Ele utiliza um recurso que a migração automática ainda não abrange: foreach_batch sinks, ganchos de evento, CDC AUTOMÁTICO a partir de uma fonte de função de instantâneo ou uma imagem personalizada.

Pipelines que não forem migrados automaticamente continuarão sendo executados em seu ambiente de execução anterior do Python, sem alterações. Você pode ativar uma versão de ambiente manualmente assim que o pipeline estiver qualificado.

Ative uma versão do ambiente você mesmo

A migração automática cobre a maioria dos pipelines. Você também pode configurar explicitamente uma versão do ambiente, por exemplo, para migrar mais cedo ou fixar uma versão específica, através da interface do editor de pipelines, da API REST do Pipelines ou dos Pacotes de Automação Declarativa.

Antes de ativar explicitamente uma versão do ambiente, verifique se seu pipeline é compatível com o Spark Connect. Se o Databricks detectar que ativar a versão mudaria o comportamento do seu pipeline, a atualização falha antes que qualquer dado seja escrito, com um erro identificando a diferença a ser resolvida.

Habilitar por meio da interface do usuário

1. No editor de pipeline, clique em Configurações.
2. Em Ambiente de Pipeline, selecione Editar ambiente.
3. Selecione uma versão do ambiente na lista suspensa.
4. Salve as configurações de pipeline.

As dependências externas adicionadas na seção Ambiente do Pipeline são sobrepostas às bibliotecas incluídas na versão do ambiente selecionada. Consulte Gerenciar dependências do Python para pipelines.

Habilitar por meio da API

A API REST de Pipelines aceita um bloco environment na criação e na atualização de pipelines. A autenticação de Token de Acesso Pessoal deve ser habilitada para o workspace.

Para criar um pipeline com uma versão de ambiente:

curl --request POST \
  --url 'https://<workspace-host>/api/2.0/pipelines' \
  --header 'Authorization: Bearer <personal-access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<pipeline-name>",
    "catalog": "<catalog>",
    "schema": "<schema>",
    "channel": "CURRENT",
    "environment": {
      "environment_version": "4",
      "dependencies": [
        "simplejson==3.19.*"
      ]
    }
  }'

Para definir a versão do ambiente em um pipeline existente, envie o mesmo environment bloco com PUT /api/2.0/pipelines/<pipeline-id>.

Habilitar por meio de Pacotes de Automação Declarativa

Ao criar um pipeline usando Pacotes de Automação Declarativa, você pode definir uma versão de ambiente na definição yaml do pipeline.

1. Verifique se a CLI do Databricks está na versão v0.294.0 ou posterior. Caso contrário, atualize seguindo o guia de instalação.
2. Configure um pacote seguindo o tutorial do pacote de pipelines.
3. Encontre o arquivo YAML do pipeline no seu pacote, normalmente <bundle-folder>/resources/<pipeline_name>_pipeline.yml.
4. Defina os campos environment_version e dependencies no YAML do pipeline:

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      catalog: ${var.catalog}
      schema: ${var.schema}
      root_path: '../src/my_pipeline'
      libraries:
        - glob:
            include: ../src/my_pipeline/transformations/**
      environment:
        environment_version: 4
        dependencies:
          - --editable ${workspace.file_path}

Verificar a versão do ambiente em um pipeline

Para verificar qual versão do ambiente um pipeline está rodando, se você o define explicitamente ou se o Databricks o selecionou durante a migração automática:

• UI: abra as configurações do pipeline e verifique a seção Ambiente do Pipeline, ou inspecione o painel JSON para o campo environment.environment_version.
• API: chame GET /api/2.0/pipelines/<pipeline-id> e procure environment.environment_version na resposta. Isso mostra uma versão que você definiu explicitamente; Para ver uma versão selecionada pela migração automática, use o registro de eventos abaixo.
• Registro de eventos: Inspecione o runtime_details evento, que reporta a versão do ambiente usada na atualização. Veja os detalhes do evento runtime_details.

Desative ou reverta uma versão do ambiente

Você não precisa reverter uma migração automática manualmente. Uma migração que falha é revertida automaticamente na próxima atualização. Quando a versão do ambiente é removida, o pipeline retorna à configuração de runtime Python anterior. Se algo inesperado acontecer, entre em contato com o suporte do Azure Databricks.

Recursos adicionais

• Compatibilidade de versões do ambiente — limitações, mudanças de comportamento, varredura de compatibilidade e migração automática.
• Gerenciar dependências do Python para pipelines – sobreposição de dependências externas do Python a uma versão de ambiente.