Mettre à niveau des environnements

Cette page explique comment mettre à niveau votre environnement vers une nouvelle version d'Airflow.

À propos des opérations de mise à niveau

Dans Managed Airflow (3e génération), vous ne gérez pas la version de Managed Airflow de votre environnement :

• Managed Airflow met automatiquement à niveau les composants d'infrastructure de votre environnement. Ces composants sont liés à la fonctionnalité Managed Airflow et ne modifient pas le fonctionnement d'Airflow ni l'exécution de vos DAG Airflow.
• Managed Airflow ne met pas automatiquement à niveau la version et la compilation d'Airflow, les composants Airflow ni les composants étroitement liés aux charges de travail Airflow. Ils ne sont pas modifiés lorsque les composants de l'infrastructure sont mis à niveau automatiquement.
• Vous pouvez effectuer une mise à niveau manuelle vers une nouvelle version ou compilation d'Airflow.

Par exemple, vous pouvez utiliser la même version et la même compilation d'Airflow pendant plusieurs mois, sans effectuer de mise à niveau, et votre environnement reçoit toujours les dernières mises à jour, corrections et améliorations de Managed Airflow pour les composants d'infrastructure de l'environnement. Lorsque vous décidez de passer à une nouvelle version ou compilation d'Airflow, vous mettez à niveau la version d'Airflow dans votre environnement.

À propos de la mise à niveau de la version d'Airflow

Votre environnement modifie la version ou la compilation d'Airflow de la manière suivante :

• Vous contrôlez la version (et la compilation) d'Airflow de votre environnement. Vous pouvez effectuer l'opération de mise à niveau de la version d'Airflow lorsque vous choisissez de passer votre environnement à une autre version d'Airflow. Par exemple, cela peut se produire si la version et la compilation actuelles d'Airflow ne sont plus compatibles.

• Managed Airflow redéploie les composants Airflow de votre environnement à l'aide de la version et de la compilation Airflow spécifiées.

• Managed Airflow applique les modifications de configuration d'Airflow, telles que les packages PyPI personnalisés ou les remplacements d'options de configuration d'Airflow, si votre environnement en disposait avant la mise à niveau.

• Managed Airflow met à jour la connexion Airflow airflow_db pour qu'elle pointe vers la nouvelle base de données Cloud SQL.

La modification de la version d'Airflow ne change pas la façon dont vous vous connectez aux ressources de votre environnement, telles que l'URL du bucket de votre environnement ou le serveur Web Airflow.

À propos des opérations de mise à niveau automatique de l'infrastructure

Managed Airflow exécute régulièrement des opérations de mise à niveau automatique de l'infrastructure :

• Les opérations de mise à niveau automatique de l'infrastructure s'exécutent régulièrement pendant les intervalles de maintenance spécifiés pour l'environnement.

• Il n'est pas possible de désactiver les mises à niveau automatiques de l'infrastructure dans Managed Airflow (Gen 3). Vous pouvez contrôler les périodes pendant lesquelles les mises à niveau automatiques peuvent s'exécuter en spécifiant des intervalles de maintenance personnalisés pour votre environnement.

• Cette opération est visible dans la console Cloud de Confiance et les journaux de l'environnement, comme toute autre opération de longue durée. Pendant l'exécution de l'opération, vous ne pouvez pas démarrer d'autres opérations au niveau de l'environnement (mais vous pouvez toujours exécuter des DAG Airflow).

• Dans certains cas, les mises à niveau automatiques de l'infrastructure peuvent redémarrer les composants Airflow. Lors de ces redémarrages, les nœuds de calcul Airflow sont arrêtés de manière progressive avec un délai de grâce de 24 heures. Si vous avez des tâches qui nécessitent plus de 24 heures, envisagez d'utiliser des opérateurs différables. Une mise à niveau peut entraîner une courte période d'indisponibilité des composants d'infrastructure de l'environnement, tels que la surveillance de l'environnement.

Limites des opérations de mise à niveau et de rollback

Les opérations de mise à niveau sont soumises aux limites suivantes :

• Les versions de Managed Airflow sont déployées progressivement dans toutes les régions compatibles avec Managed Airflow sur plusieurs jours. Il est possible que la dernière version d'une version en cours de déploiement ne soit pas encore disponible dans votre région.

