2026 年 9 月 15 日，所有 Cloud Composer 1 版本和 Cloud Composer 2 2.0.x 版都會按照計畫終止服務。您將無法使用這些版本的環境。建議您規劃遷移至 Cloud Composer 3。Cloud Composer 2 版本 2.1.x 以上仍受支援，不會受到這項異動影響。

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

升級環境

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer�

本頁面說明如何將環境升級至新的 Cloud Composer 或 Airflow 版本。

關於升級作業

您可以升級 Cloud Composer 版本、Airflow 版本，或同時升級這兩者。

變更環境使用的 Airflow 或 Cloud Composer 版本時：

Cloud Composer 會使用新版 Cloud Composer 映像檔，重新部署環境的元件。
如果環境在升級前有自訂 PyPI 套件或 Airflow 設定選項覆寫等設定，Cloud Composer 會套用這些變更。
Cloud Composer 會更新 Airflow airflow_db 連線，使其指向新的 Cloud SQL 資料庫。

升級後，連線至環境中資源的方式不會有所改變，例如環境值區的網址或 Airflow 網路伺服器。

升級作業的限制

升級作業有下列限制：

Cloud Composer 版本會在幾天內，逐步推出至 Cloud Composer 支援的所有區域。您所在的區域可能尚未推出最新版本。
您無法降級至先前版本的 Cloud Composer 或 Airflow。
在 Google Cloud 控制台中，您只能升級至 Cloud Composer 2 的最新支援版本。
在 Google Cloud CLI、API 或 Terraform 中，您可以將環境升級至最新支援版本、Cloud Composer 2 的前三個版本、前一個次要版本的最後一個修補程式版本，以及升級時間表延長的版本。即使其他 Cloud Composer 2 版本仍受支援，且可用於建立新環境，您也無法升級至這些版本。

Google Cloud CLI、API 和 Terraform 的升級選項範例：
- 最新版本：composer-2.11.5-airflow-*
- 先前的三個 Cloud Composer 2 版本： composer-2.11.4-airflow-*、composer-2.11.3-airflow-*、 composer-2.11.2-airflow-*。
- 前一個 Cloud Composer 2 次要版本的最後一個修補程式： composer-2.10.2-airflow-*
- 升級時間延長的 Cloud Composer 2 版本：composer-2.10.2-airflow-*、composer-2.10.1-ariflow-*、composer-2.9.7-airflow-*，以及其他升級時間延長的版本。
升級目標版本必須支援環境目前的 Python 版本。
Compute Engine API 配額限制可能會導致升級失敗。在 Google Cloud 控制台，依序前往「IAM and Admin」(IAM 與管理) >「Quotas and System Limits」(配額與系統限制) 頁面，然後檢查 CPU 的 Compute Engine API 配額是否未超出上限。如果配額即將達到上限，請先申請擴充配額，再繼續進行升級作業。
如果 Airflow 資料庫包含超過 16 GB 的資料，您就無法升級環境。升級期間，如果 Airflow 資料庫大小超過 16 GB，系統會顯示警告。在此情況下，請執行資料庫維護作業，縮減資料庫大小。
如果使用 XCom 機制傳輸檔案，請務必按照 Airflow 的指南使用。使用 XCom 傳輸大型檔案或大量檔案會影響 Airflow 資料庫的效能，並可能導致載入快照或升級環境時發生錯誤。請考慮使用 Cloud Storage 等替代方案來移轉大量資料。

事前準備

注意：

請務必瞭解目前 Airflow 和 Cloud Composer 版本與升級目標版本之間的差異。新版本可能包含不同版本的預先安裝套件、Cloud Composer 的修補程式，或 Airflow 開放原始碼計畫提供的 Airflow 功能變更。您可以查看特定版本中包含的供應商套件版本。
請確認 DAG 與新版 Airflow 和所有供應商套件 (包括 Google Cloud 和 Google 服務的 Airflow 供應商套件) 的新版本相容。如有不相容的變更，可能會導致 DAG 無法運作。
升級作業期間，所有正在執行的工作都會終止。升級完成後，Airflow 會根據您為 DAG 設定的重試方式，排定這些工作的重試時間。
請勿將 Cloud Composer 環境的 GKE 叢集升級至較新版本。使用在建立環境時預先設定的 GKE 版本，並仰賴 GKE 服務的自動升級功能。

建議您建立環境的新快照，以便在需要時重新建立環境。
您的帳戶必須具備可觸發環境升級作業的角色。此外，環境的服務帳戶必須具備足夠權限的角色，才能執行升級作業。詳情請參閱存取權控管一文。
您可能會注意到專案中環境所屬 GKE 叢集的 Compute Engine 中繼資料項目。在建立及升級 GKE 叢集期間，Google Kubernetes Engine 會自動新增專案層級的中繼資料項目 (google_compute_project_metadata)，追蹤次要 IP 位址範圍的使用情形。請勿修改或移除這些項目。Google Kubernetes Engine 會自動管理這些節點。

