Mastering Gcloud Commands

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

Environment Variables

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

Scripts

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

For complete troubleshooting guide, see references/troubleshooting.md.

Best Practices

Common Mistakes

Avoid these anti-patterns:

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

Mastering Google Cloud CLI

Expert-level Google Cloud CLI (gcloud) skill for managing GCP resources.

Overview

This skill provides comprehensive gcloud CLI patterns for:

• Cross-platform installation guides for macOS, Windows, and Linux
• Multi-account management with named configurations
• Authentication patterns including OAuth, service accounts, and Workload Identity Federation
• IAM governance with least-privilege patterns
• Deployment workflows for Cloud Run, Firebase, and containerized applications
• CI/CD integration with GitHub Actions and Cloud Build
• Database management for AlloyDB and Cloud SQL
• VPC networking including subnets, firewall rules, and VPC connectors
• Secret management with Secret Manager integration
• Automation scripts with error handling and idempotent patterns

Installing with Skilz (Universal Installer)

The recommended way to install this skill across different AI coding agents is using the skilz universal installer.

Install Skilz

pip install skilz

This skill supports Agent Skill Standard which means it supports 14 plus coding agents including Claude Code, OpenAI Codex, Cursor and Gemini.

Git URL Options

You can use either -g or --git with HTTPS or SSH URLs:

# HTTPS URL
skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands

# SSH URL
skilz install --git git@github.com:SpillwaveSolutions/mastering-gcloud-commands.git

Claude Code

Install to user home (available in all projects):

skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands

Install to current project only:

skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands --project

OpenCode

Install for OpenCode:

skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands --agent opencode

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands --project --agent opencode

Gemini

Project-level install for Gemini:

skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands --agent gemini

OpenAI Codex

Install for OpenAI Codex:

skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands --agent codex

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/mastering-gcloud-commands --project --agent codex

Install from Skillzwave Marketplace

# Claude to user home dir ~/.claude/skills
skilz install SpillwaveSolutions_mastering-gcloud-commands/mastering-gcloud-commands

# Claude skill in project folder ./claude/skills
skilz install SpillwaveSolutions_mastering-gcloud-commands/mastering-gcloud-commands --project

# OpenCode install to user home dir ~/.config/opencode/skills
skilz install SpillwaveSolutions_mastering-gcloud-commands/mastering-gcloud-commands --agent opencode

# OpenCode project level
skilz install SpillwaveSolutions_mastering-gcloud-commands/mastering-gcloud-commands --agent opencode --project

# OpenAI Codex install to user home dir ~/.codex/skills
skilz install SpillwaveSolutions_mastering-gcloud-commands/mastering-gcloud-commands --agent codex

# OpenAI Codex project level ./.codex/skills
skilz install SpillwaveSolutions_mastering-gcloud-commands/mastering-gcloud-commands --agent codex --project

# Gemini CLI (project level) -- only works with project level
skilz install SpillwaveSolutions_mastering-gcloud-commands/mastering-gcloud-commands --agent gemini

See this site skill Listing to see how to install this exact skill to 14+ different coding agents.

Other Supported Agents

Skilz supports 14+ coding agents including Windsurf, Qwen Code, Aidr, and more.

For the full list of supported platforms, visit SkillzWave.ai/platforms or see the skilz-cli GitHub repository

Manual Installation

Copy this skill to your Claude Code skills directory:

# User-level installation
cp -r mastering-gcloud-commands ~/.claude/skills/

# Or create a symlink
ln -s "$(pwd)" ~/.claude/skills/mastering-gcloud-commands

Verify Installation

The skill activates automatically when you mention gcloud, GCP, Cloud Run, or related terms.

Skill Structure

mastering-gcloud-commands/
├── SKILL.md                    # Main skill file with decision trees and workflows
├── references/                 # Detailed documentation (loaded on-demand)
│   ├── installation-macos.md   # macOS: Homebrew, Apple Silicon
│   ├── installation-windows.md # Windows: installer, PowerShell, silent
│   ├── installation-linux.md   # Linux: apt, dnf, Docker
│   ├── authentication.md       # OAuth, service accounts, WIF
│   ├── authentication-reset.md # Credential cleanup procedures
│   ├── multi-account-management.md
│   ├── iam-permissions.md      # Roles, custom roles, policies
│   ├── cloud-run-deployment.md # Source, container, traffic splitting
│   ├── cloud-scheduler.md      # Scheduled jobs with OIDC
│   ├── cloud-storage.md        # Bucket and object operations
│   ├── alloydb-management.md   # Cluster and instance management
│   ├── firebase-management.md  # Firebase CLI integration
│   ├── cicd-integration.md     # GitHub Actions, Cloud Build
│   ├── api-enablement.md       # Required APIs by category
│   ├── verification-patterns.md
│   ├── vpc-networking.md       # VPCs, subnets, firewall, connectors
│   ├── secret-manager.md       # Secrets, versions, IAM bindings
│   ├── troubleshooting.md      # Debug mode, common errors
│   └── scripting-patterns.md   # Error handling, batch ops, jq parsing
└── scripts/                    # Ready-to-use automation scripts
    ├── deploy-cloud-run.sh     # Deployment with common options
    ├── setup-wif-github.sh     # Workload Identity Federation setup
    ├── verify-gcp-setup.sh     # Comprehensive project verification
    ├── reset-gcloud-auth.sh    # Authentication cleanup
    ├── switch-gcloud-project.sh # Project switching helper
    └── setup-gcloud-configs.sh # Multi-config initialization

Quick Reference

Essential Commands

# Authentication
gcloud auth login                              # Browser-based user login
gcloud auth list                               # List authenticated accounts
gcloud auth activate-service-account --key-file=KEY.json

# Configuration Management
gcloud config configurations list              # List all configurations
gcloud config configurations create NAME       # Create new profile
gcloud config configurations activate NAME     # Switch active profile
gcloud config set project PROJECT_ID           # Set default project

# Common Operations
gcloud projects list                           # List accessible projects
gcloud run deploy SERVICE --source .           # Deploy to Cloud Run
gcloud storage cp FILE gs://BUCKET/            # Upload to Cloud Storage

Example Prompts

When using Claude Code with this skill:

"Help me set up gcloud on my Mac"
"Configure Workload Identity Federation for GitHub Actions"
"Deploy my app to Cloud Run with traffic splitting"
"Set up a Cloud Scheduler job to trigger my Cloud Run service"
"Create IAM roles for my CI/CD pipeline"
"Switch between my dev and prod GCP projects"

Scripts

deploy-cloud-run.sh

Deploy to Cloud Run with common options:

./scripts/deploy-cloud-run.sh my-api --source . --allow-unauth
./scripts/deploy-cloud-run.sh my-api --image gcr.io/project/image:v1 --env API_KEY=abc
./scripts/deploy-cloud-run.sh my-api --source . --no-traffic --tag canary

setup-wif-github.sh

Set up Workload Identity Federation for GitHub Actions (keyless authentication):

# Preview changes
./scripts/setup-wif-github.sh --dry-run my-project my-org my-repo

# Execute setup
./scripts/setup-wif-github.sh my-project my-org my-repo

verify-gcp-setup.sh

Comprehensive verification of your GCP project:

./scripts/verify-gcp-setup.sh --project-id my-project --verbose

reset-gcloud-auth.sh

Clean up authentication when troubleshooting:

./scripts/reset-gcloud-auth.sh              # Credentials only
./scripts/reset-gcloud-auth.sh --full-reset # Credentials + configurations

switch-gcloud-project.sh

Efficient project switching:

./scripts/switch-gcloud-project.sh switch my-project
./scripts/switch-gcloud-project.sh list
./scripts/switch-gcloud-project.sh status

Features by Category

Installation & Setup

• Homebrew installation for macOS
• Interactive installer for Windows
• Package manager (apt/dnf) for Linux
• Docker-based installation
• Shell integration (bash, zsh, fish, PowerShell)

Authentication

• Browser-based OAuth login
• Service account key authentication
• Service account impersonation (recommended)
• Workload Identity Federation (keyless CI/CD)
• Application Default Credentials (ADC)

Multi-Account Management

• Named configurations for different projects/environments
• Quick context switching
• Per-command configuration override
• Environment variable configuration

Deployment

• Cloud Run from source or container
• Traffic splitting and canary deployments
• Cloud Scheduler with OIDC authentication
• Firebase Hosting and Functions
• Artifact Registry integration

Security & IAM

• Least-privilege role patterns
• Custom role creation
• Conditional IAM bindings
• Service account best practices
• Audit logging

CI/CD

• GitHub Actions with WIF (keyless)
• GitHub Actions with service account keys
• Cloud Build triggers and configurations
• GitLab CI integration
• Jenkins pipelines

Progressive Disclosure Architecture

This skill uses a three-level loading system for efficient context usage:

1. Metadata (~100 words) - Always loaded, triggers skill activation 2. SKILL.md (<5K words) - Quick reference workflows 3. References (unlimited) - Detailed docs loaded on-demand

When you ask about a specific topic, Claude loads only the relevant reference file.

Version

• Version: 1.0.0
• Author: Richard Hightower / Spillwave Solutions
• License: MIT

Contributing

1. Fork this repository 2. Add or update reference files in references/ 3. Update SKILL.md navigation if adding new files 4. Submit a pull request

Related Skills

• mastering-aws-cli - AWS CLI reference
• mastering-github-cli - GitHub CLI reference

---

<a href="https://skillzwave.ai/">Largest Agentic Marketplace for AI Agent Skills</a> and <a href="https://spillwave.com/">SpillWave: Leaders in AI Agent Development.</a>

AlloyDB Management Guide

This guide covers managing AlloyDB for PostgreSQL clusters and instances using the gcloud CLI.

Prerequisites

Enable the AlloyDB API:

gcloud services enable alloydb.googleapis.com

AlloyDB requires:

• A VPC network with Private Service Access configured
• Service Networking API enabled

gcloud services enable servicenetworking.googleapis.com

Network Setup

AlloyDB uses private IP addresses and requires VPC peering:

# Allocate IP range for private services
gcloud compute addresses create google-managed-services-default \
  --global \
  --purpose=VPC_PEERING \
  --prefix-length=16 \
  --network=default

# Create private connection
gcloud services vpc-peerings connect \
  --service=servicenetworking.googleapis.com \
  --ranges=google-managed-services-default \
  --network=default

Cluster Operations

Create Cluster

# Basic cluster
gcloud alloydb clusters create my-cluster \
  --region=us-central1 \
  --password=MY_SECURE_PASSWORD \
  --network=default

# With specific database version
gcloud alloydb clusters create my-cluster \
  --region=us-central1 \
  --password=MY_SECURE_PASSWORD \
  --network=default \
  --database-version=POSTGRES_15

# With Private Service Connect
gcloud alloydb clusters create my-cluster \
  --region=us-central1 \
  --password=MY_SECURE_PASSWORD \
  --enable-private-service-connect \
  --network=default

# Async (returns immediately)
gcloud alloydb clusters create my-cluster \
  --region=us-central1 \
  --password=MY_SECURE_PASSWORD \
  --network=default \
  --async

List Clusters

# List all clusters in region
gcloud alloydb clusters list --region=us-central1

# List all clusters
gcloud alloydb clusters list

# With specific format
gcloud alloydb clusters list \
  --region=us-central1 \
  --format="table(name,state,databaseVersion)"

Describe Cluster

gcloud alloydb clusters describe my-cluster \
  --region=us-central1

# Get specific field
gcloud alloydb clusters describe my-cluster \
  --region=us-central1 \
  --format="value(state)"

Update Cluster

# Update automated backup policy
gcloud alloydb clusters update my-cluster \
  --region=us-central1 \
  --automated-backup-enabled \
  --automated-backup-start-time=02:00 \
  --automated-backup-days-of-week=SUNDAY

# Update maintenance window
gcloud alloydb clusters update my-cluster \
  --region=us-central1 \
  --maintenance-window-day=SUNDAY \
  --maintenance-window-hour=3

Delete Cluster

# Delete cluster (must delete instances first)
gcloud alloydb clusters delete my-cluster \
  --region=us-central1

# Force delete (deletes instances too)
gcloud alloydb clusters delete my-cluster \
  --region=us-central1 \
  --force

Instance Operations

Create Primary Instance

# Basic primary instance
gcloud alloydb instances create my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --instance-type=PRIMARY \
  --cpu-count=2

# With specific machine type
gcloud alloydb instances create my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --instance-type=PRIMARY \
  --cpu-count=4 \
  --availability-type=REGIONAL

