這篇記錄把 VM 的管理員登入從防火牆對 0.0.0.0/0 開放 22 與 3389 port，改成走 IAP TCP forwarding 的實際操作。內容依操作的順序是：切換前盤點依賴舊規則的連線；準備並實際登入一次救援入口（Serial Console 與本機救援帳號）；啟用 IAP API、開啟 IAP 的稽核紀錄、建立只放行 IAP 來源的防火牆規則與 network tag；授予開通道的 IAM 權限；停用舊規則、用 IAP 驗證新規則；刪除對外開放的規則；收斂 default-allow-internal 與 default-allow-icmp；啟用 OS Login；建 Cloud NAT 並移除外部 IP。每一步寫出這次的取值與實測結果，以及沒做或換一種做法時的結果；替代做法與沒做時的結果沒有另外標註的是這次實測看到的，照官方文件推出的寫出文件，推論的寫明沒有實跑。IAP 的連線路徑、預設規則為什麼要換、切換的順序為什麼這樣排、IAM 授權的範圍、連不上時的依層判讀、OS Login 與 Cloud NAT 的機制，寫在 GCP VM 的 SSH 與 RDP 管理通道：從預設的全開規則改走 IAP TCP forwarding（下文稱概念篇），這裡不重寫。

這一篇的指令以單台 VM 為對象。由 MIG 或 GKE 管理的 VM，同樣的設定改寫在 instance template 與 node pool 上，做法在 GCP 上 MIG 與 GKE 管理存取的實測紀錄；Shared VPC 的 service project、用 Terraform 管理的專案，指令要改寫在別的位置；新專案從零開始則可以跳過盤點與停用驗證。這幾種環境的調整見概念篇開場之後「另外四種環境要先調整做法再往下讀」那一段。

切換前的盤點：依賴舊規則的連線

default-allow-ssh 放行的不只是管理員本人的 SSH：CI 或部署腳本用外部 IP 直連 VM、Ansible 這類組態管理工具、監控程式的探測、第三方廠商的維護連線，都可能經過這條規則，而預設規則沒有開 logging，手上沒有紀錄可以查出它們。盤點分兩步。先對舊規則開啟 logging，列出經過它的候選來源：

1# 對舊規則開啟 logging，之後每一次放行都會寫進 Cloud Logging
2gcloud compute firewall-rules update default-allow-ssh --enable-logging
3gcloud compute firewall-rules update default-allow-rdp --enable-logging
4
5# 觀察一段時間後，列出經由舊規則連進來的來源 IP 與次數（RDP 把規則名稱換成 default-allow-rdp）
6gcloud logging read \
7  'logName:"compute.googleapis.com%2Ffirewall" AND jsonPayload.rule_details.reference:"default-allow-ssh"' \
8  --freshness=7d --format="value(jsonPayload.connection.src_ip)" | sort | uniq -c

--freshness=7d 是查詢往回看的時間長度，依自己的部署週期調整，要涵蓋到一次完整的部署與排程工作。實際依賴這條規則的連線，要從 VM 上的成功登入紀錄找（理由見概念篇〈切換到 IAP 的順序〉）：

1# 在 Linux VM 上列出這段期間成功的 SSH 登入：帳號、來源 IP 與金鑰指紋
2sudo journalctl -u ssh -u sshd --since "7 days ago" | grep "Accepted publickey"

每一行的格式是 Accepted publickey for <user> from <ip> ... <金鑰指紋>，用帳號與金鑰指紋就認得出是哪個人或哪個自動化工具。Windows VM 看事件檢視器的安全性紀錄裡事件 ID 4624、登入類型 10（遠端互動，也就是 RDP）的事件。找出來的非人員來源要先改走 IAP 才能停用舊規則：CI 與自動化工具用服務帳號開 IAP 通道，一般 ssh 的工具照概念篇〈IAP TCP forwarding 的連線路徑與來源範圍〉的 ProxyCommand 改設定。

• 沒做時：停用舊規則的那一刻，依賴它的 CI、監控與廠商連線跟管理員的一起被拒；這些失敗出現在部署或排程執行時，不一定在切換當下被看到（從規則的作用推論，這次沒有實跑）。
• 替代做法：觀察期縮短或省略，換到的是切換提早，付出的是只盤點到觀察期內發生過的連線，一個月跑一次的排程會漏掉；只看防火牆紀錄、不看 VM 上的登入紀錄，換到的是不必登入每一台 VM，付出的是 CI 這類來源 IP 每次不同的連線認不出來（兩者都從紀錄的形狀推論，這次沒有實跑）。

準備救援入口：Serial Console 與本機救援帳號

Serial Console 透過 VM 的虛擬序列埠提供登入，不經過 VM 的網路設定與 sshd，在防火牆 tag 漏加、sshd 設定改壞、OS Login 設錯、磁碟滿導致 sshd 起不來時當作救援入口。它用 VM 內的本機帳號密碼登入，與 metadata 金鑰、OS Login 都無關，所以救援帳號要在 VM 還正常時就建好：

1# 在每台 Linux VM 上建一個設了密碼的本機救援帳號（RHEL 系把 sudo 群組換成 wheel）
2sudo useradd -m rescue && sudo passwd rescue && sudo usermod -aG sudo rescue
3
4# 確認 sshd 仍然只收金鑰，救援帳號的密碼只在 Serial Console 上有效
5sudo sshd -T | grep -i passwordauthentication

rescue 是自己取的帳號名稱。密碼用密碼管理工具逐台隨機產生、存在團隊的密碼庫，不同 VM 不共用同一組；持有救援密碼的人離開團隊時，逐台輪替。sshd -T 印出 sshd 實際生效的設定，那一行要是 passwordauthentication no，否則救援帳號的密碼也能從 SSH 登入。Windows VM 的序列主控台（Special Administration Console）用 Windows 的本機管理員帳號登入，要事先確認那個帳號的密碼在手上。

Serial Console 的互動登入預設關閉，平時保持關閉，救援時才對單一 VM 開啟：

1# 救援時對單一 VM 開啟 Serial Console 並連上
2gcloud compute instances add-metadata <instance-name> --zone=<zone> --metadata serial-port-enable=TRUE
3gcloud compute connect-to-serial-port <instance-name> --zone=<zone>
4
5# 救援結束後關回去
6gcloud compute instances add-metadata <instance-name> --zone=<zone> --metadata serial-port-enable=FALSE

<instance-name> 與 <zone> 用 gcloud compute instances list 查，第一欄是 VM 名稱、第二欄是 zone。建好救援帳號之後，對一台 VM 照上面的指令開啟、用 rescue 登入並執行一次 sudo -v 確認 sudo 可用，再關回去；這次在 Debian 12 的 VM 上實跑，登入與 sudo 都成功。Windows VM 的 SAC 這次沒有實跑。

• 沒做時：停用舊規則、或之後啟用 OS Login 時任何一項設錯，VM 沒有不經過網路與 sshd 的入口；剩下的路是在 metadata 設 startup-script（Linux）或 windows-startup-script-ps1（Windows）、重開機以 root 或 SYSTEM 執行來建帳號或改回設定，或把開機磁碟卸下掛到另一台 VM 修改，兩條都要重開機（Compute Engine 的啟動腳本與救援文件，這次沒有實跑）。
• 替代做法：
  • 救援帳號寫進自訂映像檔，換到的是新建的 VM 一開始就有，付出的是密碼雜湊在每台 VM 上相同、要輪替就要重做映像（推論，這次沒有實跑）。
  • 靠 startup-script 臨時建帳號，換到的是平時不留密碼，付出的是救援時要重開機，而且 startup-script 存在 metadata 裡，有讀取權限的人都看得到內容（Compute Engine 的 metadata 文件，這次沒有實跑）。
  • 組織強制了 compute.disableSerialPortAccess 時，救援名單要有能對專案解除這條政策的人，見 GCP VM 的 SSH 與 RDP 管理通道 的〈組織層級的護欄：Organization Policy 與階層式防火牆〉。

啟用 IAP API、開啟稽核紀錄並建立只放行 IAP 來源的防火牆規則

IAP 端點以 API 的形式在專案上開關，沒有啟用時，--tunnel-through-iap 的連線在 IAP 端點那一步就開不起來：

1# 啟用 IAP API（每個專案一次）
2gcloud services enable iap.googleapis.com

同一步在 Google Cloud 控制台的「IAM 與管理 > 稽核記錄」為 Cloud Identity-Aware Proxy 開啟 Data Access 紀錄裡的「管理員讀取」（ADMIN_READ）類型。開通道時 IAP 檢查的權限 iap.tunnelInstances.accessViaIAP 歸在這個類型，每一次開通道會留下一筆方法名稱為 AuthorizeUser 的紀錄。開啟之後經由 IAP 連一次，查到這次連線的紀錄才算開對了類型（protoPayload.resourceName 是 VM 的執行個體 ID）：

1gcloud logging read 'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.methodName="AuthorizeUser"' \
2  --freshness=1h --format="value(timestamp,protoPayload.authenticationInfo.principalEmail,protoPayload.resourceName)"

也在同一步確認所有要開通道的 Google 帳號都已強制兩步驟驗證，理由見概念篇〈IAP 的 IAM 授權範圍：誰拿得到通道〉最後兩段。

• 沒做時（不開 ADMIN_READ）：開通道的帳號與目標 VM 沒有 VM 以外的紀錄，事後調查只剩 Admin Activity 裡的設定變更與 VM 上的 sshd 紀錄；開啟之前的通道紀錄查不回來（Cloud Audit Logs 文件，這次沒有實跑）。
• 替代做法：只開「資料讀取」（DATA_READ）實測過：連了十次左右，紀錄零筆。兩種都開，換到的是不必判斷權限歸在哪一類，付出的是紀錄量與費用增加（推論，這次沒有量）。

新規則只開需要的 port，並用 target tag 限定作用的 VM：

 1# 放行 IAP 的 IPv4 來源連到帶指定 tag 的 Linux VM 的 22 port
 2gcloud compute firewall-rules create allow-ssh-from-iap \
 3  --network=<network-name> \
 4  --direction=INGRESS \
 5  --action=allow \
 6  --rules=tcp:22 \
 7  --source-ranges=35.235.240.0/20 \
 8  --target-tags=<ssh-via-iap-tag> \
 9  --enable-logging
10
11# 有 Windows VM 時，另建一條放行 3389 port 的規則，用另一個 tag
12gcloud compute firewall-rules create allow-rdp-from-iap \
13  --network=<network-name> \
14  --direction=INGRESS \
15  --action=allow \
16  --rules=tcp:3389 \
17  --source-ranges=35.235.240.0/20 \
18  --target-tags=<rdp-via-iap-tag> \
19  --enable-logging

• allow-ssh-from-iap、allow-rdp-from-iap：規則名稱，自己取，同一個專案裡不能重複。
• <network-name>：VM 所在的 VPC 名稱，預設網路就是 default，自建網路用 gcloud compute networks list 查。
• <ssh-via-iap-tag>、<rdp-via-iap-tag>：自己取的 network tag 名稱，例如 ssh-iap、rdp-iap。SSH 與 RDP 用不同的 tag，Linux VM 就不會被順便開了 3389。
• --enable-logging：讓防火牆把這條規則的每一次放行寫進 Cloud Logging，驗證新規則與之後稽核都要用到。
• --source-ranges=35.235.240.0/20：Google 公開的 IAP 來源位址段，每個專案都相同；--rules 依通道填要開的 port（SSH 是 tcp:22、RDP 是 tcp:3389）。這兩條規則沒有寫 --priority，預設是 1000（實測），比 default-allow-ssh 的 65534 先被評估。

