Upgrade degli ambienti

In questa pagina viene descritto come eseguire l'upgrade dell'ambiente a una nuova versione di Airflow.

Informazioni sulle operazioni di upgrade

In Managed Airflow (Gen 3), non gestisci la versione di Managed Airflow del tuo ambiente:

• Managed Airflow esegue automaticamente l'upgrade dei componenti dell'infrastruttura del tuo ambiente. Questi componenti sono correlati alla funzionalità Managed Airflow e non modificano il funzionamento di Airflow o il modo in cui vengono eseguiti i DAG Airflow.
• Managed Airflow non esegue automaticamente l'upgrade della versione e della build di Airflow, dei componenti Airflow o dei componenti strettamente correlati ai workload Airflow. Non vengono modificati quando i componenti dell'infrastruttura vengono aggiornati automaticamente.
• Puoi eseguire l'upgrade manualmente a una nuova versione o build di Airflow.

Ad esempio, puoi utilizzare la stessa versione e build di Airflow per diversi mesi, senza eseguire alcun upgrade, e il tuo ambiente riceverà comunque gli aggiornamenti, le correzioni e i miglioramenti più recenti di Managed Airflow per i componenti dell'infrastruttura dell'ambiente. Quando in un secondo momento decidi di passare a una nuova versione o build di Airflow, esegui l'upgrade della versione di Airflow nel tuo ambiente.

Informazioni sull'upgrade della versione di Airflow

Il tuo ambiente cambia la versione o la build di Airflow nel seguente modo:

• Sei tu a controllare la versione (e la build) di Airflow del tuo ambiente. Puoi eseguire l'operazione di upgrade della versione di Airflow quando scegli di passare l'ambiente a una versione diversa di Airflow. Ad esempio, questo potrebbe accadere se la versione e la build attuali di Airflow non sono più supportate.

• Managed Airflow esegue nuovamente il deployment dei componenti Airflow del tuo ambiente utilizzando la versione e la build di Airflow specificate.

• Managed Airflow applica le modifiche alla configurazione di Airflow, come i pacchetti PyPI personalizzati o gli override delle opzioni di configurazione di Airflow, se l'ambiente li aveva prima dell'upgrade.

• Managed Airflow aggiorna la connessione Airflow airflow_db in modo che punti al nuovo database Cloud SQL.

La modifica della versione di Airflow non cambia il modo in cui ti connetti alle risorse nel tuo ambiente, ad esempio l'URL del bucket del tuo ambiente o il server web di Airflow.

Informazioni sulle operazioni di upgrade automatico dell'infrastruttura

Managed Airflow esegue periodicamente operazioni di upgrade automatico dell'infrastruttura:

• Le operazioni di upgrade automatico dell'infrastruttura vengono eseguite periodicamente durante i periodi di manutenzione specificati per l'ambiente.

• Non è possibile disattivare gli upgrade automatici dell'infrastruttura in Managed Airflow (Gen 3). Puoi controllare i periodi di tempo in cui possono essere eseguiti gli upgrade automatici specificando periodi di manutenzione personalizzati per il tuo ambiente.

• Questa operazione è visibile nella console Cloud de Confiance e nei log dell'ambiente, come qualsiasi altra operazione a lunga esecuzione. Mentre l'operazione è in esecuzione, non puoi avviare altre operazioni a livello di ambiente (ma puoi comunque eseguire i DAG Airflow).

• In alcuni casi, gli upgrade automatici dell'infrastruttura possono riavviare i componenti Airflow. Durante questi riavvii, i worker Airflow vengono terminati correttamente con un periodo di tolleranza di 24 ore. Se hai attività che richiedono più di 24 ore per essere completate, valuta l'utilizzo di operatori differibili. Un upgrade potrebbe comportare un breve periodo di indisponibilità dei componenti dell'infrastruttura dell'ambiente, ad esempio il monitoraggio dell'ambiente.

Limitazioni delle operazioni di upgrade e rollback

Le operazioni di upgrade presentano le seguenti limitazioni:

• Le release di Managed Airflow vengono implementate gradualmente in tutte le regioni supportate da Managed Airflow nel corso di diversi giorni. L'ultima versione di una release in corso potrebbe non essere ancora disponibile nella tua regione.

