Mengupgrade lingkungan

Halaman ini menjelaskan cara mengupgrade lingkungan Anda ke versi Airflow baru.

Tentang operasi upgrade

Di Managed Airflow (Gen 3), Anda tidak mengelola versi Managed Airflow lingkungan Anda:

• Managed Airflow otomatis mengupgrade komponen infrastruktur lingkungan Anda. Komponen ini terkait dengan fungsi Managed Airflow dan tidak mengubah cara kerja Airflow atau cara DAG Airflow Anda dijalankan.
• Managed Airflow tidak otomatis mengupgrade versi dan build Airflow, komponen Airflow, atau komponen yang terkait erat dengan workload Airflow. Komponen tersebut tidak berubah saat komponen infrastruktur diupgrade secara otomatis.
• Anda dapat mengupgrade secara manual ke versi atau build Airflow baru.

Misalnya, Anda dapat menggunakan versi dan build Airflow yang sama selama beberapa bulan, tanpa melakukan upgrade apa pun, dan lingkungan Anda masih menerima update, perbaikan, dan peningkatan Managed Airflow terbaru dari komponen infrastruktur lingkungan. Jika nanti Anda memutuskan untuk beralih ke versi atau build Airflow baru, Anda dapat mengupgrade versi Airflow di lingkungan Anda.

Tentang upgrade versi Airflow

Lingkungan Anda mengubah versi atau build Airflow dengan cara berikut:

• Anda mengontrol versi (dan build) Airflow di lingkungan Anda. Anda dapat melakukan operasi upgrade versi Airflow saat memilih untuk mengalihkan lingkungan Anda ke versi Airflow yang berbeda. Misalnya, hal ini mungkin terjadi jika versi dan build Airflow saat ini tidak lagi didukung.

• Managed Airflow men-deploy ulang komponen Airflow lingkungan Anda menggunakan versi dan build Airflow yang ditentukan.

• Managed Airflow menerapkan perubahan konfigurasi Airflow, seperti paket PyPI kustom atau penggantian opsi konfigurasi Airflow, jika lingkungan Anda memilikinya sebelum upgrade.

• Managed Airflow mengupdate koneksi airflow_db Airflow agar mengarah ke database Cloud SQL baru.

Mengubah versi Airflow tidak akan mengubah cara Anda terhubung ke resource di lingkungan Anda, seperti URL bucket lingkungan Anda, atau server web Airflow.

Tentang operasi upgrade infrastruktur otomatis

Managed Airflow secara berkala menjalankan operasi upgrade infrastruktur otomatis:

• Operasi upgrade infrastruktur otomatis berjalan secara berkala selama masa pemeliharaan yang ditentukan untuk lingkungan.

• Anda tidak dapat menonaktifkan upgrade infrastruktur otomatis di Managed Airflow (Gen 3). Anda dapat mengontrol jangka waktu saat upgrade otomatis dapat dijalankan dengan menentukan masa pemeliharaan kustom untuk lingkungan Anda.

• Operasi ini terlihat di konsol Cloud de Confiance dan log lingkungan, seperti operasi yang berjalan lama lainnya. Saat operasi berjalan, Anda tidak dapat memulai operasi lain di level lingkungan (tetapi Anda masih dapat menjalankan DAG Airflow).

• Dalam beberapa kasus, upgrade infrastruktur otomatis dapat memulai ulang komponen Airflow. Selama mulai ulang tersebut, worker Airflow dihentikan dengan baik dengan masa tenggang 24 jam. Jika Anda memiliki tugas yang memerlukan waktu lebih dari 24 jam untuk diselesaikan, pertimbangkan untuk menggunakan operator yang dapat ditangguhkan. Upgrade dapat mengakibatkan komponen infrastruktur lingkungan, seperti pemantauan lingkungan, tidak tersedia dalam waktu singkat.

Batasan operasi upgrade dan rollback

Operasi upgrade memiliki batasan berikut:

• Rilis Managed Airflow diluncurkan secara bertahap ke semua region yang didukung oleh Managed Airflow selama beberapa hari. Versi terbaru dari rilis yang sedang berlangsung mungkin belum tersedia di wilayah Anda.