# With database flags
gcloud alloydb instances create my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --instance-type=PRIMARY \
  --cpu-count=2 \
  --database-flags="max_connections=200,log_min_duration_statement=1000"

Create Read Pool Instance

# Create read pool
gcloud alloydb instances create my-read-pool \
  --cluster=my-cluster \
  --region=us-central1 \
  --instance-type=READ_POOL \
  --cpu-count=2 \
  --read-pool-node-count=2

List Instances

gcloud alloydb instances list \
  --cluster=my-cluster \
  --region=us-central1

# With format
gcloud alloydb instances list \
  --cluster=my-cluster \
  --region=us-central1 \
  --format="table(name,instanceType,state,ipAddress)"

Describe Instance

gcloud alloydb instances describe my-primary \
  --cluster=my-cluster \
  --region=us-central1

# Get IP address
gcloud alloydb instances describe my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --format="value(ipAddress)"

Update Instance

# Scale up CPU
gcloud alloydb instances update my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --cpu-count=4

# Update database flags
gcloud alloydb instances update my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --database-flags="max_connections=500"

Delete Instance

gcloud alloydb instances delete my-primary \
  --cluster=my-cluster \
  --region=us-central1

Restart Instance

gcloud alloydb instances restart my-primary \
  --cluster=my-cluster \
  --region=us-central1

User Management

Create User

# Create database user
gcloud alloydb users create myuser \
  --cluster=my-cluster \
  --region=us-central1 \
  --password=MY_USER_PASSWORD \
  --db-roles=alloydbsuperuser

# Create user with specific roles
gcloud alloydb users create readonly_user \
  --cluster=my-cluster \
  --region=us-central1 \
  --password=READONLY_PASSWORD \
  --db-roles=pg_read_all_data

List Users

gcloud alloydb users list \
  --cluster=my-cluster \
  --region=us-central1

Update User Password

gcloud alloydb users set-password myuser \
  --cluster=my-cluster \
  --region=us-central1 \
  --password=NEW_PASSWORD

Delete User

gcloud alloydb users delete myuser \
  --cluster=my-cluster \
  --region=us-central1

Backup Operations

Create Backup

# Manual backup
gcloud alloydb backups create my-backup \
  --cluster=my-cluster \
  --region=us-central1

# With description
gcloud alloydb backups create pre-upgrade-backup \
  --cluster=my-cluster \
  --region=us-central1 \
  --description="Backup before major upgrade"

List Backups

gcloud alloydb backups list --region=us-central1

# Filter by cluster
gcloud alloydb backups list \
  --region=us-central1 \
  --filter="clusterName:my-cluster"

Describe Backup

gcloud alloydb backups describe my-backup \
  --region=us-central1

Delete Backup

gcloud alloydb backups delete my-backup \
  --region=us-central1

Connecting to AlloyDB

AlloyDB instances use private IPs. Connection options:

From GCE VM in Same VPC

# Get instance IP
ALLOYDB_IP=$(gcloud alloydb instances describe my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --format="value(ipAddress)")

# Connect with psql
psql -h $ALLOYDB_IP -U postgres -d postgres

Using AlloyDB Auth Proxy

# Download AlloyDB Auth Proxy
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.8.1/alloydb-auth-proxy.darwin.arm64
chmod +x alloydb-auth-proxy

# Start proxy
./alloydb-auth-proxy \
  projects/PROJECT_ID/locations/us-central1/clusters/my-cluster/instances/my-primary

# Connect via proxy
psql -h 127.0.0.1 -U postgres -d postgres

From Cloud Run

# Deploy Cloud Run with VPC connector
gcloud run deploy my-app \
  --image IMAGE \
  --vpc-connector my-connector \
  --set-env-vars="DATABASE_URL=postgresql://user:pass@ALLOYDB_IP:5432/db"

High Availability

Regional Availability

# Create instance with regional availability
gcloud alloydb instances create my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --instance-type=PRIMARY \
  --cpu-count=4 \
  --availability-type=REGIONAL

# This provides:
# - Automatic failover
# - Synchronous replication
# - 99.99% SLA

Promote Read Pool

# In case of primary failure, promote read pool
gcloud alloydb instances failover my-read-pool \
  --cluster=my-cluster \
  --region=us-central1

Monitoring

View Operations

# List ongoing operations
gcloud alloydb operations list \
  --region=us-central1

# Describe operation
gcloud alloydb operations describe OPERATION_ID \
  --region=us-central1

Wait for Operation

# Wait for async operation to complete
gcloud alloydb operations wait OPERATION_ID \
  --region=us-central1

Common Patterns

Full Cluster Setup Script

#!/bin/bash

PROJECT_ID="my-project"
REGION="us-central1"
CLUSTER_NAME="production"
PRIMARY_NAME="primary"
PASSWORD="SecurePassword123!"

# Create cluster
gcloud alloydb clusters create $CLUSTER_NAME \
  --region=$REGION \
  --password=$PASSWORD \
  --network=default \
  --database-version=POSTGRES_15

# Wait for cluster
gcloud alloydb clusters describe $CLUSTER_NAME \
  --region=$REGION \
  --format="value(state)"

# Create primary instance
gcloud alloydb instances create $PRIMARY_NAME \
  --cluster=$CLUSTER_NAME \
  --region=$REGION \
  --instance-type=PRIMARY \
  --cpu-count=4 \
  --availability-type=REGIONAL

# Get connection info
gcloud alloydb instances describe $PRIMARY_NAME \
  --cluster=$CLUSTER_NAME \
  --region=$REGION \
  --format="table(ipAddress,state)"

echo "AlloyDB cluster ready!"

Migration from Cloud SQL

# 1. Create AlloyDB cluster
gcloud alloydb clusters create migrated-db \
  --region=us-central1 \
  --password=PASSWORD \
  --network=default

# 2. Create instance
gcloud alloydb instances create primary \
  --cluster=migrated-db \
  --region=us-central1 \
  --instance-type=PRIMARY \
  --cpu-count=4

# 3. Use Database Migration Service
# https://cloud.google.com/database-migration

Troubleshooting

Cluster Creation Fails

# Check VPC peering status
gcloud services vpc-peerings list \
  --network=default

# Verify IP range allocation
gcloud compute addresses list --global

# Check for quota issues
gcloud compute project-info describe --project=PROJECT_ID

Connection Issues

# Verify instance is running
gcloud alloydb instances describe my-primary \
  --cluster=my-cluster \
  --region=us-central1

# Check firewall rules
gcloud compute firewall-rules list \
  --filter="network:default"

# Test connectivity from VM
gcloud compute ssh my-vm --command="nc -zv ALLOYDB_IP 5432"

Performance Issues

# Check instance metrics
gcloud monitoring dashboards list

# Update database flags
gcloud alloydb instances update my-primary \
  --cluster=my-cluster \
  --region=us-central1 \
  --database-flags="shared_buffers=2GB,effective_cache_size=6GB"

Required IAM Roles

# AlloyDB Admin (full control)
roles/alloydb.admin

# AlloyDB Client (connect)
roles/alloydb.client

# AlloyDB Viewer (read-only)
roles/alloydb.viewer

Grant permissions:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:admin@example.com" \
  --role="roles/alloydb.admin"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:app@PROJECT.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

GCP API Enablement Guide

This guide covers enabling and managing GCP APIs, including a comprehensive list of commonly required APIs organized by category.

API Management Basics

Enable a Single API

gcloud services enable API_NAME --project=PROJECT_ID

Enable Multiple APIs

gcloud services enable \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    --project=PROJECT_ID

List Enabled APIs

# All enabled APIs
gcloud services list --enabled --project=PROJECT_ID

# Filter by pattern
gcloud services list --enabled \
    --filter="name:(*aiplatform* OR *run* OR *artifactregistry*)" \
    --project=PROJECT_ID

Check if API is Enabled

if gcloud services list --enabled \
    --filter="name:run.googleapis.com" \
    --format="value(name)" \
    --project=PROJECT_ID | grep -q .; then
    echo "API is enabled"
else
    echo "API is not enabled"
fi

Comprehensive API List by Category

Core Infrastructure APIs

Essential APIs for any GCP project:

CORE_APIS=(
    "cloudresourcemanager.googleapis.com"  # Project and resource management
    "compute.googleapis.com"               # VPC, networks, VMs, load balancers
    "iam.googleapis.com"                   # Identity and Access Management
    "iamcredentials.googleapis.com"        # Service Account Credentials API
    "sts.googleapis.com"                   # Security Token Service (for WIF)
    "serviceusage.googleapis.com"          # Service usage and quotas
)

Container & Deployment APIs

For containerized application deployments:

CONTAINER_APIS=(
    "run.googleapis.com"                   # Cloud Run (serverless containers)
    "cloudbuild.googleapis.com"            # Cloud Build (CI/CD)
    "artifactregistry.googleapis.com"      # Artifact Registry (container images)
    "containerregistry.googleapis.com"     # Legacy Container Registry
    "container.googleapis.com"             # Google Kubernetes Engine (GKE)
)

Data & Storage APIs

For data persistence and storage:

DATA_APIS=(
    "storage.googleapis.com"               # Cloud Storage (GCS buckets)
    "sqladmin.googleapis.com"              # Cloud SQL / AlloyDB admin
    "alloydb.googleapis.com"               # AlloyDB for PostgreSQL
    "redis.googleapis.com"                 # Memorystore for Redis
    "firestore.googleapis.com"             # Firestore database
    "bigtable.googleapis.com"              # Cloud Bigtable
    "spanner.googleapis.com"               # Cloud Spanner
)

AI/ML APIs

For AI and machine learning workloads:

AI_APIS=(
    "aiplatform.googleapis.com"            # Vertex AI
    "ml.googleapis.com"                    # AI Platform (legacy)
    "vision.googleapis.com"                # Cloud Vision API
    "language.googleapis.com"              # Natural Language API
    "translate.googleapis.com"             # Cloud Translation API
    "speech.googleapis.com"                # Speech-to-Text API
    "texttospeech.googleapis.com"          # Text-to-Speech API
)

Monitoring & Operations APIs

For observability and operations:

OPERATIONS_APIS=(
    "logging.googleapis.com"               # Cloud Logging
    "monitoring.googleapis.com"            # Cloud Monitoring
    "cloudtrace.googleapis.com"            # Cloud Trace
    "cloudprofiler.googleapis.com"         # Cloud Profiler
    "clouderrorreporting.googleapis.com"   # Error Reporting
    "cloudscheduler.googleapis.com"        # Cloud Scheduler (cron jobs)
    "cloudtasks.googleapis.com"            # Cloud Tasks (async tasks)
)

Security APIs

For security and secrets management:

SECURITY_APIS=(
    "secretmanager.googleapis.com"         # Secret Manager
    "cloudkms.googleapis.com"              # Cloud Key Management Service
    "iap.googleapis.com"                   # Identity-Aware Proxy
    "certificatemanager.googleapis.com"    # Certificate Manager
    "securitycenter.googleapis.com"        # Security Command Center
)

Networking APIs

For advanced networking:

NETWORKING_APIS=(
    "servicenetworking.googleapis.com"     # Service Networking (VPC peering)
    "vpcaccess.googleapis.com"             # Serverless VPC Access
    "dns.googleapis.com"                   # Cloud DNS
    "networkconnectivity.googleapis.com"   # Network Connectivity Center
)

Common Application Profiles

Web Application (Cloud Run)

APIs for a typical Cloud Run web application:

WEB_APP_APIS=(
    "run.googleapis.com"
    "cloudbuild.googleapis.com"
    "artifactregistry.googleapis.com"
    "iam.googleapis.com"
    "iamcredentials.googleapis.com"
    "sts.googleapis.com"
    "logging.googleapis.com"
    "monitoring.googleapis.com"
    "secretmanager.googleapis.com"
)

Full-Stack Application with Database

APIs for a complete application with database and AI:

FULLSTACK_APIS=(
    # Core
    "cloudresourcemanager.googleapis.com"
    "compute.googleapis.com"
    "iam.googleapis.com"
    "iamcredentials.googleapis.com"
    "sts.googleapis.com"
    "serviceusage.googleapis.com"
    # Deployment
    "run.googleapis.com"
    "cloudbuild.googleapis.com"
    "artifactregistry.googleapis.com"
    # Data
    "sqladmin.googleapis.com"
    "storage.googleapis.com"
    "redis.googleapis.com"
    # AI
    "aiplatform.googleapis.com"
    # Operations
    "logging.googleapis.com"
    "monitoring.googleapis.com"
    "cloudtrace.googleapis.com"
    "cloudscheduler.googleapis.com"
    # Security
    "secretmanager.googleapis.com"
    "cloudkms.googleapis.com"
)

