gcloud：环境、Project 与 Billing

验证：静态检查 · 核验于 2026-10-13

适用版本: 云环境版本未实测；适用条件见正文
验证范围: 已检查文档构建、链接与脚本语法；未执行云端实验。

切换环境先确认身份与目标，再执行资源操作。

常用操作#

替换为实际资源；本段不依赖 lab.env。

PROJECT_ID='REPLACE_PROJECT_ID'

gcloud auth list --filter=status:ACTIVE
gcloud config list
gcloud config get-value auth/impersonate_service_account
gcloud billing projects describe "$PROJECT_ID"

容易踩的坑#

PROJECT_ID 只是 shell 变量；未传 –project 或设置 CLOUDSDK_CORE_PROJECT 时不会自动选择目标。

切换 gcloud account / Project 不会切换应用 ADC。 CLI 和 SDK 分别确认实际身份与目标项目；Budget 只通知，不是费用硬上限。

CLI / ADC · 多账号

配置说明与完整示例（按需展开）

前置与费用#

前置：可用登录身份及 Project / Cloud Billing account 权限。公司尚未配置员工身份时，先完成公司初始化。

使用独立沙箱或管理员分配的空 Project。创建 Project、关联 Cloud Billing account 需要对应两侧授权，并受 Organization Policy 约束。

工具：Cloud Shell 或本机 gcloud，以及 Bash、Python 3、curl、jq；Docker / kubectl / Terraform 按篇安装。macOS zsh 用户先进入 bash，以支持 read -rs -p 等语法。按段执行并检查预期失败，不整篇粘贴。

VM、NAT、GKE、Cloud SQL、Redis、负载均衡有持续费用，停止请求不代表停止计费。预算是通知，不是消费硬上限。预算文档

1. 初始化#

登录并确认当前身份#

首次为实验创建独立的 gcloud 配置并登录。若 gcp-learning 配置已经存在，用 gcloud config configurations activate gcp-learning 激活，不必重复 create。

gcloud config configurations create gcp-learning
gcloud auth login
gcloud config get-value account

最后输出是操作者邮箱，不是 Cloud Billing account ID。

已有项目：先检查关联的 Cloud Billing account#

已有 Project 时先查询结算状态：

export PROJECT_ID='替换为已有项目ID'
gcloud billing projects describe "$PROJECT_ID"

只读查询，已启用结算的示例输出：

billingAccountName: billingAccounts/XXXXXX-XXXXXX-XXXXXX
billingEnabled: true
name: projects/your-project-id/billingInfo
projectId: your-project-id

billingAccountName 中 billingAccounts/ 后为账号 ID，billingEnabled 表示结算是否启用：查询命令。

查询结果	含义	后续操作
账号非空，`billingEnabled: true`	已关联可用 Cloud Billing account 并启用结算	确认是本次实验可使用的项目及付款账号，直接复用
账号非空，`billingEnabled: false`	有关联，但结算未启用，可能因账号关闭或暂停	检查账号状态，恢复结算或经授权关联其他可用账号；不要只凭有 ID 就继续
账号为空，`billingEnabled: false`	尚未关联 Cloud Billing account	按下一节查询可用账号，再执行 link；跳过创建项目
命令报错	可能是项目 ID 错误、项目不存在或当前身份无查询权限	先核对项目与权限，不把报错当成“尚未关联”

若已启用结算，切换到该项目即可：

gcloud config set project "$PROJECT_ID"
gcloud config get-value project

已启用结算则跳过查询账号、创建 Project 和 link，直接确认预算，再将当前 PROJECT_ID 写入第 2 节 lab.env。Console 可在该 Project 的 Billing 查看关联关系。

查询已有 Cloud Billing account ID#

仅在新建 Project 或启用/更换结算时查询可用账号：

gcloud billing accounts list

按 NAME 选择本次获准使用且 OPEN=True 的账号，将 ACCOUNT_ID 写入 BILLING_ACCOUNT；不要自动取首条。查询命令

Console：Billing → My billing accounts。Billing account ID 格式为 XXXXXX-XXXXXX-XXXXXX，由 Google 生成。查找 ID

列表为空时先查登录身份与查看权限；确认无可用账号再创建或联系管理员。免费试用已创建试用 Cloud Billing account，可直接查询复用。试用说明

填写变量、创建项目并关联账单#

变量	从哪里获取	示例格式
`PROJECT_ID`	为新项目自行取一个全球唯一的 ID；已有项目则复制其实际项目 ID	`rick-gcp-learning-20261009`
`BILLING_ACCOUNT`	上一步查询结果中的 `ACCOUNT_ID`，或控制台中的结算账号 ID	`XXXXXX-XXXXXX-XXXXXX`

替换下面两个占位值再执行。export 只设置当前 shell 的变量，不会创建项目或 Cloud Billing account。