自建的 custom-mode VPC 有 IPv6 VM 時，再建一條名稱不同（例如 allow-ssh-from-iap-v6）、--source-ranges=2600:2d00:1:7::/64、其餘引數相同的規則。接著對每台 VM 加上對應的 tag，VM 分布在不同 zone 時逐台以各自的 --zone 執行：

1gcloud compute instances add-tags <instance-name> --zone=<zone> --tags=<ssh-via-iap-tag>
2gcloud compute instances add-tags <windows-instance-name> --zone=<zone> --tags=<rdp-via-iap-tag>

• 沒做時（漏加 tag）：停用舊規則之後，IAP 回 4003（failed to connect to backend），Connectivity Tests 指出擋下它的是 default-deny-ingress。
• 替代做法：
  • 省略 --target-tags，換到的是不必逐台加 tag，付出的是 IAP 來源連得到網路裡每一台 VM 的 22 port（照規則的作用推論，這次沒有實跑）。
  • 把 --rules 寫成 all，換到的是不必列 port，付出的是 IAP 來源連得到每一台 VM 的每一個 port，等於把 default-allow-internal 的寬度複製給 IAP（照規則的作用推論，這次沒有實跑）。
  • 改用 --target-service-accounts 以服務帳號選 VM，換到的是 tag 不能被持有 VM 修改權限的人隨手加上（能編輯 VM 的人改得了它的 tag），付出的是同一個服務帳號的 VM 全部一起套用，而且 VM 換服務帳號要停機（VPC 防火牆規則文件，這次沒有實跑）。

授予開通道的 IAM 權限

開通道的權限是 IAM role roles/iap.tunnelResourceAccessor。下面的指令把它綁在專案層級，並用 IAM Conditions（在角色綁定上附加條件，條件成立時這個綁定才生效）限定可以連的 port 或期限；條件的寫法依環境選一種：

 1# 只有 Linux VM：條件限定只能連 22 port
 2gcloud projects add-iam-policy-binding <project-id> \
 3  --member=user:<admin-email> \
 4  --role=roles/iap.tunnelResourceAccessor \
 5  --condition='expression=destination.port == 22,title=iap-ssh-only'
 6
 7# 同時有 Windows VM：條件放行 22 與 3389
 8gcloud projects add-iam-policy-binding <project-id> \
 9  --member=user:<admin-email> \
10  --role=roles/iap.tunnelResourceAccessor \
11  --condition='expression=destination.port == 22 || destination.port == 3389,title=iap-ssh-rdp'
12
13# 只允許連特定一台 VM 的 22 port
14gcloud projects add-iam-policy-binding <project-id> \
15  --member=user:<admin-email> \
16  --role=roles/iap.tunnelResourceAccessor \
17  --condition='expression=destination.port == 22 && destination.ip == "<vm-internal-ip>",title=iap-ssh-one-vm'
18
19# 外包或臨時存取：到期之後綁定自動失效
20gcloud projects add-iam-policy-binding <project-id> \
21  --member=user:<contractor-email> \
22  --role=roles/iap.tunnelResourceAccessor \
23  --condition='expression=destination.port == 22 && request.time < timestamp("<expiry-time>"),title=iap-ssh-until-expiry'

• <project-id>：VM 所在的專案 ID，用 gcloud config get-value project 查目前設定的是哪一個。
• <admin-email>、<contractor-email>：要給權限的人的 Google 帳號；給一群人時把 user: 換成 group: 加 Google Group 的位址，CI 這類機器身分換成 serviceAccount: 加服務帳號的位址。
• <vm-internal-ip>：VM 的內部 IP，gcloud compute instances list 的 INTERNAL_IP 欄查得到。
• <expiry-time>：綁定失效的時間，RFC 3339 格式，例如 2027-03-31T00:00:00Z。
• title：這個條件的顯示名稱，自己取，會出現在 IAM 頁面上。

這次用第二個帳號實測：沒有這個角色時開通道回 4033；條件只放行 22 時連 3389 回 4033（Owner 帳號對照回 4003，代表 Owner 不受條件限制、而是被防火牆擋下）；限定單一 VM 與過期的條件連續三分鐘回 4033，正對照在 75 秒內放行。IAM 綁定從送出到生效約 60 到 120 秒，這段時間內的 4033 不代表條件寫錯。

Linux VM 的 gcloud compute ssh 另外要 VM 端的登入權限：還沒啟用 OS Login 時，gcloud compute ssh 把公鑰寫進專案或 VM 的 metadata（實測寫進專案 metadata），所以非 Owner 的帳號要有修改 metadata 的權限（例如 roles/compute.instanceAdmin.v1），VM 掛著服務帳號時另外要那個服務帳號的 roles/iam.serviceAccountUser；已經啟用 OS Login 時，改由〈啟用 OS Login：先授角色、單台先行、再做專案層級〉的登入角色決定。兩種情形都要讀取 VM 與專案資訊的權限（例如 roles/compute.viewer）。

• 沒做時：非 Owner 的管理員開通道回 4033。Owner 不需要這一步，所以團隊全員都是 Owner 時，這一步看起來不必做，而 IAM Conditions 對 Owner 不生效，條件寫了也限不住任何人（Owner 連 3389 回 4003 而不是 4033）。
• 替代做法：不加條件，換到的是指令短、不必維護條件，付出的是持有角色的人連得到專案裡每台 VM 的每個 port（只要防火牆放行）；綁給 domain: 或大型群組，換到的是不必逐人授權，付出的是整個組織的帳號都能開通道（兩者都從角色的作用推論，這次沒有實跑）。取捨的判斷見概念篇〈IAP 的 IAM 授權範圍：誰拿得到通道〉。

停用舊規則，用 IAP 驗證新規則

先在舊規則還在時，每一位管理員各自用自己的帳號連一次，確認 IAM 權限：

1# Linux：透過 IAP 通道 SSH 進 VM
2gcloud compute ssh <instance-name> --zone=<zone> --tunnel-through-iap
3
4# Windows：把 VM 的 3389 port 經 IAP 轉到本機的 13389，再用 RDP 用戶端連 localhost:13389
5gcloud compute start-iap-tunnel <windows-instance-name> 3389 --local-host-port=localhost:13389 --zone=<zone>

加上 --tunnel-through-iap 時，gcloud 改走 IAP、不連 VM 的外部 IP；VM 還有外部 IP 時，少了這個參數的連線走的是舊路徑。這一次連線驗證的是 IAM：IAP 端點會拒絕沒有權限的帳號。防火牆規則與 tag 這一次驗不到，因為舊規則的 0.0.0.0/0 也放行 IAP 的位址段。接著停用舊規則（規則仍在，只是不生效），由一位管理員對 Linux 與 Windows 各一台 VM 再連一次：

1gcloud compute firewall-rules update default-allow-ssh --disabled
2gcloud compute firewall-rules update default-allow-rdp --disabled
3gcloud compute ssh <instance-name> --zone=<zone> --tunnel-through-iap

這一次連得上，代表放行連線的是新規則；前提是專案裡沒有其他來源涵蓋 35.235.240.0/20 的允許規則，用概念篇〈預設網路自帶的防火牆規則〉的列出規則指令確認。這次實測停用之後經由 IAP 連得上、不加 --tunnel-through-iap 的直連被拒，Windows 經 IAP 的 3389 回了 X.224 Connection Confirm。新規則建立時加了 --enable-logging，可以查防火牆紀錄確認命中的是哪一條規則：

1# 查最近一小時經由 IAP 規則放行的連線
2gcloud logging read \
3  'logName:"compute.googleapis.com%2Ffirewall" AND jsonPayload.rule_details.reference:"allow-ssh-from-iap"' \
4  --freshness=1h --limit=10

規則剛開啟 logging 的最初幾分鐘，紀錄裡的 rule_details 可能是空的（實測前兩筆沒有、約五分鐘後的三筆有），照本節的順序正好落在這段時間，所以上面這條查不到不代表新規則沒有命中。這時改用來源 IP 查，結果與 rule_details 是否已經填入無關；驗 RDP 的規則時把 22 換成 3389：

1gcloud logging read \
2  'logName:"compute.googleapis.com%2Ffirewall" AND ip_in_net(jsonPayload.connection.src_ip, "35.235.240.0/20") AND jsonPayload.connection.dest_port=22' \
3  --freshness=1h --limit=10 \
4  --format="value(timestamp,jsonPayload.connection.src_ip,jsonPayload.rule_details.reference)"

連不上時，用下面的指令把舊規則恢復，再照概念篇〈IAP 通道連不上時的依層判讀〉找出是哪一層；防火牆規則透過 GCP 的 API 修改，SSH 連不上也改得回來：

1gcloud compute firewall-rules update default-allow-ssh --no-disabled
2gcloud compute firewall-rules update default-allow-rdp --no-disabled

4003 時要用 Connectivity Tests 查是哪一條規則或政策擋下：gcloud network-management connectivity-tests create <test-name> --source-ip-address=35.235.240.1 --destination-instance=projects/<project-id>/zones/<zone>/instances/<instance-name> --destination-port=22 --protocol=TCP，<test-name> 自己取，--source-ip-address 只收單一 IP，取 IAP 位址段裡的任一個。

• 主控台的 SSH 按鈕（SSH-in-browser）：官方〈Connect to Linux VMs using IAP〉寫明它只在 VM 沒有外部 IP 時才走 IAP。所以 VM 還帶外部 IP 時，停用舊規則之後，用主控台按鈕的人連不上，而 --tunnel-through-iap 驗起來是通的，這不代表新規則壞了；外部 IP 移除之後，主控台按鈕改走 IAP（照官方文件推出，這次沒有實跑）。盤點時把用主控台按鈕登入的人一起找出來，切換期間請他們改用 --tunnel-through-iap。
• 沒做時（只在舊規則還在時驗證）：連得上的那一次可能是舊規則放行的，tag 漏加或規則寫錯都測不出來，要到刪除舊規則之後才發現（照規則的作用推論，這次沒有實跑）。
• 替代做法：
  • 不停用、只查防火牆紀錄裡命中的規則名稱，換到的是驗證期間外部來源照常連得到，付出的是要等 rule_details 填入，而且兩條規則都放行時紀錄記的是先被評估的那一條（推論，這次沒有在兩條並存時查）。
  • 直接刪除舊規則再驗證，換到的是少一步，付出的是出錯時要重建規則，重建時可能寫錯；停用的規則用 --no-disabled 一行恢復原樣。

刪除對外開放的規則

刪除之前，列出還沒帶 tag 的 VM，兩份清單都要是空的（只有 Linux 或只有 Windows 時，查對應的那一份）：

1gcloud compute instances list --filter="NOT tags.items=<ssh-via-iap-tag>"
2gcloud compute instances list --filter="NOT tags.items=<rdp-via-iap-tag>"