• Di Managed Airflow (Gen 3), Anda dapat me-roll back upgrade ke versi atau build Airflow sebelumnya dengan batasan berikut:

  • Rollback didukung untuk upgrade yang dilakukan dari versi Airflow 3, atau dari versi Airflow 2 yang dimulai dengan build airflow-2.7.3-build.0.
  • Rollback didukung untuk upgrade yang dilakukan ke versi target airflow-2.11.1-build.20 atau yang lebih baru, airflow-3.2.2-build.7 atau yang lebih baru, dan airflow-3.3.1-build.3 atau yang lebih baru.
  • Anda dapat memulai operasi rollback dalam waktu 30 hari setelah upgrade. Jika build Airflow target telah melewati tanggal akhir dukungan, Anda masih dapat melakukan roll back ke build tersebut. Anda dapat melakukan rollback dengan melewati versi. Jika Anda telah mengupgrade lebih dari sekali dalam waktu 30 hari, Anda dapat melakukan roll back ke versi yang digunakan sebelumnya selama versi tersebut memenuhi batasan kelayakan.
  • Lingkungan berada dalam status RUNNING saat Anda memulai rollback.

• Anda tidak dapat mengupgrade lingkungan jika database Airflow berisi lebih dari 20 GB data. Selama upgrade, peringatan akan ditampilkan jika ukuran database Airflow lebih dari 20 GB. Dalam hal ini, lakukan pemeliharaan database untuk mengurangi ukuran database.

• Jika Anda menggunakan mekanisme XCom untuk mentransfer file, pastikan Anda menggunakannya sesuai dengan panduan Airflow. Mentransfer file besar atau file dalam jumlah besar menggunakan XCom akan memengaruhi performa database Airflow dan dapat menyebabkan kegagalan saat memuat snapshot atau mengupgrade lingkungan Anda. Pertimbangkan untuk menggunakan alternatif seperti Cloud Storage untuk mentransfer data dalam volume besar.

Sebelum memulai

• Sebaiknya buat snapshot baru lingkungan agar dapat membuat ulang lingkungan jika diperlukan.

• Akun Anda harus memiliki peran yang dapat memicu operasi upgrade lingkungan. Selain itu, akun layanan lingkungan harus memiliki peran yang memiliki izin yang cukup untuk melakukan operasi upgrade. Untuk mengetahui informasi selengkapnya, lihat Kontrol akses.

Memastikan lingkungan Anda sudah yang terbaru

Managed Airflow menampilkan peringatan saat build Airflow lingkungan Anda mendekati akhir tanggal dukungan. Anda dapat menggunakan peringatan ini untuk selalu menjaga lingkungan Anda tetap didukung.

Managed Airflow melacak versi dan build Airflow yang menjadi dasar lingkungan Anda. Saat mendekati tanggal akhir dukungan, Anda dapat melihat peringatan dalam daftar lingkungan dan di halaman Detail lingkungan.

Untuk memeriksa apakah lingkungan Anda sudah yang terbaru:

Lihat upgrade yang disarankan

Managed Airflow menyediakan daftar build Airflow yang dapat Anda gunakan untuk mengupgrade lingkungan.

Untuk melihat versi Managed Airflow yang disarankan untuk diupgrade:

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

Memeriksa konflik paket PyPI

Anda dapat memeriksa apakah paket PyPI yang diinstal di lingkungan Anda memiliki konflik dengan paket yang telah diinstal sebelumnya di versi atau build Airflow baru.

Pemeriksaan yang berhasil berarti tidak ada konflik dalam dependensi paket PyPI antara versi saat ini dan versi yang ditentukan. Namun, operasi upgrade mungkin masih belum berhasil karena alasan lain.

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

Memeriksa konflik dengan Managed Airflow (Gen 3)

Managed Airflow (Gen 3) adalah versi utama terbaru dari Managed Airflow. Anda dapat memeriksa apakah lingkungan Managed Airflow (Gen 2) dapat diupgrade ke Managed Airflow (Gen 3) dengan pemeriksaan upgrade. Deskripsi berikut berlaku untuk lingkungan Managed Airflow (Gen 2).

Meskipun Anda tidak dapat memigrasikan lingkungan dari Managed Airflow (Gen 2) ke Managed Airflow (Gen 3) di tempat, Anda dapat memeriksa masalah kompatibilitas menggunakan pemeriksaan upgrade. Sebaiknya lakukan hal ini sebelum bermigrasi ke Managed Airflow (Gen 3).

Untuk memeriksa kompatibilitas dengan Managed Airflow (Gen 3), lakukan pemeriksaan upgrade rutin pada lingkungan Managed Airflow (Gen 2) Anda dan tentukan versi Managed Airflow (Gen 3) sebagai target.

