2026 年 9 月 15 日，所有 Cloud Composer 1 和 Cloud Composer 2 2.0.x 版環境將達到預計的生命週期終止日，屆時您將無法使用這些環境。建議您規劃遷移至 Cloud Composer 3。

本頁面由 Cloud Translation API 翻譯而成。

將環境遷移至 Cloud Composer 3 (遷移指令碼)

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

本頁說明如何使用遷移指令碼，將現有 Cloud Composer 2 環境中的 DAG、資料和設定遷移至新的 Cloud Composer 3 環境。

其他遷移指南

寄件者	收件者	方法	指南
Cloud Composer 2	Cloud Composer 3	並排使用遷移指令碼	本指南
Cloud Composer 2	Cloud Composer 3	並排比較快照	快照遷移指南
Cloud Composer 1、Airflow 2	Cloud Composer 3	並排比較快照	快照遷移指南
Cloud Composer 1、Airflow 2	Cloud Composer 2	並排比較快照	快照遷移指南
Cloud Composer 1、Airflow 2	Cloud Composer 2	並排比較，手動轉移	手動遷移指南
Cloud Composer 1、Airflow 1	Cloud Composer 2、Airflow 2	並排比較快照	快照遷移指南
Cloud Composer 1、Airflow 1	Cloud Composer 2、Airflow 2	並排比較，手動轉移	手動遷移指南
Cloud Composer 1、Airflow 1	Cloud Composer 1、Airflow 2	並排比較，手動轉移	手動遷移指南

關於遷移指令碼

遷移指令碼是 Python 指令碼，適用於並行遷移作業，可自動將 Cloud Composer 2 遷移至 Cloud Composer 3。這項功能會使用環境快照，將環境設定轉移至新環境。

指令碼會執行下列動作：

取得 Cloud Composer 2 環境的設定。
建立 Cloud Composer 3 環境，並使用與取得的設定相符的設定。

由於 Cloud Composer 3 環境採用不同架構，部分參數可能會經過調整，以配合這些差異。您也可以稍後調整大部分的環境參數。
逐一暫停 Cloud Composer 2 環境中的所有 DAG。只有先前在 Cloud Composer 2 環境中取消暫停的 DAG，才會在稍後取消暫停。

注意： 如果環境中有大量 DAG，這個程序可能需要很長時間。您可以使用 composer_dags 指令碼，在執行遷移作業前暫停所有 DAG，並在遷移作業完成後取消暫停 DAG。在這種情況下，遷移指令碼不會取消暫停 DAG。詳情請參閱 GitHub 上 composer_dags 指令碼的 README 檔案。
儲存來源 Cloud Composer 2 環境的快照。快照會儲存在快照的預設位置，也就是 Cloud Composer 2 環境的值區。
將快照載入 Cloud Composer 3 環境。

指令碼不會檢查自訂 PyPI 套件、環境變數和 Airflow 設定選項覆寫項目是否與 Cloud Composer 3 環境相容。

如有衝突，系統會在建立 Cloud Composer 3 環境後載入快照時，導致遷移作業失敗。在這種情況下，您可以調整 Cloud Composer 2 環境的設定來解決衝突，也可以不使用遷移指令碼進行遷移，並在載入快照時略過載入自訂 PyPI 套件、環境變數或 Airflow 設定覆寫。
取消暫停 Cloud Composer 3 環境中的 DAG。如果部分 DAG 在執行指令碼前已暫停，則會維持暫停狀態。

指令碼有下列限制：

這個指令碼一律會建立新的 Cloud Composer 3 環境。您無法將快照載入現有的 Cloud Composer 3 環境。如要這麼做，您可以使用快照進行遷移，不必使用遷移指令碼。
這個指令碼只會在與 Cloud Composer 2 環境相同的區域和專案中，建立 Cloud Composer 3 環境。
您只能將快照載入相同或較新版本的 Airflow。舉例來說，您無法將 Airflow 2.10.2 的快照載入 Airflow 2.9.3。
只有 Cloud Composer 2 環境可以透過遷移指令碼遷移。