Batch Enable Script

Complete script for enabling APIs:

#!/usr/bin/env bash
set -euo pipefail

PROJECT_ID="${1:-$(gcloud config get-value project)}"

echo "Enabling APIs for project: $PROJECT_ID"
echo

# Define your API list
APIS=(
    "cloudresourcemanager.googleapis.com"
    "compute.googleapis.com"
    "iam.googleapis.com"
    "iamcredentials.googleapis.com"
    "sts.googleapis.com"
    "serviceusage.googleapis.com"
    "artifactregistry.googleapis.com"
    "cloudbuild.googleapis.com"
    "run.googleapis.com"
    "aiplatform.googleapis.com"
    "storage.googleapis.com"
    "sqladmin.googleapis.com"
    "redis.googleapis.com"
    "logging.googleapis.com"
    "monitoring.googleapis.com"
    "cloudtrace.googleapis.com"
    "secretmanager.googleapis.com"
    "cloudkms.googleapis.com"
    "cloudscheduler.googleapis.com"
    "vpcaccess.googleapis.com"
)

for api in "${APIS[@]}"; do
    echo "  Enabling $api..."
    gcloud services enable "$api" --project="$PROJECT_ID" 2>/dev/null || {
        echo "    ⚠️  Could not enable $api (may require billing or permissions)"
    }
done

echo
echo "✅ API enablement complete"

# Verify
echo
echo "Verifying enabled APIs..."
gcloud services list --enabled \
    --project="$PROJECT_ID" \
    --format="table(config.name)" | head -20

API Verification Script

Verify required APIs are enabled:

#!/usr/bin/env bash
set -euo pipefail

PROJECT_ID="${1:-$(gcloud config get-value project)}"

REQUIRED_APIS=(
    "run.googleapis.com"
    "cloudbuild.googleapis.com"
    "artifactregistry.googleapis.com"
    "iam.googleapis.com"
)

echo "Checking APIs for project: $PROJECT_ID"
echo

# Get enabled APIs once
ENABLED=$(gcloud services list --enabled \
    --format="value(config.name)" \
    --project="$PROJECT_ID")

MISSING=0
for api in "${REQUIRED_APIS[@]}"; do
    if echo "$ENABLED" | grep -q "^$api$"; then
        echo "  ✅ $api"
    else
        echo "  ❌ $api (not enabled)"
        ((MISSING++))
    fi
done

echo
if [ $MISSING -eq 0 ]; then
    echo "✅ All required APIs are enabled"
else
    echo "❌ $MISSING APIs need to be enabled"
    exit 1
fi

Troubleshooting

API Not Found

# Search for API name
gcloud services list --available \
    --filter="name:*run*" \
    --format="table(config.name,config.title)"

Permission Denied

# Check if you have permission to enable APIs
gcloud projects get-iam-policy PROJECT_ID \
    --filter="bindings.members:YOUR_EMAIL" \
    --format="value(bindings.role)" | grep -E "(Owner|Editor|serviceUsage)"

Billing Not Enabled

Some APIs require billing to be enabled:

# Check billing status
gcloud billing projects describe PROJECT_ID

# Link billing account
gcloud billing projects link PROJECT_ID \
    --billing-account=BILLING_ACCOUNT_ID

API Quota Issues

# Check quotas
gcloud services quotas list \
    --service=run.googleapis.com \
    --project=PROJECT_ID

# Request quota increase via console
echo "Visit: https://console.cloud.google.com/iam-admin/quotas?project=PROJECT_ID"

Best Practices

1. Enable in batches - Group related APIs and enable together 2. Document requirements - Keep a list of required APIs for your project 3. Verify after enabling - Always confirm APIs are enabled before deploying 4. Use service accounts - Enable APIs using a service account with appropriate permissions 5. Check dependencies - Some APIs require other APIs to be enabled first 6. Monitor costs - Some APIs have costs; review pricing before enabling

GCP Authentication Reset Guide

This guide covers complete authentication reset procedures for gcloud CLI, including credential clearing, configuration reset, and re-authentication workflows.

When to Reset Authentication

Reset authentication when:

• Switching between accounts or organizations
• Troubleshooting permission errors
• After credential expiration or revocation
• Cleaning up stale configurations
• Moving to a new machine or environment

Credential Locations

Understanding where gcloud stores credentials:

~/.config/gcloud/
├── access_tokens.db              # Cached access tokens (SQLite)
├── credentials.db                # Refresh tokens (SQLite)
├── application_default_credentials.json  # ADC file
├── properties                    # SDK properties
├── configurations/               # Named configurations
│   ├── config_default
│   └── config_production
└── legacy_credentials/           # Legacy credential files

Show Current Authentication State

Before resetting, understand current state:

show_auth_state() {
    echo "Current authentication state:"
    echo

    # Active accounts
    echo "  Active account(s):"
    gcloud auth list --format="table(account, status)" 2>/dev/null || echo "    No accounts found"
    echo

    # Current configuration
    echo "  Current project: $(gcloud config get-value project 2>/dev/null || echo 'Not set')"
    echo "  Current configuration: $(gcloud config configurations list --format='value(name)' --filter='is_active=true' 2>/dev/null || echo 'default')"
    echo

    # Check for ADC
    local adc_file="$HOME/.config/gcloud/application_default_credentials.json"
    if [ -f "$adc_file" ]; then
        echo "  Application Default Credentials: Present"
        if command -v jq &> /dev/null; then
            local adc_account=$(jq -r '.client_email // .client_id // "unknown"' "$adc_file" 2>/dev/null)
            echo "    Account: $adc_account"
        fi
    else
        echo "  Application Default Credentials: Not found"
    fi
}

Clear Credentials

Revoke All Accounts

clear_credentials() {
    echo "Clearing authentication credentials..."

    # Revoke all credentials
    if gcloud auth list --format='value(account)' 2>/dev/null | grep -q .; then
        echo "  Revoking all existing credentials..."
        gcloud auth revoke --all 2>/dev/null || true
        echo "  ✅ All credentials revoked"
    else
        echo "  No credentials to revoke"
    fi
}

Clear Application Default Credentials

clear_adc() {
    local adc_file="$HOME/.config/gcloud/application_default_credentials.json"
    if [ -f "$adc_file" ]; then
        echo "  Removing Application Default Credentials..."
        rm -f "$adc_file"
        echo "  ✅ ADC removed"
    else
        echo "  No ADC file found"
    fi
}

Clear Token Cache

clear_token_cache() {
    local token_cache="$HOME/.config/gcloud/credentials.db"
    if [ -f "$token_cache" ]; then
        echo "  Clearing token cache..."
        rm -f "$token_cache"
        echo "  ✅ Token cache cleared"
    fi

    local access_tokens="$HOME/.config/gcloud/access_tokens.db"
    if [ -f "$access_tokens" ]; then
        echo "  Clearing access tokens..."
        rm -f "$access_tokens"
        echo "  ✅ Access tokens cleared"
    fi
}

Clear Legacy Credentials

clear_legacy_credentials() {
    local legacy_dir="$HOME/.config/gcloud/legacy_credentials"
    if [ -d "$legacy_dir" ]; then
        echo "  Clearing legacy credentials..."
        rm -rf "$legacy_dir"
        echo "  ✅ Legacy credentials cleared"
    fi
}

Clear Configurations

Delete Non-Default Configurations

clear_configurations() {
    echo "Clearing gcloud configurations..."

    # List all configurations
    local configs=($(gcloud config configurations list --format='value(name)' 2>/dev/null))

    for config in "${configs[@]}"; do
        if [ "$config" != "default" ]; then
            echo "  Deleting configuration: $config"
            gcloud config configurations delete "$config" --quiet 2>/dev/null || true
        fi
    done

    # Reset default configuration
    echo "  Resetting default configuration..."
    gcloud config unset project 2>/dev/null || true
    gcloud config unset account 2>/dev/null || true
    gcloud config unset compute/zone 2>/dev/null || true
    gcloud config unset compute/region 2>/dev/null || true

    echo "  ✅ Configurations cleared"
}

Re-Authentication

Interactive Re-Authentication

re_authenticate() {
    local project_id=${1:-}

    echo "Re-authenticating with Google Cloud..."
    echo

    # Login to gcloud
    echo "Please login to your Google account:"
    gcloud auth login

    # Set project
    if [ -n "$project_id" ]; then
        echo "Setting project to: $project_id"
        gcloud config set project "$project_id"
    else
        echo "No project specified. Set it with: gcloud config set project PROJECT_ID"
    fi
}

Setup Application Default Credentials

setup_adc() {
    local project_id=${1:-}

    echo "Setting up Application Default Credentials..."

    if [ -n "$project_id" ]; then
        gcloud auth application-default login --project="$project_id"
        gcloud auth application-default set-quota-project "$project_id"
    else
        gcloud auth application-default login
    fi

    echo "✅ Application Default Credentials configured"
}

Configure Docker for Artifact Registry

setup_docker_auth() {
    local region=${1:-us-central1}

    echo "Configuring Docker authentication..."
    gcloud auth configure-docker "${region}-docker.pkg.dev" --quiet
    echo "✅ Docker configured for Artifact Registry"
}

Complete Reset Script

#!/usr/bin/env bash
# reset-gcloud-auth.sh - Complete authentication reset

set -euo pipefail

# Color codes
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m'

# Configuration
PROJECT_ID="${GCP_PROJECT_ID:-}"
CLEAR_CONFIGS=false
FULL_RESET=false

print_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
print_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
print_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
print_error() { echo -e "${RED}[ERROR]${NC} $1"; }

confirm() {
    local message=$1
    local default=${2:-N}

    if [ "$default" = "Y" ]; then
        read -p "$(echo -e "${YELLOW}[CONFIRM]${NC} $message [Y/n]: ")" -n 1 -r
        echo
        [[ -z "$REPLY" || $REPLY =~ ^[Yy]$ ]]
    else
        read -p "$(echo -e "${YELLOW}[CONFIRM]${NC} $message [y/N]: ")" -n 1 -r
        echo
        [[ $REPLY =~ ^[Yy]$ ]]
    fi
}

usage() {
    cat << EOF
Usage: $0 [OPTIONS]

GCP Authentication Reset Tool

Options:
    -p, --project-id PROJECT_ID    GCP project ID to set after reset
    -c, --clear-configs            Also clear all gcloud configurations
    -f, --full-reset               Perform full reset (configs + credentials)
    -h, --help                     Show this help message

Examples:
    # Basic authentication reset
    $0

    # Full reset with specific project
    $0 --full-reset --project-id my-project

    # Clear configurations only
    $0 --clear-configs

EOF
    exit 0
}

# Parse arguments
while [[ $# -gt 0 ]]; do
    case $1 in
        -p|--project-id) PROJECT_ID="$2"; shift 2 ;;
        -c|--clear-configs) CLEAR_CONFIGS=true; shift ;;
        -f|--full-reset) FULL_RESET=true; CLEAR_CONFIGS=true; shift ;;
        -h|--help) usage ;;
        *) print_error "Unknown option: $1"; usage ;;
    esac
done

main() {
    echo -e "${CYAN}=========================================${NC}"
    echo -e "${CYAN}  GCP Authentication Reset Tool${NC}"
    echo -e "${CYAN}=========================================${NC}"
    echo

    # Check prerequisites
    if ! command -v gcloud &> /dev/null; then
        print_error "gcloud CLI not installed"
        exit 1
    fi

    # Show current state
    show_auth_state

    # Confirm reset
    print_warning "This will reset your GCP authentication."
    if [ "$FULL_RESET" = true ]; then
        print_warning "Full reset mode: Will clear all configurations and credentials."
    fi
    echo

    if ! confirm "Do you want to continue?"; then
        print_info "Reset cancelled."
        exit 0
    fi

    echo

    # Perform reset
    clear_credentials
    clear_adc
    clear_token_cache
    clear_legacy_credentials

    if [ "$CLEAR_CONFIGS" = true ]; then
        clear_configurations
    fi

    echo
    print_success "Authentication reset complete!"
    echo

    # Re-authentication
    if confirm "Do you want to re-authenticate now?" "Y"; then
        echo
        re_authenticate "$PROJECT_ID"

        if confirm "Set up Application Default Credentials?" "Y"; then
            setup_adc "$PROJECT_ID"
        fi

        if confirm "Configure Docker for Artifact Registry?"; then
            setup_docker_auth
        fi
    else
        print_info "You can re-authenticate later with:"
        echo -e "${CYAN}  gcloud auth login${NC}"
        echo -e "${CYAN}  gcloud auth application-default login${NC}"
    fi

    echo
    print_info "Final authentication state:"
    show_auth_state

    print_success "Reset process complete!"
}

