Fazer upgrade dos ambientes

Nesta página, descrevemos como fazer upgrade do ambiente para uma nova versão do Airflow.

Sobre as operações de upgrade

No Airflow Gerenciado (Geração 3), você não gerencia a versão do Airflow Gerenciado do seu ambiente:

• O Airflow Gerenciado faz upgrade automático dos componentes de infraestrutura do seu ambiente. Esses componentes estão relacionados à funcionalidade do Airflow gerenciado e não mudam o funcionamento do Airflow nem a execução dos DAGs do Airflow.
• O Airflow Gerenciado não faz upgrade automático da versão e do build do Airflow, dos componentes do Airflow ou dos componentes relacionados às cargas de trabalho do Airflow. Eles não são alterados quando os componentes da infraestrutura são atualizados automaticamente.
• É possível fazer upgrade manualmente para uma nova versão ou build do Airflow.

Por exemplo, é possível usar a mesma versão e build do Airflow por vários meses, sem fazer upgrades, e o ambiente ainda recebe as atualizações, correções e melhorias mais recentes do Airflow gerenciado dos componentes de infraestrutura do ambiente. Quando você decidir migrar para uma nova versão ou build do Airflow, faça upgrade da versão do Airflow no ambiente.

Sobre o upgrade da versão do Airflow

O ambiente muda a versão ou o build do Airflow da seguinte maneira:

• Você controla a versão (e o build) do Airflow do seu ambiente. É possível realizar a operação de upgrade da versão do Airflow ao mudar o ambiente para uma versão diferente do Airflow. Por exemplo, isso pode acontecer se a versão e o build atuais do Airflow não forem mais compatíveis.

• O Airflow Gerenciado implanta novamente os componentes do Airflow do seu ambiente usando a versão e o build especificados do Airflow.

• O Airflow Gerenciado aplica mudanças de configuração do Airflow, como pacotes PyPI personalizados ou substituições de opções de configuração do Airflow, se o ambiente as tiver antes do upgrade.

• O Airflow Gerenciado atualiza a conexão do Airflow airflow_db para apontar para o novo banco de dados do Cloud SQL.

Mudar a versão do Airflow não altera a forma como você se conecta aos recursos no ambiente, como o URL do bucket do ambiente ou o servidor da Web do Airflow.

Sobre as operações de upgrade automático de infraestrutura

O Airflow Gerenciado executa periodicamente operações de upgrade automático de infraestrutura:

• As operações de upgrade automático da infraestrutura são executadas periodicamente durante as janelas de manutenção especificadas para o ambiente.

• Não é possível desativar os upgrades automáticos de infraestrutura no Airflow Gerenciado (3ª geração). É possível controlar os períodos em que os upgrades automáticos podem ser executados especificando janelas de manutenção personalizadas para seu ambiente.

• Essa operação fica visível no console do Cloud de Confiance e nos registros do ambiente, como qualquer outra operação de longa duração. Enquanto a operação estiver em execução, não será possível iniciar outras operações no nível do ambiente, mas ainda será possível executar DAGs do Airflow.

• Em alguns casos, os upgrades automáticos de infraestrutura podem reiniciar os componentes do Airflow. Durante essas reinicializações, os workers do Airflow são encerrados com um período de carência de 24 horas. Se você tiver tarefas que precisam de mais de 24 horas para serem concluídas, use operadores adiáveis. Um upgrade pode resultar em um curto período de indisponibilidade para os componentes de infraestrutura do ambiente, como o monitoramento do ambiente.

Limitações das operações de upgrade e reversão

As operações de upgrade têm as seguintes limitações:

• As versões do Airflow Gerenciado são lançadas gradualmente em todas as regiões compatíveis com o Airflow Gerenciado ao longo de vários dias. A versão mais recente de um lançamento em andamento pode ainda não estar disponível na sua região.