Setiap konflik yang dilaporkan dapat memiliki jenis berikut:

• BLOCKING melaporkan elemen konfigurasi lingkungan yang tidak kompatibel dan tidak didukung di Managed Airflow (Gen 3). Sebaiknya selesaikan konflik ini sebelum memulai migrasi ke Managed Airflow (Gen 3).

• Konflik NON_BLOCKING melaporkan elemen konfigurasi lingkungan yang berbeda di Managed Airflow (Gen 3) dan dapat menyebabkan perilaku yang tidak terduga. Misalnya, perubahan nilai default seperti masa pemeliharaan default dilaporkan sebagai konflik yang tidak memblokir. Sebaiknya periksa apakah konflik ini dapat menyebabkan masalah sebelum memulai proses migrasi.

• Konflik paket PyPI juga dilaporkan sebagai bagian dari pemeriksaan ini. Konflik ini dilaporkan secara terpisah dari konflik konfigurasi, dengan cara yang sama seperti untuk pemeriksaan kompatibilitas paket PyPI reguler.

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

Mengupgrade lingkungan Anda

Untuk mengupgrade lingkungan Anda ke versi atau build Airflow baru:

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

Me-roll back upgrade

Anda dapat melakukan roll back upgrade lingkungan jika mengalami penurunan performa, bug Airflow, atau masalah kompatibilitas dengan DAG, plugin, atau dependensi Anda.

Anda dapat me-roll back upgrade dalam waktu 30 hari setelah operasi upgrade jika lingkungan berada dalam status RUNNING. Anda dapat melakukan roll back ke versi yang telah mencapai tanggal akhir dukungan. Untuk mengetahui informasi selengkapnya, lihat Batasan operasi upgrade dan rollback.

Selain me-roll back satu upgrade, Anda dapat:

• Melakukan beberapa rollback berturut-turut:

  Contoh: A > B > C > B > A (jika melakukan roll back ke B dan A memenuhi batasan).

• Melakukan rollback lewati versi:

  Contoh: A > B > C > A (jika melakukan roll back ke A memenuhi batasan).

Selama rollback, hanya build Airflow lingkungan yang akan dikembalikan ke versi yang ditentukan. Managed Airflow mempertahankan data dan status lingkungan Anda selama rollback:

• File DAG dan histori eksekusi: Semua definisi DAG, histori operasi DAG, status instance tugas, dan XCom tetap utuh dalam database metadata.

• Konfigurasi lingkungan: Penggantian konfigurasi Airflow, variabel lingkungan, paket PyPI kustom, dan setelan penskalaan dipertahankan. Jika Anda menggunakan persyaratan versi paket PyPI non-ketat untuk paket PyPI kustom, lingkungan Anda mungkin memiliki versi paket yang berbeda setelah rollback (versi ini akan tetap memenuhi persyaratan versi yang ditentukan).

  Jika Anda mengubah konfigurasi lingkungan selama upgrade, seperti mengubah variabel lingkungan atau menyesuaikan batas resource untuk komponen Airflow, perubahan ini tidak akan dikembalikan. Jika diperlukan, Anda dapat mengembalikan perubahan secara manual sebelum atau setelah rollback.

• Log dan pemantauan: Log eksekusi tugas yang disimpan di Cloud Logging dan histori metrik di Cloud Monitoring akan dipertahankan.

Update skema database Airflow (migrasi Alembic) otomatis di-roll back agar sesuai dengan skema versi Airflow target. Untuk mengetahui daftar migrasi database yang ada di setiap versi Airflow, lihat Migrasi Database Airflow dalam dokumentasi Airflow. Selama operasi rollback, semua migrasi yang tercantum antara versi Airflow saat ini dan versi Airflow target akan di-roll back.

Menemukan versi yang digunakan sebelumnya

Untuk menemukan versi yang digunakan sebelumnya:

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

Menjalankan operasi rollback

Untuk melakukan roll back lingkungan Anda ke build atau versi Airflow sebelumnya:

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

Jika operasi rollback gagal selama eksekusi, Managed Airflow akan otomatis mencoba memulihkan lingkungan ke status pra-operasi, yaitu versi dan build Airflow yang digunakan sebelum rollback dimulai. Tinjau pesan error dan log operasi di Cloud Logging untuk mengetahui detail pemecahan masalah.

Langkah berikutnya

• Memecahkan masalah update dan upgrade
• Daftar versi
• Pembuatan versi Managed Airflow
• Memperbarui lingkungan