main

Quick Commands

Quick Reset (Credentials Only)

# Revoke all and re-authenticate
gcloud auth revoke --all
gcloud auth login
gcloud auth application-default login

Full Reset (Everything)

# Clear everything
gcloud auth revoke --all
rm -f ~/.config/gcloud/application_default_credentials.json
rm -f ~/.config/gcloud/credentials.db
rm -f ~/.config/gcloud/access_tokens.db
rm -rf ~/.config/gcloud/legacy_credentials

# Reset configurations
gcloud config unset project
gcloud config unset account

# Re-authenticate
gcloud auth login
gcloud config set project PROJECT_ID
gcloud auth application-default login --project=PROJECT_ID

Single Account Switch

# Switch without full reset
gcloud config set account other-account@gmail.com
gcloud config set project other-project

Troubleshooting

Token Refresh Failures

# Force token refresh
gcloud auth login

# For service accounts
gcloud auth activate-service-account --key-file=key.json

Permission Denied After Reset

# Verify account
gcloud auth list

# Check project permissions
gcloud projects get-iam-policy PROJECT_ID \
    --filter="bindings.members:YOUR_EMAIL"

ADC Not Working

# Re-create ADC
rm -f ~/.config/gcloud/application_default_credentials.json
gcloud auth application-default login

# Verify token
gcloud auth application-default print-access-token

Google Cloud CLI Authentication

This guide covers all authentication methods for gcloud CLI, from interactive browser login to service accounts and Workload Identity Federation.

Contents

• Authentication Methods Overview
• User Authentication (OAuth 2.0)
• Service Account Authentication
• Service Account Impersonation
• Workload Identity Federation
• Environment Variables
• Credential Storage
• Idempotent Service Account Creation
• ADC File Locations and Cleanup
• Security Best Practices
• Troubleshooting

Authentication Methods Overview

User Authentication (OAuth 2.0)

Standard Browser Login

For interactive use on local workstations:

# Opens browser for authentication
gcloud auth login

# Verify logged in accounts
gcloud auth list

The login flow: 1. Opens default browser to Google sign-in 2. User authenticates (including MFA if configured) 3. Refresh token stored locally in ~/.config/gcloud/

Remote/SSH Session Login

When browser access is unavailable:

gcloud auth login --no-launch-browser

This provides a URL to copy to another machine's browser, then paste the authorization code back.

Application Default Credentials (ADC)

For local development with client libraries:

# Set up ADC for local code
gcloud auth application-default login

# Verify ADC
gcloud auth application-default print-access-token

Important: ADC is separate from gcloud's own auth. Applicable scenarios:

• Local Python/Go/Java code using Google Cloud client libraries
• Terraform with Google provider
• Local development servers

Managing Multiple User Accounts

# List all authenticated accounts
gcloud auth list

# OUTPUT:
# Credentialed Accounts
# ACTIVE  ACCOUNT
# *       user1@example.com
#         user2@example.com

# Switch active account
gcloud config set account user2@example.com

# Revoke specific account
gcloud auth revoke user1@example.com

# Revoke all accounts
gcloud auth revoke --all

Service Account Authentication

Service accounts are non-human identities for automation and services.

Creating Service Accounts

# Create service account
gcloud iam service-accounts create my-service-account \
  --display-name="My Service Account" \
  --description="Used for CI/CD deployments"

# List service accounts
gcloud iam service-accounts list

# Get service account email
# Format: NAME@PROJECT_ID.iam.gserviceaccount.com

Key-Based Authentication (Use Sparingly)

Security Warning: JSON keys are long-lived credentials. Prefer impersonation or Workload Identity.

# Create and download key
gcloud iam service-accounts keys create ~/keys/sa-key.json \
  --iam-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

# Set restrictive permissions
chmod 600 ~/keys/sa-key.json

# Activate service account
gcloud auth activate-service-account \
  my-sa@PROJECT_ID.iam.gserviceaccount.com \
  --key-file=~/keys/sa-key.json

# Alternative: use login with cred-file (newer method)
gcloud auth login --cred-file=~/keys/sa-key.json

Key Management Best Practices

# List keys for service account
gcloud iam service-accounts keys list \
  --iam-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

# Delete old/compromised keys
gcloud iam service-accounts keys delete KEY_ID \
  --iam-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

# Set key expiration (organization policy)
# Requires Org Admin - keys auto-expire after configured period

Service Account Impersonation (Recommended)

Impersonation allows using service account permissions without managing keys.

Setting Up Impersonation

# Grant user permission to impersonate
gcloud iam service-accounts add-iam-policy-binding \
  my-sa@PROJECT_ID.iam.gserviceaccount.com \
  --member="user:developer@example.com" \
  --role="roles/iam.serviceAccountTokenCreator"

Using Impersonation

# Single command with impersonation
gcloud compute instances list \
  --impersonate-service-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

# Set as default for configuration
gcloud config set auth/impersonate_service_account \
  my-sa@PROJECT_ID.iam.gserviceaccount.com

# All subsequent commands use impersonated identity
gcloud storage buckets list  # Uses my-sa permissions

# Clear impersonation
gcloud config unset auth/impersonate_service_account

Benefits of Impersonation

1. No keys to manage: Eliminates key rotation requirements 2. Short-lived tokens: Credentials expire quickly 3. Audit trail: Clear record of who impersonated what 4. Revocable access: Remove impersonation permission to revoke

Workload Identity Federation (WIF)

WIF enables external identities (GitHub, AWS, Azure, etc.) to access GCP without keys.

Create Workload Identity Pool

# Create identity pool
gcloud iam workload-identity-pools create "github-pool" \
  --location="global" \
  --display-name="GitHub Actions Pool" \
  --description="Pool for GitHub Actions workflows"

# Get pool name for later use
gcloud iam workload-identity-pools describe "github-pool" \
  --location="global" \
  --format="value(name)"

Create OIDC Provider for GitHub

gcloud iam workload-identity-pools providers create-oidc "github-provider" \
  --workload-identity-pool="github-pool" \
  --location="global" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --allowed-audiences="https://github.com/OWNER" \
  --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --attribute-condition="assertion.repository_owner == 'YOUR_GITHUB_ORG'"

Grant Service Account Access

# Get the principal identifier
PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')

# Grant service account impersonation to GitHub repo
gcloud iam service-accounts add-iam-policy-binding \
  deploy-sa@PROJECT_ID.iam.gserviceaccount.com \
  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/github-pool/attribute.repository/OWNER/REPO" \
  --role="roles/iam.workloadIdentityUser"

GitHub Actions Configuration

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write  # Required for WIF

    steps:
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-pool/providers/github-provider'
          service_account: 'deploy-sa@PROJECT_ID.iam.gserviceaccount.com'

      - uses: google-github-actions/setup-gcloud@v2

      - run: gcloud run deploy ...

Environment Variables

# Application Default Credentials file
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

# Force specific Python
export CLOUDSDK_PYTHON=/usr/bin/python3.11

# Disable prompts in scripts
export CLOUDSDK_CORE_DISABLE_PROMPTS=1

# Set active configuration
export CLOUDSDK_ACTIVE_CONFIG_NAME=production

Credential Storage

Credentials are stored in ~/.config/gcloud/:

~/.config/gcloud/
├── access_tokens.db       # Cached access tokens (SQLite)
├── credentials.db         # Refresh tokens (SQLite)
├── properties             # SDK properties
├── configurations/        # Named configurations
│   ├── config_default
│   └── config_production
└── legacy_credentials/    # Legacy credential files

Idempotent Service Account Creation

When scripting service account creation, use check-before-create patterns for safe re-execution:

Check If Service Account Exists

# Check before creating
sa_exists() {
    local sa_name=$1
    local project_id=$2
    gcloud iam service-accounts describe \
        "${sa_name}@${project_id}.iam.gserviceaccount.com" \
        --project="$project_id" &> /dev/null
}

# Idempotent create
create_service_account_if_not_exists() {
    local sa_name=$1
    local project_id=$2
    local display_name=${3:-$sa_name}

    if sa_exists "$sa_name" "$project_id"; then
        echo "  ✓ Service account $sa_name already exists"
        return 0
    fi

    echo "  Creating service account $sa_name..."
    gcloud iam service-accounts create "$sa_name" \
        --display-name="$display_name" \
        --project="$project_id"
}

Idempotent IAM Binding

# Check if role is already granted (avoids duplicate bindings)
has_role() {
    local member=$1
    local role=$2
    local project_id=$3

    gcloud projects get-iam-policy "$project_id" \
        --flatten="bindings[].members" \
        --filter="bindings.role:$role AND bindings.members:$member" \
        --format="value(bindings.role)" 2>/dev/null | grep -q .
}

# Grant role only if not present
grant_role_if_needed() {
    local member=$1
    local role=$2
    local project_id=$3

    if has_role "$member" "$role" "$project_id"; then
        echo "  ✓ $role already granted"
        return 0
    fi

    echo "  Granting $role..."
    gcloud projects add-iam-policy-binding "$project_id" \
        --member="$member" \
        --role="$role" \
        --condition=None \
        --quiet
}

Complete Idempotent Setup Script

#!/usr/bin/env bash
set -euo pipefail

PROJECT_ID="${1:-$(gcloud config get-value project)}"
SA_NAME="my-service-account"

# Check and create
if ! sa_exists "$SA_NAME" "$PROJECT_ID"; then
    gcloud iam service-accounts create "$SA_NAME" \
        --display-name="My Service Account" \
        --project="$PROJECT_ID"
    echo "Created service account: $SA_NAME"
else
    echo "Service account already exists: $SA_NAME"
fi

# Grant roles idempotently
SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
for role in "roles/run.invoker" "roles/storage.objectViewer"; do
    grant_role_if_needed "serviceAccount:$SA_EMAIL" "$role" "$PROJECT_ID"
done

ADC File Locations and Cleanup

Application Default Credentials are stored in specific locations:

ADC File Locations

~/.config/gcloud/
├── application_default_credentials.json  # Main ADC file
├── access_tokens.db                      # Cached access tokens (SQLite)
├── credentials.db                        # Refresh tokens (SQLite)
└── legacy_credentials/                   # Legacy credential files

Checking ADC Status

# Check if ADC exists
if [ -f "$HOME/.config/gcloud/application_default_credentials.json" ]; then
    echo "ADC configured"

    # Check quota project (if jq available)
    if command -v jq &> /dev/null; then
        jq -r '.quota_project_id // "not set"' \
            "$HOME/.config/gcloud/application_default_credentials.json"
    fi
else
    echo "ADC not configured"
fi

Clearing ADC and Credentials

# Clear ADC only
rm -f "$HOME/.config/gcloud/application_default_credentials.json"

# Clear all cached tokens
rm -f "$HOME/.config/gcloud/access_tokens.db"
rm -f "$HOME/.config/gcloud/credentials.db"

# Clear legacy credentials
rm -rf "$HOME/.config/gcloud/legacy_credentials/"

# Complete credential reset (use reset script)
# See: scripts/reset-gcloud-auth.sh

Setting ADC Quota Project

# Set quota project for ADC
gcloud auth application-default set-quota-project PROJECT_ID

# Verify quota project
gcloud auth application-default print-access-token 2>&1 | head -1

Security Best Practices

1. Use impersonation over keys whenever possible 2. Implement WIF for CI/CD - eliminates key management 3. Set key expiration policies at organization level 4. Never commit keys to git - use .gitignore 5. Rotate keys regularly if keys are required 6. Audit auth logs via Cloud Logging 7. Use short-lived tokens via impersonation 8. Restrict service account permissions to least privilege 9. Use idempotent scripts - check-before-create patterns 10. Clean up credentials when switching projects or troubleshooting

Troubleshooting

"Permission denied" Errors

# Verify active account
gcloud auth list

# Check account has required roles
gcloud projects get-iam-policy PROJECT_ID \
  --filter="bindings.members:ACCOUNT_EMAIL"

Token Refresh Failures

# Re-authenticate
gcloud auth login

# For service accounts, re-activate
gcloud auth activate-service-account --key-file=key.json

ADC Not Working with Client Libraries

# Ensure ADC is set up
gcloud auth application-default login

# Verify token works
gcloud auth application-default print-access-token

# Check GOOGLE_APPLICATION_CREDENTIALS
echo $GOOGLE_APPLICATION_CREDENTIALS

CI/CD Integration Guide

This guide covers integrating gcloud CLI with CI/CD pipelines, focusing on GitHub Actions, Cloud Build, and Workload Identity Federation for secure, keyless authentication.