清單裡出現的是另一種作業系統的 VM 時合理（Linux VM 本來就不帶 RDP 的 tag），其餘的要先補上 tag 再刪規則。專案裡還沒有任何 VM 帶 tag 時，gcloud 會先印一行 WARNING: The following filter keys were not present in any resource : tags.items，下面列出的 VM 清單仍然正確（實測）。

1gcloud compute firewall-rules delete default-allow-ssh default-allow-rdp

刪除之後才發現有漏掉的連線來源時，照原樣把規則建回來，再回頭處理（實測建得回來）：

1gcloud compute firewall-rules create default-allow-ssh --network=default \
2  --direction=INGRESS --action=allow --rules=tcp:22 --source-ranges=0.0.0.0/0 --priority=65534 --enable-logging
3gcloud compute firewall-rules create default-allow-rdp --network=default \
4  --direction=INGRESS --action=allow --rules=tcp:3389 --source-ranges=0.0.0.0/0 --priority=65534 --enable-logging

• 沒做時（停用之後不刪）：停用的規則不放行任何連線，效果與刪除相同；留著的代價是有人用 --no-disabled 一行就恢復全開（照規則的作用推論，這次沒有實跑）。Security Command Center 的 OPEN_SSH_PORT finding 是否把停用的規則算進去，這次沒有確認。
• 替代做法：用 gcloud compute firewall-rules update default-allow-ssh --source-ranges=<固定的管理網段> 把來源收窄、不刪除，換到的是保留一條直連的路，付出的是這條路的授權仍然是來源 IP，分辨不出人（取捨見 伺服器管理通道的設計：網路可達性、通道授權、主機登入驗證三層的做法與選擇，以及救援入口 的〈網路可達性的做法：管理 port 對誰開放〉，這次沒有實跑）。

收斂 default-allow-internal 與 default-allow-icmp

default-allow-internal 要先確認 VM 之間實際需要哪些 port（應用連資料庫、節點之間的叢集通訊）再改成具體的規則。改法是為每一組需要的連線各建一條規則，例如應用連 PostgreSQL：

1gcloud compute firewall-rules create allow-app-to-db --network=default \
2  --direction=INGRESS --action=allow --rules=tcp:5432 \
3  --source-tags=<app-tag> --target-tags=<db-tag>

<app-tag>、<db-tag> 是自己取的 tag，加在應用與資料庫 VM 上；tcp:5432 換成實際的服務 port。每一組需要的連線都建好之後，再刪 default-allow-internal。default-allow-icmp 的處理看用途：監控或除錯流程會用 ping 確認 VM 存活時，保留並把來源縮到內部網段與監控主機（gcloud compute firewall-rules update default-allow-icmp --source-ranges=10.128.0.0/9,<monitoring-host-ip>/32，<monitoring-host-ip> 是發 ping 的監控主機的 IP）；沒有這種用途就一起刪除。這一節的指令這次沒有實跑。

• 沒做時：同一個網路裡的 VM 之間不受 port 限制，一台 VM 被入侵之後能直接連到其他 VM 的資料庫與管理 port；管理通道本身不受影響，所以這一步可以排進另一次變更（照規則的作用推論，這次沒有實跑）。
• 替代做法：直接刪除 default-allow-internal，換到的是一步收完，付出的是 VM 之間的服務連線當場中斷；整個網路改成自己規劃的 custom-mode VPC，換到的是預設規則一次清掉，付出的是 VM 要搬網路，見概念篇〈預設網路自帶的防火牆規則〉（兩者都是推論，這次沒有實跑）。

啟用 OS Login：先授角色、單台先行、再做專案層級

啟用 OS Login 之後，VM 不再接受 metadata 裡的金鑰（實測：metadata 金鑰被拒），順序為什麼是先授角色、單台先行，見 GCP VM 的 SSH 與 RDP 管理通道 的〈SSH 金鑰在 GCP 上的管理位置：metadata 金鑰與 OS Login 的啟用條件〉。先把登入角色授予每一位管理員與每一個要登入 VM 的服務帳號；VM 掛著服務帳號時，每一個登入者另外需要那個服務帳號的 roles/iam.serviceAccountUser：

 1# 授予管理員 OS Login 的登入角色：一般登入與含 sudo 的兩種擇一
 2gcloud projects add-iam-policy-binding <project-id> \
 3  --member=user:<admin-email> --role=roles/compute.osLogin
 4gcloud projects add-iam-policy-binding <project-id> \
 5  --member=user:<admin-email> --role=roles/compute.osAdminLogin
 6
 7# CI 或自動化工具的服務帳號同樣要授予（需要 sudo 時改用 osAdminLogin）
 8gcloud projects add-iam-policy-binding <project-id> \
 9  --member=serviceAccount:<ci-service-account-email> --role=roles/compute.osLogin
10
11# 查 VM 掛的服務帳號，並授予登入者使用它的權限
12gcloud compute instances describe <instance-name> --zone=<zone> \
13  --format="get(serviceAccounts[0].email)"
14gcloud iam service-accounts add-iam-policy-binding <service-account-email> \
15  --member=user:<admin-email> --role=roles/iam.serviceAccountUser

<ci-service-account-email> 是 CI 或自動化工具開通道用的服務帳號，<service-account-email> 是上一條 describe 查出來、VM 掛的那個服務帳號，兩者不同。這次用第二個帳號實測：缺 serviceAccountUser 時 Permission denied (publickey)，補上之後 20 秒內登入；osLogin 不能 sudo、osAdminLogin 可以。

接著先對一台 VM 啟用，讓每一位非 Owner 的管理員各自用自己的帳號連通並確認 sudo 可用，CI 也對這台跑一次部署，再做專案層級：

1# 先對單一 VM 啟用，連通確認
2gcloud compute instances add-metadata <instance-name> --zone=<zone> --metadata enable-oslogin=TRUE
3
4# 確認之後在專案層級啟用（VM 層級的設定會蓋過專案層級）
5gcloud compute project-info add-metadata --metadata enable-oslogin=TRUE
6
7# 連不上時還原（修改 metadata 走 API，不需要登入 VM）
8gcloud compute instances add-metadata <instance-name> --zone=<zone> --metadata enable-oslogin=FALSE
9gcloud compute project-info add-metadata --metadata enable-oslogin=FALSE

專案層級啟用之後再盤點兩件事。VM 層級設了 enable-oslogin=FALSE 的 VM 會蓋過專案設定、仍然讀 metadata 金鑰（實測），用下面這條列出它們的名稱，逐台改成 TRUE 或移除這個鍵：

1gcloud compute instances list --format=json \
2  | jq -r '.[] | select(any(.metadata.items[]?; .key=="enable-oslogin" and (.value|ascii_downcase)=="false")) | .name'

專案 metadata 的 ssh-keys 仍然留著前任與現任成員的公鑰，OS Login 一旦還原成 FALSE 它們就又能用，確認全部 VM 都啟用之後用 gcloud compute project-info remove-metadata --keys=ssh-keys 清掉（實測）。

• 沒做時（不啟用 OS Login）：登入驗證仍是 metadata 裡的公鑰，寫在專案 metadata 的公鑰對專案裡每台 VM 都生效，成員離職時漏刪一把，那把金鑰就持續能登入整個專案（OS Login 文件，這次沒有實跑）。
• 替代做法：
  • 直接在專案層級啟用、不經過單台，換到的是少一輪驗證，付出的是角色漏授時鎖住的是整個專案的每一台 VM；只由 Owner 驗證，看不出漏授，因為 Owner 持有全部權限（推論，這次沒有實跑）。
  • 改用 SSH 憑證（OpenSSH CA），換到的是主機不全在 GCP 時也能用同一套，付出的是要維運 CA，見 OpenSSH 內建 CA 的 SSH 憑證導入。
  • 再加 enable-oslogin-2fa=TRUE 要求每次登入多一次第二因素，同樣先對單一 VM 設定驗證，連不上時改回 FALSE。付出的是每一位登入者的 Google 帳號都要先啟用兩步驟驗證，沒有啟用的會登不進去；而 OS Login 文件寫明兩步驟驗證不套用在服務帳號上，CI 這類登入者不受它約束（OS Login 文件，這次沒有實跑）。換到的是帳號密碼或本機的 refresh token 外洩時，登入還要第二因素（推論，這次沒有實跑）。

建 Cloud NAT 並移除外部 IP

Cloud NAT 承接沒有外部 IP 的 VM 往外的連線，建在 Cloud Router 上，以 region 為單位生效。哪些出站連線改由 Cloud NAT 承接、哪些改走 Private Google Access，以及出站的驗證為什麼要在移除外部 IP 之後做，見概念篇〈拿掉外部 IP 之後的出站路徑：Cloud NAT 與 Private Google Access〉。

 1# 在 VM 所在的 region 建 Cloud Router，再在上面建 Cloud NAT（出站 IP 自動配發）
 2gcloud compute routers create <router-name> \
 3  --network=<network-name> --region=<region>
 4gcloud compute routers nats create <nat-name> \
 5  --router=<router-name> --region=<region> \
 6  --auto-allocate-nat-external-ips \
 7  --nat-all-subnet-ip-ranges
 8
 9# 外部服務要求來源 IP 白名單時：先預留靜態 IP，NAT 改用它出站
10gcloud compute addresses create <nat-ip-name> --region=<region>
11gcloud compute routers nats create <nat-name> \
12  --router=<router-name> --region=<region> \
13  --nat-external-ip-pool=<nat-ip-name> \
14  --nat-all-subnet-ip-ranges

• <router-name>、<nat-name>、<nat-ip-name>：自己取的資源名稱。
• <region>：VM 所在 zone 去掉最後的字母那一段，例如 zone asia-east1-b 對應 region asia-east1；VM 分布在幾個 region 就要各建一組。
• --auto-allocate-nat-external-ips 讓 GCP 自動配發出站用的外部 IP，這些 IP 可能變動；--nat-external-ip-pool 改用預留的靜態 IP。
• --nat-all-subnet-ip-ranges 讓這個 region 裡所有 subnet 都走這個 NAT，只想讓部分 subnet 出站時改用 --nat-custom-subnet-ip-ranges 逐一列出。

VM 要存取 Cloud Storage、Artifact Registry 這類 Google API 時，subnet 開啟 Private Google Access，就能用內部 IP 連到 Google API，不經過 Cloud NAT：

1gcloud compute networks subnets update <subnet-name> \
2  --region=<region> --enable-private-ip-google-access

<subnet-name> 用 gcloud compute networks subnets list --filter="region:<region>" 查；default 網路在每個 region 各有一個名為 default 的 subnet。

外部 IP 設定在 VM 網卡的 access config 上，delete-access-config 要靠名稱指定移除哪一個，而這個名稱依 VM 建立的方式不同，所以先查出來。對外提供服務的 VM 移除之前，要先把流量入口換到負載平衡器；只做管理用途的 VM 可以直接移除。先在一台 VM 上移除、確認，再做其餘的 VM：

1# 查 VM 第一張網卡的 access config 名稱
2gcloud compute instances describe <instance-name> --zone=<zone> \
3  --format="get(networkInterfaces[0].accessConfigs[0].name)"
4
5# 用查到的名稱移除外部 IP
6gcloud compute instances delete-access-config <instance-name> --zone=<zone> \
7  --access-config-name="<access-config-name>"