事前準備

由於遷移指令碼會建立環境，然後儲存及載入快照，因此遷移程序可能需要超過一小時。
指令碼會使用快照。支援快照
Cloud Composer 2 版本 2.0.9 以上版本。
您的帳戶需要身分與存取權管理角色，才能建立環境、儲存快照及載入快照。
支援快照的 Airflow 資料庫大小上限為 20 GB。如果環境的資料庫超過 20 GB，請縮減 Airflow 資料庫的大小。
如要建立快照，環境值區中 /dags、/plugins 和 /data 資料夾的物件總數必須少於 100,000 個。
如果使用 XCom 機制傳輸檔案，請務必按照 Airflow 的指南使用。使用 XCom 傳輸大型檔案或大量檔案會影響 Airflow 資料庫的效能，並可能導致載入快照或升級環境時發生錯誤。請考慮使用 Cloud Storage 等替代方案來移轉大量資料。

遷移至 Cloud Composer 3

本節說明如何使用遷移指令碼進行遷移。

瞭解 Cloud Composer 2 和 Cloud Composer 3 的差異

請參閱這篇文章，瞭解 Cloud Composer 2 和 Cloud Composer 3 的差異。

請確認環境未使用 Cloud Composer 3 尚未支援的功能，並熟悉如何使用及設定 Cloud Composer 3 專屬功能。

確認 DAG 與 Cloud Composer 3 相容

請按照下列建議操作，確保 DAG 與 Cloud Composer 3 相容：

Cloud Composer 3 環境中的套件清單可能與 Cloud Composer 2 環境不同。這可能會影響 DAG 與 Cloud Composer 3 的相容性。
在 Cloud Composer 3 中，環境的叢集位於租戶專案。請確認 DAG 與這項變更相容。具體來說，KubernetesPodOperator 工作負載現在可獨立於環境進行擴縮，且無法使用 Pod 親和性設定。

安裝指令碼的依附元件

這個指令碼需要 Python 3.8 以上版本。
遷移指令碼會使用 gcloud CLI 和 curl 公用程式。確認電腦上已安裝這兩項公用程式。

下載指令碼

從 GitHub 存放區下載遷移指令碼 (composer_migrate.py)。

在 gcloud CLI 中授權

在 gcloud CLI 中授權：

gcloud auth login

預覽新環境的參數

您可以先預覽 Cloud Composer 3 環境的參數，再進行遷移。您可以藉此瞭解 Cloud Composer 2 環境的設定如何對應至 Cloud Composer 3。

Airflow 設定選項覆寫、自訂 PyPI 套件和環境變數會從環境快照載入，且不會顯示在預覽畫面中。

展開

執行下列指令：

python3 composer_migrate.py \
    --project PROJECT_ID \
    --location LOCATION \
    --source_environment COMPOSER_2_ENV \
    --target_environment COMPOSER_3_ENV \
    --target_airflow_version COMPOSER_3_AIRFLOW_VERSION \
    --dry_run

更改下列內容：

PROJECT_ID：專案 ID。
COMPOSER_2_ENV：Cloud Composer 2 環境的名稱。
LOCATION：Cloud Composer 2 環境所在的區域。系統會在相同區域中建立 Cloud Composer 3 環境。
COMPOSER_3_AIRFLOW_VERSION：Cloud Composer 3 環境的 Airflow 版本。這個版本必須與 Cloud Composer 2 環境中的版本相同或更新，且必須是 Cloud Composer 3 提供的版本之一。

範例：

python3 composer_migrate.py \
    --project example-project \
    --location us-central1 \
    --source_environment example-composer-2-environment \
    --target_environment example-composer-3-environment \
    --target_airflow_version 2.10.2

檢查環境的健康狀態

確認要遷移的 Cloud Composer 2 環境運作正常。

如果環境不健全，建立新的 Cloud Composer 3 環境後，遷移程序就會失敗，因為無法建立快照。

如要進一步瞭解如何檢查環境和資料庫的健康狀態，請參閱「使用監控資訊主頁」。

執行遷移指令碼