Contents

• Authentication Strategies
• GitHub Actions
• Cloud Build
• Firebase CI/CD
• Testing in CI/CD
• Secrets Management
• Best Practices
• Troubleshooting

Authentication Strategies

Recommendation: Workload Identity Federation eliminates key management for GitHub Actions.

GitHub Actions

Base Workflow Template

All GitHub Actions workflows share this structure:

name: GCP Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write  # Required for WIF

    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
      - uses: google-github-actions/setup-gcloud@v2
      - run: gcloud run deploy my-service --source . --region us-central1 --quiet

Variations:

• SA Key Auth: Replace workload_identity_provider/service_account with credentials_json: ${{ secrets.GCP_SA_KEY }}
• Multi-env: Add environment detection step (see Multi-Environment section below)
• Docker build: Add docker build/push steps before deploy

Workload Identity Federation Setup

WIF setup involves creating an identity pool, OIDC provider, and granting access:

# 1. Create identity pool
gcloud iam workload-identity-pools create "github-pool" \
  --location="global" --display-name="GitHub Actions Pool"

# 2. Create OIDC provider
gcloud iam workload-identity-pools providers create-oidc "github-provider" \
  --workload-identity-pool="github-pool" --location="global" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --attribute-condition="assertion.repository_owner == 'YOUR_GITHUB_ORG'"

# 3. Create and configure service account
gcloud iam service-accounts create github-deploy-sa --display-name="GitHub Deploy SA"

# Grant required roles (run.admin, artifactregistry.writer, iam.serviceAccountUser)
for role in roles/run.admin roles/artifactregistry.writer roles/iam.serviceAccountUser; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:github-deploy-sa@PROJECT_ID.iam.gserviceaccount.com" \
    --role="$role"
done

# 4. Grant WIF access
PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')
gcloud iam service-accounts add-iam-policy-binding \
  github-deploy-sa@PROJECT_ID.iam.gserviceaccount.com \
  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/github-pool/attribute.repository/YOUR_ORG/YOUR_REPO" \
  --role="roles/iam.workloadIdentityUser"

Multi-Environment Deployment

Add environment detection before the auth step:

- name: Set environment
  id: env
  run: |
    case $GITHUB_REF in
      refs/heads/main)    ENV=production; PROJECT=${{ secrets.PROD_PROJECT_ID }};;
      refs/heads/staging) ENV=staging; PROJECT=${{ secrets.STAGING_PROJECT_ID }};;
      *)                  ENV=development; PROJECT=${{ secrets.DEV_PROJECT_ID }};;
    esac
    echo "environment=$ENV" >> $GITHUB_OUTPUT
    echo "project=$PROJECT" >> $GITHUB_OUTPUT

- name: Deploy
  run: gcloud run deploy my-service-${{ steps.env.outputs.environment }} --source . --region us-central1 --project ${{ steps.env.outputs.project }} --quiet

Docker Build and Deploy

For container-based deployments, add these steps after auth:

env:
  IMAGE: ${{ vars.REGION }}-docker.pkg.dev/${{ vars.PROJECT_ID }}/${{ vars.REPO }}/${{ vars.SERVICE }}:${{ github.sha }}

steps:
  # ... auth steps ...
  - run: gcloud auth configure-docker ${{ vars.REGION }}-docker.pkg.dev
  - run: docker build -t ${{ env.IMAGE }} .
  - run: docker push ${{ env.IMAGE }}
  - run: gcloud run deploy ${{ vars.SERVICE }} --image ${{ env.IMAGE }} --region ${{ vars.REGION }} --quiet

Cloud Build

cloudbuild.yaml Template

Base template with substitution variables for reusability:

steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:$COMMIT_SHA', '.']
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:$COMMIT_SHA']
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    entrypoint: gcloud
    args: ['run', 'deploy', '${_SERVICE}', '--image=${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:$COMMIT_SHA', '--region=${_REGION}', '--quiet']

substitutions:
  _REGION: us-central1
  _REPO: my-repo
  _SERVICE: my-service

options:
  logging: CLOUD_LOGGING_ONLY

Build Triggers and Submission

# Create GitHub trigger
gcloud builds triggers create github \
  --name="deploy-on-push" --repo-name=my-repo --repo-owner=my-org \
  --branch-pattern="^main$" --build-config=cloudbuild.yaml --region=us-central1

# Manual submission
gcloud builds submit --config cloudbuild.yaml --region us-central1

# Quick container build (no cloudbuild.yaml needed)
gcloud builds submit --tag us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-service:latest

Build Monitoring

# Submit async and capture ID
BUILD_ID=$(gcloud builds submit --config cloudbuild.yaml --region us-central1 --async --format='value(id)')

# Stream logs
gcloud builds log "$BUILD_ID" --region us-central1 --stream

# Check status
gcloud builds describe "$BUILD_ID" --region us-central1 --format='value(status)'

# List recent builds
gcloud builds list --limit=10 --region=us-central1 --format='table(id,status,createTime,duration)'

Cloud Build Service Account Setup

PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')
CB_SA="${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com"

# Grant required roles
for role in roles/run.admin roles/artifactregistry.writer; do
  gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:${CB_SA}" --role="$role"
done

# Grant SA impersonation for runtime SA
gcloud iam service-accounts add-iam-policy-binding runtime-sa@PROJECT_ID.iam.gserviceaccount.com \
  --member="serviceAccount:${CB_SA}" --role="roles/iam.serviceAccountUser"

Firebase CI/CD

Firebase Deployment

GitHub Actions:

- uses: w9jds/firebase-action@master
  with:
    args: deploy --only functions,hosting
  env:
    FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

Cloud Build:

steps:
  - name: 'node:20'
    dir: 'functions'
    entrypoint: npm
    args: ['ci']
  - name: 'us-docker.pkg.dev/firebase-cli/us/firebase'
    args: ['deploy', '--project=$PROJECT_ID', '--only=functions,hosting']
    env: ['FIREBASE_TOKEN=${_FIREBASE_TOKEN}']

Testing in CI/CD

Add a test job that runs before deploy:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

  deploy:
    needs: test
    # ... deploy steps ...

Secrets Management

Retrieve secrets from Secret Manager in workflows:

- name: Get secrets
  run: |
    API_KEY=$(gcloud secrets versions access latest --secret="api-key")
    echo "::add-mask::$API_KEY"
    echo "api_key=$API_KEY" >> $GITHUB_OUTPUT

Best Practices

Troubleshooting

# Verify WIF setup
gcloud iam workload-identity-pools providers describe github-provider \
  --workload-identity-pool=github-pool --location=global

# Check SA IAM
gcloud iam service-accounts get-iam-policy github-deploy-sa@PROJECT_ID.iam.gserviceaccount.com

# View build logs
gcloud builds log BUILD_ID --region us-central1

# Check Cloud Run logs
gcloud run services logs read my-service --region=us-central1 --limit=50

Cloud Run Deployment Guide

This guide covers deploying containerized applications to Cloud Run, including source deployments, container image deployments, traffic management, and security configuration.

Prerequisites

Enable required APIs:

gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com

Deployment Methods

Method 1: Deploy from Source Code

Cloud Run builds the container automatically using Cloud Build and Buildpacks:

# Basic source deployment
gcloud run deploy SERVICE_NAME \
  --source . \
  --region us-central1 \
  --platform managed

# With options
gcloud run deploy my-api \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 512Mi \
  --cpu 1 \
  --timeout 300s \
  --max-instances 10 \
  --min-instances 0

The --source . flag: 1. Detects language/framework automatically 2. Builds container using Google Buildpacks 3. Pushes to Artifact Registry (creates cloud-run-source-deploy repo) 4. Deploys to Cloud Run

Method 2: Deploy from Container Image

For more control, build and push images separately:

# 1. Create Artifact Registry repository
gcloud artifacts repositories create my-repo \
  --repository-format=docker \
  --location=us-central1 \
  --description="Container images"

# 2. Configure Docker authentication
gcloud auth configure-docker us-central1-docker.pkg.dev

# 3. Build and push
docker build -t us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-service:v1 .
docker push us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-service:v1

# 4. Deploy
gcloud run deploy my-service \
  --image us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-service:v1 \
  --region us-central1

Method 3: Cloud Build Submission

Build with Cloud Build, then deploy:

# Build and push with Cloud Build
gcloud builds submit --tag us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-service:$COMMIT_SHA .

# Deploy the built image
gcloud run deploy my-service \
  --image us-central1-docker.pkg.dev/PROJECT_ID/my-repo/my-service:$COMMIT_SHA \
  --region us-central1

Deployment Configuration

Resource Allocation

gcloud run deploy my-service \
  --image IMAGE \
  --region us-central1 \
  --memory 1Gi \           # Memory: 128Mi to 32Gi
  --cpu 2 \                # CPU: 1, 2, 4, 6, 8
  --concurrency 80 \       # Max concurrent requests per instance
  --timeout 300s \         # Request timeout (max 3600s)
  --max-instances 100 \    # Maximum auto-scaling
  --min-instances 1        # Keep warm instances (costs apply)

Environment Variables

# Set environment variables
gcloud run deploy my-service \
  --image IMAGE \
  --set-env-vars="DATABASE_URL=postgres://...,API_KEY=abc123,DEBUG=false"

# Update existing service
gcloud run services update my-service \
  --update-env-vars="NEW_VAR=value"

# Remove environment variable
gcloud run services update my-service \
  --remove-env-vars="OLD_VAR"

Secret Integration

# Create secret
echo -n "secret-value" | gcloud secrets create my-secret --data-file=-

# Mount as environment variable
gcloud run deploy my-service \
  --image IMAGE \
  --set-secrets="DB_PASSWORD=my-secret:latest"

# Mount as file
gcloud run deploy my-service \
  --image IMAGE \
  --set-secrets="/secrets/api-key=api-key-secret:latest"

Service Account

# Create runtime service account
gcloud iam service-accounts create cloud-run-sa \
  --display-name="Cloud Run Runtime SA"

# Grant necessary permissions
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:cloud-run-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/datastore.user"

# Deploy with custom service account
gcloud run deploy my-service \
  --image IMAGE \
  --service-account=cloud-run-sa@PROJECT_ID.iam.gserviceaccount.com

VPC Connectivity

# Create VPC connector
gcloud compute networks vpc-access connectors create my-connector \
  --region us-central1 \
  --network default \
  --range 10.8.0.0/28

# Deploy with VPC access
gcloud run deploy my-service \
  --image IMAGE \
  --vpc-connector my-connector \
  --vpc-egress all-traffic  # or private-ranges-only

Traffic Management

Revisions and Tags

# Deploy new revision without traffic
gcloud run deploy my-service \
  --image NEW_IMAGE \
  --no-traffic \
  --tag canary

# Tagged revision URL: https://canary---my-service-HASH.a.run.app

# List revisions
gcloud run revisions list --service my-service --region us-central1

Traffic Splitting

# Route percentage to tagged revision
gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-tags canary=10

# Increase canary traffic
gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-tags canary=50

# Full rollout
gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-tags canary=100

# Route to latest revision
gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-latest

Blue-Green Deployment

# Deploy green version with no traffic
gcloud run deploy my-service \
  --image NEW_IMAGE \
  --no-traffic \
  --tag green

# Test green at tagged URL
curl https://green---my-service-HASH.a.run.app

# Switch all traffic to green
gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-tags green=100

Rollback

# Get previous revision name
gcloud run revisions list \
  --service my-service \
  --region us-central1 \
  --format='value(REVISION)' \
  --sort-by=~metadata.creationTimestamp \
  --limit=5

# Route traffic to specific revision
gcloud run services update-traffic my-service \
  --region us-central1 \
  --to-revisions=my-service-00005-abc=100

Authentication and Security

Public Access

# Allow unauthenticated access during deployment
gcloud run deploy my-service \
  --image IMAGE \
  --allow-unauthenticated

# Or add IAM binding afterward
gcloud run services add-iam-policy-binding my-service \
  --region us-central1 \
  --member="allUsers" \
  --role="roles/run.invoker"

Authenticated Access Only

# Deploy with auth required (default)
gcloud run deploy my-service \
  --image IMAGE \
  --no-allow-unauthenticated

# Grant access to specific principals
gcloud run services add-iam-policy-binding my-service \
  --region us-central1 \
  --member="serviceAccount:invoker@PROJECT.iam.gserviceaccount.com" \
  --role="roles/run.invoker"

gcloud run services add-iam-policy-binding my-service \
  --region us-central1 \
  --member="user:developer@example.com" \
  --role="roles/run.invoker"

Invoking Authenticated Services