移除之後經由 IAP 連進這台 VM，執行 curl -s https://ifconfig.me 印出出站時對方看到的來源 IP；那個 IP 列在 gcloud compute routers get-nat-ip-info <router-name> --region=<region> 的清單裡，就代表出站走了 Cloud NAT。這次實測 --auto-allocate-nat-external-ips 配到的 IP 正好是這台 VM 剛釋放的外部 IP，移除前後 curl 印出同一個 IP，gcloud compute addresses list 的 PURPOSE 欄是 NAT_AUTO，所以判斷依據是那份清單，而不是移除前後的 IP 有沒有變。連不到網際網路時，用 gcloud compute instances add-access-config <instance-name> --zone=<zone> 把外部 IP 加回去，再回頭查 Cloud NAT 的 region 與 subnet 設定。

• 沒做時（保留外部 IP）：管理通道已經只放行 IAP，SSH 照樣安全；外部 IP 仍讓 VM 的其他 port 只靠防火牆擋，而防火牆規則一寫寬，那台 VM 就直接暴露（照規則的作用推論，這次沒有實跑）。Security Command Center 有標出帶公開 IP 的資源的 finding 類別，VM 不需要對外時移除之後少一類要處理的 finding（Security Health Analytics 文件）。
• 替代做法：
  • 反過來先移除 IP、再建 NAT，換到的是驗證不受外部 IP 干擾，付出的是移除到 NAT 建好之間 VM 連不到網際網路，apt update 這類操作會失敗（推論，這次沒有實跑）。
  • 不建 Cloud NAT、只開 Private Google Access，換到的是不經過 NAT、不產生 NAT 的閘道時數與資料處理費，付出的是 VM 只連得到 Google API，連不到外部的套件來源與第三方 API（Cloud NAT 定價與 Private Google Access 文件，這次沒有實跑）。
  • 用 --nat-external-ip-pool 改用預留的靜態 IP，換到的是外部服務可以把這個固定的 IP 列進白名單；Cloud NAT 定價頁寫明 NAT 使用的外部 IP 不論靜態或自動配發都按 IP 計費，差別在靜態 IP 從 NAT 拿下來之後仍然保留在專案裡、要另外釋放（Cloud NAT 定價與 IP 位址文件，這次沒有實跑）。

移除之後，這台 VM 只剩 IAP 一條管理路徑，連線一律加 --tunnel-through-iap；救援入口是〈準備救援入口：Serial Console 與本機救援帳號〉建好的那一條。

這篇記錄把 GCP VM 的 SSH 與 RDP 改走 IAP 的實測紀錄（下文稱 IAP 實作文章）的三項設定（IAP 用的 network tag、OS Login、移除外部 IP）套到 MIG 與 GKE 上的實際操作。內容依操作的順序是：建一份帶這三項設定的新 instance template，先讓一台 VM 換成新版（canary）再讓整組更新；用 recreate-instances 重建一台壞掉的 VM、比對重建之後換掉的主機金鑰；template 本身寫錯時退回上一版；在 GKE 上建一個專門給節點除錯用的 namespace，用 kubectl debug node 查看節點；node pool 的 private nodes、network tag 與 OS Login；控制平面的 authorized networks，以及改連 DNS-based endpoint、關掉 IP 端點的兩步切換。每一步寫出這次的取值與實測結果，以及沒做或換一種做法時的結果；替代做法與沒做時的結果沒有另外標註的是這次實測看到的，照官方文件推出的寫出文件，推論的寫明沒有實跑。逐台設定為什麼在這兩種環境裡會消失、MIG 救援的取捨、GKE 的兩個存取面、kubectl debug node 的權限邊界，以及控制平面的 authorized networks、DNS-based endpoint 與 private endpoint 三種存取方式的差別，寫在 GCP 上由 MIG 與 GKE 管理的 VM 的管理存取（下文稱概念篇），這裡不重寫。

MIG 與 GKE 由 Terraform 這類 IaC 管理時，下面的 gcloud 修改要改寫在程式碼裡，CLI 上只執行 describe 這類讀取用的指令；這篇的指令在沒有 IaC 的環境照著執行，有 IaC 的環境把它們當成欄位對照。instance template 不能修改、又被 MIG 引用著，所以 IaC 改 template 時，取代的順序要另外設成先建新的再刪舊的（Terraform 是 name_prefix 搭配 lifecycle { create_before_destroy = true }），否則先刪舊 template 的那一步會因為它還在使用中而失敗；canary 對應 google_compute_instance_group_manager 的兩個 version 區塊。這一段是推論，這次沒有用 Terraform 實跑。

建新的 instance template：現行設定照抄，再加 tag、OS Login 與不配外部 IP

instance template 建立之後不能修改，instance-templates create 從預設值開始建、不沿用舊 template 的任何設定，所以先把現行 template 讀出來，逐項帶進新的那一份。這三項設定為什麼要寫進 template、不能在 VM 上逐台改，見概念篇〈autohealing、滾動更新與擴增後消失的逐台設定：network tag、OS Login metadata 與外部 IP〉。

 1# 讀出現行 template 的完整設定，新 template 要逐項帶上
 2gcloud compute instance-templates describe <current-template-name> --format=yaml
 3
 4# 建一份新的 instance template：現行設定照抄，再加上 IAP 用的 tag、啟用 OS Login、不配外部 IP
 5gcloud compute instance-templates create <new-template-name> \
 6  --machine-type=<machine-type> \
 7  --image-family=<image-family> --image-project=<image-project> \
 8  --boot-disk-size=<boot-disk-size> \
 9  --network=<network-name> --subnet=<subnet-name> --region=<region> \
10  --service-account=<service-account-email> --scopes=<scopes> \
11  --labels=<labels> \
12  --tags=<ssh-via-iap-tag> \
13  --metadata=enable-oslogin=TRUE \
14  --metadata-from-file=startup-script=<startup-script-file> \
15  --no-address
16
17# 比對新舊兩份的設定：差異只該是刻意改的 tag、enable-oslogin 與 accessConfigs
18diff <(gcloud compute instance-templates describe <current-template-name> --format="yaml(properties)") \
19     <(gcloud compute instance-templates describe <new-template-name> --format="yaml(properties)")

• <current-template-name>：MIG 目前用的 template，gcloud compute instance-groups managed describe <mig-name> --zone=<zone> 的 instanceTemplate 欄。
• <new-template-name>：新 template 的名稱，自己取；template 不能改名也不能改內容，常見的做法是名稱帶版本或日期。
• --machine-type、--image-family、--image-project、--boot-disk-size、--network、--subnet、--region、--service-account、--scopes、--labels、--metadata-from-file=startup-script=：照 describe 讀出來的值填，describe 裡還有其他欄位（額外的磁碟、GPU、其他 metadata 鍵）也要對應的旗標一起帶上。--region 是 --subnet 所在的 region。describe 的欄位與旗標不是一對一：映像在 disks[].initializeParams.sourceImage，值可能是一個特定映像的完整路徑，也可能是 .../images/family/<family> 這種 family 的路徑（實測：用 --image-family 建的 template 讀出來是 .../images/family/debian-12），兩種都可以原樣交給 --image=<sourceImage 的值>，取代 --image-family 與 --image-project；服務帳號在 serviceAccounts[].email，template 用的是 Compute Engine 預設服務帳號時這一欄顯示 default 而不是 email（實測），原樣寫成 --service-account=default，建出的 template 用的仍是同一個預設服務帳號；startup-script 在 metadata.items 裡 key: startup-script 的 value，先把它存成檔案再交給 --metadata-from-file；regional 的 template 讀取時 describe 要加 --region=<region>。
• --tags=<ssh-via-iap-tag>：與 IAP 規則的 --target-tags 相同的 tag。新 template 只帶這裡列出的 tag，所以現行 template 已經有的其他 tag（describe 輸出的 tags.items，例如負載平衡器健康檢查用的）要一起列進來，逗號分隔。
• --metadata=enable-oslogin=TRUE：讓這個 template 建出的 VM 都啟用 OS Login；專案層級已經啟用時可以省略。
• --no-address：不配外部 IP。先確認流量入口已經在負載平衡器上，gcloud compute backend-services list --format="table(name, backends[].group)" 的 backends 欄要有這個 MIG。這一點只能事先查：服務若是靠 VM 的外部 IP 對外，〈先讓一台 VM 換成新 template（canary），再讓整組更新〉換上新版的那一台只是收不到流量、不容易察覺，canary 這一步驗不出來，整組更新之後服務就斷了。出站改由 Cloud NAT 承接，所以 Cloud NAT 要在滾動更新之前建好。已經存在的 VM 在滾動更新把它換成新版時才失去外部 IP。

這次用 --service-account=default 建的新 template，與現行 template 的 properties 比對，只差刻意改的 tag、enable-oslogin 與 accessConfigs。

• 沒做時（漏帶 describe 裡的欄位）：漏掉的欄位回到預設值，常見的後果是 VM 換成預設的服務帳號而失去存取權限，或啟動腳本沒有執行（從 create 由預設值開始建這一點推論，這次沒有實跑）；上面的 diff 會把漏掉的欄位列出來。
• 替代做法：
  • 用 gcloud compute instance-templates create <new-template-name> --source-instance=<instance-name> --source-instance-zone=<zone> 從一台現有的 VM 產生 template，換到的是不必逐項抄旗標；付出的是這條指令只能另外覆寫磁碟的定義，tag、OS Login 與 --no-address 要再以它為基礎建第二份，而來源 VM 有靜態外部 IP 時，那個位址會被抄進 template（Compute Engine〈Create instance templates〉，這次沒有實跑）。
  • 在專案層級設 enable-oslogin=TRUE、不寫進 template，換到的是 template 少一個鍵，付出的是 template 的行為依賴專案的設定，搬到別的專案就變了（推論，這次沒有實跑）。

先讓一台 VM 換成新 template（canary），再讓整組更新

1# 先讓一台 VM 用新 template（canary），其餘維持現行 template
2gcloud compute instance-groups managed rolling-action start-update <mig-name> \
3  --version=template=<current-template-name> \
4  --canary-version=template=<new-template-name>,target-size=1 \
5  --zone=<zone>
6
7# 那一台驗證通過之後，讓整組換成新 template
8gcloud compute instance-groups managed rolling-action start-update <mig-name> \
9  --version=template=<new-template-name> --zone=<zone>

• --version=template=：canary 那一行放現行的 template，代表其餘 VM 維持原狀；整組更新那一行放新的 template。兩行的 --version 放的 template 相反。
• --canary-version=template=<new-template-name>,target-size=1：讓一台 VM 換成新 template；target-size 也可以寫百分比（10%），條件是 MIG 有 10 台以上（Compute Engine〈Rolling out updates〉）。
• <mig-name>、--zone：MIG 的名稱與所在 zone，gcloud compute instance-groups managed list 查得到；regional MIG 把 --zone 換成 --region。

start-update 送出之後 MIG 在背景替換 VM，指令本身不等它完成。用下面兩條確認替換做完、並找出 canary 那一台：