• Dans Managed Airflow (Gen 3), vous pouvez effectuer un rollback d'une mise à niveau vers une version ou un build antérieur d'Airflow, avec les limites suivantes :

  • Les rollbacks sont compatibles avec les mises à niveau effectuées à partir des versions d'Airflow 3 ou des versions d'Airflow 2 à partir de la version airflow-2.7.3-build.0.
  • Les rollbacks sont compatibles avec les mises à niveau effectuées vers les versions cibles airflow-2.11.1-build.20 ou ultérieures, airflow-3.2.2-build.7 ou ultérieures, et airflow-3.3.1-build.3 ou ultérieures.
  • Vous pouvez lancer l'opération de rollback dans les 30 jours suivant la mise à niveau. Si la date de fin de compatibilité de la version Airflow cible est dépassée, vous pouvez toujours effectuer un rollback vers cette version. Vous pouvez effectuer des rollbacks en ignorant des versions. Si vous avez effectué plusieurs mises à niveau en 30 jours, vous pouvez revenir à n'importe quelle version précédemment utilisée, à condition qu'elle respecte les contraintes d'éligibilité.
  • L'environnement est à l'état RUNNING lorsque vous lancez le rollback.

• Vous ne pouvez pas mettre à niveau votre environnement si la base de données Airflow contient plus de 20 Go de données. Lors d'une mise à niveau, un avertissement s'affiche si la taille de la base de données Airflow est supérieure à 20 Go. Dans ce cas, effectuez la maintenance de la base de données pour réduire sa taille.

• Si vous utilisez le mécanisme XCom pour transférer des fichiers, assurez-vous de l'utiliser conformément aux consignes d'Airflow. Le transfert de fichiers volumineux ou d'un grand nombre de fichiers à l'aide de XCom a un impact sur les performances de la base de données Airflow et peut entraîner des échecs lors du chargement d'instantanés ou de la mise à niveau de votre environnement. Envisagez d'utiliser des alternatives telles que Cloud Storage pour transférer de grands volumes de données.

Avant de commencer

• Nous vous recommandons de créer un instantané de l'environnement pour pouvoir le recréer si nécessaire.

• Votre compte doit disposer d'un rôle pouvant déclencher des opérations de mise à niveau de l'environnement. De plus, le compte de service de l'environnement doit disposer d'un rôle doté d'autorisations suffisantes pour effectuer des opérations de mise à niveau. Pour plus d'informations, consultez la section Contrôle des accès.

Vérifier que votre environnement est à jour

Managed Airflow affiche des avertissements lorsque la version d'Airflow de votre environnement approche de sa date de fin de compatibilité. Vous pouvez utiliser ces avertissements pour que votre environnement soit toujours compatible.

Managed Airflow effectue le suivi de la version et de la compilation d'Airflow sur lesquelles votre environnement est basé. À l'approche de la date de fin de compatibilité, un avertissement s'affiche dans la liste des environnements et sur la page Détails de l'environnement.

Pour vérifier si votre environnement est à jour :

Afficher les mises à niveau suggérées

Managed Airflow fournit une liste de builds Airflow vers lesquels vous pouvez mettre à niveau votre environnement.

Pour afficher les versions de Managed Airflow suggérées pour une mise à niveau :

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

Rechercher des conflits de packages PyPI

Vous pouvez vérifier si les packages PyPI installés dans votre environnement présentent des conflits avec les packages préinstallés dans la nouvelle version ou compilation d'Airflow.

Une vérification réussie signifie qu'il n'y a pas de conflit dans les dépendances des packages PyPI entre la version actuelle et la version spécifiée. Toutefois, une opération de mise à niveau peut toujours échouer pour d'autres raisons.

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

Rechercher les conflits avec Managed Airflow (3e génération)

Managed Airflow (3e génération) est la dernière version majeure de Managed Airflow. Vous pouvez vérifier si un environnement Managed Airflow (2e génération) peut être mis à niveau vers Managed Airflow (3e génération) à l'aide d'une vérification de mise à niveau. La description suivante s'applique aux environnements Managed Airflow (2e génération).

Bien qu'il ne soit pas possible de migrer votre environnement de Managed Airflow (Gen 2) vers Managed Airflow (Gen 3) sur place, vous pouvez vérifier les problèmes de compatibilité à l'aide d'une vérification de mise à niveau. Nous vous recommandons de le faire avant de migrer vers Managed Airflow (3e génération).

Pour vérifier la compatibilité avec Managed Airflow (3e génération), effectuez une vérification de mise à niveau standard de votre environnement Managed Airflow (2e génération) et spécifiez une version de Managed Airflow (3e génération) comme cible.

