Em 15 de setembro de 2026, todos os ambientes do Cloud Composer 1 e da versão 2.0.x do Cloud Composer 2 vão atingir o fim da vida útil planejado e não poderão mais ser usados. Recomendamos planejar a migração para o Cloud Composer 3.

Esta página foi traduzida pela API Cloud Translation.

Migrar ambientes para o Cloud Composer 3 (script de migração)

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

Nesta página, explicamos como migrar DAGs, dados e configuração do ambiente atual do Cloud Composer 2 para um novo ambiente do Cloud Composer 3 usando o script de migração.

Outros guias de migração

De	Para	Método	Guia
Cloud Composer 2	Cloud Composer 3	Lado a lado, usando o script de migração	Este guia
Cloud Composer 2	Cloud Composer 3	Lado a lado, usando snapshots	Guia de migração de snapshots
Cloud Composer 1, Airflow 2	Cloud Composer 3	Lado a lado, usando snapshots	Guia de migração de snapshots
Cloud Composer 1, Airflow 2	Cloud Composer 2	Lado a lado, usando snapshots	Guia de migração de snapshots
Cloud Composer 1, Airflow 2	Cloud Composer 2	Lado a lado, transferência manual	Guia de migração manual
Cloud Composer 1, Airflow 1	Cloud Composer 2, Airflow 2	Lado a lado, usando snapshots	Guia de migração de snapshots
Cloud Composer 1, Airflow 1	Cloud Composer 2, Airflow 2	Lado a lado, transferência manual	Guia de migração manual
Cloud Composer 1, Airflow 1	Cloud Composer 1, Airflow 2	Lado a lado, transferência manual	Guia de migração manual

Sobre o script de migração

O script de migração é um script Python para migrações lado a lado que automatiza o processo de migração do Cloud Composer 2 para o Cloud Composer 3. Ele usa snapshots de ambiente para transferir a configuração do ambiente para o novo ambiente.

O script executa as seguintes ações:

Recebe a configuração do ambiente do Cloud Composer 2.
Cria um ambiente do Cloud Composer 3 com uma configuração que corresponde à configuração obtida.

Como os ambientes do Cloud Composer 3 têm uma arquitetura diferente, alguns parâmetros podem ser ajustados para corresponder às diferenças. Também é possível ajustar a maioria dos parâmetros do ambiente mais tarde.
Pausa todos os DAGs no ambiente do Cloud Composer 2 um por um. Somente os DAGs que foram retomados no ambiente do Cloud Composer 2 serão retomados mais tarde.

Observação: se o ambiente tiver um grande número de DAGs, esse processo poderá levar muito tempo. É possível usar o script composer_dags para pausar todos os DAGs antes de realizar a migração e retomar os DAGs depois que a migração for concluída. Nesse caso, o script de migração não vai retomar os DAGs. Para mais informações, consulte o arquivo README do script composer_dags no GitHub.
Salva um snapshot do ambiente de origem do Cloud Composer 2. O snapshot é salvo no local padrão para snapshots, o bucket do ambiente do Cloud Composer 2.
Carrega o snapshot no ambiente do Cloud Composer 3.

O script não verifica a compatibilidade de pacotes PyPI personalizados, variáveis de ambiente e substituições de opções de configuração do Airflow com o ambiente do Cloud Composer 3.

Em caso de conflitos, a migração falha após a criação do ambiente do Cloud Composer 3, durante o processo de carregamento do snapshot. Nesse caso, ajuste a configuração do ambiente do Cloud Composer 2 para resolver o conflito ou migre sem o script de migração e pule o carregamento de pacotes PyPI personalizados, variáveis de ambiente ou substituições de configuração do Airflow ao carregar o snapshot.
Cancela a pausa dos DAGs no ambiente do Cloud Composer 3. Se alguns DAGs já estavam pausados antes da execução do script, eles vão continuar pausados.

O script tem as seguintes limitações:

O script sempre cria um novo ambiente do Cloud Composer 3. Não é possível carregar o snapshot em um ambiente do Cloud Composer 3. Para fazer isso, migre usando snapshots sem usar o script de migração.
O script cria um ambiente do Cloud Composer 3 apenas na mesma região e no mesmo projeto do ambiente do Cloud Composer 2.
Só é possível carregar snapshots para a mesma versão ou uma versão mais recente do Airflow. Por exemplo, não é possível carregar um snapshot do Airflow 2.10.2 para o Airflow 2.9.3.
Somente ambientes do Cloud Composer 2 podem ser migrados com o script de migração.

Antes de começar