1# 等到每台 VM 都換成指定的版本才返回
2gcloud compute instance-groups managed wait-until <mig-name> --version-target-reached --zone=<zone>
3
4# 列出 MIG 裡的 VM 與各自用的 template，INSTANCE_TEMPLATE 欄是新 template 的那一台就是 canary
5gcloud compute instance-groups managed list-instances <mig-name> --zone=<zone>

實測 wait-until 在替換做完之後才返回，list-instances 的 INSTANCE_TEMPLATE 欄只有一台是新 template。找到 canary 那一台之後，經由 IAP 連進去，確認 OS Login 登得進去、出站經過 Cloud NAT（驗證方式見 GCP VM 的 SSH 與 RDP 改走 IAP 的實測紀錄 的〈建 Cloud NAT 並移除外部 IP〉）。整組更新之後同樣用 wait-until 等它完成。

• 沒做時（不經過 canary、直接整組更新）：template 的 tag 或 OS Login 寫錯時，整組 VM 一起連不上（照滾動更新的作用推論，這次沒有實跑）。
• 替代做法：
  • 只改 tag 與 metadata 時加 --minimal-action=refresh：Compute Engine〈Rolling out updates〉寫明 refresh 不停止 VM，可以套用 metadata、labels、tags 這類項目，換到的是 VM 不重建、主機金鑰不變；付出的是 --no-address 移除外部 IP 不在那份清單上，很可能仍要重建（照官方文件推出，這次沒有實跑）。
  • --type=opportunistic 只在 VM 重建或擴增時才套用新 template，換到的是不主動中斷任何一台，付出的是組內新舊混雜，舊的 VM 一直沒有新的 tag（照官方文件推出，這次沒有實跑）。
  • 整組更新時加 --max-surge=1 --max-unavailable=0，每一批先多建一台新的、再刪一台舊的（實測先建後刪），換到的是更新期間可用台數不減少，付出的是多一台 VM 的費用，而且這兩個旗標只控制速度，更新仍會把整組換完。regional MIG 的 --max-surge 用固定數字時，GCP 只接受 0 或不小於 zone 數的值，錯誤訊息是 has to be either 0 or at least equal to the number of zones，所以分布在兩個以上 zone 的 regional MIG，--max-surge=1 會被拒絕。

重建一台壞掉的 VM：recreate-instances 與重建之後的主機金鑰

一台 VM 連不上、而原因是那台 VM 自己壞了（sshd 設定改壞、磁碟滿），讓 MIG 依 template 重建它：

1# 依 template 重建一台 VM：開機磁碟換成依 MIG 目前的版本設定新建的一顆，VM 重新開機
2gcloud compute instance-groups managed recreate-instances <mig-name> \
3  --instances=<instance-name> --zone=<zone>

<instance-name> 是要重建的那台 VM，gcloud compute instance-groups managed list-instances <mig-name> --zone=<zone> 列出 MIG 裡的 VM。實測重建在稽核紀錄裡是一次 instances.update（沒有 delete 與第二次 insert），VM 沿用原本的名稱與執行個體 ID，gcloud compute instances describe 的建立時間也不變，所以確認重建做完要看開機磁碟：MIG 建的 VM 開機磁碟預設與 VM 同名，gcloud compute disks describe <instance-name> --zone=<zone> --format="value(creationTimestamp)" 印出的時間落在重建的那一刻，就代表磁碟已經換新。canary 期間重建的 VM 用哪一版，由 MIG 依兩個版本各自的 target-size 分配，實測重建的那一台沿用了原版本。

重建之後第一次 gcloud compute ssh 出現 WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! 並拒絕連線（實測），原因與這個警告為什麼不能直接略過，見 GCP 上由 MIG 與 GKE 管理的 VM 的管理存取 的〈MIG 的救援：重建、退回舊版 template 與 Serial Console 各自適用的情形〉。比對的來源是 VM 回報到 guest attributes 的主機金鑰，專案或 template 的 metadata 要事先設了 enable-guest-attributes=TRUE（專案層用 gcloud compute project-info add-metadata --metadata enable-guest-attributes=TRUE）：

1# 讀出 VM 回報的 ED25519 主機金鑰指紋，與警告訊息裡 "The fingerprint for the ED25519 key sent by the remote host is" 下一行的 SHA256 值比對
2gcloud compute instances get-guest-attributes <instance-name> --zone=<zone> \
3  --query-path=hostkeys/ssh-ed25519 --format="value(value)" \
4  | awk '{print "ssh-ed25519 " $1}' | ssh-keygen -lf -
5
6# 兩個指紋相同之後，移除這台 VM 的舊紀錄，再用 gcloud compute ssh 連線
7ssh-keygen -R compute.<instance-id> -f ~/.ssh/google_compute_known_hosts

<instance-id> 是 gcloud compute instances describe <instance-name> --zone=<zone> --format="value(id)" 印出的數字。ssh-keygen -R 會把原本的檔案備份成同目錄的 google_compute_known_hosts.old。實測啟用 guest attributes 之後，gcloud 不會自動更新已經存在的 known_hosts 紀錄，讀出的 ED25519 指紋與警告裡的一致，移除舊紀錄之後即可連線。兩個指紋不同時不要移除，先確認連到的 IP 仍是這台 VM 的位址，以及連線是否經過了 IAP 以外的代理；兩項都正常而指紋仍不同時，改從 Serial Console 登入 VM、讀 /etc/ssh/ssh_host_ed25519_key.pub 的指紋再比一次。警告寫的是 ECDSA 時，指令裡的 ED25519 與 ssh-ed25519 分別換成 ECDSA 與 ecdsa-sha2-nistp256。

• 沒做時（不設 enable-guest-attributes）：重建之後沒有不經過這條 SSH 連線的地方可以比對主機金鑰，只剩從 Serial Console 登入讀指紋，或不比對就移除舊紀錄；不比對就移除，等於關掉主機金鑰檢查（推論，這次沒有實跑）。
• 替代做法：
  • 從 Serial Console 登入修那台 VM，換到的是保留現場，付出的是要事先在映像檔裡放救援帳號（救援帳號的密碼雜湊寫在映像檔裡，不寫進 template 的 startup-script，理由與共用密碼雜湊的代價見概念篇〈MIG 的救援：重建、退回舊版 template 與 Serial Console 各自適用的情形〉）；登入與 sudo 的做法見 IAP 實作文章的〈準備救援入口：Serial Console 與本機救援帳號〉。
  • VM 上有不能丟的狀態時，MIG 的 stateful 設定（stateful policy 或 per-instance config）把指定的磁碟、IP 與 metadata 標為要保留，recreate-instances 重建時會沿用它們（Compute Engine〈Stateful MIGs〉，這次沒有實跑）。

template 本身寫錯時退回上一版

重建修不好的是 template 本身的錯：新版 template 的 tag 寫錯、啟動腳本有錯，重建出來的每一台都一樣壞。這種錯要退回上一版 template，所以舊版 template 留到新版驗證完之後再刪：

1# 退回上一版 template：整組換回舊版；canary 期間執行時，只有 canary 那幾台被換回
2gcloud compute instance-groups managed rolling-action start-update <mig-name> \
3  --version=template=<previous-template-name> --zone=<zone>

<previous-template-name> 是新版之前那一份 template 的名稱，gcloud compute instance-templates list 列得出來。這次實測退回成功。Compute Engine〈Rolling out updates〉寫明沒有專門的退回指令，退回就是送一次指向舊 template 的更新。

• 沒做時（新版一驗證就刪掉舊 template）：退回時要用 describe 讀過的舊設定重建一份 template，而舊 template 已經刪掉、讀不到了（從 template 不能修改、刪了就沒有這兩點推論，這次沒有實跑）。

GKE 節點除錯：建專用的 namespace，用 kubectl debug node 查看節點

節點除錯集中在一個刻意保留為 privileged 等級、只有維運群組能建 Pod 的 namespace，由叢集管理員事先建好：

1# 建一個專門給節點除錯用的 namespace，並允許特權 Pod
2kubectl create namespace <namespace>
3kubectl label namespace <namespace> pod-security.kubernetes.io/enforce=privileged

<namespace> 自己取，例如 node-debug；建好之後只把 GCP 上由 MIG 與 GKE 管理的 VM 的管理存取 的〈kubectl debug node 的權限邊界：RBAC 與 Pod Security Admission〉列的那組 pods 與 pods/attach 權限綁給維運群組。接著在這個 namespace 裡對節點開除錯 Pod：

1# 在指定節點上開一個除錯用的 Pod，節點的根目錄掛在 /host
2kubectl debug node/<node-name> -it --image=ubuntu --profile=sysadmin --namespace=<namespace>
3
4# 進到 Pod 之後，切換到節點的根目錄，像登入節點一樣查看
5chroot /host

• <node-name>：節點名稱，kubectl get nodes 的第一欄。
• --image=ubuntu：除錯 Pod 用的映像檔，換成組織允許、帶著除錯工具的映像檔。
• --profile=sysadmin：讓除錯 Pod 以特權容器（privileged container）執行，多給的是需要額外 Linux capability 的操作，例如用 nsenter 進入節點 PID 1 的 namespace、掛載檔案系統；只查看檔案與 log 時，預設的 general profile 就夠了（kubectl debug --help 的 --profile 說明寫著預設值）。
• --namespace=<namespace>：除錯 Pod 建在上面建好的那個 namespace；不給時落在 kubeconfig 目前設定的 namespace（通常是 default）。

這個 Pod 用完不會自動刪除，結束後用 kubectl delete pod <debug-pod-name> --namespace=<namespace> 刪掉（kubectl get pods --namespace=<namespace> 找名稱以 node-debugger- 開頭的那一個）。實測 GKE 上未設 label 的 default 接受除錯 Pod、設了 baseline 的 namespace 拒絕；kind 上 privileged 的 namespace 接受。

• 沒做時（不建專用 namespace）：沒有設 Pod Security label 的 namespace（包括 default）在 GKE Standard 上接受特權 Pod，任何能在 default 建 Pod 的帳號都能用這個方法以 root 操作節點。少了 list 或 watch 權限時，Pod 已經建好而 kubectl 停在等待、反覆印出 cannot list resource "pods"；少了 pods/attach 時 Pod 建得出來卻進不去；兩種都會留下一個在跑的除錯 Pod，要用 kubectl delete pod 刪掉（kind 上實跑）。
• 替代做法：
  • 用 --profile=baseline 或 restricted，換到的是建得進 baseline 以上的 namespace，付出的是看不到節點的檔案。
  • 查節點層的狀況先看 Cloud Logging 裡的節點紀錄，換到的是不必在節點上開任何 Pod，付出的是只看得到已經送進 Logging 的紀錄（推論，這次沒有實跑）。GKE Autopilot 預設拒絕特權 Pod，也不提供節點 SSH，只剩這一條（GKE〈Autopilot overview〉，這次沒有實跑）。

node pool：private nodes、network tag 與 OS Login

節點仍要 SSH 時（GKE Standard），把 GCP VM 的 SSH 與 RDP 改走 IAP 的實測紀錄 的三項設定搬到 node pool 上：

