Cloud Composer 1 處於維護後模式。Google 不會再發布 Cloud Composer 1 的更新，包括 Airflow 新版本、錯誤修正和安全性更新。建議您規劃遷移至 Cloud Composer 3。

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

使用 Composer Local Development CLI 工具執行本機 Airflow 環境

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

本節說明如何使用 Composer 本機開發 CLI 工具建立、設定及執行本機 Airflow 環境。

關於 Composer 本機開發 CLI 工具

Composer 本機開發 CLI 工具會在本機執行 Airflow 環境，簡化 Cloud Composer 的 Apache Airflow DAG 開發作業。這個本機 Airflow 環境會使用特定 Cloud Composer 版本使用的 Cloud Composer 映像檔。

您可以根據現有的 Cloud Composer 環境建立本機 Airflow 環境。在這種情況下，本機 Airflow 環境會從 Cloud Composer 環境取得已安裝的 PyPI 套件清單和環境變數名稱。

您可以使用這個本機 Airflow 環境進行測試和開發作業，例如測試新的 DAG 程式碼、PyPI 套件或 Airflow 設定選項。

事前準備

Composer 本機開發 CLI 工具會在您執行 composer-dev create 指令的目錄中建立本機 Airflow 環境。如要日後存取本機 Airflow 環境，請在最初建立本機環境的路徑中執行工具指令。本機環境的所有資料都會儲存在您建立本機環境的路徑 (./composer/<local_environment_name>) 中。
電腦必須有足夠的磁碟空間，才能儲存 Cloud Composer 圖像。Composer 本機開發 CLI 工具會為每個 Cloud Composer 版本儲存一個映像檔。舉例來說，如果您有兩個本機 Airflow 環境，且兩者使用不同的 Cloud Composer 版本，則 Composer 本機開發 CLI 工具會儲存兩個 Cloud Composer 映像檔。
Composer 本機開發 CLI 工具會使用著色輸出內容。您可以使用 NO_COLOR=1 變數停用著色輸出：NO_COLOR=1 composer-dev <other commands>。
如果您只有一個本機環境，除了 run-airflow-cmd 以外，您可以省略所有 composer-dev 指令中的本機環境名稱。
安裝 Composer 本機開發 CLI 工具依附元件：
- 使用 pip 的 Python 版本，從 3.8 到 3.11
- Google Cloud CLI
安裝 Docker。您必須在本機系統中安裝 Docker 並執行。如要確認 Docker 是否正在執行，您可以執行任何 Docker CLI 指令，例如 docker ps。

設定憑證

如果您尚未取得新的使用者憑證，請取得新的使用者憑證，以便用於應用程式預設憑證：

gcloud auth application-default login

使用 Google 帳戶登入 gcloud CLI：

gcloud auth login

Composer 本機開發 CLI 工具和 DAG 執行的所有 API 呼叫，都是透過您在 gcloud CLI 中使用的帳戶執行。舉例來說，如果本機 Airflow 環境中的 DAG 會讀取 Cloud Storage 值區的內容，則該帳戶必須具備存取該值區的權限。這與 Cloud Composer 環境不同，在那裡，環境的服務帳戶會發出呼叫。

安裝 Composer 本機開發 CLI 工具

複製 Composer 本機開發 CLI 存放區：

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

在複製存放區的頂層目錄中執行：

pip install .

視 pip 設定而定，工具的安裝路徑可能不在 PATH 變數中。在這種情況下，pip 會顯示警告訊息。您可以使用這則警告訊息中的資訊，將這個目錄新增至作業系統中的 PATH 變數。

使用 Cloud Composer 映像檔建立本機 Airflow 環境

如要列出可用的 Cloud Composer 映像檔，請執行：

composer-dev list-available-versions --include-past-releases --limit 10

如要使用預設參數建立本機 Airflow 環境，請執行：

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

其他參數：

composer-dev create \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  LOCAL_ENVIRONMENT_NAME

取代：

IMAGE_VERSION 改為 Cloud Composer 映像檔的名稱。
將 PROJECT_ID 替換為專案 ID。
WEB_SERVER_PORT 與 Airflow 網路伺服器必須監聽的通訊埠。
LOCAL_DAGS_PATH，其中包含 DAG 檔案所在本機目錄的路徑。
LOCAL_ENVIRONMENT_NAME 與本機 Airflow 環境的名稱。

