微信扫一扫Google Cloud CLI Expert Skill
A unified tool to manage Google Cloud resources from the terminal. This guide focuses on gcloud CLI patterns, practical examples, and production deployment workflows.
Contents
- Quick Start
- When Not to Use
- Decision Trees
- Global Flags
- Environment Variables
- Workflows
- Reference Files
- Scripts
- Troubleshooting
- Best Practices
- Common Mistakes
- Pre-Deployment Checklist
Quick Start
# Verify installation
gcloud --version
# Interactive login
gcloud auth login
# Set default project and region
gcloud config set project PROJECT_ID
gcloud config set compute/region us-central1
# Verify identity
gcloud auth list
gcloud config list
When Not to Use
- Terraform/Pulumi — This skill covers gcloud CLI, not Infrastructure as Code tools
- GCP Console UI — CLI-focused; use GCP documentation for console walkthroughs
- AWS/Azure CLI — Use mastering-aws-cli or azure-cli skills instead
- Client libraries — For Python/Go/Java SDK code, use programming documentation
- Kubernetes kubectl — For K8s cluster operations, use kubectl documentation
Decision Trees
Compute & Containers
Need compute?
├── Serverless containers ──────────► Cloud Run (references/cloud-run-deployment.md)
├── Virtual machines ───────────────► GCE (gcloud compute instances)
├── Kubernetes ─────────────────────► GKE (gcloud container clusters)
└── Serverless functions ───────────► Cloud Functions (gcloud functions)
Data & Databases
Need database?
├── PostgreSQL (managed) ───────────► AlloyDB (references/alloydb-management.md)
├── MySQL/PostgreSQL/SQL Server ────► Cloud SQL (gcloud sql instances)
├── NoSQL document ─────────────────► Firestore (references/firebase-management.md)
└── NoSQL key-value ────────────────► Bigtable (gcloud bigtable)
Networking
Need networking?
├── Custom VPC/subnets ─────────────► VPC (references/vpc-networking.md)
├── Cloud Run → private DB ─────────► VPC Connector (references/vpc-networking.md)
├── Private Google API access ──────► Private Service Connect
└── Firewall rules ─────────────────► VPC Firewall (references/vpc-networking.md)
Security & Identity
Need security/access?
├── Users, roles, policies ─────────► IAM (references/iam-permissions.md)
├── GitHub Actions → GCP ───────────► WIF (references/authentication.md)
├── Secrets & credentials ──────────► Secret Manager (references/secret-manager.md)
└── Service accounts ───────────────► SA (references/iam-permissions.md)
Build & Deploy
Need CI/CD?
├── GitHub Actions ─────────────────► WIF + deploy (references/cicd-integration.md)
├── Container builds ───────────────► Cloud Build (references/cicd-integration.md)
├── Container registry ─────────────► Artifact Registry (references/cicd-integration.md)
└── Deployment automation ──────────► Scripting (references/scripting-patterns.md)
Global Flags
| Flag | Description |
|:-----|:------------|
| --project=PROJECT_ID | Override default project |
| --region=REGION | Specify region (e.g., us-central1) |
| --zone=ZONE | Specify zone (e.g., us-central1-a) |
| --format=FORMAT | Output: json, yaml, table, value(FIELD) |
| --filter=EXPRESSION | Filter results (e.g., status=RUNNING) |
| --quiet | Disable prompts (critical for CI/CD) |
| --verbosity=debug | Enable debug output |
| --log-http | Show HTTP request/response |
Environment Variables
| Variable | Purpose | Example |
|:---------|:--------|:--------|
| CLOUDSDK_CORE_PROJECT | Default project | my-project |
| CLOUDSDK_COMPUTE_REGION | Default region | us-central1 |
| CLOUDSDK_COMPUTE_ZONE | Default zone | us-central1-a |
| CLOUDSDK_CORE_DISABLE_PROMPTS | Non-interactive mode | 1 |
| GOOGLE_APPLICATION_CREDENTIALS | SA key file path | /path/to/key.json |
| CLOUDSDK_CORE_VERBOSITY | Log level | debug |
Workflows
Installation
macOS (recommended):
brew install --cask google-cloud-sdk
gcloud init
For other platforms: references/installation-macos.md, references/installation-linux.md, references/installation-windows.md
Authentication
# User login (interactive)
gcloud auth login
# Service account (automation)
gcloud auth activate-service-account --key-file=key.json
# Application Default Credentials
gcloud auth application-default login
# Impersonation (recommended over keys)
gcloud config set auth/impersonate_service_account SA@PROJECT.iam.gserviceaccount.com
For WIF, impersonation patterns, and ADC details, see references/authentication.md.
Multi-Account Configuration
# Create named configurations
gcloud config configurations create dev
gcloud config set project dev-project-123
gcloud config set compute/region us-west1
# Switch contexts
gcloud config configurations activate prod
# Override for single command
gcloud --configuration=prod compute instances list
For complete multi-account patterns, see references/multi-account-management.md.
Cloud Run Deployment
Phase 1: Prepare
# Verify project and region
gcloud config get-value project
gcloud config get-value compute/region
Phase 2: Build & Push (container deployments)
# Build and push to Artifact Registry
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT/REPO/IMAGE:TAG
Phase 3: Deploy (zero-traffic)
# Deploy from source (builds automatically)
gcloud run deploy SERVICE --source . --region us-central1 --no-traffic --quiet
# Or deploy from container
gcloud run deploy SERVICE --image IMAGE --region us-central1 --no-traffic --quiet
Phase 4: Validate & Shift Traffic
# Verify revision is ready
gcloud run revisions list --service=SERVICE --region=us-central1
# Shift traffic (full or canary)
gcloud run services update-traffic SERVICE --to-latest --region=us-central1
# Or canary: --to-tags canary=10
For VPC connectivity, secrets, and advanced patterns, see references/cloud-run-deployment.md.
IAM Permissions
# Grant project role
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="user:user@example.com" \
--role="roles/viewer"
# Grant resource role
gcloud run services add-iam-policy-binding SERVICE \
--region=REGION \
--member="serviceAccount:sa@PROJECT.iam.gserviceaccount.com" \
--role="roles/run.invoker"
For custom roles and governance, see references/iam-permissions.md.
Secret Manager
# Create secret
echo -n "my-secret-value" | gcloud secrets create SECRET_NAME --data-file=-
# Access secret
gcloud secrets versions access latest --secret=SECRET_NAME
# Mount in Cloud Run
gcloud run deploy SERVICE --set-secrets="ENV_VAR=SECRET_NAME:latest"
For IAM bindings and rotation, see references/secret-manager.md.
VPC Networking
# Create custom VPC
gcloud compute networks create my-vpc --subnet-mode=custom
# Create subnet with Private Google Access
gcloud compute networks subnets create my-subnet \
--network=my-vpc --region=us-central1 --range=10.0.1.0/24 \
--enable-private-ip-google-access
# Create VPC connector for Cloud Run
gcloud compute networks vpc-access connectors create my-connector \
--region=us-central1 --network=my-vpc --range=10.8.0.0/28
For firewall rules, peering, and Private Service Connect, see references/vpc-networking.md.
AlloyDB
# Create cluster
gcloud alloydb clusters create CLUSTER --region=us-central1 --password=PASSWORD --network=default
# Create instance
gcloud alloydb instances create INSTANCE --cluster=CLUSTER --region=us-central1 \
--instance-type=PRIMARY --cpu-count=2
For backups and connections, see references/alloydb-management.md.
CI/CD Integration
GitHub Actions with WIF (recommended):
permissions:
id-token: write
contents: read
- uses: google-github-actions/auth@v2
with:
workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}
For Cloud Build, multi-environment, and Firebase, see references/cicd-integration.md.
Enable APIs
# Core APIs for Cloud Run deployment
gcloud services enable \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
secretmanager.googleapis.com \
iam.googleapis.com \
iamcredentials.googleapis.com
For complete API list, see references/api-enablement.md.
Reference Files
| Reference | Description | Key Triggers |
|:----------|:------------|:-------------|
| Installation (macOS) | Homebrew, Apple Silicon setup | install gcloud, macos |
| Installation (Linux) | apt, dnf/yum, Docker | install gcloud, linux |
| Installation (Windows) | Installer, PowerShell | install gcloud, windows |
| Authentication | OAuth, SA, WIF, impersonation | gcloud auth, wif, service account |
| Multi-Account | Configurations, switching | config, switch project |
| IAM Permissions | Roles, policies, governance | iam, role, permission |
| Cloud Run | Deploy, traffic, secrets | cloud run, deploy |
| Cloud Scheduler | Cron jobs, triggers | scheduler, cron |
| Cloud Storage | Buckets, objects, IAM | storage, gcs, bucket |
| AlloyDB | Clusters, instances | alloydb, postgresql |
| VPC Networking | VPCs, subnets, firewall, connectors | vpc, subnet, firewall |
| Secret Manager | Secrets, versions, IAM | secret, secrets manager |
| CI/CD Integration | GitHub Actions, Cloud Build | github actions, cloud build |
| Scripting Patterns | Error handling, batch ops | script, automation |
| Firebase | Functions, Hosting, Firestore | firebase, firestore |
| API Enablement | Required APIs by service | enable api |
| Verification | Setup verification | verify, check |
| Auth Reset | Credential cleanup | reset auth, revoke |
| Troubleshooting | Debug, logs, common errors | debug, error, logs |
Scripts
| Script | Description |
|:-------|:------------|
| scripts/verify-gcp-setup.sh | Comprehensive GCP setup verification |
| scripts/setup-gcloud-configs.sh | Initialize multi-environment configs |
| scripts/switch-gcloud-project.sh | Switch between projects |
| scripts/reset-gcloud-auth.sh | Complete auth reset |
| scripts/deploy-cloud-run.sh | Cloud Run deployment helper |
| scripts/setup-wif-github.sh | WIF setup for GitHub Actions |
Troubleshooting
Quick Debug Commands
# Check configuration
gcloud config list
gcloud auth list
# Enable debug output
gcloud COMMAND --verbosity=debug --log-http
# View logs
gcloud logging read 'resource.type="cloud_run_revision"' --limit=50
Common Errors
| Error | Solution |
|:------|:---------|
| PERMISSION_DENIED | Check IAM roles: gcloud projects get-iam-policy PROJECT_ID |
| API not enabled | Enable API: gcloud services enable API_NAME |
| VPC connector failed | Check connector status, may need recreation |
| Container failed to start | Check Cloud Run logs, test locally first |
For complete troubleshooting guide, see references/troubleshooting.md.
Best Practices
| Category | Recommendation |
|:---------|:---------------|
| Security | Use Workload Identity Federation over service account keys |
| Security | Use Secret Manager for sensitive configuration |
| Scripting | Always use --quiet flag in automation |
| Scripting | Use --format=json or --format=value() for parsing |
| Safety | Use gcloud ... --verbosity=debug to troubleshoot |
| Performance | Use --filter to reduce API response size |
| Regions | Explicitly set region in scripts to avoid surprises |
Common Mistakes
Avoid these anti-patterns:
| Mistake | Problem | Correct Approach |
|:--------|:--------|:-----------------|
| gcloud auth activate-service-account --key-file=key.json | Keys can leak, hard to rotate | Use WIF or impersonation |
| gcloud run deploy SERVICE --source . (no region) | Deploys to random default region | Always specify --region |
| echo $SECRET in logs | Exposes secrets in CI logs | Use --format=value() quietly |
| Hardcoding project ID in scripts | Breaks portability | Use gcloud config get-value project |
| Missing --quiet in CI/CD | Scripts hang on prompts | Always add --quiet for automation |
| Using roles/editor or roles/owner | Over-privileged, security risk | Use specific roles like roles/run.admin |
Bad vs Good Examples:
# BAD: No region, no quiet, hardcoded project
gcloud run deploy my-service --source . --project my-project-123
# GOOD: Explicit region, quiet mode, portable
gcloud run deploy my-service \
--source . \
--region="${REGION:-us-central1}" \
--project="$(gcloud config get-value project)" \
--quiet
# BAD: Using service account key file
gcloud auth activate-service-account --key-file=key.json
# GOOD: Using impersonation (no key file needed)
gcloud config set auth/impersonate_service_account deploy-sa@PROJECT.iam.gserviceaccount.com
Pre-Deployment Checklist
Run before every Cloud Run deployment:
[ ] 1. Verify identity: gcloud auth list
[ ] 2. Confirm project: gcloud config get-value project
[ ] 3. Check APIs enabled: gcloud services list --enabled | grep -E "run|build|artifact"
[ ] 4. Verify SA permissions: gcloud projects get-iam-policy PROJECT_ID --filter="bindings.members:SA_EMAIL"
[ ] 5. Test locally: docker run -p 8080:8080 IMAGE && curl localhost:8080/health
[ ] 6. Check secrets exist: gcloud secrets list --filter="name:SECRET_NAME"
[ ] 7. Verify VPC connector (if needed): gcloud compute networks vpc-access connectors describe CONNECTOR --region=REGION
[ ] 8. Deploy with --no-traffic first: gcloud run deploy SERVICE --image=IMAGE --no-traffic
[ ] 9. Verify revision ready: gcloud run revisions list --service=SERVICE --region=REGION
[ ] 10. Shift traffic: gcloud run services update-traffic SERVICE --to-latest --region=REGION