1# 既有 node pool 改成節點只有內部 IP（GKE 依升級策略逐批重建節點）
2gcloud container node-pools update <pool-name> --cluster=<cluster-name> --location=<location> --enable-private-nodes
3
4# 讀出現有的 tag，再用整份清單設定（這個指令整組取代使用者設定的 tag）
5gcloud container node-pools describe <pool-name> --cluster=<cluster-name> --location=<location> --format="value(config.tags)"
6gcloud container node-pools update <pool-name> --cluster=<cluster-name> --location=<location> --tags=<tag1>,<tag2>

• <pool-name>、<cluster-name>：gcloud container node-pools list --cluster=<cluster-name> --location=<location> 與 gcloud container clusters list 查得到。<location> 是叢集所在的 zone 或 region。
• --enable-private-nodes：先確認節點所在 subnet 的 region 已經有 Cloud NAT，換成內部 IP 之後節點的出站都經過它；沒有它時節點拉不到外部 registry 的映像，工作負載起不來。GKE 依 node pool 的升級策略逐批重建節點，所以排在可以承受節點輪替的時段做。新叢集在 gcloud container clusters create 加 --enable-private-nodes 作為整個叢集的預設。實測既有 node pool 的這項變更重建了節點，出站走 Cloud NAT、tag 保留。
• --tags=<tag1>,<tag2>：實測整組取代（gcloud 的確認提示也這樣寫），GKE 自動建立的防火牆規則用的 tag 保留，節點沒有重建。

OS Login 的授權方式同單台 VM，見 GCP VM 的 SSH 與 RDP 改走 IAP 的實測紀錄 的〈啟用 OS Login：先授角色、單台先行、再做專案層級〉。專案層級的 enable-oslogin=TRUE 是否套用到 GKE Standard 的節點，GKE 自己的兩份文件寫法相反，所以啟用之後經由 IAP 實際登入一個節點確認：登入後執行 whoami，看到的是由 Google 帳號 email 轉換而來的 OS Login 帳號，才表示這個 node pool 的節點套用了 OS Login；看到的是 metadata 金鑰對應的本機帳號，代表節點沒有套用，SSH 仍由 metadata 金鑰控制。這次在 1.36.4-gke 的節點上看到的是 OS Login 帳號，這是單一版本的觀察。

• 沒做時（只在單一節點上 add-tags）：節點升級或自動修復重建之後 tag 消失，IAP 規則套不到它（照概念篇〈autohealing、滾動更新與擴增後消失的逐台設定：network tag、OS Login metadata 與外部 IP〉的機制推論，這次沒有實跑）。
• 替代做法：不開節點 SSH、只用 kubectl debug node，換到的是不必維護節點的 tag、OS Login 與 IAP 規則，付出的是能建除錯 Pod 的帳號就等於節點的 root，權限邊界移到 RBAC 與 Pod Security Admission。

控制平面：authorized networks，或改連 DNS-based endpoint 再關掉 IP 端點

 1# authorized networks：只放行列出的來源 IP 範圍連到控制平面的 IP 端點
 2gcloud container clusters update <cluster-name> --location=<location> \
 3  --enable-master-authorized-networks --master-authorized-networks=<cidr1>,<cidr2>
 4
 5# DNS-based endpoint 的啟用：IP 端點仍然開著
 6gcloud container clusters update <cluster-name> --location=<location> \
 7  --enable-dns-access
 8
 9# 關掉 IP 端點：每個人與每條 CI 都改連網域名稱端點之後才執行
10gcloud container clusters update <cluster-name> --location=<location> \
11  --no-enable-ip-access

• <cidr1>,<cidr2>：允許的來源 IP 範圍，CIDR 格式，單一個 IP 寫成 /32。實測以 Private Service Connect 建立的叢集拒絕文件範例用的保留網段 203.0.113.0/24，錯誤訊息寫明只接受在網際網路上可路由的範圍。--master-authorized-networks 每次都整組取代舊清單，執行這條指令的人與 CI 的出口 IP 要列在裡面：實測漏列時指令一生效 kubectl 就逾時，gcloud 不經過這個端點，用同一條指令改回清單就恢復。
• --enable-dns-access 與 --no-enable-ip-access 分成兩次執行：寫在同一條指令裡會在啟用的同時關掉 IP 端點，還在用 IP 端點的人與 CI 當場連不上。--no-enable-ip-access 關掉的是公開與內部兩個 IP 端點，VPC 內用內部 IP 連 API server 的跳板機、自架 runner 與 Terraform 也在要改的範圍內。

改連 DNS-based endpoint 時，每個人在本機執行 gcloud container clusters get-credentials <cluster-name> --location=<location> --dns-endpoint，讓 kubeconfig 指向那個網域名稱。確認有沒有改連：每個人與每條 CI 用的 kubeconfig，kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}' 輸出的是網域名稱而不是 IP。DNS-based endpoint 預設只接受 Google 的 IAM 憑證，CI 或工具若用 kubeconfig 裡靜態的 Kubernetes ServiceAccount token 或 client certificate，要另外在 clusters update 加 --enable-k8s-tokens-via-dns 或 --enable-k8s-certs-via-dns。

實測：DNS endpoint 的兩步切換不受 IP 清單限制；--no-enable-ip-access 之後 IP 端點逾時（對照組：開啟且來源在清單內時 HTTP 401），DNS 照常；clusters update --enable-ip-access 恢復。用第二個帳號以 --token 帶入它的 access token：沒有 IAM 角色時 DNS endpoint 回 Google 前端的 403 HTML；只有 roles/container.clusterViewer 時進到 API server，列節點回 cannot list resource "nodes"，訊息裡寫著它要的 IAM 權限 container.nodes.list。

• 沒做時（維持公開端點、不設任何限制）：任何地方都連得到 API server，只靠 Kubernetes 的認證與 RBAC 擋下沒有權限的請求，等於網路可達性全開（照 GKE〈Access the control plane〉推出，這次沒有在公開端點上量）。
• 替代做法：
  • authorized networks 換到的是設定一條指令，付出的是 IP 會變動時要一直改、分辨不出個人；設了之後，GCP 上其他客戶的外部 IP 是否放行由 --enable-google-cloud-access／--no-enable-google-cloud-access 決定。實測沒碰過這兩個旗標時，describe 沒有 gcpPublicCidrsAccessEnabled 欄位，這時實際是否放行沒有驗證；變更可能要幾個小時才生效（GKE 文件，這次沒有實跑）。
  • private endpoint（--enable-private-endpoint）換到的是控制平面只剩內部 IP，付出的是從 VPC 外管理時要經過 VPN 或跳板機（GKE 文件，這次沒有實跑）。三種端點的比較見概念篇〈GKE 控制平面的存取：authorized networks、DNS-based endpoint 與 private endpoint〉。

這篇記錄在 GCP 上建預算警示與停損開關（由預算通知觸發、把專案從帳單帳戶解除連結的函式）的實際操作。內容依操作的順序是：建立限定一個專案的預算；建接收通知的 Pub/Sub 主題並把預算接上；建服務帳號並授予解除帳單連結與讀取帳單狀態的角色；函式的程式；部署函式並指定兩個服務帳號、執行個體上限與重試；授予觸發器呼叫函式的權限；停損開關放在另一個專案時要改的指令；用第一則真實通知與兩則測試訊息做兩段驗收；設心跳監看；超支停用之後的恢復。每一步寫出這次的取值與實測結果，以及漏掉或換一種做法時的結果；替代做法與沒做時的結果沒有另外標註的是這次實測看到的，照官方文件推出的寫出文件，推論的寫明沒有實跑。費用失控的來源與帳單資料的延遲、預算警示與強制執行支出上限的作用範圍、兩種處置（解除帳單連結、只停止花錢的資源）該選哪一種、停損開關為什麼要放在另一個專案、驗收為什麼分兩段，寫在 GCP 上的雲端費用失控防護（下文稱概念篇），這裡不重寫。

停損開關的效果是一次自己造成的全面停機。建之前先照 GCP 上的雲端費用失控防護 的〈由預算通知觸發的處置：解除帳單連結與只停止花錢的資源〉判斷這個專案該不該建、建哪一種。下文以停損開關為例；只停止花錢的資源那一種的取捨與實測結果（跨全部 zone 停 VM、約兩分鐘 TERMINATED）寫在那一節，它的函式本體這篇沒有收。

停損開關部署了卻沒有動作時，成因依呼叫鏈的段落分在這幾節：通知裡的 costAmount 沒有越過預算（抵免、帳單資料延遲、--filter-projects 的範圍）見〈建立限定一個專案的預算〉；通知沒有送到主題或主題接錯預算，見〈建接收通知的主題並把預算接上〉；函式收到了卻沒有解除連結，見〈建服務帳號並授予兩個角色〉〈部署函式：兩個服務帳號、執行個體上限與重試〉〈授予觸發器呼叫函式的權限〉；要確認是哪一段，照〈兩段驗收：第一則真實通知，再發兩則測試訊息〉。

下面的指令用到三個本文取的名稱：主題 budget-alerts、服務帳號 budget-killswitch-sa、函式 budget-killswitch。換成別的名稱時，同一個名稱出現的每一條指令都要一起換。<project-id> 指的是放停損開關、同時也是要被停用帳單的那個專案；兩者分開的情形見〈停損開關放在另一個專案時要改的指令〉。

建立限定一個專案的預算

建立預算的人要通過兩道權限檢查：實測沒有任何角色的帳號先被 --billing-project 那個專案擋下（缺 serviceusage.services.use，訊息寫 USER_PROJECT_DENIED）；補上 roles/serviceusage.serviceUsageConsumer 約一分鐘後，才換成帳單帳戶的權限不足。所以建立預算的人要有那個專案的 serviceusage.services.use，以及帳單帳戶上能管理預算的角色（帳單帳戶管理員或帳單帳戶費用管理員）。

 1# 查帳單帳戶的 ID 與幣別：預算金額用的是這個幣別
 2gcloud billing accounts list
 3gcloud billing accounts describe <billing-account-id> --format="value(currencyCode)"
 4
 5# gcloud 透過 --billing-project 指定的專案呼叫預算 API，那個專案要先啟用這個 API
 6gcloud services enable billingbudgets.googleapis.com --project=<project-id>
 7
 8# 建立預算：金額寫成「數字加幣別代碼」，幣別要與帳單帳戶相同
 9gcloud billing budgets create --billing-account=<billing-account-id> \
10  --display-name=<budget-display-name> --budget-amount=<amount><currency-code> \
11  --filter-projects=projects/<project-id> \
12  --threshold-rule=percent=0.5 --threshold-rule=percent=0.9 --threshold-rule=percent=1.0 \
13  --threshold-rule=percent=1.0,basis=forecasted-spend \
14  --billing-project=<project-id>

• <billing-account-id>：gcloud billing accounts list 的第一欄，是三段各六個英數字、以 - 分隔的字串，例如 000000-AAAAAA-111111（這是佔位值）。
• <budget-display-name>：自己取的名稱，只用來在主控台與通知裡辨識這個預算。
• <amount><currency-code>：例如帳單帳戶的幣別是新台幣時寫成 320TWD。主控台建立預算的表單只顯示一個 $，不顯示幣別；幣別是新台幣的帳戶在那裡填 10，門檻是新台幣 10 元而不是 10 美元。
• --filter-projects：預算只計算這些專案的花費。gcloud billing budgets describe 的 budgetFilter.projects 存的是專案編號，不是專案 ID。
• 門檻比例：50% 與 90% 留給收到通知的人處理的時間，100% 對齊花費達到預算的那一刻，預測花費的門檻提早反映速度異常；比例依處理一次所需的時間自己調整。
• --billing-project：gcloud 呼叫預算 API 所用的專案，不影響預算的範圍。