# Get identity token
TOKEN=$(gcloud auth print-identity-token)

# Call service
curl -H "Authorization: Bearer $TOKEN" https://my-service-HASH.a.run.app

# For service-to-service calls, use service account
gcloud run services add-iam-policy-binding target-service \
  --region us-central1 \
  --member="serviceAccount:caller-sa@PROJECT.iam.gserviceaccount.com" \
  --role="roles/run.invoker"

Managing Services

List Services

gcloud run services list --region us-central1

# All regions
gcloud run services list --platform managed

Describe Service

gcloud run services describe my-service \
  --region us-central1 \
  --format yaml

Update Service

gcloud run services update my-service \
  --region us-central1 \
  --memory 1Gi \
  --update-env-vars="NEW_VAR=value"

Delete Service

gcloud run services delete my-service --region us-central1

View Logs

# Recent logs
gcloud run services logs read my-service --region us-central1 --limit 50

# Follow logs
gcloud run services logs tail my-service --region us-central1

# Filtered logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=my-service" --limit 100

Cloud Run Jobs

For run-to-completion workloads:

# Create job
gcloud run jobs create my-job \
  --image IMAGE \
  --region us-central1 \
  --memory 2Gi \
  --cpu 2 \
  --task-timeout 3600s \
  --max-retries 3

# Execute job
gcloud run jobs execute my-job --region us-central1

# Execute and wait
gcloud run jobs execute my-job --region us-central1 --wait

# List executions
gcloud run jobs executions list --job my-job --region us-central1

Required IAM Roles

For Deployment

# Cloud Run Admin (full control)
roles/run.admin

# Cloud Run Developer (deploy/update)
roles/run.developer

# Plus Artifact Registry access
roles/artifactregistry.reader

# Plus Service Account User (if using custom SA)
roles/iam.serviceAccountUser

Grant Deployment Permissions

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:deployer@example.com" \
  --role="roles/run.developer"

gcloud iam service-accounts add-iam-policy-binding \
  runtime-sa@PROJECT_ID.iam.gserviceaccount.com \
  --member="user:deployer@example.com" \
  --role="roles/iam.serviceAccountUser"

Troubleshooting

Deployment Failures

# Check build logs
gcloud builds list --limit 5
gcloud builds log BUILD_ID

# Check service status
gcloud run services describe my-service --region us-central1

# Check revision status
gcloud run revisions describe REVISION --region us-central1

Container Startup Issues

# Check logs for startup errors
gcloud run services logs read my-service --region us-central1 --limit 100

# Verify container runs locally
docker run -p 8080:8080 IMAGE

Permission Errors

# Verify active account
gcloud auth list

# Check IAM bindings
gcloud run services get-iam-policy my-service --region us-central1

Cloud Scheduler Guide

This guide covers creating and managing scheduled jobs with Google Cloud Scheduler, including HTTP targets, Pub/Sub integration, and authentication.

Prerequisites

Enable the Cloud Scheduler API:

gcloud services enable cloudscheduler.googleapis.com

Creating Scheduler Jobs

HTTP Jobs

Basic HTTP Job

gcloud scheduler jobs create http my-job \
  --location=us-central1 \
  --schedule="0 * * * *" \
  --uri="https://example.com/api/task" \
  --http-method=GET

HTTP POST with Body

gcloud scheduler jobs create http api-job \
  --location=us-central1 \
  --schedule="*/15 * * * *" \
  --uri="https://api.example.com/process" \
  --http-method=POST \
  --headers="Content-Type=application/json" \
  --message-body='{"action":"process","timestamp":"now"}'

# Body from file
gcloud scheduler jobs create http batch-job \
  --location=us-central1 \
  --schedule="0 2 * * *" \
  --uri="https://api.example.com/batch" \
  --http-method=POST \
  --headers="Content-Type=application/json" \
  --message-body-from-file=payload.json

Pub/Sub Jobs

# Create Pub/Sub topic
gcloud pubsub topics create my-topic

# Create scheduler job to publish
gcloud scheduler jobs create pubsub pubsub-job \
  --location=us-central1 \
  --schedule="*/10 * * * *" \
  --topic=my-topic \
  --message-body='{"event":"scheduled","timestamp":"$(date)"}'

# With attributes
gcloud scheduler jobs create pubsub pubsub-job \
  --location=us-central1 \
  --schedule="0 * * * *" \
  --topic=my-topic \
  --message-body="process" \
  --attributes="type=scheduled,source=scheduler"

App Engine Jobs

gcloud scheduler jobs create app-engine ae-job \
  --location=us-central1 \
  --schedule="0 0 * * *" \
  --service=my-service \
  --relative-url=/cron/daily

Schedule Syntax (Cron Format)

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Common Schedule Patterns

Time Zone Configuration

gcloud scheduler jobs create http my-job \
  --location=us-central1 \
  --schedule="0 9 * * *" \
  --time-zone="America/Los_Angeles" \
  --uri="https://api.example.com/daily"

Authentication

OIDC Authentication (for Cloud Run)

# 1. Create service account for scheduler
gcloud iam service-accounts create scheduler-sa \
  --display-name="Cloud Scheduler SA"

# 2. Grant Cloud Run Invoker role
gcloud run services add-iam-policy-binding my-service \
  --region=us-central1 \
  --member="serviceAccount:scheduler-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.invoker"

# 3. Create job with OIDC auth
gcloud scheduler jobs create http trigger-cloud-run \
  --location=us-central1 \
  --schedule="0 * * * *" \
  --uri="https://my-service-HASH.a.run.app/task" \
  --http-method=POST \
  --oidc-service-account-email=scheduler-sa@PROJECT_ID.iam.gserviceaccount.com

OIDC with Audience

For Cloud Run, specify the audience (service URL):

SERVICE_URL=$(gcloud run services describe my-service \
  --region us-central1 \
  --format='value(status.url)')

gcloud scheduler jobs create http secure-trigger \
  --location=us-central1 \
  --schedule="0 2 * * *" \
  --uri="${SERVICE_URL}/api/scheduled" \
  --http-method=POST \
  --oidc-service-account-email=scheduler-sa@PROJECT_ID.iam.gserviceaccount.com \
  --oidc-token-audience="${SERVICE_URL}"

OAuth Authentication

For Google APIs or services requiring OAuth:

gcloud scheduler jobs create http oauth-job \
  --location=us-central1 \
  --schedule="0 6 * * *" \
  --uri="https://www.googleapis.com/some/api" \
  --http-method=POST \
  --oauth-service-account-email=api-caller@PROJECT_ID.iam.gserviceaccount.com \
  --oauth-token-scope="https://www.googleapis.com/auth/cloud-platform"

Retry Configuration

gcloud scheduler jobs create http retry-job \
  --location=us-central1 \
  --schedule="0 * * * *" \
  --uri="https://api.example.com/task" \
  --http-method=POST \
  --max-retry-attempts=5 \
  --max-retry-duration=3600s \
  --min-backoff=5s \
  --max-backoff=1h \
  --max-doublings=5

Retry parameters:

• max-retry-attempts: Maximum number of retries (0-5)
• max-retry-duration: Maximum time to keep retrying
• min-backoff: Minimum wait before first retry
• max-backoff: Maximum wait between retries
• max-doublings: Number of times to double backoff

Managing Jobs

List Jobs

# List all jobs in location
gcloud scheduler jobs list --location=us-central1

# List all jobs across locations
gcloud scheduler jobs list

Describe Job

gcloud scheduler jobs describe my-job --location=us-central1

Update Job

# Update schedule
gcloud scheduler jobs update http my-job \
  --location=us-central1 \
  --schedule="0 */2 * * *"

# Update URI
gcloud scheduler jobs update http my-job \
  --location=us-central1 \
  --uri="https://new-endpoint.example.com/api"

# Update headers
gcloud scheduler jobs update http my-job \
  --location=us-central1 \
  --headers="Authorization=Bearer new-token"

Pause and Resume

# Pause job (stops execution but keeps configuration)
gcloud scheduler jobs pause my-job --location=us-central1

# Resume job
gcloud scheduler jobs resume my-job --location=us-central1

Run Job Manually

# Trigger immediate execution (for testing)
gcloud scheduler jobs run my-job --location=us-central1

Delete Job

gcloud scheduler jobs delete my-job --location=us-central1

Common Patterns

Trigger Cloud Run Service

#!/bin/bash
# Setup script for Cloud Run + Scheduler

PROJECT_ID="my-project"
REGION="us-central1"
SERVICE_NAME="my-service"
JOB_NAME="trigger-service"

# Create scheduler service account
gcloud iam service-accounts create scheduler-sa \
  --display-name="Cloud Scheduler SA"

# Get Cloud Run service URL
SERVICE_URL=$(gcloud run services describe $SERVICE_NAME \
  --region=$REGION \
  --format='value(status.url)')

# Grant invoker role
gcloud run services add-iam-policy-binding $SERVICE_NAME \
  --region=$REGION \
  --member="serviceAccount:scheduler-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/run.invoker"

# Create scheduler job
gcloud scheduler jobs create http $JOB_NAME \
  --location=$REGION \
  --schedule="0 * * * *" \
  --uri="${SERVICE_URL}/scheduled-task" \
  --http-method=POST \
  --headers="Content-Type=application/json" \
  --message-body='{"source":"scheduler"}' \
  --oidc-service-account-email="scheduler-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
  --oidc-token-audience="${SERVICE_URL}"

Daily Database Backup

gcloud scheduler jobs create http daily-backup \
  --location=us-central1 \
  --schedule="0 2 * * *" \
  --time-zone="UTC" \
  --uri="https://backup-service.a.run.app/backup" \
  --http-method=POST \
  --headers="Content-Type=application/json" \
  --message-body='{"type":"full","retention_days":30}' \
  --oidc-service-account-email=scheduler-sa@PROJECT.iam.gserviceaccount.com \
  --max-retry-attempts=3

Cache Invalidation

gcloud scheduler jobs create http cache-refresh \
  --location=us-central1 \
  --schedule="*/30 * * * *" \
  --uri="https://api.example.com/cache/invalidate" \
  --http-method=DELETE \
  --oidc-service-account-email=scheduler-sa@PROJECT.iam.gserviceaccount.com

Report Generation

gcloud scheduler jobs create http weekly-report \
  --location=us-central1 \
  --schedule="0 8 * * 1" \
  --time-zone="America/New_York" \
  --uri="https://reports.example.com/generate" \
  --http-method=POST \
  --message-body='{"report_type":"weekly_summary","recipients":["team@example.com"]}' \
  --oidc-service-account-email=scheduler-sa@PROJECT.iam.gserviceaccount.com \
  --max-retry-attempts=3 \
  --max-retry-duration=1800s

Required IAM Roles

# Cloud Scheduler Admin (create/manage jobs)
roles/cloudscheduler.admin

# Cloud Scheduler Viewer (read-only)
roles/cloudscheduler.viewer

Grant scheduler permissions:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:admin@example.com" \
  --role="roles/cloudscheduler.admin"

Troubleshooting

Job Not Triggering

# Check job status
gcloud scheduler jobs describe my-job --location=us-central1

# Verify schedule is correct
# Check time zone settings
# Ensure job is not paused

# View execution history in Cloud Logging
gcloud logging read "resource.type=cloud_scheduler_job AND resource.labels.job_id=my-job" --limit=10

Authentication Failures (401/403)

# Verify service account exists
gcloud iam service-accounts list | grep scheduler-sa

# Check service account has invoker role
gcloud run services get-iam-policy my-service --region=us-central1

# Verify OIDC configuration
gcloud scheduler jobs describe my-job --location=us-central1 | grep oidc

HTTP Errors

# View detailed error logs
gcloud logging read "resource.type=cloud_scheduler_job" --format="json" --limit=5

# Test endpoint manually
curl -X POST https://my-service.a.run.app/task \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)"

Missing Audience Error

For Cloud Run, ensure --oidc-token-audience matches the service URL exactly:

# Get exact service URL
gcloud run services describe SERVICE --region=REGION --format='value(status.url)'

# Use this URL for audience

Google Cloud Storage (GCS) Guide

This guide covers managing Cloud Storage buckets and objects using the gcloud CLI, including bucket creation, permissions, lifecycle policies, and data transfer.

Prerequisites

Enable the Cloud Storage API:

gcloud services enable storage.googleapis.com

Bucket Operations

Create Buckets

# Basic bucket (default settings)
gcloud storage buckets create gs://my-bucket-name

# With location
gcloud storage buckets create gs://my-bucket \
  --location=us-central1

# Multi-regional bucket
gcloud storage buckets create gs://my-global-bucket \
  --location=us

