gcloud CLI 與自動化 — GCP PCA 學習筆記

Q: Q1. 我該如何更新 gcloud CLI？

執行 gcloud components update 。如果您是通過套件管理員 (如 apt 或 brew ) 安裝的，請改用該管理員。

Q: Q2. 我可以在 GCE VM 內部執行 gcloud 命令嗎？

可以。如果 VM 附加了具有正確 IAM 權限的服務帳戶，您甚至不需要登入。 gcloud 會透過 metadata server 自動使用 VM 的身分。

Q: Q3. gcloud 和 gsutil 有什麼區別？

gcloud 處理大多數 GCP 服務。 gsutil 是一個專門針對 Cloud Storage (管理儲存桶和物件) 的較舊專門工具。新版 gcloud storage 速度更快、原生支援平行上傳，最終將取代 gsutil 。

Q: Q4. 如果我迷路了，該如何找到正確的命令？

使用 gcloud help 或交互式介面： gcloud alpha interactive 。它會在您輸入時提供自動補全和說明文件。 gcloud topic 則涵蓋跨命令概念。

Q: Q5. gcloud 中的 「Alpha」 和 「Beta」 是什麼意思？

gcloud alpha 功能處於早期測試階段，可能會發生變化。 gcloud beta 功能較穩定，但仍未正式發佈 (GA)。對於生產腳本，請始終優先選擇 GA 命令 (無 alpha/beta 前綴)。

gcloud CLI 簡介

gcloud CLI 是用於建立和管理 Google Cloud 資源的主要命令列工具。對於 Professional Cloud Architect 來說，精通 gcloud 對於自動化、疑難排解以及執行 Cloud Console 過於繁瑣的批次操作至關重要。

gcloud 是 Google Cloud SDK 的一部分，該 SDK 還包括 gsutil (用於 Cloud Storage) 和 bq (用於 BigQuery)。

白話文解釋（Plain English Explanation）

比喻 1 — 魔法棒 vs. 藍圖 (CLI vs IaC)

如果 Terraform 是整棟建築的藍圖，那麼 gcloud 就是魔法棒。您使用藍圖從頭開始蓋房子；使用魔法棒則是為了現在快速開燈、打開特定窗戶或更改單面牆壁的顏色。gcloud 用於即時行動，IaC 則用於宣告式可重現性。

比喻 2 — 瑞士軍刀 (SDK)

Google Cloud SDK 就像一把瑞士軍刀。gcloud 是主刀 (運算/網路/IAM)；gsutil 是螺絲起子 (Cloud Storage)；bq 是開瓶器 (BigQuery)；gcloud storage 則是新的整合刀刃，正逐步取代舊的螺絲起子。您攜帶一個工具，但它針對您在實務中遇到的每項任務都有特定的配件。

比喻 3 — 分類帽 (過濾與格式化)

想像一個裝滿 1,000 名學生的房間。過濾 (--filter) 就像分類帽說：「只顯示葛來分多且正在讀五年級的學生。」格式化 (--format) 則是說：「現在，將他們的名字按身高排序，列印成一份整齊的清單，並只列出徽章號碼。」gcloud 在伺服器端透過 --filter 過濾，在客戶端透過 --format 投影，大幅減少傳輸量與解析複雜度。

gcloud 命令剖析

大多數 gcloud 命令遵循一致的 GROUP / RESOURCE / VERB 模式： gcloud GROUP RESOURCE VERB [NAME] --flags

例如，gcloud compute instances create my-vm --zone=us-central1-a 可拆解為：

頂層組群: gcloud 本身，可選擇性加上 alpha 或 beta 前綴。
服務組群: compute、container、functions、sql、iam、storage、pubsub、dataflow。
資源: instances、clusters、databases、topics、buckets、service-accounts。
動詞: create、list、describe、delete、update、add-iam-policy-binding。
位置參數: 資源名稱（若適用）。
旗標: --project、--zone、--region、--format、--filter、--quiet。