接停損開關的預算要另外建，不接到既有的帳戶層級警示預算上；它的金額設成這個專案本期能承受的最高花費，減掉帳單資料延遲期間多出的費用，估法見概念篇〈由預算通知觸發的處置：解除帳單連結與只停止花錢的資源〉。

• 沒做時（不給 --filter-projects）：gcloud billing budgets create --help 寫著預算涵蓋所有專案，通知裡的 costAmount 是帳單帳戶下所有專案的合計；接上停損開關時，別的專案超支會停掉這一個（從程式的判斷規則推論，這次沒有實跑）。
• 替代做法：
  • 加 --credit-types-treatment=exclude-all-credits，換到的是以抵免前的金額計算、大額抵免期間門檻照樣觸發，實測同一段期間扣掉抵免的帳戶層級預算報 costAmount 0.05、exclude-all-credits 的預算報 0.37；付出的是免費方案的用量也以原價算進花費（推論：FREE_TIER 是預算接受的抵免類型，這次沒有量）。
  • 改用 --credit-types-treatment=include-specified-credits 搭配 --filter-credit-types=FREE_TIER，換到的是只讓免費方案的用量照常扣掉；類型寫錯時回 INVALID_ARGUMENT: ... is not a valid credit type string，--help 不列出可用的類型，以 Cloud Billing 文件為準。
  • 加 --notifications-rule-monitoring-notification-channels=<channel-resource-name>，把通知另外寄到 Cloud Monitoring 的電子郵件通知管道，換到的是值班的人收得到，付出的是只支援電子郵件類型：接上 webhook 類型的管道時只回 INVALID_ARGUMENT: Request contains an invalid argument，訊息不說原因。<channel-resource-name> 形如 projects/<project-id>/notificationChannels/<channel-id>，在主控台的 Monitoring 通知管道頁面查得到。

建接收通知的主題並把預算接上

1gcloud services enable pubsub.googleapis.com cloudfunctions.googleapis.com run.googleapis.com \
2  cloudbuild.googleapis.com artifactregistry.googleapis.com eventarc.googleapis.com \
3  cloudbilling.googleapis.com --project=<project-id>
4
5# 建立主題，並讓接停損開關的預算把通知送過來
6gcloud pubsub topics create budget-alerts --project=<project-id>
7gcloud billing budgets update <budget-resource-name> \
8  --notifications-rule-pubsub-topic=projects/<project-id>/topics/budget-alerts \
9  --billing-project=<project-id>

<budget-resource-name> 是 gcloud billing budgets list --billing-account=<billing-account-id> --billing-project=<project-id> --format="value(name)" 印出的完整名稱，形如 billingAccounts/<id>/budgets/<uuid>，與建立時給的顯示名稱是兩個值。設定通知目標時，GCP 會自動讓預算服務的系統帳號 billing-budget-alert@system.gserviceaccount.com 擁有這個主題的發布權限，gcloud pubsub topics get-iam-policy budget-alerts --project=<project-id> 看得到這條綁定。

預算接上主題之後，GCP 一天會送好幾次通知過來，不論花費有沒有越過門檻。第一則送到的時間兩次實跑不同：第一次實跑約 8 分鐘，第二次新建的預算約 35 分鐘；Cloud Billing 文件說第一則可能要數小時。通知的內容如下，alertThresholdExceeded 這類欄位要等越過門檻才會出現：

1{"budgetDisplayName": "<budget-display-name>", "costAmount": 0.0, "costIntervalStart": "2026-10-01T07:00:00Z",
2 "budgetAmount": 320.0, "budgetAmountType": "SPECIFIED_AMOUNT", "currencyCode": "TWD"}

主題原本接在別的預算上時，只有一種做法拿得掉：gcloud billing budgets update 沒有清除 Pub/Sub 通知的旗標，要對預算 API 送 PATCH，updateMask 設成 notificationsRule.pubsubTopic、notificationsRule.pubsubTopic 設成空字串。這次用這個方式拿掉了；送出的完整指令沒有留下來，請求的形狀以 Cloud Billing Budget API 的 budgets.patch 文件為準。

• 沒做時（一個主題接了好幾個預算）：本文的函式不分辨通知來自哪一個預算，任何一個超支都會讓它停掉 TARGET_PROJECT_ID（從程式的判斷規則推論，這次沒有實跑）。要依預期花費收通知，另建一個不接主題的預算。

建服務帳號並授予兩個角色

 1gcloud iam service-accounts create budget-killswitch-sa --project=<project-id>
 2
 3# 解除專案的帳單連結
 4gcloud projects add-iam-policy-binding <project-id> \
 5  --member=serviceAccount:budget-killswitch-sa@<project-id>.iam.gserviceaccount.com \
 6  --role=roles/billing.projectManager
 7
 8# 讀取專案的帳單狀態（getBillingInfo 需要 resourcemanager.projects.get）
 9gcloud projects add-iam-policy-binding <project-id> \
10  --member=serviceAccount:budget-killswitch-sa@<project-id>.iam.gserviceaccount.com \
11  --role=roles/browser

roles/billing.projectManager 只包含兩個權限，建立與刪除專案的帳單連結（gcloud iam roles describe roles/billing.projectManager 列得出來），讀取帳單狀態不在裡面。roles/browser 包含 resourcemanager.projects.get，整個角色是讀取專案、資料夾與組織的中繼資料以及專案 IAM policy 的六個權限，不包含讀取專案內資源的權限。執行部署指令的人另外要有這個服務帳號的 roles/iam.serviceAccountUser，才能把它指定給函式與觸發器；專案擁有者本來就有。要管多個專案時，每個專案各建一個限定在該專案的預算、一個主題與一個函式部署，兩個角色在每個專案各綁一次。

• 沒做時（只給 roles/billing.projectManager）：函式在解除連結之前先讀一次帳單狀態，那一步回 403「The caller does not have permission」；函式部署成功、狀態 ACTIVE，停損開關卻不會解除帳單連結。
• 替代做法：拿掉函式裡讀帳單狀態的那一步、只留解除連結，換到的是少一個角色，付出的是重複的通知會對已經停用的專案再送一次解除連結（推論，這次沒有實跑）。

判斷並解除帳單連結的函式

下面的程式存成 <source-dir>/main.py，判斷規則只看實際花費：

 1import base64
 2import json
 3import os
 4
 5import functions_framework
 6from googleapiclient import discovery
 7
 8PROJECT_ID = os.environ["TARGET_PROJECT_ID"]
 9PROJECT_NAME = f"projects/{PROJECT_ID}"
10
11def should_disable(notification: dict) -> bool:
12    # 只看實際花費：改看預測花費時，一次短暫的尖峰就可能讓函式停掉正常的服務
13    try:
14        cost = float(notification["costAmount"])
15        budget = float(notification["budgetAmount"])
16    except (KeyError, TypeError, ValueError):
17        print(json.dumps({"warning": "unreadable notification, ignored"}))
18        return False
19    return budget > 0 and cost >= budget
20
21def billing_enabled(billing) -> bool:
22    info = billing.projects().getBillingInfo(name=PROJECT_NAME).execute()
23    return info.get("billingEnabled", False)
24
25@functions_framework.cloud_event
26def stop_billing(cloud_event):
27    # 讀不懂的通知不構成停機的理由；直接結束，不拋出例外，免得 --retry 讓它一直重送
28    try:
29        notification = json.loads(base64.b64decode(cloud_event.data["message"]["data"]))
30    except (KeyError, TypeError, ValueError):
31        print(json.dumps({"warning": "undecodable message, ignored"}))
32        return
33    print(json.dumps({"received": notification}))
34
35    if not should_disable(notification):
36        print(json.dumps({"action": "none"}))
37        return
38
39    # 呼叫 Cloud Billing API 的錯誤不攔，讓 --retry 重送這則通知
40    billing = discovery.build("cloudbilling", "v1", cache_discovery=False)
41    if not billing_enabled(billing):
42        print(json.dumps({"action": "none", "reason": "billing already disabled"}))
43        return
44
45    # billingAccountName 給空字串，就是把專案從帳單帳戶解除連結
46    billing.projects().updateBillingInfo(
47        name=PROJECT_NAME, body={"billingAccountName": ""}
48    ).execute()
49    print(json.dumps({"action": "billing disabled", "project": PROJECT_ID}))

同一個目錄放一份 requirements.txt，列出 functions-framework 與 google-api-python-client。實測對主題發一則不是 JSON 的訊息，函式留下一筆 undecodable message, ignored 的警告、請求回 200，之後沒有重送。

• 沒做時（讀不懂的訊息拋出例外）：加了 --retry 之後，那則訊息會被一直重送（從重試政策的作用推論，這次沒有實跑）。
• 替代做法（判斷規則）：改看 forecastThresholdExceeded，換到的是更早解除連結、被濫用時損失更少，付出的是一次正常的流量尖峰也可能讓整個專案停擺；改成「讀不懂就解除連結」，換到的是格式異常時偏向保護費用，付出的是通知格式變動時就會誤停（兩者都是推論，這次沒有實跑）。現在的寫法在誤停與漏停兩種錯誤裡最不會誤停，代價是被濫用時要等到實際花費寫進帳單資料才動作。

部署函式：兩個服務帳號、執行個體上限與重試

1gcloud functions deploy budget-killswitch --gen2 --region=<region> --runtime=python312 \
2  --source=<source-dir> --entry-point=stop_billing --trigger-topic=budget-alerts \
3  --service-account=budget-killswitch-sa@<project-id>.iam.gserviceaccount.com \
4  --trigger-service-account=budget-killswitch-sa@<project-id>.iam.gserviceaccount.com \
5  --set-env-vars=TARGET_PROJECT_ID=<project-id> --max-instances=1 --retry \
6  --project=<project-id>

• <region>：函式所在的 region，例如 asia-east1；它與預算或要停用帳單的專案在哪個區域無關。

• --runtime：Python 的版本，可用的值由 gcloud functions runtimes list --region=<region> 列出；舊版本停止支援之後部署會被拒絕。

• <source-dir>：放 main.py 與 requirements.txt 的本機目錄。

• --entry-point：程式裡加了 @functions_framework.cloud_event 的那個函式的名稱。

• --service-account：函式執行時的身分，函式以它呼叫 Cloud Billing API。

• --trigger-service-account：Eventarc 觸發器呼叫函式時的身分。不給這個旗標時用哪個帳號，gcloud functions deploy --help 寫的是專案的 Compute Engine 預設服務帳號，而這次實測用的是 --service-account 那一個，兩者不同，所以明確指定，部署後用 gcloud functions describe budget-killswitch --region=<region> --project=<project-id> 輸出的 eventTrigger.serviceAccountEmail 確認。

• TARGET_PROJECT_ID：要停用帳單的專案。

• --max-instances=1：同一時間最多只啟動一個執行個體，超支之後一天好幾則通知依序處理，不會同時送出多個解除連結的呼叫。