確認環境是否為最新版本

當環境的映像檔即將終止完整支援時，Cloud Composer 會顯示警告。您可以根據這些警告，確保環境一律受到支援。

Cloud Composer 會追蹤環境所用的 Cloud Composer 映像檔版本。當環境即將達到支援終止日期時，環境清單和「環境詳細資料」頁面會顯示警告。

如要檢查環境是否為最新版本，請按照下列步驟操作：

主控台

前往 Google Cloud 控制台的「Environments」頁面。

前往「環境」
在環境清單中，按一下環境名稱。「環境詳細資料」頁面隨即開啟。
前往「環境設定」分頁。
「映像檔版本」欄位會顯示下列其中一則訊息：
- 最新可用版本。環境圖片完全支援。
- 已推出新版本。環境映像檔完全受到支援，您可以升級至較新版本。
- 這個映像檔版本的支援將於...結束您的環境圖片即將結束完整支援期。
- 這個版本自...起不再支援 您的環境已超過完整支援期限。

gcloud

Google Cloud CLI 不支援這項功能。您可以改為查看建議的升級，瞭解有哪些新版本。

API

這項功能無法透過 API 使用。您可以改為查看建議的升級，瞭解有哪些新版本。

查看建議升級項目

Cloud Composer 提供可升級環境的 Cloud Composer 版本清單。

如要查看建議升級的 Cloud Composer 版本，請按照下列步驟操作：

主控台

前往 Google Cloud 控制台的「Environments」頁面。

前往「環境」
在環境清單中，按一下環境名稱。「環境詳細資料」頁面隨即開啟。
前往「環境設定」分頁，然後按一下「升級映像檔版本」。
如要查看建議版本清單，請按一下 Cloud Composer「Image version」(映像檔版本) 下拉式選單。

gcloud

gcloud composer environments list-upgrades \
  ENVIRONMENT_NAME \
  --location LOCATION

取代：

將 ENVIRONMENT_NAME 替換為環境的名稱。
LOCATION 改成環境所在的地區。

範例：

gcloud composer environments list-upgrades example-environment \
  --location us-central1

API

您可以查看地點的可用版本。如要這麼做，請建構 imageVersions.list API 要求。

例如：

// GET https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/imageVersions

檢查 PyPI 套件衝突

您可以檢查環境中安裝的 PyPI 套件，是否與新版 Cloud Composer 映像檔中預先安裝的套件有任何衝突。

如果檢查成功，表示目前版本和指定版本之間的 PyPI 套件依附元件沒有衝突。不過，升級作業仍可能因其他原因而失敗。

主控台

如要對環境執行升級檢查，請按照下列步驟操作：

前往 Google Cloud 控制台的「Environments」頁面。

前往「環境」
在環境清單中，按一下環境名稱。「環境詳細資料」頁面隨即開啟。
前往「環境設定」分頁，找出「映像檔版本」項目，然後按一下「升級」。
在「環境版本升級」對話方塊中，從「新版本」下拉式清單選取要升級的 Cloud Composer 版本。
在「PyPI 套件相容性」部分，按一下「檢查衝突」。
請等待檢查完成。如果 PyPI 套件依附元件發生衝突，顯示的錯誤訊息會包含衝突套件和套件版本的詳細資料。

gcloud

如要對環境執行升級檢查，請搭配要升級的 Cloud Composer 映像檔版本，執行 environments check-upgrade 指令。

gcloud composer environments check-upgrade \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --image-version VERSION

取代：

將 ENVIRONMENT_NAME 替換為環境的名稱。
LOCATION 改成環境所在的地區。
VERSION 採用 composer-a.b.c-airflow-x.y.z 格式，指定要升級的新 Cloud Composer 映像檔版本。您可以使用所有版本別名。

範例：

gcloud composer environments check-upgrade example-environment \
  --location us-central1 \
  --image-version composer-2.14.4-airflow-2.10.5

輸出內容範例：

Waiting for [projects/example-project/locations/us-central1/environments/
example-environment] to be checked for PyPI package conflicts when upgrading
to composer-2.14.4-airflow-2.10.5. 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.

或者，您也可以非同步執行升級檢查。使用 --async 引數進行非同步呼叫，然後使用 gcloud composer operations describe 指令檢查結果。

API

建構 environments.checkUpgrade API 要求。

在 imageVersion 欄位中指定映像檔版本：

{
  "imageVersion": "VERSION"
}

將 VERSION 替換成要升級的新版本，格式為 composer-a.b.c-airflow-x.y.z。

檢查是否與 Cloud Composer 3 發生衝突