這種可預測性意味著一旦學會一個服務，其他服務都會感到熟悉。gcloud compute instances list 與 gcloud sql instances list 使用相同的心智模型。

Release track（發布軌道） — gcloud 命令介面的平行版本。GA 命令不帶任何前綴；gcloud beta 與 gcloud alpha 暴露較新或實驗性功能。track 與 SDK 版本互不相干：單一個 gcloud 安裝同時內含三條軌道，其中 alpha 需要 gcloud components install alpha 才能啟用。

命令語法: gcloud [release-track] SERVICE RESOURCE VERB [NAME] --flags。release track（alpha/beta）為選填，緊接在 gcloud 之後。每個 GA 命令都省略 track。

精通 --format 旗標

--format 控制結果在客戶端如何呈現。PCA 最需要熟悉的格式：

內建格式

table — 預設人類可讀視圖；欄位可自訂：--format="table(name,zone,status)"。
json — 完整結構化輸出，適用於 jq 管道與程式化解析。
yaml — 人類友善的結構化輸出，常用於匯出資源 manifest。
csv — 逗號分隔列，適合試算表與批次匯入。
value — 純欄位值無標題，最適合擷取到 Bash 變數：IP=$(gcloud compute instances describe vm-1 --format="value(networkInterfaces[0].accessConfigs[0].natIP)")。

投影與轉換

在 --format 內可使用投影（欄位選擇器）與轉換（函式）。例如：

--format="value(name,creationTimestamp.date('%Y-%m-%d'))" 格式化時間戳記。
--format="table(name, labels.env:label=ENV)" 重新命名欄位標題。
--format="json(name, networkInterfaces.networkIP)" 攤平巢狀 JSON。

腳本中絕不要解析預設 table 輸出。 欄位寬度、順序或標題文字可能在不同 SDK 版本間變動。請使用 --format="value(...)"（單欄）或 --format="json" 搭配 jq（多欄），才能讓自動化在升級後仍能運作。

--filter 旗標（伺服器端過濾）

--filter 在伺服器端評估表達式後才回傳結果，可在大規模機隊上節省頻寬與時間。

過濾運算子

相等: status=RUNNING
不等: status!=TERMINATED
子字串比對: name~prod-（regex）、name:prod（包含）。
邏輯: AND、OR、NOT。
巢狀欄位: labels.env=prod、networkInterfaces.network~default。

範例

# 所有 prod 環境中執行中的 VM，且為特定機型
gcloud compute instances list \
  --filter="status=RUNNING AND labels.env=prod AND machineType~n1-standard-1"

# 特定日期之前建立的所有 bucket
gcloud storage buckets list \
  --filter="timeCreated<'2025-01-01T00:00:00Z'"

# 特定服務帳戶的所有 IAM bindings
gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:sa-name@PROJECT_ID.iam.gserviceaccount.com" \
  --format="value(bindings.role)"

將 --filter（伺服器端）與 --format（客戶端投影）結合，建構精準、輕量的查詢。先用 filter 縮小結果集，再用 format 只取出需要的欄位——這個模式幾乎是所有 gcloud 自動化腳本的骨幹。

gcloud 組態與命名 profile

gcloud config configurations 讓您維護多個命名 profile，每個都有自己的啟用帳戶、專案、region 與 zone。可以避免「不小心刪掉 prod」的災難。

常見流程

gcloud config configurations create prod
gcloud config set account [email protected]
gcloud config set project acme-prod-001
gcloud config set compute/region us-central1

gcloud config configurations create dev
gcloud config set account [email protected]
gcloud config set project acme-dev-001
gcloud config set compute/region asia-east1

gcloud config configurations activate dev
gcloud config configurations list

單次命令覆寫

也可以不切換 profile 而在單一命令上覆寫： gcloud compute instances list --configuration=prod。

CI/CD 友善

在 CI runner 中，與其建立長期 configurations，不如以 gcloud auth activate-service-account --key-file=$KEY 啟用服務帳戶並明確帶 --project。在共用環境中不要依賴預設組態——讓每個命令都自給自足。