Chaque conflit signalé peut être de l'un des types suivants :

• Les conflits BLOCKING signalent des éléments de configuration d'environnement incompatibles qui ne sont pas compatibles avec Managed Airflow (Gen 3). Nous vous recommandons de résoudre ces conflits avant de commencer une migration vers Managed Airflow (3e génération).

• Les conflits NON_BLOCKING signalent des éléments de configuration de l'environnement qui sont différents dans Managed Airflow (3e génération) et qui peuvent entraîner un comportement inattendu. Par exemple, les modifications des valeurs par défaut telles que les intervalles de maintenance par défaut sont signalées comme des conflits non bloquants. Nous vous recommandons de vérifier si ces conflits peuvent causer des problèmes avant de lancer le processus de migration.

• Les conflits de packages PyPI sont également signalés dans le cadre de cette vérification. Ils sont signalés séparément des conflits de configuration, de la même manière que pour une vérification de compatibilité des packages PyPI standard.

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

Mettre à niveau votre environnement

Pour mettre à niveau votre environnement vers une nouvelle version ou un nouveau build d'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"
    }
  }
}

Effectuer le rollback d'une mise à niveau

Vous pouvez effectuer un rollback d'une mise à niveau d'environnement si vous rencontrez des problèmes de performances, des bugs Airflow ou des problèmes de compatibilité avec vos DAG, plug-ins ou dépendances.

Vous pouvez effectuer un rollback d'une mise à niveau dans les 30 jours suivant l'opération de mise à niveau si l'environnement est à l'état RUNNING. Il est possible de revenir à des versions qui ont atteint leur date de fin de compatibilité. Pour en savoir plus, consultez Limites des opérations de mise à niveau et de rollback.

En plus d'effectuer le rollback d'une seule mise à niveau, vous pouvez :

• Effectuez plusieurs rollbacks successifs :

  Exemple : A > B > C > B > A (si le rollback vers B et A respecte les limites).

• Effectuez des rollbacks en ignorant des versions :

  Exemple : A > B > C > A (si le rollback vers A respecte les limites).

Lors d'un rollback, seule la compilation Airflow de l'environnement est rétablie à la version spécifiée. Managed Airflow préserve les données et l'état de votre environnement lors des rollbacks :

• Fichiers DAG et historique d'exécution : toutes les définitions de DAG, l'historique d'exécution des DAG, les états des instances de tâche et les XComs restent intacts dans la base de données de métadonnées.

• Configuration de l'environnement : les remplacements de configuration Airflow, les variables d'environnement, les packages PyPI personnalisés et les paramètres de scaling sont conservés. Si vous utilisez des exigences de version de package PyPI non strictes pour vos packages PyPI personnalisés, votre environnement peut avoir une version de package différente après le rollback (cette version répondra toujours à l'exigence de version spécifiée).

  Si vous avez modifié la configuration de l'environnement lors de la mise à niveau (par exemple, en modifiant des variables d'environnement ou en ajustant les limites de ressources pour les composants Airflow), ces modifications ne sont pas annulées. Si nécessaire, vous pouvez annuler les modifications manuellement avant ou après le rollback.

• Journaux et surveillance : les journaux d'exécution des tâches stockés dans Cloud Logging et l'historique des métriques dans Cloud Monitoring sont conservés.

Les mises à jour du schéma de base de données Airflow (migrations Alembic) sont automatiquement annulées pour correspondre au schéma de la version Airflow cible. Pour obtenir la liste des migrations de bases de données présentes dans chaque version d'Airflow, consultez Migrations de bases de données Airflow dans la documentation Airflow. Lors d'une opération de rollback, toutes les migrations listées entre la version actuelle d'Airflow et la version cible d'Airflow sont annulées.

Rechercher la version utilisée précédemment

Pour trouver la version précédemment utilisée :

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

Exécuter l'opération de rollback

Pour effectuer un rollback de votre environnement vers une version précédente d'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"
    }
  }
}

Si une opération de rollback échoue pendant l'exécution, Managed Airflow tente automatiquement de restaurer l'environnement à son état antérieur à l'opération, c'est-à-dire la version et la compilation d'Airflow utilisées avant le début du rollback. Consultez le message d'erreur de l'opération et les journaux dans Cloud Logging pour obtenir des informations de dépannage.

Étapes suivantes

• Résoudre les problèmes liés aux mises à jour et aux mises à niveau
• Liste des versions
• Gestion des versions de Managed Airflow
• Mettre à jour des environnements