• In Managed Airflow (Gen 3), puoi eseguire il rollback di un upgrade a una versione o build precedente di Airflow con le seguenti limitazioni:

  • I rollback sono supportati per gli upgrade eseguiti da versioni di Airflow 3 o da versioni di Airflow 2 a partire dalla build airflow-2.7.3-build.0.
  • I rollback sono supportati per gli upgrade eseguiti alle versioni target airflow-2.11.1-build.20 o successive, airflow-3.2.2-build.7 o successive e airflow-3.3.1-build.3 o successive.
  • Puoi avviare l'operazione di rollback entro 30 giorni dall'upgrade. Se la build Airflow di destinazione ha superato la data di fine del supporto, è comunque possibile eseguire il rollback. Puoi eseguire rollback saltando le versioni. Se hai eseguito l'upgrade più di una volta nell'arco di 30 giorni, puoi eseguire il rollback a qualsiasi versione utilizzata in precedenza, purché soddisfi i vincoli di idoneità.
  • L'ambiente è in stato RUNNING quando avvii il rollback.

• Non puoi eseguire l'upgrade dell'ambiente se il database Airflow contiene più di 20 GB di dati. Durante un upgrade, viene visualizzato un avviso se le dimensioni del database Airflow sono superiori a 20 GB. In questo caso, esegui la manutenzione del database per ridurne le dimensioni.

• Se utilizzi il meccanismo XCom per trasferire i file, assicurati di utilizzarlo in base alle linee guida di Airflow. Il trasferimento di file di grandi dimensioni o di un numero elevato di file utilizzando XCom influisce sulle prestazioni del database Airflow e può causare errori durante il caricamento degli snapshot o l'upgrade dell'ambiente. Valuta la possibilità di utilizzare alternative come Cloud Storage per trasferire grandi volumi di dati.

Prima di iniziare

• Ti consigliamo di creare un nuovo snapshot dell'ambiente per poterlo ricreare, se necessario.

• Il tuo account deve avere un ruolo che possa attivare le operazioni di upgrade dell'ambiente. Inoltre, il account di servizio dell'ambiente deve avere un ruolo con autorizzazioni sufficienti per eseguire le operazioni di upgrade. Per saperne di più, consulta Controllo dell'accesso.

Controlla che l'ambiente sia aggiornato

Managed Airflow visualizza avvisi quando la build Airflow del tuo ambiente si avvicina alla data di fine del supporto. Puoi utilizzare questi avvisi per mantenere sempre il tuo ambiente supportato.

Managed Airflow tiene traccia della versione e della build di Airflow su cui si basa il tuo ambiente. Quando si avvicina la data di fine del supporto, puoi visualizzare un avviso nell'elenco degli ambienti e nella pagina Dettagli ambiente.

Per verificare se l'ambiente è aggiornato:

Visualizza gli upgrade suggeriti

Managed Airflow fornisce un elenco di build di Airflow di cui puoi eseguire l'upgrade nel tuo ambiente.

Per visualizzare le versioni di Managed Airflow suggerite per un 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

Verifica la presenza di conflitti tra i pacchetti PyPI

Puoi verificare se i pacchetti PyPI installati nel tuo ambiente presentano conflitti con i pacchetti preinstallati nella nuova versione o build di Airflow.

Un controllo riuscito indica che non esistono conflitti nelle dipendenze dei pacchetti PyPI tra la versione attuale e quella specificata. Tuttavia, un'operazione di upgrade potrebbe comunque non riuscire per altri motivi.

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"
}

Verifica la presenza di conflitti con Managed Airflow (3ª gen.)

Managed Airflow (Gen 3) è l'ultima versione principale di Managed Airflow. Puoi verificare se un ambiente Managed Airflow (Gen 2) può essere aggiornato a Managed Airflow (Gen 3) con un controllo dell'upgrade. La seguente descrizione si applica agli ambienti Managed Airflow (2ª gen.).

Sebbene non sia possibile eseguire la migrazione dell'ambiente da Managed Airflow (Gen 2) a Managed Airflow (Gen 3) in loco, puoi verificare la presenza di problemi di compatibilità utilizzando un controllo dell'upgrade. Ti consigliamo di farlo prima di eseguire la migrazione a Managed Airflow (3ª gen.).

Per verificare la compatibilità con Managed Airflow (Gen 3), esegui un controllo di upgrade regolare del tuo ambiente Managed Airflow (Gen 2) e specifica una versione di Managed Airflow (Gen 3) come target.

Ogni conflitto segnalato può avere i seguenti tipi:

• BLOCKING conflitti segnalano elementi di configurazione dell'ambiente incompatibili che non sono supportati in Managed Airflow (Gen 3). Ti consigliamo di risolvere questi conflitti prima di avviare una migrazione a Managed Airflow (3ª gen.).

