需要管理 Google Cloud…

用 Google Cloud Privileged Access Manager 以按需、限时、可审计的方式授予临时 IAM 权限，替代永久角色绑定。

适用场景

解决思路

1. 核心概念：Entitlement（授权配置，定义访问范围、可申请人、审批人）与 Grant（针对授权创建的短期请求，用于激活对应 IAM 角色）；流程为管理员创建 Entitlement → 申请人请求 Grant → 如需审批则由审批人批准 → 全部审批完成后 Grant 在请求时长内激活 → 到期自动结束并移除提权。
2. privilegedAccess 块定义访问范围，包含三要素：Resource（授予访问的目标资源：项目/文件夹/组织）、Role Setup（要分配的 IAM 角色 roleBindings.role）、Condition（可选，roleBindings.conditionExpression 限制角色生效条件）。
3. 审批工作流：当敏感环境需要人工审批时，在 entitlement.yaml 中配置 approvalWorkflow 块，可设 requireApproverJustification: true（要求审批人填写理由），steps 中指定 approvalsNeeded 数量、approverEmailRecipients 邮件接收者、approvers.principals（如 user:db-lead@my-company.com 或 group:sre-leads@my-company.com）；配置后用户请求的 Grant 会进入 APPROVAL_AWAITED 状态，需等待审批人决定。
4. 最大请求时长 maxRequestDuration：按用户要求配置（如 8 小时/28800s、1 小时/3600s、24 小时/86400s）；用户未指定时默认 4 小时（14400s）；YAML 中始终以秒为单位的字符串表示（如 "14400s"）。
5. 安全与确认策略：修改/破坏性操作（Create、Update、Delete、Approve、Deny、Revoke）必须先给出纯文本计划摘要并让用户明确确认（Yes/No）；只读检查（List、Describe、Search）可自主执行无需确认；为减少确认弹窗，把顺序执行的只读与查询命令合并到单个 bash 脚本一次调用（如把项目、文件夹、组织层级审计合并为一次多行执行）；反循环策略：命令失败且错误明确可自调试重试，错误含糊则立即停止、展示 stderr 并等待用户指示。
6. 对所有修改操作（Mode 1 Step 3、Mode 2 的 Create/Update/Delete、Mode 3 的 Approve/Deny）遵循 Plan-Validate-Execute 模式：Plan（构造参数或读取示例 Entitlement 结构，创建时加载模板 assets/entitlement_template.yaml）→ Validate（检查资源名、角色绑定、时长限制等是否符合公司规则）→ Execute（展示已验证计划、获得用户明确确认后运行 gcloud 命令）。
7. Mode 1 交互式提权：当用户以申请人身份请求临时提权时，加载并遵循 references/requester.md 的详细说明。
8. Mode 2 独立 Entitlement CRUD 所需权限：roles/privilegedaccessmanager.admin（创建/更新/删除授权配置）；目标层级范围还需 IAM 管理员权限（组织用 roles/iam.securityAdmin，文件夹用 roles/resourcemanager.folderAdmin，项目用 roles/resourcemanager.projectIamAdmin）；roles/privilegedaccessmanager.viewer（跨范围列出和描述授权）。所有 CRUD 命令按授权定义位置使用对应标志：--project=PROJECT_ID、--folder=FOLDER_ID 或 --organization=ORGANIZATION_ID。
9. 创建 Entitlement：先用 gcloud pam entitlements describe ENTITLEMENT_ID --location=global --project=PROJECT_ID 检查是否存在；若已存在则停止并询问用户要查看详情还是改为更新（View/Update/Exit）；若 NOT_FOUND 则加载模板 assets/entitlement_template.yaml，用角色名派生小写连字符 ID（如 roles/compute.admin 对应 compute-admin）；roleBindings 下可指定多个 IAM 角色，每个角色绑定可含可选 conditionExpression；不支持旧版基础角色（roles/viewer、roles/editor、roles/owner），改用 v2 基础角色等价物（roles/basic.viewer、roles/basic.editor、roles/basic.owner），确保选择有效的预定义、自定义或 v2 基础角色；按用户指定设置 maxRequestDuration（未指定默认 "14400s"）；若策略或用户要求人工审批则配置 approvalWorkflow 块；保留 requesterJustificationConfig: {unstructured: {}}；提示用户确认创建后执行 gcloud pam entitlements create ENTITLEMENT_ID --location=global --entitlement-file=entitlement.yaml --project=PROJECT_ID。
10. 读取 Entitlements（可自主执行）：单范围列出用 gcloud pam entitlements list --location=global --project=PROJECT_ID；跨整个资源层级（项目、祖先文件夹、组织）列出用 bash scripts/list_entitlements_hierarchy.sh --project=PROJECT_ID（或传 --folder/--organization）；描述用 gcloud pam entitlements describe ENTITLEMENT_ID --location=global --project=PROJECT_ID。
11. 更新 Entitlement：先运行 gcloud pam entitlements export ENTITLEMENT_ID --location=global --project=PROJECT_ID > {scratch}/updated_entitlement.yaml 导出当前配置（含 etag），若不存在则提供 list 或退出；编辑导出的 YAML 应用所需变更（如 maxRequestDuration、approvalWorkflow、eligibleUsers），不要改动 etag；提示用户确认更新后执行 gcloud pam entitlements update ENTITLEMENT_ID --location=global --entitlement-file={scratch}/updated_entitlement.yaml --project=PROJECT_ID。
12. 删除 Entitlement：先用 describe 验证存在，不存在则提供 list/退出；安全检查——存在未关闭 Grant 时无法删除，先搜索 ACTIVE 或 SCHEDULED 的 Grant：gcloud pam grants list --entitlement=ENTITLEMENT_ID --location=global --project=PROJECT_ID --filter="state:(ACTIVE, SCHEDULED)"；若发现未关闭 Grant，询问用户是否授权撤销：gcloud pam grants revoke GRANT_ID --entitlement=ENTITLEMENT_ID --location=global --project=PROJECT_ID --reason="Revoking to delete entitlement"；提示用户确认永久删除后执行 gcloud pam entitlements delete ENTITLEMENT_ID --location=global --project=PROJECT_ID。
13. Mode 3 审批人工作流：当审批人需要审查、批准或拒绝待处理的 Grant 请求时，加载并遵循 references/approver.md 的详细说明。

适用边界 · 注意事项

• 不用于永久 IAM 策略绑定（permanent IAM policy bindings）。
• 不用于排查 IAM 权限错误（troubleshooting IAM permission errors）。
• 不用于通用的 Google Cloud 资源置备（general Google Cloud resource provisioning）。