雖然無法將環境從 Cloud Composer 2 遷移至 Cloud Composer 3，但您可以透過升級檢查功能，確認是否有相容性問題。建議您在遷移至 Cloud Composer 3 前完成這項作業。

如要檢查是否與 Cloud Composer 3 相容，請定期檢查 Cloud Composer 2 環境的升級情況，並指定 Cloud Composer 3 版本做為目標。

每項回報的衝突都可能屬於下列類型：

BLOCKING 衝突報表會列出 Cloud Composer 3 不支援的不相容環境設定元素。建議您先解決這些衝突，再開始遷移至 Cloud Composer 3。
NON_BLOCKING 衝突報告會列出 Cloud Composer 3 中不同的環境設定元素，這些元素可能會導致無法預期的行為。舉例來說，如果變更預設值 (例如預設維護時段)，系統會回報為非阻斷衝突。建議您在開始遷移程序前，先檢查這些衝突是否會導致問題。
這項檢查也會回報 PyPI 套件衝突。這類衝突會與設定衝突分開回報，與一般 PyPI 套件相容性檢查的回報方式相同。

主控台

如要檢查是否與 Cloud Composer 3 相容，請使用 gcloud CLI 或 Cloud Composer API。Google Cloud 控制台僅支援檢查 PyPI 套件相容性。

gcloud

如要檢查是否與 Cloud Composer 3 相容，請執行 environments check-upgrade 指令，並指定 Cloud Composer 3 版本做為目標。

gcloud composer environments check-upgrade \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --image-version COMPOSER_3_VERSION

取代：

將 ENVIRONMENT_NAME 替換為環境的名稱。
LOCATION 改成環境所在的地區。
COMPOSER_3_VERSION，並以 airflow-x.y.z-build.t 格式指定要升級的 Airflow 版本和建構版本。您可以使用所有版本別名。

範例：

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
...

或者，您也可以非同步執行這項檢查。使用 --async 引數進行非同步呼叫，然後使用 gcloud composer operations describe 指令檢查結果。

API

建構 environments.checkUpgrade API 要求。

在 imageVersion 欄位中指定映像檔版本：

{
  "imageVersion": "COMPOSER_3_VERSION"
}

將 COMPOSER_3_VERSION 替換為要升級的 Airflow 版本和建構版本，格式為 airflow-x.y.z-build.t。您可以使用所有版本別名。

升級環境

如要將環境升級至較新版本的 Cloud Composer 或 Airflow，請按照下列步驟操作：

主控台

前往 Google Cloud 控制台的「Environments」頁面。

前往「環境」
在環境清單中，按一下環境名稱。「環境詳細資料」頁面隨即開啟。
前往「環境設定」分頁。
找出「圖片版本」項目，然後按一下「升級」。
在「映像檔版本」下拉式選單中，選取要升級的 Cloud Composer 版本。
按一下「升級」。

gcloud

gcloud composer environments update \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --image-version VERSION

取代：

將 ENVIRONMENT_NAME 替換為環境的名稱。
LOCATION 改成環境所在的地區。
VERSION 採用 composer-a.b.c-airflow-x.y.z 格式，指定要升級的新 Cloud Composer 映像檔版本。您也可以使用所有版本別名。

例如：

gcloud composer environments update
  example-environment \
  --location us-central1 \
  --image-version composer-2.14.4-airflow-2.10.5

API

建構 environments.patch API 要求。
在這項要求中：
1. 在 updateMask 參數中，指定 config.softwareConfig.imageVersion 遮罩。
2. 在要求主體的 imageVersion 欄位中，指定要升級的新版本。

例如：

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.imageVersion

  {
    "config": {
      "softwareConfig": {
        "imageVersion": "composer-2.14.4-airflow-2.10.5"
      }
    }
  }

Terraform

config.software_config 區塊中的 image_version 欄位會控管環境的 Cloud Composer 映像檔。在這個欄位中，指定新的 Cloud Composer 映像檔。

  resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {
    software_config {
      image_version = "VERSION"
    }
  }
}

取代：

將 ENVIRONMENT_NAME 替換為環境的名稱。
LOCATION 改成環境所在的地區。要升級的新 Cloud Composer 映像檔版本，格式為 composer-a.b.c-airflow-x.y.z。您也可以使用所有版本別名。

範例：

resource "google_composer_environment" "example" {
  provider = google-beta
  name = "example-environment"
  region = "us-central1"

  config {
    software_config {
      image_version = "composer-2.14.4-airflow-2.10.5"
    }
  }
}

升級環境 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

關於升級作業

升級作業的限制

事前準備

確認環境是否為最新版本

主控台

gcloud

API

查看建議升級項目

主控台

gcloud

API

檢查 PyPI 套件衝突

主控台

gcloud

API

檢查是否與 Cloud Composer 3 發生衝突

主控台

gcloud

API

升級環境

主控台

gcloud

API

Terraform

後續步驟

升級環境