每個專案、每個環境各一個 configuration。 搭配不同的 gcloud 帳戶（或服務帳戶）區分 prod 與非 prod，這樣即使腳本忘了 --project，啟用中的身分也不會在錯的專案上擁有權限。

用 xargs 與 GNU parallel 做批次操作

對於大量操作，可將 gcloud --format="value(...)" 與 xargs 或 GNU parallel 結合，把工作擴散出去。

xargs 循序執行

# 停止所有非 prod 的 VM
gcloud compute instances list \
  --filter="labels.env!=prod AND status=RUNNING" \
  --format="value(name,zone)" \
| while read NAME ZONE; do
    gcloud compute instances stop "$NAME" --zone="$ZONE" --quiet
  done

GNU parallel 並行

gcloud compute instances list \
  --filter="labels.env=stage" \
  --format="csv[no-heading](name,zone)" \
| parallel --colsep , -j 10 \
    gcloud compute instances delete {1} --zone={2} --quiet

-j 10 可同時跑十個 delete。要小心 API 配額——Compute Engine 有專案級每分鐘的限制，批次操作很容易撞上。可用 gcloud compute operations list 確認長時間操作是否成功。

批次刪除時配額耗盡。 一次平行發 500 個 gcloud compute instances delete 可能會超過專案的 mutating API 配額，最終讓一半機器卡在 STOPPING、另一半完全沒動。請以 parallel -j 5 節流，或改用 managed instance group + resize-to-zero 模式取代迴圈刪除。

腳本模式與 Bash 防呆習慣

正式環境 gcloud 腳本要具防禦性。標準開頭：

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

PROJECT_ID="${PROJECT_ID:?PROJECT_ID is required}"
REGION="${REGION:-us-central1}"

gcloud config set project "$PROJECT_ID" >/dev/null

set -e 一遇到錯誤即中止。
set -u 對未設定變數報錯（可抓出 $PROJ_ID 與 $PROJECT_ID 的誤拼）。
set -o pipefail 將管線中任何階段的失敗向後傳遞（將 gcloud 管到 jq 時極關鍵）。
${VAR:?msg} 早期強制必填輸入。

冪等性

包裝 mutating 命令讓腳本可重跑：

if ! gcloud compute networks describe my-vpc --project="$PROJECT_ID" >/dev/null 2>&1; then
  gcloud compute networks create my-vpc --subnet-mode=custom --project="$PROJECT_ID"
fi

對長時間操作，使用 --async 取得 operation ID，再以 gcloud compute operations wait 等待，可獲得明確、可腳本化的完成訊號。

若所涉資源不只少數幾個，請從 Bash 升級到 Terraform 或 Config Connector。gcloud 適合一次性操作、疑難排解與 bootstrap 自動化；持續性、必須收斂到既定狀態的基礎設施則交給宣告式 IaC。

用 gcloud topic 探索命令

gcloud topic 是內建的參考子系統，記錄跨命令的概念。每位架構師至少應略讀一遍的條目：

gcloud topic filters — --filter 完整語法，包含 transform 函式與日期運算。
gcloud topic formats — 所有支援的 --format、投影語法以及內建 transforms（date、duration、size）。
gcloud topic configurations — 命名 profile、個別屬性覆寫、環境變數優先順序。
gcloud topic escaping — 旗標值內含逗號、分號、引號時如何處理（標籤與 metadata 時關鍵）。
gcloud topic startup — 初始化順序，解釋為何某些命令首次執行特別慢。
gcloud topic flags-file — 用 YAML 檔案傳入旗標值，讓超長命令更易讀。

迷路時，gcloud help SERVICE RESOURCE VERB 或 gcloud SERVICE RESOURCE VERB --help 可拉出完整 man page。學習階段搭配 gcloud alpha interactive 自動補全 REPL 效果尤佳。

gcloud beta 與 alpha：存取 pre-GA 功能

gcloud 在同一個 binary 內提供三個 release track：