• --retry：讓 Pub/Sub 依觸發器的重試政策在幾分鐘內重送失敗的通知，一次暫時性的錯誤（剛授予的權限還沒生效）不必等到下一則通知。不會自己恢復的錯誤（權限少了一個、專案的帳單連結被鎖定）重試也不會成功，那一類只能靠〈兩段驗收：第一則真實通知，再發兩則測試訊息〉在上線前找出來。

• 沒做時（不加 --retry）：觸發器的重試政策是 RETRY_POLICY_DO_NOT_RETRY（gcloud functions describe 輸出的 eventTrigger.retryPolicy）。函式在讀取帳單狀態時拋出例外，Cloud Run 的請求紀錄卻是 HTTP 200，Pub/Sub 因此把那則超出預算的通知標為已確認收訊（ack），之後不再送；下一次有機會解除連結，要等數小時後的下一則預算通知，這段期間帳單照常計費。

• 沒做時（不加 --max-instances=1）：超支之後同時到的幾則通知可能各自啟動一個執行個體、各送一次解除連結（推論，這次沒有實跑）。

授予觸發器呼叫函式的權限

第二代的 Cloud Run functions 跑在 Cloud Run 上，Eventarc 觸發器以 --trigger-service-account 指定的服務帳號身分呼叫它，而那個服務帳號預設沒有呼叫權限：

1# 第一個 budget-killswitch 是函式名稱：第二代函式在 Cloud Run 上的服務與函式同名
2gcloud run services add-iam-policy-binding budget-killswitch --region=<region> \
3  --member=serviceAccount:budget-killswitch-sa@<project-id>.iam.gserviceaccount.com \
4  --role=roles/run.invoker --project=<project-id>

• 沒做時：Cloud Run 以 403 擋下每一次推送，紀錄寫著「The IAM principal lacks {run.routes.invoke} permission」，函式一次都不會執行，而 gcloud functions describe 顯示的狀態仍是 ACTIVE。
• 替代做法：觸發器改用另一個只有 roles/run.invoker 的服務帳號，換到的是呼叫權限與解除帳單連結的權限分在兩個身分上，付出的是多管一個服務帳號（推論，這次沒有實跑）。

停損開關放在另一個專案時要改的指令

主題、函式與服務帳號放在一個專門放帳單工具的管理專案、要停用帳單的是另一個專案時，上面的指令照下面改，其餘不變：

• 主題、服務帳號、函式、觸發器的呼叫權限：--project=<project-id> 與服務帳號位址裡的 <project-id> 都填管理專案。
• 服務帳號的兩個角色：gcloud projects add-iam-policy-binding 的第一個引數改成被保護的專案，--member 仍是管理專案裡的服務帳號。
• 部署：--set-env-vars=TARGET_PROJECT_ID= 填被保護的專案。
• 預算：--filter-projects=projects/ 填被保護的專案。

第二次實跑把函式放在 blog-verify-20261024、TARGET_PROJECT_ID 指向另一個可拋棄的專案：超出預算的訊息讓被保護的專案在 9 秒後停用，管理專案的帳單維持啟用，緊接著的低於預算訊息照常處理。這樣放的效果與代價見概念篇〈停損開關放在另一個專案〉。

• 沒做時（停損開關跑在被保護的同一個專案）：解除連結之後，查詢函式狀態的 API 直接回 403，訊息要求確認帳單帳戶；函式本身在停用後約一分鐘內仍處理了下一則通知，之後的行為這次沒有觀察。兩段驗收的兩則測試訊息要照順序發。

兩段驗收：第一則真實通知，再發兩則測試訊息

驗收分成預算到 Pub/Sub 主題、主題之後兩段，各用不同的訊息確認，理由見概念篇〈驗收：真實通知確認預算到 Pub/Sub 主題的一段，測試訊息確認主題之後的一段〉。

Pub/Sub 主題之前的那一段，用第一則真實的預算通知確認。 接上主題之後等第一則通知，用下面這條查詢找到一筆 received 紀錄，確認 budgetDisplayName 是接停損開關的那個預算，再拿它的 costAmount 對照帳單報表上這個專案本期的費用：通知的值接近 0 而報表不是，就是抵免設定或 --filter-projects 設錯了。

1# 列出函式收到的通知；--freshness 依等待的時間調整
2gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="budget-killswitch" AND jsonPayload.received:*' \
3  --freshness=1d --format="json(timestamp,jsonPayload.received)" --project=<project-id>

Pub/Sub 主題之後的那一段，用兩則測試訊息確認。 低於預算的那一則確認訊息送得到、判斷邏輯會跑；停損開關跑在被保護的同一個專案時，它要排在超出預算那一則之前。

1gcloud pubsub topics publish budget-alerts --project=<project-id> \
2  --message='{"costAmount": 15.0, "budgetAmount": 320.0, "currencyCode": "TWD"}'
3
4# 等一兩分鐘再查：紀錄寫入有延遲；預期 action 是 none；--freshness=10m 只看最近十分鐘
5gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="budget-killswitch" AND jsonPayload.action:*' \
6  --freshness=10m --format="value(timestamp,jsonPayload.action)" --project=<project-id>

這條查詢回傳零筆時，有三種可能：紀錄還沒寫入、觸發器被 403 擋下、查詢條件寫錯。把條件裡的 AND jsonPayload.action:* 換成 AND logName:"run.googleapis.com%2Frequests"、--format 換成 "value(timestamp,httpRequest.status)"，查同一個服務的請求紀錄：有 403 的請求代表缺〈授予觸發器呼叫函式的權限〉那條綁定，查不到任何請求代表訊息沒有送到觸發器。

低於預算的訊息在判斷規則那一步就結束，讀取帳單狀態與解除帳單連結的權限一次都沒有行使。超出預算的那一則才會走到它們，結果看帳單狀態：

1gcloud pubsub topics publish budget-alerts --project=<project-id> \
2  --message='{"costAmount": 350.0, "budgetAmount": 320.0, "currencyCode": "TWD"}'
3
4# 等一兩分鐘再查；預期 billingEnabled 變成 false、billingAccountName 變成空字串
5gcloud billing projects describe <project-id>

測試訊息裡的 budgetAmount 大於 0、而且小於或等於 costAmount 時，函式就會解除帳單連結，與預算實際設定的金額無關。實測從發出超出預算的訊息到 billingEnabled 變成 false 約十三秒。驗收完用 gcloud billing projects link <project-id> --billing-account=<billing-account-id> 重新連結，連結完成才算驗收結束。這次驗收會實際讓專案停擺，排在停機可以接受的時段做；之後每一次修改函式、角色或觸發器，都再做一次。

• 沒做時（只看部署成功與 ACTIVE）：〈建服務帳號並授予兩個角色〉的 roles/browser、〈部署函式：兩個服務帳號、執行個體上限與重試〉的 --retry、〈授予觸發器呼叫函式的權限〉的 roles/run.invoker，實測時各自讓停損開關在狀態顯示正常時失效過一次。

• 替代做法（專案有停用之後不能遺失的資料時）：拆開驗證，第二次實跑做過。

  • 在可拋棄的專案上完整觸發一次：另外部署一份複本，函式名稱與主題都換掉（例如 budget-killswitch-test 與 budget-alerts-test），TARGET_PROJECT_ID 指向一個可拋棄的空專案，兩個角色綁在那個空專案上，再對它發超出預算的訊息。複本若沿用正式的函式名稱，部署會蓋掉正式的函式；訊息若發到正式的主題，被停用的就是正式專案。
  • 在正式專案上只確認權限：gcloud policy-intelligence troubleshoot-policy iam //cloudresourcemanager.googleapis.com/projects/<project-id> --principal-email=<sa-email> --permission=<permission>。<sa-email> 是 budget-killswitch-sa@<project-id>.iam.gserviceaccount.com，<permission> 依序填 resourcemanager.projects.deleteBillingAssignment 與 resourcemanager.projects.get；執行的專案要先啟用 policytroubleshooter.googleapis.com。輸出的 overallAccessState 是 CAN_ACCESS 才算有，沒有綁角色的服務帳號回 CANNOT_ACCESS。

  拆開驗證仍沒有行使正式專案上那一次 updateBillingInfo，驗收紀錄要寫明缺了這一段。

心跳監看：函式停止收到通知時告警

預算一天會送好幾則通知，函式的紀錄長時間沒有出現帶 action 欄位的紀錄就通知，讓函式停止收到通知這件事本身也成為訊號。心跳監看建在第三個專案：停損開關正常觸發之後，被保護的專案整個停擺，告警放在那裡會一起停；也不放在管理專案，管理專案失效時要有人知道。實測的做法是用 gcloud logging metrics create 把帶 action 欄位的那類紀錄做成日誌指標，再在 Cloud Monitoring 建一條缺席條件（condition absent）的告警；缺席條件的時間窗上限是 23 小時 30 分，設成 24 小時會被拒，所以時間窗設 23 小時。設好之後暫時把時間窗縮到幾分鐘，確認通知送到收的人手上，再改回 23 小時：實測時間窗設 3 分鐘，最後一筆紀錄之後 4 到 9 分鐘告警送達。這次建指標與告警政策的完整指令沒有留下來，日誌指標的 filter 用〈兩段驗收：第一則真實通知，再發兩則測試訊息〉那條 jsonPayload.action:* 的查詢條件。

• 沒做時：別人調整了角色（例如權限盤點時收掉 roles/browser）或鎖定了專案的帳單連結時，部署的人不會知道要重驗，停損開關一直顯示 ACTIVE（推論，這次沒有實跑）。

超支停用之後的恢復

恢復之前先調預算的理由（costAmount 是本期累計值，只重新連結的話下一則通知會讓函式再解除一次）與依停用原因分開的順序，見概念篇〈解除連結之後恢復服務的順序〉。

服務自己出錯：修好程式之後，先調高預算金額或刪掉函式，再重新連結：

1gcloud billing budgets update <budget-resource-name> --budget-amount=<amount><currency-code> --billing-project=<project-id>
2gcloud billing projects link <project-id> --billing-account=<billing-account-id>

資源被別人濫用：重新連結之前，把預算金額調成目前的 costAmount 加上清理期間能承受的金額，並先撤銷外洩的 API 金鑰與服務帳號金鑰：實測帳單停用期間 gcloud services api-keys list 與 delete 都照常可用。重新連結之後列出並刪除不屬於自己的 VM、instance template 與 MIG，確認乾淨之後再把預算調回原本的金額。

實測停用約兩分半鐘再重新連結，Cloud Router、Cloud NAT、函式與它的觸發器都還在、設定沒變（這次沒有觀察 VM 與資料庫）；停用期間 gcloud compute routers list 回傳零筆，重新連結之後 Cloud Router 仍在。重新連結之後 4 分鐘內沒有再被停用：停用期間對主題發布的訊息照樣被接受，而函式在停用後的那一分鐘內就把它處理掉了（回報帳單已停用），沒有留到重新連結之後。

• 替代做法：刪掉函式再重新連結，換到的是不必估清理期間的金額，付出的是清理期間沒有停損開關；被濫用的情形下，這段時間正是攻擊者可能再開資源的時候（推論，這次沒有實跑）。