Como o script de migração cria um ambiente e salva e carrega um snapshot, o processo de migração pode levar mais de uma hora.
O script usa snapshots. Há suporte para snapshots
no Cloud Composer 2 versão 2.0.9 e posteriores.
Sua conta precisa de um papel do IAM que possa criar ambientes, salvar e carregar snapshots.
O tamanho máximo do banco de dados do Airflow que aceita snapshots é de 20 GB. Se o banco de dados do ambiente ocupar mais de 20 GB, reduza o tamanho do banco de dados do Airflow.
O número total de objetos nas pastas /dags, /plugins e /data no bucket do ambiente precisa ser menor que 100.000 para criar snapshots.
Se você usar o mecanismo XCom para transferir arquivos, use-o de acordo com as diretrizes do Airflow. A transferência de arquivos grandes ou de um grande número de arquivos usando XCom afeta o desempenho do banco de dados do Airflow e pode causar falhas ao carregar snapshots ou fazer upgrade do ambiente. Considere usar alternativas como o Cloud Storage para transferir grandes volumes de dados.

Migrar para o Cloud Composer 3

Nesta seção, descrevemos o processo de migração usando o script de migração.

Confira as diferenças entre o Cloud Composer 2 e o Cloud Composer 3

Confira a lista de diferenças entre o Cloud Composer 2 e o Cloud Composer 3.

Verifique se o ambiente não usa recursos que ainda não estão disponíveis no Cloud Composer 3 e se você sabe como usar e configurar recursos específicos do Cloud Composer 3.

Verifique se os DAGs são compatíveis com o Cloud Composer 3

Siga estas sugestões para garantir que seus DAGs sejam compatíveis com o Cloud Composer 3:

A lista de pacotes no ambiente do Cloud Composer 3 pode ser diferente da do ambiente do Cloud Composer 2. Isso pode afetar a compatibilidade dos seus DAGs com o Cloud Composer 3.
No Cloud Composer 3, o cluster do ambiente está localizado no projeto do locatário. Verifique se os DAGs são compatíveis com essa mudança. Em particular, as cargas de trabalho KubernetesPodOperator agora são escalonadas de forma independente do seu ambiente, e não é possível usar configurações de afinidade de pod.

Instalar as dependências do script

O script requer o Python 3.8 ou versões mais recentes.
O script de migração usa a CLI gcloud e utilitários curl. Verifique se os dois utilitários estão instalados no computador.

Faça o download do script

Faça o download do script de migração (composer_migrate.py) no repositório do GitHub.

Autorizar na CLI gcloud

Autorize na CLI gcloud:

gcloud auth login

Visualizar os parâmetros do novo ambiente

É possível visualizar os parâmetros do ambiente do Cloud Composer 3 antes de migrar. Use isso para ver como a configuração do ambiente do Cloud Composer 2 corresponde ao Cloud Composer 3.

Substituições de opções de configuração do Airflow, pacotes PyPI personalizados e variáveis de ambiente são carregados do snapshot do ambiente e não aparecem na prévia.

Abrir

Execute este comando:

python3 composer_migrate.py \
    --project PROJECT_ID \
    --location LOCATION \
    --source_environment COMPOSER_2_ENV \
    --target_environment COMPOSER_3_ENV \
    --target_airflow_version COMPOSER_3_AIRFLOW_VERSION \
    --dry_run

Substitua:

PROJECT_ID: o ID do projeto.
COMPOSER_2_ENV: o nome do seu ambiente do Cloud Composer 2.
LOCATION: a região em que o ambiente do Cloud Composer 2 está localizado. O ambiente do Cloud Composer 3 será criado na mesma região.
COMPOSER_3_AIRFLOW_VERSION: a versão do Airflow do ambiente do Cloud Composer 3. Essa versão precisa ser igual ou posterior à do ambiente do Cloud Composer 2 e precisa ser uma das versões disponíveis no Cloud Composer 3.

Exemplo:

python3 composer_migrate.py \
    --project example-project \
    --location us-central1 \
    --source_environment example-composer-2-environment \
    --target_environment example-composer-3-environment \
    --target_airflow_version 2.10.2

Verificar a integridade do ambiente

Verifique se o ambiente do Cloud Composer 2 que você quer migrar está íntegro.

Se o ambiente não estiver íntegro, o processo de migração vai falhar depois da criação de um novo ambiente do Cloud Composer 3 porque não será possível criar um snapshot.

Consulte Usar o painel de monitoramento para mais informações sobre como verificar a integridade do ambiente e do banco de dados.

Executar o script de migração