# With storage class
gcloud storage buckets create gs://archive-bucket \
  --location=us-central1 \
  --storage-class=COLDLINE

# With uniform bucket-level access (recommended)
gcloud storage buckets create gs://secure-bucket \
  --location=us-central1 \
  --uniform-bucket-level-access \
  --public-access-prevention

Bucket naming rules:

• Globally unique across all of GCS
• 3-63 characters
• Lowercase letters, numbers, hyphens, underscores
• Cannot start with "goog" prefix

Storage Classes

List Buckets

# List all buckets in project
gcloud storage buckets list

# With details
gcloud storage buckets list --format="table(name,location,storageClass)"

Describe Bucket

gcloud storage buckets describe gs://my-bucket

# Specific properties
gcloud storage buckets describe gs://my-bucket --format="value(location)"

Update Bucket

# Enable versioning
gcloud storage buckets update gs://my-bucket --versioning

# Disable versioning
gcloud storage buckets update gs://my-bucket --no-versioning

# Set default storage class
gcloud storage buckets update gs://my-bucket --default-storage-class=NEARLINE

Delete Bucket

# Delete empty bucket
gcloud storage buckets delete gs://my-bucket

# Delete bucket and all contents (use with caution!)
gcloud storage rm -r gs://my-bucket

Object Operations

Upload Files

# Upload single file
gcloud storage cp local-file.txt gs://my-bucket/

# Upload with specific name
gcloud storage cp local-file.txt gs://my-bucket/remote-name.txt

# Upload to subdirectory
gcloud storage cp local-file.txt gs://my-bucket/path/to/file.txt

# Upload directory recursively
gcloud storage cp -r ./local-directory gs://my-bucket/

# Upload with parallel processing
gcloud storage cp -r ./large-directory gs://my-bucket/ --parallel

Download Files

# Download single file
gcloud storage cp gs://my-bucket/file.txt ./local/

# Download directory
gcloud storage cp -r gs://my-bucket/directory ./local/

# Download matching pattern
gcloud storage cp gs://my-bucket/*.json ./downloads/

# Resume interrupted download
gcloud storage cp gs://my-bucket/large-file.zip ./local/ --resumable

List Objects

# List all objects
gcloud storage ls gs://my-bucket/

# List with details
gcloud storage ls -l gs://my-bucket/

# List recursively
gcloud storage ls -r gs://my-bucket/

# List with prefix filter
gcloud storage ls gs://my-bucket/logs/2024/

# List only directories
gcloud storage ls gs://my-bucket/ --format="value(name)" | grep '/$'

Move and Copy Objects

# Move within bucket
gcloud storage mv gs://my-bucket/old-path/file.txt gs://my-bucket/new-path/

# Copy between buckets
gcloud storage cp gs://source-bucket/file.txt gs://dest-bucket/

# Move between buckets
gcloud storage mv gs://source-bucket/file.txt gs://dest-bucket/

# Copy with metadata preservation
gcloud storage cp gs://source/file gs://dest/ --preserve-acl

Delete Objects

# Delete single object
gcloud storage rm gs://my-bucket/file.txt

# Delete multiple objects
gcloud storage rm gs://my-bucket/file1.txt gs://my-bucket/file2.txt

# Delete with pattern
gcloud storage rm gs://my-bucket/*.log

# Delete directory recursively
gcloud storage rm -r gs://my-bucket/directory/

# Delete all objects (keep bucket)
gcloud storage rm gs://my-bucket/**

Object Metadata

# View object metadata
gcloud storage objects describe gs://my-bucket/file.txt

# Update content type
gcloud storage objects update gs://my-bucket/file.txt \
  --content-type="application/json"

# Add custom metadata
gcloud storage objects update gs://my-bucket/file.txt \
  --custom-metadata="author=john,version=1.0"

Permissions

Bucket IAM

# View bucket policy
gcloud storage buckets get-iam-policy gs://my-bucket

# Grant read access
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="user:analyst@example.com" \
  --role="roles/storage.objectViewer"

# Grant write access
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:app@PROJECT.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

# Make bucket public (read-only)
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="allUsers" \
  --role="roles/storage.objectViewer"

# Remove access
gcloud storage buckets remove-iam-policy-binding gs://my-bucket \
  --member="user:former@example.com" \
  --role="roles/storage.objectViewer"

Common Storage Roles

Object-Level IAM

# Grant access to specific object
gcloud storage objects add-iam-policy-binding \
  gs://my-bucket/sensitive/report.pdf \
  --member="user:executive@example.com" \
  --role="roles/storage.objectViewer"

Lifecycle Management

Create Lifecycle Rules

Create lifecycle.json:

{
  "lifecycle": {
    "rule": [
      {
        "action": {"type": "Delete"},
        "condition": {"age": 30}
      },
      {
        "action": {
          "type": "SetStorageClass",
          "storageClass": "NEARLINE"
        },
        "condition": {"age": 90}
      },
      {
        "action": {
          "type": "SetStorageClass",
          "storageClass": "COLDLINE"
        },
        "condition": {"age": 365}
      }
    ]
  }
}

Apply lifecycle policy:

gcloud storage buckets update gs://my-bucket \
  --lifecycle-file=lifecycle.json

View Lifecycle Rules

gcloud storage buckets describe gs://my-bucket \
  --format="json(lifecycle)"

Remove Lifecycle Rules

# Create empty lifecycle file
echo '{"lifecycle": {"rule": []}}' > empty-lifecycle.json

gcloud storage buckets update gs://my-bucket \
  --lifecycle-file=empty-lifecycle.json

Common Lifecycle Patterns

Delete old logs:

{
  "lifecycle": {
    "rule": [
      {
        "action": {"type": "Delete"},
        "condition": {
          "age": 30,
          "matchesPrefix": ["logs/"]
        }
      }
    ]
  }
}

Archive and delete:

{
  "lifecycle": {
    "rule": [
      {
        "action": {"type": "SetStorageClass", "storageClass": "ARCHIVE"},
        "condition": {"age": 90}
      },
      {
        "action": {"type": "Delete"},
        "condition": {"age": 730}
      }
    ]
  }
}

Versioning

# Enable versioning
gcloud storage buckets update gs://my-bucket --versioning

# List object versions
gcloud storage ls --all-versions gs://my-bucket/file.txt

# Delete specific version
gcloud storage rm gs://my-bucket/file.txt#GENERATION_NUMBER

# Restore previous version (copy old version to current)
gcloud storage cp gs://my-bucket/file.txt#OLD_GENERATION gs://my-bucket/file.txt

Signed URLs

Generate temporary access URLs:

# Generate signed URL (requires service account key)
gcloud storage sign-url gs://my-bucket/file.txt \
  --duration=1h \
  --private-key-file=service-account-key.json

# For downloading
gcloud storage sign-url gs://my-bucket/file.txt \
  --duration=24h \
  --private-key-file=key.json \
  --http-verb=GET

# For uploading
gcloud storage sign-url gs://my-bucket/uploads/ \
  --duration=1h \
  --private-key-file=key.json \
  --http-verb=PUT

CORS Configuration

Create cors.json:

[
  {
    "origin": ["https://example.com"],
    "method": ["GET", "HEAD", "PUT", "POST"],
    "responseHeader": ["Content-Type"],
    "maxAgeSeconds": 3600
  }
]

Apply CORS:

gcloud storage buckets update gs://my-bucket --cors-file=cors.json

Data Transfer

Large-Scale Transfers

# Parallel upload for large datasets
gcloud storage cp -r ./large-data gs://my-bucket/ \
  --parallel \
  --content-type-inference

# Resume interrupted transfer
gcloud storage cp ./huge-file.zip gs://my-bucket/ --resumable

Sync Directories

# Sync local to bucket (upload new/changed files)
gcloud storage rsync ./local-dir gs://my-bucket/remote-dir

# Sync with delete (mirror)
gcloud storage rsync --delete-unmatched-destination-objects \
  ./local-dir gs://my-bucket/remote-dir

# Sync bucket to local
gcloud storage rsync gs://my-bucket/remote-dir ./local-dir

# Dry run
gcloud storage rsync --dry-run ./local-dir gs://my-bucket/remote-dir

Static Website Hosting

# Create bucket for website
gcloud storage buckets create gs://www.example.com \
  --location=us-central1 \
  --uniform-bucket-level-access

# Set main and error pages
gcloud storage buckets update gs://www.example.com \
  --web-main-page-suffix=index.html \
  --web-error-page=404.html

# Make public
gcloud storage buckets add-iam-policy-binding gs://www.example.com \
  --member="allUsers" \
  --role="roles/storage.objectViewer"

# Upload website files
gcloud storage cp -r ./website/* gs://www.example.com/

Notifications

# Create Pub/Sub topic
gcloud pubsub topics create gcs-notifications

# Create notification
gcloud storage buckets notifications create gs://my-bucket \
  --topic=gcs-notifications \
  --event-types=OBJECT_FINALIZE,OBJECT_DELETE

# List notifications
gcloud storage buckets notifications list gs://my-bucket

# Delete notification
gcloud storage buckets notifications delete gs://my-bucket \
  --notification-id=NOTIFICATION_ID

Troubleshooting

Access Denied

# Check bucket permissions
gcloud storage buckets get-iam-policy gs://my-bucket

# Check active account
gcloud auth list

# Verify account has correct role
gcloud projects get-iam-policy PROJECT_ID \
  --filter="bindings.members:$(gcloud config get-value account)"

Bucket Already Exists

# Bucket names are globally unique
# Try a more unique name:
gcloud storage buckets create gs://$(gcloud config get-value project)-my-bucket

Slow Transfers

# Use parallel processing
gcloud storage cp -r ./data gs://bucket/ --parallel

# Use composite uploads for large files
gcloud storage cp ./large-file.zip gs://bucket/ --resumable

Firebase Management Guide

This guide covers managing Firebase projects and services using both gcloud CLI and the Firebase CLI.

Understanding the Firebase/GCP Relationship

Firebase projects are Google Cloud projects with Firebase-specific services enabled. Management requires:

• gcloud CLI: For GCP infrastructure (Firestore, Cloud Storage, IAM, etc.)
• Firebase CLI: For Firebase-specific features (Hosting, Functions, Rules, etc.)

Firebase CLI Setup

Installation

# Via npm (recommended)
npm install -g firebase-tools

# Via standalone binary
curl -sL https://firebase.tools | bash

# Verify installation
firebase --version

Authentication

# Interactive login (opens browser)
firebase login

# Login without browser (for CI)
firebase login --no-localhost

# CI token generation
firebase login:ci
# Outputs token for CI_TOKEN environment variable

# Use token in CI
export FIREBASE_TOKEN="your-ci-token"
firebase deploy

Project Management

# List projects
firebase projects:list

# Set active project
firebase use PROJECT_ID

# Create project alias
firebase use --add
# Interactive: set alias like "production" or "staging"

# Switch between aliases
firebase use production
firebase use staging

Firebase Initialization

Initialize Firebase in your project directory:

firebase init

This creates:

• firebase.json: Project configuration
• .firebaserc: Project aliases
• Service-specific files (rules, functions directory, etc.)

Select features:

• Functions: Cloud Functions for Firebase
• Hosting: Static web hosting
• Firestore: Database rules and indexes
• Storage: Cloud Storage rules
• Emulators: Local development

Cloud Functions Deployment

Basic Function

Create functions/index.js:

const functions = require('firebase-functions');
const admin = require('firebase-admin');
admin.initializeApp();

// HTTP function
exports.helloWorld = functions.https.onRequest((req, res) => {
  res.json({ message: 'Hello from Firebase!' });
});

// Firestore trigger
exports.onUserCreate = functions.firestore
  .document('users/{userId}')
  .onCreate((snap, context) => {
    const user = snap.data();
    console.log('New user:', context.params.userId, user);
    return null;
  });

// Scheduled function
exports.dailyCleanup = functions.pubsub
  .schedule('every 24 hours')
  .onRun(async (context) => {
    console.log('Running daily cleanup');
    // Cleanup logic
    return null;
  });

Deploy Functions

# Deploy all functions
firebase deploy --only functions

# Deploy specific function
firebase deploy --only functions:helloWorld

# Deploy multiple functions
firebase deploy --only functions:helloWorld,functions:onUserCreate

Function Configuration

# Set environment config
firebase functions:config:set someservice.key="API_KEY" someservice.url="https://api.example.com"

# Get config
firebase functions:config:get

# Unset config
firebase functions:config:unset someservice.key

# Use in code:
# const config = functions.config();
# const apiKey = config.someservice.key;

Functions with Runtime Options

exports.memoryIntensive = functions
  .runWith({
    memory: '1GB',
    timeoutSeconds: 300,
    maxInstances: 10
  })
  .https.onRequest((req, res) => {
    // Heavy processing
  });

Firebase Hosting

Configuration

Edit firebase.json:

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "/api/**",
        "function": "api"
      },
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    "headers": [
      {
        "source": "**/*.@(js|css)",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "max-age=31536000"
          }
        ]
      }
    ]
  }
}

