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�

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

關於升級作業

在 Cloud Composer 3 中，您不必管理環境的 Cloud Composer 版本：

Cloud Composer 會自動升級環境的基礎架構元件。這些元件與 Cloud Composer 功能相關，不會變更 Airflow 的運作方式或 Airflow DAG 的執行方式。
Cloud Composer 不會自動升級 Airflow 版本和建構版本、Airflow 元件，或與 Airflow 工作負載密切相關的元件。基礎架構元件自動升級時，這些值不會變更。
您可以手動升級至新的 Airflow版本或建構版本。

舉例來說，您可以使用相同版本的 Airflow 數月，不必執行任何升級，環境仍會收到最新的 Cloud Composer 更新、修正和改善項目，以及環境基礎架構元件。日後決定改用新版或新組建的 Airflow 時，請升級環境中的 Airflow 版本。

關於 Airflow 版本升級

您的環境會透過下列方式變更 Airflow 的版本或建構版本：

您可以控管環境的 Airflow 版本 (和建構版本)。選擇將環境切換至其他 Airflow 版本時，您可以執行 Airflow 版本升級作業。舉例來說，如果目前使用的 Airflow 版本和建構版本不再受支援，就可能發生這種情況。
Cloud Composer 會使用指定的 Airflow 版本和建構版本，重新部署環境的 Airflow 元件。
如果環境在升級前有自訂 PyPI 套件或 Airflow 設定選項覆寫等設定，Cloud Composer 會套用這些變更。
Cloud Composer 會更新 Airflow airflow_db 連線，使其指向新的 Cloud SQL 資料庫。

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

關於基礎架構自動升級作業

Cloud Composer 會定期執行自動基礎架構升級作業：

系統會在環境指定的維護期間，定期執行基礎架構自動升級作業。
在 Cloud Composer 3 中，您無法停用基礎架構自動升級功能。您可以為環境指定自訂維護期間，控管自動升級的執行時間。
這項作業會顯示在 Google Cloud 控制台和環境記錄中，就像任何其他長時間執行的作業一樣。作業執行期間，您無法在環境層級啟動其他作業 (但仍可執行 Airflow DAG)。
在某些情況下，自動基礎架構升級可能會重新啟動 Airflow 元件。重新啟動期間，Airflow 工作站會以 24 小時的寬限期安全終止。如果工作需要超過 24 小時才能完成，請考慮使用可延遲運算子。升級作業可能會導致環境基礎架構元件 (例如環境監控) 短暫無法使用。

升級作業的限制

升級作業有下列限制：

Cloud Composer 版本會在幾天內，逐步推出至 Cloud Composer 支援的所有區域。您所在的區域可能尚未推出最新版本。
您無法降級至先前版本的 Airflow 或建構版本。
如果 Airflow 資料庫包含超過 20 GB 的資料，您就無法升級環境。升級期間，如果 Airflow 資料庫大小超過 20 GB，系統就會顯示警告。在此情況下，請執行資料庫維護作業，縮減資料庫大小。
如果使用 XCom 機制傳輸檔案，請務必按照 Airflow 的指南使用。使用 XCom 傳輸大型檔案或大量檔案會影響 Airflow 資料庫的效能，並可能導致載入快照或升級環境時發生錯誤。請考慮使用 Cloud Storage 等替代方案來移轉大量資料。

事前準備

建議您建立環境的新快照，以便在需要時重新建立環境。
您的帳戶必須具備可觸發環境升級作業的角色。此外，環境的服務帳戶必須具備足夠權限的角色，才能執行升級作業。詳情請參閱存取權控管一文。

確認環境是否為最新版本

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

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

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

主控台

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

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

gcloud

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

API

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

查看建議升級項目

Cloud Composer 提供 Airflow 建構版本清單，您可以將環境升級至這些版本。

如要查看建議升級的 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 套件，是否與新版或新版建構的 Airflow 中預先安裝的套件有任何衝突。

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

主控台

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

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

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

gcloud

如要對環境執行升級檢查，請搭配要升級的 Airflow 版本或建構版本，執行 environments check-upgrade 指令。

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

取代：

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

範例：

gcloud composer environments check-upgrade example-environment \
  --location us-central1 \
  --airflow-version airflow-2.10.5-build.16

輸出內容範例：

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.10.5-build.16. 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-3-airflow-x.y.z-build.t。

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

Cloud Composer 3 是 Cloud Composer 的最新主要版本。您可以透過升級檢查，確認 Cloud Composer 2 環境是否能升級至 Cloud Composer 3。以下說明適用於 Cloud Composer 2 環境。

雖然無法將環境從 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。您可以使用所有版本別名。

升級環境

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

主控台

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

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

gcloud

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

取代：

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

例如：

gcloud composer environments update
  example-environment \
  --location us-central1 \
  --airflow-version airflow-2.10.5-build.16

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-3-airflow-2.10.5-build.16"
      }
    }
  }

Terraform

config.software_config 區塊中的 image_version 欄位可控管環境的 Airflow 版本和建構作業。在這個欄位中，指定新的 Airflow 版本和建構版本。

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

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

取代：

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

範例：

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

  config {
    software_config {
      image_version = "airflow-2.10.5-build.16"
    }
  }
}

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

關於升級作業

關於 Airflow 版本升級

關於基礎架構自動升級作業

升級作業的限制

事前準備

確認環境是否為最新版本

主控台

gcloud

API

查看建議升級項目

主控台

gcloud

API

檢查 PyPI 套件衝突

主控台

gcloud

API

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

主控台

gcloud

API

升級環境

主控台

gcloud

API

Terraform

後續步驟

升級環境