Upgrade für Umgebungen ausführen

Auf dieser Seite wird beschrieben, wie Sie Ihre Umgebung auf eine neue Airflow-Version aktualisieren.

Upgradevorgänge

In Managed Airflow (Gen 3) verwalten Sie die Managed Airflow-Version Ihrer Umgebung nicht:

• Managed Airflow aktualisiert die Infrastrukturkomponenten Ihrer Umgebung automatisch. Diese Komponenten hängen mit der Funktionalität von Managed Airflow zusammen und ändern weder die Funktionsweise von Airflow noch die Ausführung Ihrer Airflow-DAGs.
• Managed Airflow aktualisiert die Airflow-Version und den Build, die Airflow-Komponenten oder die Komponenten, die eng mit Airflow-Arbeitslasten verbunden sind, nicht automatisch. Sie werden nicht geändert, wenn die Infrastrukturkomponenten automatisch aktualisiert werden.
• Sie können ein manuelles Upgrade auf eine neue Airflow-Version oder einen neuen Build durchführen.

Sie können beispielsweise mehrere Monate lang dieselbe Version und denselben Build von Airflow verwenden, ohne Upgrades durchzuführen. Ihre Umgebung erhält trotzdem die neuesten Managed Airflow-Updates, -Fehlerkorrekturen und -Verbesserungen der Infrastrukturkomponenten der Umgebung. Wenn Sie später zu einer neuen Version oder einem neuen Build von Airflow wechseln möchten, aktualisieren Sie die Airflow-Version in Ihrer Umgebung.

Informationen zum Upgrade der Airflow-Version

In Ihrer Umgebung wird die Version oder der Build von Airflow so geändert:

• Sie steuern die Airflow-Version (und den Build) Ihrer Umgebung. Sie können das Airflow-Versionsupgrade ausführen, wenn Sie Ihre Umgebung auf eine andere Airflow-Version umstellen möchten. Das kann beispielsweise passieren, wenn die aktuelle Version und der aktuelle Build von Airflow nicht mehr unterstützt werden.

• Managed Airflow stellt die Airflow-Komponenten Ihrer Umgebung mit der angegebenen Airflow-Version und dem angegebenen Build neu bereit.

• Managed Airflow wendet Airflow-Konfigurationsänderungen wie benutzerdefinierte PyPI-Pakete oder Überschreibungen von Airflow-Konfigurationsoptionen an, wenn diese vor dem Upgrade in Ihrer Umgebung vorhanden waren.

• Managed Airflow aktualisiert die Airflow-airflow_db-Verbindung, sodass sie auf die neue Cloud SQL-Datenbank verweist.

Wenn Sie die Airflow-Version ändern, ändert sich nicht, wie Sie eine Verbindung zu den Ressourcen in Ihrer Umgebung herstellen, z. B. zur URL des Buckets Ihrer Umgebung oder zum Airflow-Webserver.

Automatische Infrastrukturupgrades

Managed Airflow führt regelmäßig automatische Infrastruktur-Upgrades aus:

• Automatische Infrastrukturupgrades werden regelmäßig während der für die Umgebung angegebenen Wartungsfenster ausgeführt.

• Es ist nicht möglich, automatische Infrastrukturupgrades in Managed Airflow (Gen 3) zu deaktivieren. Sie können die Zeiträume, in denen automatische Upgrades ausgeführt werden können, steuern, indem Sie benutzerdefinierte Wartungsfenster für Ihre Umgebung angeben.

• Dieser Vorgang ist wie jeder andere Vorgang mit langer Ausführungszeit in der Cloud de Confiance Console und in den Umgebungsprotokollen sichtbar. Während der Vorgang ausgeführt wird, können Sie keine anderen Vorgänge auf Umgebungsebene starten. Sie können jedoch weiterhin Airflow-DAGs ausführen.

• In einigen Fällen können automatische Infrastrukturupgrades Airflow-Komponenten neu starten. Während solcher Neustarts werden Airflow-Worker mit einer Kulanzzeit von 24 Stunden ordnungsgemäß beendet. Wenn Sie Aufgaben haben, die länger als 24 Stunden dauern, sollten Sie zurückstellbare Operatoren verwenden. Ein Upgrade kann dazu führen, dass Infrastrukturkomponenten der Umgebung, z. B. das Umgebungsmonitoring, kurzzeitig nicht verfügbar sind.

Einschränkungen bei Upgrade- und Rollback-Vorgängen

Für Upgradevorgänge gelten die folgenden Einschränkungen:

• Managed Airflow-Releases werden über mehrere Tage hinweg schrittweise in allen von Managed Airflow unterstützten Regionen eingeführt. Die neueste Version eines laufenden Release ist in Ihrer Region möglicherweise noch nicht verfügbar.