export PROJECT_ID='替换为全球唯一项目ID'
export BILLING_ACCOUNT='替换为上一步查询到的ACCOUNT_ID'
gcloud projects create "$PROJECT_ID" --name=gcp-learning
gcloud billing projects link "$PROJECT_ID" --billing-account="$BILLING_ACCOUNT"
gcloud config set project "$PROJECT_ID"
gcloud billing projects describe "$PROJECT_ID"

projects create 用指定 ID 创建项目，--name=gcp-learning 是可重复的显示名称。billing projects link 将项目关联到已有 Cloud Billing account，不创建 Cloud Billing account；后续项目费用由它承担。最后检查 billingEnabled: true，以及 billingAccountName 是否为所选账号。

已有 Project 跳过 create，结算已正确关联则跳过 link。关联需 Project 侧 Billing Manager 和账号侧 Billing Account User 等权限；查看权限不足以关联。授权要求

确认预算#

无论复用项目还是新建项目，都检查预算与通知。Console → Billing → Budgets & alerts：限定本项目，建立符合个人承受能力的月预算，设置 50% / 80% / 100% 通知并确认收件人。

2. 固定实验变量#

在专用实验目录创建 lab.env，把项目 ID 改成实际值。后续各篇从该目录运行；子目录中用 source ../lab.env。

cat > lab.env <<'EOF'
export PROJECT_ID='替换为实际项目ID'
export REGION='asia-east1'
export ZONE='asia-east1-b'
export BUCKET="${PROJECT_ID}-lab"
# Pin this shell to the lab Project; flags such as --project still take precedence.
export CLOUDSDK_CORE_PROJECT="$PROJECT_ID"
EOF
source lab.env
export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')
gcloud config set project "$PROJECT_ID"
gcloud config set compute/region "$REGION"
gcloud config set compute/zone "$ZONE"
gcloud services enable serviceusage.googleapis.com cloudresourcemanager.googleapis.com iam.googleapis.com iamcredentials.googleapis.com

gcloud auth list
gcloud config list
gcloud billing projects describe "$PROJECT_ID"

PROJECT_ID 是 shell 变量；实际选择 gcloud Project 的是 CLOUDSDK_CORE_PROJECT，显式 --project 优先。结束时 unset CLOUDSDK_CORE_PROJECT 恢复 configuration 选择；环境变量仍存在时，gcloud config set project 不能覆盖它。此设置不切换身份或 ADC。属性优先级

地域按实际配额与政策调整；数据库、应用尽量同地域，避免无意的跨区域流量。PROJECT_ID 用于资源路径，PROJECT_NUMBER 常用于 service agent 与 federated identity，两者不能互换。

3. 权限约定#

各篇创建资源的命令由有对应管理权限的实验操作者执行；运行应用的 Service Account 仅获得篇中明确授予的权限。不要把创建资源所需权限全部交给应用。

实验	操作者通常需要的预定义角色，限定沙箱
启用 API / 创建 SA / 授权	Service Usage Admin / Service Account Admin / Project IAM Admin；资源级 IAM 另需该资源的管理权限
VPC、VM、DNS、LB	Compute Network Admin、Compute Security Admin、Compute Instance Admin (v1)、DNS Administrator、Compute Load Balancer Admin
镜像、构建、运行	Artifact Registry Admin、Cloud Build Editor、Cloud Run Admin；在指定 SA 上的 Service Account User
存储、SQL、消息、密钥、分析	Storage Admin、Cloud SQL Admin、Pub/Sub Admin、Secret Manager Admin、BigQuery Admin
GKE、日志、监控	Kubernetes Engine Admin、Logging Admin、Monitoring Admin
DNS/TLS/CDN/WAF	DNS Administrator、Certificate Manager Editor、Compute Load Balancer Admin、Compute Security Admin；公开桶另需 Storage IAM 权限
调度/任务/事件	Cloud Scheduler Admin、Cloud Tasks Admin、Eventarc Admin；指定调用 SA 上的 Service Account User
加密/文档/缓存	Cloud KMS Admin、Datastore Owner（建库）、Datastore User（数据）、Redis Admin
IAP/治理/费用	IAP Policy Admin、Cloud Asset Viewer、Billing Account Viewer；OAuth 设置、账单导出另需对应管理员
私网服务	Compute Network Admin、Service Networking Admin；跨项目还需相应 Shared VPC 授权

不要一次性把表中所有角色分配给长期身份；按当前实验申请，用完撤销。自定义 Organization Policy、跨项目访问可能需要额外授权。

验收与清理#

验收：能说明当前账号、项目、 Cloud Billing account 和地域；预算通知可送达；知道每个实验的运行身份。

各篇先按自己的清理段执行。整个课程结束，只对本次专用沙箱执行：

gcloud projects delete "$PROJECT_ID"