• I conflitti di NON_BLOCKING segnalano elementi di configurazione dell'ambiente diversi in Managed Airflow (3ª gen.) e potrebbero causare un comportamento imprevisto. Ad esempio, le modifiche ai valori predefiniti, come i periodi di manutenzione predefiniti, vengono segnalate come conflitti non bloccanti. Ti consigliamo di verificare se questi conflitti possono causare problemi prima di avviare il processo di migrazione.

• Nell'ambito di questo controllo vengono segnalati anche i conflitti tra i pacchetti PyPI. Vengono segnalati separatamente dai conflitti di configurazione, nello stesso modo di un normale controllo della compatibilità dei pacchetti PyPI.

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"
}

Esegui l'upgrade dell'ambiente

Per eseguire l'upgrade dell'ambiente a una nuova versione o build di 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"
    }
  }
}

Esegui il rollback di un upgrade

Puoi eseguire il rollback di un upgrade dell'ambiente se riscontri un peggioramento delle prestazioni, bug di Airflow o problemi di compatibilità con i tuoi DAG, plug-in o dipendenze.

Puoi eseguire il rollback di un upgrade entro 30 giorni dall'operazione di upgrade se l'ambiente è nello stato RUNNING. È possibile eseguire il rollback alle versioni che hanno raggiunto la data di fine del supporto. Per saperne di più, consulta Limitazioni delle operazioni di upgrade e rollback.

Oltre a eseguire il rollback di un singolo upgrade, puoi:

• Esegui più rollback successivi:

  Esempio: A > B > C > B > A (se il rollback a B e A soddisfa le limitazioni).

• Esegui i rollback con salto di versione:

  Esempio: A > B > C > A (se il rollback ad A soddisfa le limitazioni).

Durante un rollback, viene ripristinata solo la build Airflow dell'ambiente alla versione specificata. Managed Airflow conserva i dati e lo stato dell'ambiente durante i rollback:

• File DAG e cronologia di esecuzione: tutte le definizioni dei DAG, la cronologia delle esecuzioni dei DAG, gli stati delle istanze delle attività e gli XCom rimangono intatti nel database dei metadati.

• Configurazione dell'ambiente: gli override della configurazione di Airflow, le variabili di ambiente, i pacchetti PyPI personalizzati e le impostazioni di scalabilità vengono conservati. Se utilizzi requisiti di versione dei pacchetti PyPI non rigidi per i tuoi pacchetti PyPI personalizzati, l'ambiente potrebbe avere una versione del pacchetto diversa dopo il rollback (questa versione soddisferà comunque il requisito di versione specificato).

  Se hai modificato la configurazione dell'ambiente durante l'upgrade, ad esempio modificando le variabili di ambiente o i limiti delle risorse per i componenti Airflow, queste modifiche non vengono annullate. Se necessario, puoi ripristinare le modifiche manualmente prima o dopo il rollback.

• Log e monitoraggio: i log di esecuzione delle attività archiviati in Cloud Logging e la cronologia delle metriche in Cloud Monitoring vengono conservati.

Viene eseguito automaticamente il rollback degli aggiornamenti dello schema del database Airflow (migrazioni Alembic) in modo che corrispondano allo schema della versione Airflow di destinazione. Per l'elenco delle migrazioni del database presenti in ogni versione di Airflow, consulta Migrazioni del database Airflow nella documentazione di Airflow. Durante un'operazione di rollback, viene eseguito il rollback di tutte le migrazioni elencate tra la versione attuale di Airflow e la versione di Airflow di destinazione.

Trova la versione utilizzata in precedenza

Per trovare la versione utilizzata in precedenza:

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)"

Esegui l'operazione di rollback

Per eseguire il rollback dell'ambiente a una build o versione precedente di 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 un'operazione di rollback non riesce durante l'esecuzione, Managed Airflow tenta automaticamente di ripristinare l'ambiente allo stato precedente all'operazione, ovvero alla versione e alla build di Airflow utilizzate prima dell'avvio del rollback. Esamina il messaggio di errore dell'operazione e i log in Cloud Logging per i dettagli sulla risoluzione dei problemi.

Passaggi successivi

• Risoluzione dei problemi relativi agli upgrade e agli aggiornamenti
• Elenco delle versioni
• Controllo delle versioni di Managed Airflow
• Aggiorna gli ambienti