GA（無前綴）: 穩定，受 Google 棄用政策保障。
gcloud beta: 功能完整，可能有小幅變動；通常可用於非 prod。
gcloud alpha: 早期存取，可能變動或消失；以 gcloud components install alpha 安裝。

架構師為何關注

新服務與新旗標常在 alpha/beta 出現數月後才 GA。例如 gcloud beta container clusters create-auto 在 Autopilot GKE 預覽期間是唯一的配置方式。新 zone、新 VM 系列、新 IAM 角色等 region 級功能也通常先在 beta 出現。

正式環境紀律

腳本請鎖定能滿足需求的最穩定 track。若必須用 beta，請文件化此依賴並建立 checklist，等功能 GA 後回頭測試並把前綴拿掉。任何無人值守 pipeline 都應避免 alpha——其語意可能在版本之間悄悄改變。

可用 gcloud beta version 確認所安裝的 track，並用 gcloud components list 查看本地有哪些可用元件。

gcloud builds submit：從 CLI 觸發 Cloud Build

gcloud builds submit 是開發者筆電或 CI runner 與 Cloud Build 之間的橋樑。

常見模式

# 用當前目錄 Dockerfile 建容器並推到 Artifact Registry
gcloud builds submit \
  --tag=us-central1-docker.pkg.dev/$PROJECT_ID/web/api:$GIT_SHA

# 跑多步驟 cloudbuild.yaml
gcloud builds submit \
  --config=cloudbuild.yaml \
  --substitutions=_ENV=staging,_SHA=$GIT_SHA

# 不上傳原始碼（原始碼已在 GCS 或 GitHub 時很有用）
gcloud builds submit \
  --no-source \
  --config=cloudbuild.yaml

原始碼上傳機制

gcloud builds submit 會把當前目錄打成 tarball（遵循 .gcloudignore），上傳到 staging Cloud Storage bucket，再觸發 build。預設 .gcloudignore 會引用 .gitignore。對大型 monorepo，建議寫一份明確的 .gcloudignore 控制上傳大小。

串流日誌

預設情況下日誌會串流到終端機直到 build 完成。CI 中可用 --async 發完即走，再透過 Pub/Sub 通知或 gcloud builds describe BUILD_ID 取得狀態。搭配 gcloud builds list --filter="status=WORKING" 監控進行中的 build。

對既有 artifact，可用 gcloud builds submit 搭配 gcloud artifacts docker images list 驗證 push 成功後再觸發 Cloud Run 部署。

gcloud auth print-access-token 配合 ad-hoc curl

有時某個服務尚無 gcloud 子命令，或您想直接打私有 API。gcloud auth print-access-token 可依當前啟用身分（user 或服務帳戶）發出有效約 1 小時的 OAuth 2.0 access token。

典型 curl 模式

TOKEN=$(gcloud auth print-access-token)

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://compute.googleapis.com/compute/v1/projects/$PROJECT_ID/zones/us-central1-a/instances"

Identity token vs access token

Access token（print-access-token）: 用來呼叫接受 OAuth 2.0 的 Google Cloud API。
Identity token（print-identity-token）: 簽章後的 JWT，用來呼叫 Cloud Run、Cloud Functions 或任何驗證 iap- 類 audience 的服務。