範例：

composer-dev create \
  --from-image-version composer-2.13.4-airflow-2.10.5 \
  example-local-environment

透過 Cloud Composer 環境建立本機 Airflow 環境

系統只會從 Cloud Composer 環境擷取下列資訊：

環境中使用的 Cloud Composer 和 Airflow 版本。
環境中安裝的自訂 PyPI 套件清單。
在環境中設定的環境變數名稱清單，並附上註解。

重要事項： Cloud Composer 不會複製環境變數的值。您可以手動取消註解設定檔中的環境變數，並視需要設定其值。

系統不會從 Cloud Composer 環境複製其他資訊和設定參數，例如 DAG 檔案、DAG 執行記錄、Airflow 變數和連線。

如要從現有 Cloud Composer 環境建立本機 Airflow 環境，請按照下列步驟操作：

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH

取代：

LOCAL_ENVIRONMENT_NAME 與本機 Airflow 環境的名稱。
ENVIRONMENT_NAME 與 Cloud Composer 環境名稱。
LOCATION 與 Cloud Composer 環境所在的地區。
將 PROJECT_ID 替換為專案 ID。
WEB_SERVER_PORT 與本機 Airflow 網路伺服器的通訊埠。
LOCAL_DAGS_PATH 與 DAG 所在本機目錄的路徑。

範例：

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path example_directory/dags

啟動本機 Airflow 環境

如要啟動本機 Airflow 環境，請執行：

composer-dev start LOCAL_ENVIRONMENT_NAME

取代：

LOCAL_ENVIRONMENT_NAME 與本機 Airflow 環境的名稱。

停止或重新啟動本機 Airflow 環境

重新啟動本機 Airflow 環境時，Composer 本機開發 CLI 工具會重新啟動執行環境的 Docker 容器。所有 Airflow 元件都會停止並重新啟動。因此，在重新啟動期間執行的所有 DAG 都會標示為失敗。

如要重新啟動或啟動已停止的本機 Airflow 環境，請執行：

composer-dev restart LOCAL_ENVIRONMENT_NAME

取代：

LOCAL_ENVIRONMENT_NAME 與本機 Airflow 環境的名稱。

如要停止本機 Airflow 環境，請執行：

composer-dev stop LOCAL_ENVIRONMENT_NAME

新增及更新 DAG

建立本機 Airflow 環境時，DAG 會儲存在 --dags-path 參數中指定的目錄中。根據預設，這個目錄為 ./composer/<local_environment_name>/dags。您可以使用 describe 指令取得環境使用的目錄。

如要新增及更新 DAG，請變更這個目錄中的檔案。您不需要重新啟動本機 Airflow 環境。

查看本機 Airflow 環境記錄

您可以查看執行本機 Airflow 環境的 Docker 容器中的近期記錄。這樣一來，您就能監控容器相關事件，並檢查 Airflow 記錄檔，找出 PyPI 套件安裝作業所造成的依附元件衝突等錯誤。

如要查看執行本機 Airflow 環境的 Docker 容器記錄，請執行：

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

如要追蹤記錄串流，請省略 --max-lines 引數：

composer-dev logs LOCAL_ENVIRONMENT_NAME

執行 Airflow CLI 指令

您可以在本機 Airflow 環境中執行 Airflow CLI 指令。

如要執行 Airflow CLI 指令，請按照下列步驟操作：

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

範例：

composer-dev run-airflow-cmd example-local-environment dags list -o table

設定本機 Airflow 環境

Composer 本機開發 CLI 工具會儲存本機 Airflow 環境的設定參數，例如環境變數和本機環境目錄 (./composer/<local_environment_name>) 中的 PyPI 套件需求。

當本機 Airflow 環境啟動時，系統會套用設定。舉例來說，如果您新增了互相衝突的 PyPI 套件需求，Composer 本機開發 CLI 工具在啟動本機環境時，就會回報錯誤。

Airflow 連線會儲存在本機 Airflow 環境的資料庫中。您可以執行 Airflow CLI 指令，或將連線參數儲存在環境變數中來設定這些參數。如要進一步瞭解建立及設定連線的方式，請參閱 Airflow 說明文件中的「管理連線」一節。