• No Airflow Gerenciado (3ª geração), é possível reverter um upgrade para uma versão ou build anterior do Airflow com as seguintes limitações:

  • As reversões são compatíveis com upgrades feitos a partir das versões do Airflow 3 ou das versões do Airflow 2, começando com o build airflow-2.7.3-build.0.
  • As reversões são compatíveis com upgrades feitos para as versões de destino airflow-2.11.1-build.20 ou mais recente, airflow-3.2.2-build.7 ou mais recente e airflow-3.3.1-build.3 ou mais recente.
  • É possível iniciar a operação de reversão em até 30 dias após o upgrade. Se a versão de destino do Airflow tiver passado da data de fim do suporte, ainda será possível fazer reverter para ela. É possível fazer reversões de versões ignoradas. Se você tiver feito upgrade mais de uma vez em 30 dias, poderá reverter para qualquer versão usada anteriormente, desde que ela atenda às restrições de qualificação.
  • O ambiente está em um estado RUNNING quando você inicia a reversão.

• Não será possível fazer upgrade do ambiente se o banco de dados do Airflow tiver mais de 20 GB de dados. Durante um upgrade, um aviso será exibido se o tamanho do banco de dados do Airflow for maior que 20 GB. Nesse caso, realize a manutenção do banco de dados para reduzir o tamanho dele.

• Se você usar o mecanismo XCom para transferir arquivos, siga as diretrizes do Airflow. A transferência de arquivos grandes ou de um grande número de arquivos usando o XCom afeta o desempenho do banco de dados do Airflow e pode levar a falhas ao carregar snapshots ou fazer upgrade do ambiente. Considere usar alternativas como o Cloud Storage para transferir grandes volumes de dados.

Antes de começar

• Recomendamos criar um novo snapshot do ambiente para poder recriá-lo, se necessário.

• Sua conta precisa ter um papel que possa acionar operações de upgrade de ambiente. Além disso, a conta de serviço do ambiente precisa ter um papel com permissões suficientes para realizar operações de upgrade. Consulte Controle de acesso para mais informações.

Verificar se o ambiente está atualizado

O Airflow Gerenciado mostra avisos quando o build do Airflow do seu ambiente se aproxima da data de fim do suporte. Use esses avisos para manter seu ambiente sempre compatível.

O Airflow Gerenciado monitora a versão e o build do Airflow em que seu ambiente se baseia. Quando a data de fim do suporte se aproximar, você vai receber um aviso na lista de ambientes e na página Detalhes do ambiente.

Para verificar se o ambiente está atualizado:

Ver upgrades sugeridos

O Airflow Gerenciado fornece uma lista de versões do Airflow para as quais você pode fazer upgrade do seu ambiente.

Para conferir as versões do Airflow Gerenciado sugeridas para um upgrade:

gcloud composer environments list-upgrades \
  ENVIRONMENT_NAME \
  --location LOCATION

gcloud composer environments list-upgrades example-environment \
  --location us-central1

// GET https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/imageVersions

Verificar se há conflitos de pacotes PyPI

Verifique se os pacotes PyPI instalados no seu ambiente têm algum conflito com os pacotes pré-instalados na nova versão ou build do Airflow.

Uma verificação bem-sucedida significa que não há conflitos nas dependências de pacotes do PyPI entre a versão atual e a especificada. No entanto, uma operação de upgrade ainda pode não ser bem-sucedida por outros motivos.

gcloud composer environments check-upgrade \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --airflow-version VERSION

gcloud composer environments check-upgrade example-environment \
  --location us-central1 \
  --airflow-version airflow-2.11.1-build.21

Waiting for [projects/example-project/locations/us-central1/environments/
example-environment] to be checked for PyPI package conflicts when upgrading
to composer-3-airflow-2.11.1-build.21. Operation [projects/example-project/locations/
us-central1/operations/04d0e8b2-...]...done.
...

Response:
'@type': type.googleapis.com/
google.cloud.orchestration.airflow.service.v1.CheckUpgradeResponse
buildLogUri: ...
containsPypiModulesConflict: CONFLICT
pypiConflictBuildLogExtract: |-
The Cloud Build image build failed: Build failed; check build logs for
details. Full log can be found at ...
Error details: tensorboard 2.2.2 has requirement
setuptools>=41.0.0, but you have setuptools 40.3.0.

{
  "imageVersion": "VERSION"
}

Verificar se há conflitos com o Airflow Gerenciado (3ª geração)

