IAM 自訂角色
https://www.skills.google/games/7397/labs/45407

整理 IAM Custom Roles (GSP190) 全程 CLI 實作學習筆記。這份筆記捨棄了手動編輯器 (如 nano)，完全採用終端機指令與腳本化 (Scripting) 的方式進行，非常適合自動化部署或快速複習使用。

📚 學習筆記：Google Cloud IAM Custom Roles 管理

🔧 0. 環境初始設定

在開始任何 IAM 操作前，確保 Cloud Shell 已授權，並且設定在正確的區域 (Region)。

# 授權 gcloud 使用者帳號
gcloud auth list

# 查詢目前的專案 ID (確認環境變數 $DEVSHELL_PROJECT_ID 正確對應)
gcloud config list project

# 設定實驗指定的預設 Region
gcloud config set compute/region us-east1

🔍 階段一：查詢與檢視 (Information Gathering)

在建立自訂角色之前，通常需要先了解有哪些權限可用、現有角色包含什麼，以及資源能被賦予哪些角色。

Task 1: 查詢資源可用的權限清單

學習重點： 使用 list-testable-permissions 可以列出特定資源 (如目前的專案) 支援的所有底層權限 (如 appengine.applications.create)。

gcloud iam list-testable-permissions //cloudresourcemanager.googleapis.com/projects/$DEVSHELL_PROJECT_ID

Task 2: 檢視現有角色的中繼資料 (Metadata)

學習重點： 透過 describe 指令，可以查看 Google 預先定義好的角色 (如 roles/viewer) 內部到底打包了哪些 includedPermissions。

gcloud iam roles describe roles/viewer

Task 3: 查詢資源可授予的角色清單

學習重點： 使用 list-grantable-roles 查詢目前專案層級可以指派給使用者的所有角色清單 (包含預設角色與自訂角色)。

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/$DEVSHELL_PROJECT_ID

🏗️ 階段二：建立自訂角色 (Creating Custom Roles)

建立自訂角色有兩種常見做法：透過 YAML 設定檔，或是直接在指令中帶入參數 (Flags)。

Task 4a: 使用 YAML 檔案建立自訂角色 (editor)

學習重點： 利用 cat <<EOF # (Here 1. <<EOF CLI Document) YAML ```bash cat role-definition.yaml 檔案 檔，不需開啟文字編輯器。這對自動化腳本非常有幫助。 產生 的技巧，可以直接在 直接輸出內容並建立> role-definition.yaml
title: "Role Editor"
description: "Edit access for App Versions"
stage: "ALPHA"
includedPermissions:

• appengine.versions.create
• appengine.versions.delete
  EOF

2. 根據該 YAML 檔在專案層級建立名為 editor 的自訂角色

gcloud iam roles create editor --project $DEVSHELL_PROJECT_ID --file role-definition.yaml

### Task 4b: 使用指令參數建立自訂角色 (`viewer`)
**學習重點：** 若權限單純，可省略 YAML 檔，直接透過 `--permissions` 參數以逗號分隔帶入。
```bash
gcloud iam roles create viewer --project $DEVSHELL_PROJECT_ID \
--title "Role Viewer" --description "Custom role description." \
--permissions compute.instances.get,compute.instances.list --stage ALPHA

Task 5: 驗證並列出專案內的自訂角色

學習重點： 加上 --project 參數，過濾掉 Google 預設角色，只顯示您在該專案內建立的自訂角色。

gcloud iam roles list --project $DEVSHELL_PROJECT_ID

🔄 階段三：更新自訂角色 (Updating Custom Roles)

更新角色時，IAM 會檢查 etag (實體標籤) 來防止多人同時修改造成的衝突 (Concurrency Control)。

Task 6a: 使用 YAML 檔案更新角色 (editor) ⚠️ 關鍵技巧

學習重點： 純 CLI 作業時，若使用 echo >> 附加內容容易破壞 YAML 結構。最穩健的做法是先透過 CLI 擷取最新的 etag，然後重新生成一份完整的 YAML 檔進行覆蓋。

# 1. 抓取目前 editor 角色的 etag 並存入環境變數 CURRENT_ETAG
export CURRENT_ETAG=$(gcloud iam roles describe editor --project $DEVSHELL_PROJECT_ID --format="value(etag)")

# 2. 重新產生包含新權限 (storage.buckets.*) 與最新 etag 的 YAML 檔
cat <<EOF> new-role-definition.yaml
description: "Edit access for App Versions"
etag: "$CURRENT_ETAG"
includedPermissions:
- appengine.versions.create
- appengine.versions.delete
- storage.buckets.get
- storage.buckets.list
stage: "ALPHA"
title: "Role Editor"
EOF

# 3. 根據新的 YAML 檔執行更新
gcloud iam roles update editor --project $DEVSHELL_PROJECT_ID --file new-role-definition.yaml

Task 6b: 使用指令參數更新角色 (viewer)

學習重點： 使用 --add-permissions 是最簡便的更新方式，GCP 底層會自動處理 etag 驗證與更新，不用手動介入。

gcloud iam roles update viewer --project $DEVSHELL_PROJECT_ID \
--add-permissions storage.buckets.get,storage.buckets.list

🛑 階段四：生命週期管理 (Lifecycle Management)

Task 7: 停用自訂角色 (Disable)

學習重點： 角色停用後，任何被綁定該角色的使用者將暫時失去這些權限，但角色的設定檔仍保留在專案中。

gcloud iam roles update viewer --project $DEVSHELL_PROJECT_ID \
--stage DISABLED

Task 8: 刪除自訂角色 (Delete)

學習重點： 角色刪除後會進入 7 天的「軟刪除」狀態 (Soft Delete)。在這段期間內無法指派給新使用者，舊的綁定也會失效。

gcloud iam roles delete viewer --project $DEVSHELL_PROJECT_ID

Task 9: 復原已刪除的自訂角色 (Undelete)

學習重點： 只要在刪除後的 7 天內，都能下達復原指令。復原後的角色狀態會預設停留在 DISABLED，需要再次 update 其 stage 才能正式啟用。

gcloud iam roles undelete viewer --project $DEVSHELL_PROJECT_ID