Deploy Hosting

# Deploy hosting only
firebase deploy --only hosting

# Deploy to specific site (multi-site setup)
firebase deploy --only hosting:my-site

# Preview before deploy
firebase hosting:channel:deploy preview --expires 7d

# Deploy with message
firebase deploy --only hosting -m "Release v1.2.0"

Serve Locally

# Serve hosting locally
firebase serve --only hosting

# Serve with functions
firebase serve --only hosting,functions

Security Rules Deployment

Firestore Rules

Create firestore.rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

    // Helper functions
    function isAuthenticated() {
      return request.auth != null;
    }

    function isOwner(userId) {
      return request.auth.uid == userId;
    }

    // Users collection
    match /users/{userId} {
      allow read: if isAuthenticated();
      allow write: if isOwner(userId);
    }

    // Public posts
    match /posts/{postId} {
      allow read: if true;
      allow create: if isAuthenticated()
        && request.resource.data.authorId == request.auth.uid;
      allow update, delete: if isAuthenticated()
        && resource.data.authorId == request.auth.uid;
    }

    // Admin-only collection
    match /admin/{document=**} {
      allow read, write: if request.auth.token.admin == true;
    }
  }
}

Deploy Rules

# Deploy Firestore rules
firebase deploy --only firestore:rules

# Deploy Storage rules
firebase deploy --only storage

# Deploy all rules
firebase deploy --only firestore:rules,storage

Storage Rules

Create storage.rules:

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {

    // User uploads
    match /users/{userId}/{allPaths=**} {
      allow read: if true;
      allow write: if request.auth.uid == userId
        && request.resource.size < 5 * 1024 * 1024
        && request.resource.contentType.matches('image/.*');
    }

    // Public assets
    match /public/{allPaths=**} {
      allow read: if true;
      allow write: if request.auth.token.admin == true;
    }
  }
}

Firestore Indexes

Create firestore.indexes.json:

{
  "indexes": [
    {
      "collectionGroup": "posts",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "authorId", "order": "ASCENDING" },
        { "fieldPath": "createdAt", "order": "DESCENDING" }
      ]
    }
  ],
  "fieldOverrides": []
}

Deploy indexes:

firebase deploy --only firestore:indexes

Firestore with gcloud

Export Data

# Export entire database
gcloud firestore export gs://my-bucket/firestore-backup

# Export specific collections
gcloud firestore export gs://my-bucket/firestore-backup \
  --collection-ids=users,posts

# Export to specific path
gcloud firestore export gs://my-bucket/backups/$(date +%Y%m%d)

Import Data

# Import from backup
gcloud firestore import gs://my-bucket/firestore-backup

# Import specific collections
gcloud firestore import gs://my-bucket/firestore-backup \
  --collection-ids=users

Manage Indexes with gcloud

# List indexes
gcloud firestore indexes composite list

# Create index
gcloud firestore indexes composite create \
  --collection-group=posts \
  --field-config=field-path=authorId,order=ascending \
  --field-config=field-path=createdAt,order=descending

# Delete index
gcloud firestore indexes composite delete INDEX_ID

Firebase Test Lab (gcloud)

Test mobile apps on real devices:

# Run Robo test on Android
gcloud firebase test android run \
  --app build/app-debug.apk \
  --device model=Pixel6,version=33,locale=en_US \
  --timeout 90s

# Run instrumentation test
gcloud firebase test android run \
  --app build/app-debug.apk \
  --test build/app-debug-androidTest.apk \
  --device model=Pixel6,version=33

# Run iOS test
gcloud firebase test ios run \
  --test build/ios_tests.zip \
  --device model=iphone13pro,version=15.2

Firebase Emulators

Configure Emulators

Edit firebase.json:

{
  "emulators": {
    "functions": {
      "port": 5001
    },
    "firestore": {
      "port": 8080
    },
    "hosting": {
      "port": 5000
    },
    "auth": {
      "port": 9099
    },
    "storage": {
      "port": 9199
    },
    "ui": {
      "enabled": true,
      "port": 4000
    }
  }
}

Start Emulators

# Start all emulators
firebase emulators:start

# Start specific emulators
firebase emulators:start --only functions,firestore

# Export data on shutdown
firebase emulators:start --export-on-exit=./emulator-data

# Import data on startup
firebase emulators:start --import=./emulator-data

CI/CD Integration

GitHub Actions

name: Deploy to Firebase

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        working-directory: ./functions
        run: npm ci

      - name: Deploy to Firebase
        uses: w9jds/firebase-action@master
        with:
          args: deploy --only functions,hosting
        env:
          FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

Cloud Build

Create cloudbuild.yaml:

steps:
  # Install dependencies
  - name: 'node:20'
    dir: 'functions'
    entrypoint: npm
    args: ['ci']

  # Deploy to Firebase
  - name: 'us-docker.pkg.dev/firebase-cli/us/firebase'
    args:
      - 'deploy'
      - '--project=$PROJECT_ID'
      - '--only=functions,hosting'
    env:
      - 'FIREBASE_TOKEN=${_FIREBASE_TOKEN}'

substitutions:
  _FIREBASE_TOKEN: ''

Multiple Environments

Using Aliases

# Set up aliases
firebase use --add
# Select dev project, alias: dev
firebase use --add
# Select prod project, alias: prod

# Deploy to specific environment
firebase use dev
firebase deploy

firebase use prod
firebase deploy

Environment-Specific Config

# Set config per environment
firebase use dev
firebase functions:config:set app.environment="development" app.debug="true"

firebase use prod
firebase functions:config:set app.environment="production" app.debug="false"

Required IAM Roles

For Firebase Admin

# Full Firebase access
roles/firebase.admin

# Firebase deployment
roles/firebase.developAdmin

# Firestore access
roles/datastore.owner

Grant Firebase Permissions

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:developer@example.com" \
  --role="roles/firebase.developAdmin"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:ci@PROJECT.iam.gserviceaccount.com" \
  --role="roles/firebase.admin"

Troubleshooting

Deployment Failures

# Check function logs
firebase functions:log

# Verbose deployment
firebase deploy --debug

# Check project configuration
firebase projects:list
cat .firebaserc

Rules Not Applied

# Deploy rules explicitly
firebase deploy --only firestore:rules

# Check deployed rules
# Visit Firebase Console > Firestore > Rules

Emulator Issues

# Clear emulator data
rm -rf ./emulator-data

# Start with fresh state
firebase emulators:start --clear-persistence

# Check ports
lsof -i :8080  # Firestore
lsof -i :5001  # Functions

Google Cloud CLI Installation on macOS

This guide covers installation of the Google Cloud CLI (gcloud) on macOS, including considerations for Apple Silicon and Python runtime dependencies.

Prerequisites

Python Runtime Foundation

The gcloud CLI requires Python 3.9–3.14. Verify your Python version:

python3 --version

Important: Avoid relying on system Python. Use a version manager like pyenv or Homebrew:

# Using Homebrew
brew install python@3.11

# Using pyenv
pyenv install 3.11.6
pyenv global 3.11.6

Xcode Command Line Tools

Required for some components:

xcode-select --install

Apple Silicon Considerations

For M1/M2/M3 Macs, ensure Rosetta 2 is installed for x86_64 binary compatibility:

softwareupdate --install-rosetta

Modern gcloud releases include native ARM64 binaries for most components.

Installation Methods

Method 1: Homebrew (Recommended)

The simplest installation method:

# Update Homebrew
brew update

# Install gcloud CLI
brew install --cask google-cloud-sdk

# Verify installation
gcloud --version

Note: When installed via Homebrew, the internal component manager is disabled. Use Homebrew for updates:

brew upgrade --cask google-cloud-sdk

Method 2: Interactive Script Installation

For more control over the installation:

# Download and run the installer
curl https://sdk.cloud.google.com | bash

# Restart shell or source the profile
exec -l $SHELL

# Initialize
gcloud init

The installer: 1. Detects OS and architecture (Darwin, arm64/x86_64) 2. Extracts SDK to ~/google-cloud-sdk 3. Modifies shell profile for PATH updates 4. Enables command autocompletion

Method 3: Versioned Archive (Deterministic)

For reproducible environments in CI/CD or team settings:

# Download specific version
VERSION="450.0.0"
ARCH="arm"  # or "x86_64" for Intel

curl -O "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-${VERSION}-darwin-${ARCH}.tar.gz"

# Extract to specific location
sudo tar -xzf google-cloud-cli-*.tar.gz -C /opt/

# Run install script
/opt/google-cloud-sdk/install.sh --quiet

# Add to PATH
echo 'source /opt/google-cloud-sdk/path.zsh.inc' >> ~/.zshrc
echo 'source /opt/google-cloud-sdk/completion.zsh.inc' >> ~/.zshrc

Shell Integration

Zsh (macOS default since Catalina)

The installer modifies ~/.zshrc. Verify these lines are present:

# The next line updates PATH for the Google Cloud SDK.
if [ -f '/path/to/google-cloud-sdk/path.zsh.inc' ]; then . '/path/to/google-cloud-sdk/path.zsh.inc'; fi

# The next line enables shell command completion for gcloud.
if [ -f '/path/to/google-cloud-sdk/completion.zsh.inc' ]; then . '/path/to/google-cloud-sdk/completion.zsh.inc'; fi

Bash

For Bash users, add to ~/.bash_profile or ~/.bashrc:

source '/path/to/google-cloud-sdk/path.bash.inc'
source '/path/to/google-cloud-sdk/completion.bash.inc'

Oh My Zsh Considerations

If using Oh My Zsh, add the gcloud plugin to ~/.zshrc:

plugins=(... gcloud)

Or ensure the SDK path is sourced before Oh My Zsh initialization.

Post-Installation Setup

Initialize gcloud

gcloud init

This interactive wizard: 1. Authorizes with your Google account 2. Selects or creates a configuration 3. Sets default project 4. Optionally sets default compute region/zone

For non-interactive initialization:

gcloud init --console-only

Install Additional Components

# List available components
gcloud components list

# Install common components
gcloud components install alpha beta kubectl gke-gcloud-auth-plugin

# Update all components
gcloud components update

Key components:

• alpha, beta: Preview features
• kubectl: Kubernetes management
• gke-gcloud-auth-plugin: GKE authentication
• bq: BigQuery CLI
• gsutil: Legacy Cloud Storage CLI (prefer gcloud storage)

Verify Installation

# Check version
gcloud --version

# View current configuration
gcloud config list

# Test API access
gcloud projects list

Environment Variables

Useful environment variables for customization:

# Force specific Python interpreter
export CLOUDSDK_PYTHON=/usr/local/bin/python3.11

# Set configuration directory
export CLOUDSDK_CONFIG=/custom/path/gcloud

# Set active configuration
export CLOUDSDK_ACTIVE_CONFIG_NAME=production

# Disable prompts (for scripting)
export CLOUDSDK_CORE_DISABLE_PROMPTS=1

Troubleshooting

Python Version Issues

If gcloud fails with Python errors:

# Check which Python gcloud is using
which python3

# Force specific Python
export CLOUDSDK_PYTHON=/path/to/python3.11

PATH Conflicts

If gcloud command not found after installation:

# Verify SDK path
echo $PATH | grep google-cloud-sdk

# Manually add to current session
export PATH="$PATH:$HOME/google-cloud-sdk/bin"

# Check for shadowing
which -a gcloud

Component Installation Failures on Apple Silicon

If components fail to install on M1/M2/M3:

# Ensure Rosetta is installed
softwareupdate --install-rosetta

# Try installing with architecture flag
arch -x86_64 gcloud components install COMPONENT

Homebrew Installation Issues

If Homebrew cask is outdated:

brew update
brew upgrade --cask google-cloud-sdk

# If issues persist, reinstall
brew uninstall --cask google-cloud-sdk
brew install --cask google-cloud-sdk

Uninstallation

Homebrew Installation

brew uninstall --cask google-cloud-sdk

Manual Installation

# Remove SDK directory
rm -rf ~/google-cloud-sdk

# Remove configuration directory
rm -rf ~/.config/gcloud

# Remove shell profile entries
# Edit ~/.zshrc or ~/.bash_profile to remove gcloud lines