取得本機 Airflow 環境的清單和狀態

如要列出所有可用的本機 Airflow 環境並顯示其狀態，請按照下列步驟操作：

composer-dev list

如要說明特定環境，並取得環境的詳細資料，例如映像檔版本、DAG 路徑和網頁伺服器網址：

composer-dev describe LOCAL_ENVIRONMENT_NAME

取代：

將 LOCAL_ENVIRONMENT_NAME 替換為本機 Airflow 環境的名稱。

列出本機 Airflow 環境使用的圖片

如要列出 Composer 本機開發 CLI 工具使用的所有圖片，請執行：

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

安裝外掛程式和變更資料

本機 Airflow 環境的外掛程式和資料會從本機環境的目錄 (./composer/<local_environment_name>/data 和 ./composer/<local_environment_name>/plugins) 取得。

如要變更 /data 和 /plugins 目錄的內容，請新增或移除這些目錄中的檔案。Docker 會自動將檔案變更傳播至本機 Airflow 環境。

Composer 本機開發 CLI 工具不支援為資料和外掛程式指定不同的目錄。

設定環境變數

如要設定環境變數，請編輯環境目錄中的 variables.env 檔案：./composer/<local_environment_name>/variables.env。

variables.env 檔案必須包含鍵值定義，每個環境變數一行。如要變更 Airflow 設定選項，請使用 AIRFLOW__SECTION__KEY 格式。如要進一步瞭解可用的環境變數，請參閱 Airflow 設定參考資料。

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

如要套用變更，請重新啟動本機 Airflow 環境。

安裝或移除 PyPI 套件

如要安裝或移除 PyPI 套件，請修改環境目錄中的 requirements.txt 檔案：./composer/<local_environment_name>/requirements.txt。

需求必須遵循 PEP-508 中指定的格式，其中每項需求都要以小寫指定，且包含套件名稱和選用的額外項目和版本指定碼。

如要套用變更，請重新啟動本機 Airflow 環境。

切換至其他 Cloud Composer 映像檔

您可以使用任何 Cloud Composer 映像檔搭配 Composer 本機開發 CLI 工具，並在映像檔之間切換。這與升級 Cloud Composer 環境不同，因為本機 Airflow 環境的設定參數會在啟動時套用。

舉例來說，新版 Cloud Composer 發布後，您可以切換環境來使用新版，並保留現有的本機 Airflow 環境設定。舉例來說，您可以在特定 Cloud Composer 版本中切換不同的 Airflow 版本。

如要變更本機 Airflow 環境使用的環境映像檔，請按照下列步驟操作：

編輯本機環境設定檔：./composer/<local_environment_name>/config.json。
變更 composer_image_version 參數的值。如要查看可用的值，您可以列出可用的圖片。
如要套用變更，請重新啟動本機 Airflow 環境。

刪除本機 Airflow 環境

注意：請務必儲存環境中的所有必要資料，例如記錄和設定。

如要刪除本機 Airflow 環境，請執行下列指令：

composer-dev remove LOCAL_ENVIRONMENT_NAME

如果環境正在執行，請新增 --force 標記，強制移除環境。

刪除 Docker 映像檔

如要刪除 Composer 本機開發 CLI 工具下載的所有圖片，請執行：

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

疑難排解

本節提供常見問題的解決方法。

無法在 macOS 上啟動本機環境

如果您將 composer-dev 套件安裝到 Docker 無法存取的目錄，本機環境可能無法啟動。

舉例來說，如果 Python 已安裝在 /opt 目錄中 (例如在 macOS 上使用預設的 Homebrew 設定安裝 Python)，composer-dev 套件也會一併安裝在 /opt 目錄中。由於 Docker 遵循 Apple 的沙箱規則，因此預設情況下無法使用 /opt 目錄。此外，您無法透過 UI 新增 (依序前往「設定」>「資源」>「檔案共用」)。

在這種情況下，Composer 本機開發 CLI 工具會產生類似以下範例的錯誤訊息：

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

您可以使用下列任一解決方案：

將 Python 或 composer-dev 套件安裝到其他目錄，讓 Docker 可以存取套件。
手動編輯 ~/Library/Group\ Containers/group.com.docker/settings.json 檔案，並將 /opt 新增至 filesharingDirectories。