O Airflow Gerenciado (Geração 3) é a versão principal mais recente do Airflow Gerenciado. É possível verificar se um ambiente do Airflow gerenciado (geração 2) pode ser atualizado para o Airflow gerenciado (geração 3) com uma verificação de upgrade. A descrição a seguir se aplica aos ambientes do Airflow Gerenciado (2ª geração).

Embora não seja possível migrar seu ambiente do Airflow Gerenciado (2ª geração) para o Airflow Gerenciado (3ª geração) no local, é possível verificar se há problemas de compatibilidade usando uma verificação de upgrade. Recomendamos fazer isso antes de migrar para o Airflow Gerenciado (3ª geração).

Para verificar a compatibilidade com o Airflow Gerenciado (3ª geração), faça uma verificação de upgrade regular do ambiente do Airflow Gerenciado (2ª geração) e especifique uma versão do Airflow Gerenciado (3ª geração) como destino.

Cada conflito relatado pode ter os seguintes tipos:

• BLOCKING relata elementos de configuração de ambiente incompatíveis que não são compatíveis com o Airflow gerenciado (3ª geração). Recomendamos resolver esses conflitos antes de iniciar uma migração para o Airflow Gerenciado (3ª geração).

• NON_BLOCKING relata elementos de configuração do ambiente que são diferentes no Airflow Gerenciado (3ª geração) e podem causar um comportamento inesperado. Por exemplo, as alterações dos valores padrão, como janelas de manutenção padrão, são relatadas como conflitos não bloqueantes. Recomendamos verificar se esses conflitos podem causar problemas antes de iniciar o processo de migração.

• Os conflitos de pacotes do PyPI também são informados como parte dessa verificação. Eles são informados separadamente dos conflitos de configuração, da mesma forma que em uma verificação de compatibilidade de pacotes PyPI normal.

gcloud composer environments check-upgrade \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --image-version COMPOSER_3_VERSION

gcloud composer environments check-upgrade example-environment \
  --location us-central1 \
  --image-version composer-3-airflow-2

...
- message: Error validating property [core]unit_test_mode. Overriding [core]
unit_test_mode is not permitted.
type: BLOCKING
- message: Environment variables [GOOGLE_CLOUD_PROJECT] may not be overridden.
type: BLOCKING
- message: You have to specify Worker CPUs to be 0.5, 1.0 or multiples of 2.0.
type: BLOCKING
- message: The environment uses a default maintenance window, which is
different in Composer 2 and Composer 3. Unless set to a custom value, the
maintenance window will be changed to a new default after the upgrade.
type: NON_BLOCKING
...

{
  "imageVersion": "COMPOSER_3_VERSION"
}

Fazer upgrade do ambiente

Para fazer upgrade do ambiente para uma nova versão ou build do Airflow:

gcloud composer environments update \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --airflow-version VERSION

gcloud composer environments update \
  example-environment \
  --location us-central1 \
  --airflow-version airflow-2.11.1-build.21

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.imageVersion

  {
    "config": {
      "softwareConfig": {
        "imageVersion": "composer-3-airflow-2.11.1-build.21"
      }
    }
  }

  resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {
    software_config {
      image_version = "VERSION"
    }
  }
}

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {
    software_config {
      image_version = "airflow-2.11.1-build.21"
    }
  }
}

Reverter um upgrade

É possível reverter um upgrade de ambiente se você encontrar desempenho degradado, bugs do Airflow ou problemas de compatibilidade com seus DAGs, plug-ins ou dependências.

É possível reverter um upgrade em até 30 dias após a operação se o ambiente estiver no estado RUNNING. É possível reverter para versões que chegaram ao fim da data de suporte. Para mais informações, consulte Limitações das operações de upgrade e reversão.

Além de reverter um único upgrade, você pode:

• Realize várias reversões sucessivas:

  Exemplo: A > B > C > B > A (se a reversão para B e A atender às limitações).

• Realize reversões de versões ignoradas:

  Exemplo: A > B > C > A (se a reversão para A atender às limitações).

Durante uma reversão, somente o build do Airflow do ambiente é revertido para a versão especificada. O Airflow Gerenciado preserva os dados e o estado do ambiente durante as reversões:

• Arquivos DAG e histórico de execução: todas as definições de DAG, histórico de execução de DAG, estados de instância de tarefa e XComs permanecem intactos no banco de dados de metadados.

• Configuração do ambiente: as substituições de configuração do Airflow, as variáveis de ambiente, os pacotes PyPI personalizados e as configurações de escalonamento são preservados. Se você usar requisitos de versão de pacote PyPI não estritos para seus pacotes PyPI personalizados, seu ambiente poderá ter uma versão de pacote diferente após a reversão (essa versão ainda atenderá ao requisito de versão especificado).

  Se você mudou a configuração do ambiente durante o upgrade, como modificar variáveis de ambiente ou ajustar limites de recursos para componentes do Airflow, essas mudanças não serão revertidas. Se necessário, é possível reverter as alterações manualmente antes ou depois da reversão.

• Registros e monitoramento: os registros de execução de tarefas armazenados no Cloud Logging e o histórico de métricas no Cloud Monitoring são preservados.

As atualizações do esquema do banco de dados do Airflow (migrações do Alembic) são revertidas automaticamente para corresponder ao esquema da versão de destino do Airflow. Para ver a lista de migrações de banco de dados presentes em cada versão do Airflow, consulte Migrações de banco de dados do Airflow na documentação do Airflow. Durante uma operação de reversão, todas as migrações listadas entre a versão atual do Airflow e a versão de destino do Airflow são revertidas.

Encontrar a versão usada anteriormente

Para encontrar a versão usada anteriormente:

gcloud composer operations list \
--locations LOCATION \
--filter='metadata.resource ~ "environments/ENVIRONMENT_NAME$" (metadata.operationType=UPDATE OR metadata.operationType=CREATE)'

┌──────────────────────────────────────┬───────────────┬─────────────┬──────────────────────────────┬───────────┬─────────────────────────────┐
│                 UUID                 │      TYPE     │   LOCATION  │      TARGET_ENVIRONMENT      │   STATE   │         CREATE_TIME         │
├──────────────────────────────────────┼───────────────┼─────────────┼──────────────────────────────┼───────────┼─────────────────────────────┤
│ 71c3d5c9-5b26-4a98-8b19-7f62e9f4ed51 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-10-15T11:18:32.084039Z │
│ 63da3be2-3acf-4fb4-986a-90552a6df8b3 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-08-15T10:56:10.628514Z │
│ 4ebc18a9-25bb-4325-b4c9-0957c67c078b │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-06-09T11:30:50.922080Z │
│ 8618f807-abb4-4fc8-9f5b-9353079f6e79 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-05-31T06:57:27.816925Z │
│ 22022864-0fa5-4d1b-92c6-c3f382b43a35 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2025-11-17T11:52:36.923698Z │
│ ec5bf071-e6c6-4760-b3c9-4a117cb08f7b │ CREATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2025-11-17T11:17:58.133979Z │
└──────────────────────────────────────┴───────────────┴─────────────┴──────────────────────────────┴───────────┴─────────────────────────────┘

gcloud composer operations describe OPERATION_UUID \
  --location LOCATION \
  --format="value(response.config.softwareConfig.imageVersion)"

Executar a operação de reversão

Para reverter o ambiente para um build ou uma versão anterior do Airflow:

gcloud composer environments update \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --airflow-version VERSION

gcloud composer environments update \
  example-environment \
  --location us-central1 \
  --airflow-version airflow-2.11.1-build.21

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.imageVersion

  {
    "config": {
      "softwareConfig": {
        "imageVersion": "composer-3-airflow-2.11.1-build.21"
      }
    }
  }

  resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {
    software_config {
      image_version = "VERSION"
    }
  }
}

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {
    software_config {
      image_version = "airflow-2.11.1-build.21"
    }
  }
}

Se uma operação de reversão falhar durante a execução, o Airflow Gerenciado tentará restaurar automaticamente o ambiente para o estado anterior à operação, que é a versão e o build do Airflow usados antes do início da reversão. Revise a mensagem de erro da operação e os registros no Cloud Logging para detalhes de solução de problemas.

A seguir

• Solução de problemas de atualizações e upgrades
• Lista de versões
• Controle de versões do Airflow gerenciado
• Atualizar ambientes