ID_TOKEN=$(gcloud auth print-identity-token \
  --audiences=https://my-service-xyz-uc.a.run.app)

curl -H "Authorization: Bearer $ID_TOKEN" https://my-service-xyz-uc.a.run.app/api

身分模擬（impersonation）

最小權限腳本的最佳做法是模擬服務帳戶，無需匯出金鑰：

gcloud auth print-access-token \
  --impersonate-service-account=runner-sa@$PROJECT_ID.iam.gserviceaccount.com

需在目標服務帳戶上具備 roles/iam.serviceAccountTokenCreator。這是比下載 JSON 金鑰更好的模式——金鑰是長效祕密，必須定期輪替。

Cloud Shell：架構師的終端機

Cloud Shell 是一個免費、臨時的 GCE 執行個體，預裝了 SDK 和常用工具 (git、docker、terraform、kubectl)。

包含 5 GB 的永久家目錄（在 session 之間掛載）。
包含內建的程式碼編輯器 (基於 Theia/VS Code)。
以登入 Google 帳戶預先驗證身分。
使用場景: 無需在本地安裝任何內容即可進行快速管理任務、demo 與 break-glass 操作。
限制: session 閒置 20 分鐘後逾時；不適合長時間 batch 工作。

常見問題 — gcloud CLI 與自動化

Q1. 我該如何更新 gcloud CLI？

執行 gcloud components update。如果您是通過套件管理員 (如 apt 或 brew) 安裝的，請改用該管理員。

Q2. 我可以在 GCE VM 內部執行 gcloud 命令嗎？

可以。如果 VM 附加了具有正確 IAM 權限的服務帳戶，您甚至不需要登入。gcloud 會透過 metadata server 自動使用 VM 的身分。

Q3. `gcloud` 和 `gsutil` 有什麼區別？

gcloud 處理大多數 GCP 服務。gsutil 是一個專門針對 Cloud Storage (管理儲存桶和物件) 的較舊專門工具。新版 gcloud storage 速度更快、原生支援平行上傳，最終將取代 gsutil。

Q4. 如果我迷路了，該如何找到正確的命令？

使用 gcloud help 或交互式介面：gcloud alpha interactive。它會在您輸入時提供自動補全和說明文件。gcloud topic 則涵蓋跨命令概念。

Q5. gcloud 中的「Alpha」和「Beta」是什麼意思？

gcloud alpha 功能處於早期測試階段，可能會發生變化。gcloud beta 功能較穩定，但仍未正式發佈 (GA)。對於生產腳本，請始終優先選擇 GA 命令 (無 alpha/beta 前綴)。

最後的架構師提示

在 PCA 考試中，尋找關於 「提取特定資源資訊」 或 「執行批次更新」 的問題。答案很可能涉及帶有 --filter 或 --format 旗標的 gcloud 命令。請記住使用 Configurations 來分隔專案，使用 服務帳戶（最好以 impersonation 方式） 進行腳本驗證，並用 set -euo pipefail 讓 Bash 自動化保持安全。自動化是可擴展性的關鍵。

gcloud CLI 簡介

白話文解釋（Plain English Explanation）

比喻 1 — 魔法棒 vs. 藍圖 (CLI vs IaC)

比喻 2 — 瑞士軍刀 (SDK)

比喻 3 — 分類帽 (過濾與格式化)

gcloud 命令剖析

精通 --format 旗標

內建格式

投影與轉換

--filter 旗標（伺服器端過濾）

過濾運算子

範例

gcloud 組態與命名 profile

常見流程

單次命令覆寫

CI/CD 友善

用 xargs 與 GNU parallel 做批次操作

xargs 循序執行

GNU parallel 並行

腳本模式與 Bash 防呆習慣

冪等性

用 gcloud topic 探索命令

gcloud beta 與 alpha：存取 pre-GA 功能

架構師為何關注

正式環境紀律

gcloud builds submit：從 CLI 觸發 Cloud Build

常見模式

原始碼上傳機制

串流日誌

gcloud auth print-access-token 配合 ad-hoc curl

典型 curl 模式

Identity token vs access token

身分模擬（impersonation）

Cloud Shell：架構師的終端機

常見問題 — gcloud CLI 與自動化

Q1. 我該如何更新 gcloud CLI？

Q2. 我可以在 GCE VM 內部執行 gcloud 命令嗎？

Q3. gcloud 和 gsutil 有什麼區別？

Q4. 如果我迷路了，該如何找到正確的命令？

Q5. gcloud 中的 「Alpha」 和 「Beta」 是什麼意思？

最後的架構師提示

官方資料來源

更多 PCA 主題

Q3. `gcloud` 和 `gsutil` 有什麼區別？

Q5. gcloud 中的「Alpha」和「Beta」是什麼意思？