• In Managed Airflow (Gen 3) können Sie ein Rollback eines Upgrades auf eine frühere Version oder einen früheren Build von Airflow durchführen. Dabei gelten die folgenden Einschränkungen:

  • Rollbacks werden für Upgrades von Airflow 3-Versionen oder von Airflow 2-Versionen ab dem Build airflow-2.7.3-build.0 unterstützt.
  • Rollbacks werden für Upgrades auf die Zielversionen airflow-2.11.1-build.20 oder höher, airflow-3.2.2-build.7 oder höher und airflow-3.3.1-build.3 oder höher unterstützt.
  • Sie können den Rollback-Vorgang innerhalb von 30 Tagen nach dem Upgrade starten. Wenn das Enddatum des Supports für den Ziel-Airflow-Build überschritten ist, können Sie trotzdem ein Rollback darauf durchführen. Sie können Rollbacks mit Versionsüberspringung durchführen. Wenn Sie innerhalb von 30 Tagen mehr als ein Upgrade durchgeführt haben, können Sie ein Rollback auf eine zuvor verwendete Version durchführen, sofern diese die Voraussetzungen erfüllt.
  • Die Umgebung befindet sich im Status RUNNING, wenn Sie den Rollback starten.

• Sie können Ihre Umgebung nicht aktualisieren, wenn die Airflow-Datenbank mehr als 20 GB Daten enthält. Während eines Upgrades wird eine Warnung angezeigt, wenn die Airflow-Datenbank größer als 20 GB ist. Führen Sie in diesem Fall die Datenbankwartung aus, um die Datenbankgröße zu reduzieren.

• Wenn Sie den XCom-Mechanismus zum Übertragen von Dateien verwenden, achten Sie darauf, dass Sie ihn gemäß den Airflow-Richtlinien verwenden. Die Übertragung großer Dateien oder einer großen Anzahl von Dateien mit XCom wirkt sich auf die Leistung der Airflow-Datenbank aus und kann zu Fehlern beim Laden von Snapshots oder beim Upgrade Ihrer Umgebung führen. Ziehen Sie Alternativen wie Cloud Storage in Betracht, um große Datenmengen zu übertragen.

Hinweis

• Wir empfehlen, einen neuen Snapshot der Umgebung zu erstellen, damit Sie die Umgebung bei Bedarf neu erstellen können.

• Ihr Konto muss eine Rolle haben, die Vorgänge zum Upgrade der Umgebung auslösen kann. Darüber hinaus muss das Dienstkonto der Umgebung eine Rolle mit ausreichenden Berechtigungen zum Ausführen von Upgradevorgängen haben. Weitere Informationen finden Sie unter Zugriffssteuerung.

Prüfen, ob die Umgebung auf dem neuesten Stand ist

Managed Airflow zeigt Warnungen an, wenn der Airflow-Build Ihrer Umgebung sich dem Ende des Supports nähert. Anhand dieser Warnungen können Sie dafür sorgen, dass Ihre Umgebung immer unterstützt wird.

Managed Airflow verfolgt die Airflow-Version und den Build, auf dem Ihre Umgebung basiert. Wenn das Ende des Supportdatums näher rückt, wird in der Liste der Umgebungen und auf der Seite Umgebungsdetails eine Warnung angezeigt.

So prüfen Sie, ob Ihre Umgebung auf dem neuesten Stand ist:

Vorgeschlagene Upgrades ansehen

Managed Airflow bietet eine Liste von Airflow-Builds, auf die Sie Ihre Umgebung aktualisieren können.

So rufen Sie die für ein Upgrade vorgeschlagenen Managed Airflow-Versionen auf:

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

Auf PyPI-Paketkonflikte prüfen

Sie können prüfen, ob in Ihrer Umgebung installierte PyPI-Pakete mit vorinstallierten Paketen in der neuen Airflow-Version oder dem neuen Build in Konflikt stehen.

Eine erfolgreiche Prüfung bedeutet, dass es keine Konflikte bei den PyPI-Paketabhängigkeiten zwischen der aktuellen und der angegebenen Version gibt. Ein Upgradevorgang kann jedoch aus anderen Gründen fehlschlagen.

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

Auf Konflikte mit Managed Airflow (Gen 3) prüfen

Managed Airflow (Gen 3) ist die neueste Hauptversion von Managed Airflow. Mit einer Upgrade-Prüfung können Sie feststellen, ob eine Managed Airflow-Umgebung (Gen 2) auf Managed Airflow (Gen 3) aktualisiert werden kann. Die folgende Beschreibung gilt für Managed Airflow-Umgebungen (Gen 2).

Es ist nicht möglich, Ihre Umgebung direkt von Managed Airflow (Gen 2) zu Managed Airflow (Gen 3) zu migrieren. Sie können jedoch mit einer Upgrade-Prüfung nach Kompatibilitätsproblemen suchen. Wir empfehlen, dies vor der Migration zu Managed Airflow (Gen 3) zu tun.

Wenn Sie die Kompatibilität mit Managed Airflow (Gen 3) prüfen möchten, führen Sie eine reguläre Upgrade-Prüfung Ihrer Managed Airflow (Gen 2)-Umgebung durch und geben Sie eine Managed Airflow (Gen 3)-Version als Ziel an.

Jeder gemeldete Konflikt kann einen der folgenden Typen haben:

• BLOCKING-Konflikte melden inkompatible Umgebungskonfigurationselemente, die in Managed Airflow (Gen 3) nicht unterstützt werden. Wir empfehlen, diese Konflikte zu beheben, bevor Sie mit der Migration zu Managed Airflow (Gen 3) beginnen.

• NON_BLOCKING-Konflikte melden Umgebungskonfigurationselemente, die sich in Managed Airflow (Gen 3) unterscheiden und zu unerwartetem Verhalten führen können. Beispielsweise werden Änderungen der Standardwerte wie Standardwartungsfenster als nicht blockierende Konflikte gemeldet. Wir empfehlen, vor Beginn der Migration zu prüfen, ob diese Konflikte Probleme verursachen können.

• Im Rahmen dieser Prüfung werden auch PyPI-Paketkonflikte gemeldet. Sie werden separat von den Konfigurationskonflikten gemeldet, genau wie bei einer regulären Kompatibilitätsprüfung für PyPI-Pakete.

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

Upgrade der Umgebung durchführen

So aktualisieren Sie Ihre Umgebung auf eine neue Version oder einen neuen Build von 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"
    }
  }
}

Rollback eines Upgrade durchführen

Sie können ein Upgrade der Umgebung rückgängig machen, wenn Sie Leistungseinbußen, Airflow-Fehler oder Kompatibilitätsprobleme mit Ihren DAGs, Plug-ins oder Abhängigkeiten feststellen.

Sie können ein Upgrade innerhalb von 30 Tagen nach dem Upgradevorgang rückgängig machen, wenn sich die Umgebung im Status RUNNING befindet. Es ist möglich, ein Rollback auf Versionen durchzuführen, die das Ende des Supports erreicht haben. Weitere Informationen finden Sie unter Einschränkungen von Upgrade- und Rollback-Vorgängen.

Zusätzlich zum Rollback eines einzelnen Upgrades können Sie Folgendes tun:

• Führen Sie mehrere aufeinanderfolgende Rollbacks durch:

  Beispiel: A > B > C > B > A (wenn ein Rollback auf B und A die Einschränkungen erfüllt).

• Rollbacks mit Überspringen von Versionen durchführen:

  Beispiel: A > B > C > A (wenn ein Rollback zu A die Einschränkungen erfüllt).

Bei einem Rollback wird nur der Airflow-Build der Umgebung auf die angegebene Version zurückgesetzt. Managed Airflow behält die Daten und den Status Ihrer Umgebung während Rollbacks bei:

• DAG-Dateien und Ausführungsverlauf: Alle DAG-Definitionen, der DAG-Ausführungsverlauf, die Status der Aufgabeninstanzen und XComs bleiben in der Metadatendatenbank intakt.

• Umgebungskonfiguration: Airflow-Konfigurationsüberschreibungen, Umgebungsvariablen, benutzerdefinierte PyPI-Pakete und Skalierungseinstellungen werden beibehalten. Wenn Sie für Ihre benutzerdefinierten PyPI-Pakete keine strengen Anforderungen an die PyPI-Paketversion verwenden, hat Ihre Umgebung nach dem Rollback möglicherweise eine andere Paketversion. Diese Version erfüllt jedoch weiterhin die angegebene Versionsanforderung.

  Wenn Sie während des Upgrades die Umgebungskonfiguration geändert haben, z. B. Umgebungsvariablen oder Ressourcenlimits für Airflow-Komponenten, werden diese Änderungen nicht rückgängig gemacht. Bei Bedarf können Sie die Änderungen vor oder nach dem Rollback manuell rückgängig machen.

• Logs und Monitoring: In Cloud Logging gespeicherte Logs zur Aufgabenausführung und der Messwertverlauf in Cloud Monitoring bleiben erhalten.

Airflow-Datenbankschema-Updates (Alembic-Migrationen) werden automatisch zurückgesetzt, um dem Zielschema der Airflow-Version zu entsprechen. Eine Liste der Datenbankmigrationen, die in den einzelnen Airflow-Versionen vorhanden sind, finden Sie in der Airflow-Dokumentation unter Airflow-Datenbankmigrationen. Während eines Rollback-Vorgangs werden alle aufgeführten Migrationen zwischen der aktuellen Airflow-Version und der Ziel-Airflow-Version zurückgesetzt.

Zuvor verwendete Version finden

So finden Sie die zuvor verwendete Version:

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

Rollback-Vorgang ausführen

So führen Sie ein Rollback Ihrer Umgebung auf einen vorherigen Build oder eine vorherige Version von Airflow durch:

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

Wenn ein Rollback-Vorgang während der Ausführung fehlschlägt, versucht Managed Airflow automatisch, die Umgebung auf den Zustand vor dem Vorgang zurückzusetzen. Dies ist die Airflow-Version und der Build, die vor dem Start des Rollbacks verwendet wurden. Sehen Sie sich die Fehlermeldung und die Logs in Cloud Logging an, um Details zur Fehlerbehebung zu erhalten.

Nächste Schritte

• Fehlerbehebung bei Updates und Upgrades
• Liste der Versionen
• Managed Airflow-Versionsverwaltung
• Umgebungen aktualisieren