Gcloud

Google Cloud SDK (gcloud) Skill

Comprehensive guide for working with the Google Cloud SDK (gcloud CLI) - the primary command-line interface for interacting with Google Cloud Platform services, managing resources, and automating cloud operations.

When to Use This Skill

Use this skill when you need to:

• Install and configure the Google Cloud SDK
• Authenticate with Google Cloud (user accounts, service accounts, ADC)
• Initialize gcloud and set up projects/configurations
• Manage multiple Google Cloud projects and environments
• Deploy applications to GCP (Compute Engine, GKE, App Engine, Cloud Run)
• Work with Cloud Storage, databases, and other GCP services
• Script gcloud commands for automation and CI/CD pipelines
• Troubleshoot authentication, authorization, or deployment issues
• Optimize gcloud command performance and output formatting
• Implement security best practices for cloud operations

Core Concepts

The gcloud CLI

Architecture:

• Command Structure: gcloud + [release-level] + component + entity + operation + [args] + [flags]
• Release Levels: alpha, beta, GA (general availability)
• Components: compute, container, app, sql, iam, config, auth, storage, etc.
• Global Flags: --project, --format, --filter, --quiet, --verbosity

Key Features:

• Unified CLI for 100+ Google Cloud services
• Consistent command patterns across all services
• Rich output formatting (JSON, YAML, CSV, table)
• Built-in filtering and server-side query optimization
• Interactive and non-interactive modes for automation

Authentication vs Authorization

Authentication (Who you are):

• User accounts (developers, admins)
• Service accounts (applications, automation)
• Application Default Credentials (ADC)
• OAuth 2.0, API keys, workload/workforce identity federation

Authorization (What you can do):

• IAM roles and permissions
• Service account impersonation
• Resource-level access control

Configuration Management

Named Configurations:

• Multiple configuration profiles for different environments
• Each configuration stores: account, project, region, zone, and other properties
• Switch between configurations instantly

Properties:

• 50+ configurable properties across 7 categories
• Precedence: CLI flags > env vars > config files > defaults

---

I. INSTALLATION & SETUP

A. Installation Methods

Linux (Archive Installation)

# Download (choose architecture)
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz

# Extract
tar -xf google-cloud-cli-linux-x86_64.tar.gz

# Install
./google-cloud-sdk/install.sh

# Initialize
./google-cloud-sdk/bin/gcloud init

Debian/Ubuntu (Package Manager)

# Add repo
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

# Import key
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

# Install
sudo apt-get update && sudo apt-get install google-cloud-cli

macOS

# Download installer
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz

# Extract and install
tar -xf google-cloud-cli-darwin-arm.tar.gz
./google-cloud-sdk/install.sh

Windows

# Download installer from https://cloud.google.com/sdk/docs/install
# Run GoogleCloudSDKInstaller.exe
# Follow installation wizard

B. Initialization

# Interactive setup (recommended for first-time)
gcloud init

# What it does:
# 1. Opens browser for OAuth authentication
# 2. Selects or creates a project
# 3. Sets default configuration (region, zone)
# 4. Stores credentials

# Non-interactive (CI/CD environments)
gcloud auth activate-service-account --key-file=key.json
gcloud config set project PROJECT_ID
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

C. Components

# List available components
gcloud components list

# Install additional components
gcloud components install kubectl        # Kubernetes CLI
gcloud components install app-engine-python  # App Engine
gcloud components install cloud-sql-proxy    # Cloud SQL Proxy
gcloud components install pubsub-emulator    # Pub/Sub emulator

# Update all components
gcloud components update

# Remove component
gcloud components remove COMPONENT_ID

Core Components (installed by default):

• gcloud - Main CLI
• gsutil - Cloud Storage utility
• bq - BigQuery CLI
• core - Core libraries

---

II. AUTHENTICATION & AUTHORIZATION

A. Authentication Methods

1. User Account (OAuth 2.0)

# Login with browser
gcloud auth login

# Login without browser (remote/headless)
gcloud auth login --no-browser

# Login with specific account
gcloud auth login user@example.com

# List authenticated accounts
gcloud auth list

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

# Revoke credentials
gcloud auth revoke user@example.com

2. Service Account

# Activate service account with key file
gcloud auth activate-service-account SA_EMAIL --key-file=path/to/key.json

# Create service account
gcloud iam service-accounts create SA_NAME \
  --display-name="Service Account Display Name"

# Create and download key
gcloud iam service-accounts keys create key.json \
  --iam-account=SA_EMAIL

# Grant IAM role
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/compute.admin"

3. Application Default Credentials (ADC)

# Setup ADC for client libraries
gcloud auth application-default login

# Setup ADC with service account impersonation
gcloud auth application-default login \
  --impersonate-service-account=SA_EMAIL

# Revoke ADC
gcloud auth application-default revoke

# ADC Search Order:
# 1. GOOGLE_APPLICATION_CREDENTIALS environment variable
# 2. ~/.config/gcloud/application_default_credentials.json
# 3. Metadata server (on GCP resources)

4. Service Account Impersonation (Recommended for Production)

# Impersonate for single command
gcloud compute instances list \
  --impersonate-service-account=SA_EMAIL

# Set default impersonation
gcloud config set auth/impersonate_service_account SA_EMAIL

# Verify impersonation
gcloud config get-value auth/impersonate_service_account

# Clear impersonation
gcloud config unset auth/impersonate_service_account

Why Impersonation?

• Short-lived temporary credentials (no persistent key risk)
• No need to distribute service account keys
• Centralized permission management
• Easy to audit and rotate

B. Configuration Profiles

Create and Manage Configurations

# Create new configuration
gcloud config configurations create dev

# List all configurations
gcloud config configurations list

# Activate configuration
gcloud config configurations activate dev

# Switch configuration for single command
gcloud compute instances list --configuration=prod

# Set properties
gcloud config set project my-project-dev
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

# View all properties
gcloud config list

# Unset property
gcloud config unset compute/zone

# Delete configuration
gcloud config configurations delete dev

Multi-Environment Pattern

# Development environment
gcloud config configurations create dev
gcloud config set project my-project-dev
gcloud config set account dev@example.com
gcloud config set compute/region us-central1

# Staging environment
gcloud config configurations create staging
gcloud config set project my-project-staging
gcloud config set auth/impersonate_service_account staging-sa@project.iam.gserviceaccount.com

# Production environment
gcloud config configurations create prod
gcloud config set project my-project-prod
gcloud config set auth/impersonate_service_account prod-sa@project.iam.gserviceaccount.com

# Switch environments
gcloud config configurations activate dev
gcloud config configurations activate prod

---

III. COMMON WORKFLOWS

A. Project Management

# List projects
gcloud projects list

# Create project
gcloud projects create PROJECT_ID --name="Project Name"

# Set active project
gcloud config set project PROJECT_ID

# Get current project
gcloud config get-value project

# Enable API
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com

# List enabled APIs
gcloud services list

# Describe project
gcloud projects describe PROJECT_ID

B. Compute Engine

# List instances
gcloud compute instances list

# Create instance
gcloud compute instances create my-instance \
  --zone=us-central1-a \
  --machine-type=e2-medium \
  --image-family=debian-11 \
  --image-project=debian-cloud \
  --boot-disk-size=10GB

# SSH into instance
gcloud compute ssh my-instance --zone=us-central1-a

# Copy files
gcloud compute scp local-file.txt my-instance:~/remote-file.txt \
  --zone=us-central1-a

# Stop instance
gcloud compute instances stop my-instance --zone=us-central1-a

# Delete instance
gcloud compute instances delete my-instance --zone=us-central1-a

C. Google Kubernetes Engine (GKE)

# Create cluster
gcloud container clusters create my-cluster \
  --zone=us-central1-a \
  --num-nodes=3 \
  --machine-type=e2-medium

# Get cluster credentials
gcloud container clusters get-credentials my-cluster --zone=us-central1-a

# List clusters
gcloud container clusters list

# Resize cluster
gcloud container clusters resize my-cluster \
  --num-nodes=5 \
  --zone=us-central1-a

# Delete cluster
gcloud container clusters delete my-cluster --zone=us-central1-a

D. Cloud Storage

# Create bucket
gsutil mb gs://my-bucket-name

# Upload file
gsutil cp local-file.txt gs://my-bucket-name/

# Download file
gsutil cp gs://my-bucket-name/file.txt ./

# List bucket contents
gsutil ls gs://my-bucket-name/

# Sync directory
gsutil rsync -r ./local-dir gs://my-bucket-name/remote-dir

# Set bucket permissions
gsutil iam ch user:user@example.com:objectViewer gs://my-bucket-name

# Delete bucket
gsutil rm -r gs://my-bucket-name

E. App Engine

# Deploy application
gcloud app deploy app.yaml

# View application
gcloud app browse

# View logs
gcloud app logs tail

# List versions
gcloud app versions list

# Delete version
gcloud app versions delete VERSION_ID

# Set traffic split
gcloud app services set-traffic SERVICE \
  --splits v1=0.5,v2=0.5

F. Cloud Run

# Deploy container
gcloud run deploy my-service \
  --image=gcr.io/PROJECT_ID/my-image:tag \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated

# List services
gcloud run services list

# Describe service
gcloud run services describe my-service --region=us-central1

# Delete service
gcloud run services delete my-service --region=us-central1

---

IV. SCRIPTING & AUTOMATION

A. Output Formats

# JSON (recommended for scripting)
gcloud compute instances list --format=json

# YAML
gcloud compute instances list --format=yaml

# CSV
gcloud compute instances list --format="csv(name,zone,status)"

# Table (default)
gcloud compute instances list --format=table

# Value (single field extraction)
gcloud config get-value project --format="value()"

# Custom format
gcloud compute instances list \
  --format="table(name,zone,machineType,status)"

B. Filtering

# Server-side filtering (more efficient)
gcloud compute instances list --filter="zone:us-central1-a"
gcloud compute instances list --filter="status=RUNNING"
gcloud compute instances list --filter="name~^web-.*"

# Multiple conditions
gcloud compute instances list \
  --filter="zone:us-central1 AND status=RUNNING"

# Negation
gcloud compute instances list --filter="NOT status=TERMINATED"

# Complex expressions
gcloud compute instances list \
  --filter="(status=RUNNING OR status=STOPPING) AND zone:us-central1"

C. Error Handling

#!/bin/bash

# Simple error check
if ! gcloud compute instances create my-instance; then
  echo "Failed to create instance"
  exit 1
fi

# Capture exit code
gcloud compute instances describe my-instance
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
  echo "Instance not found or error occurred"
  exit $EXIT_CODE
fi

# Capture stderr
ERROR_OUTPUT=$(gcloud compute instances create my-instance 2>&1)
if [ $? -ne 0 ]; then
  echo "Error: $ERROR_OUTPUT"
  exit 1
fi

# Validate before create (idempotent pattern)
if ! gcloud compute instances describe my-instance &>/dev/null; then
  gcloud compute instances create my-instance
else
  echo "Instance already exists, skipping creation"
fi

D. Retry Logic

#!/bin/bash

MAX_RETRIES=5
RETRY_DELAY=5

for i in $(seq 1 $MAX_RETRIES); do
  if gcloud compute instances create my-instance; then
    echo "Instance created successfully"
    exit 0
  else
    echo "Attempt $i failed, retrying in ${RETRY_DELAY}s..."
    sleep $RETRY_DELAY
    RETRY_DELAY=$((RETRY_DELAY * 2))  # Exponential backoff
  fi
done

echo "Failed after $MAX_RETRIES attempts"
exit 1

E. Batch Operations

#!/bin/bash

# Parallel instance creation
INSTANCES=("web-1" "web-2" "web-3")

for instance in "${INSTANCES[@]}"; do
  gcloud compute instances create "$instance" \
    --zone=us-central1-a \
    --machine-type=e2-medium \
    --async  # Run in background
done

# Wait for all operations to complete
gcloud compute operations list --filter="status=RUNNING" \
  --format="value(name)" | while read op; do
  gcloud compute operations wait "$op" --zone=us-central1-a
done

echo "All instances created"

F. CI/CD Integration

GitHub Actions

name: Deploy to GCP

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - id: auth
        uses: google-github-actions/auth@v1
        with:
          credentials_json: ${{ secrets.GCP_SA_KEY }}

      - name: Set up Cloud SDK
        uses: google-github-actions/setup-gcloud@v1

      - name: Deploy to Cloud Run
        run: |
          gcloud run deploy my-service \
            --image=gcr.io/${{ secrets.GCP_PROJECT_ID }}/my-image:${{ github.sha }} \
            --region=us-central1 \
            --platform=managed

GitLab CI

deploy:
  image: google/cloud-sdk:alpine
  script:
    - echo $GCP_SA_KEY | base64 -d > key.json
    - gcloud auth activate-service-account --key-file=key.json
    - gcloud config set project $GCP_PROJECT_ID
    - gcloud app deploy
  only:
    - main

---

V. BEST PRACTICES

A. Security

1. Never Commit Credentials

# Add to .gitignore
echo "key.json" >> .gitignore
echo ".config/gcloud/" >> .gitignore
echo "application_default_credentials.json" >> .gitignore

2. Use Service Account Impersonation

# Prefer impersonation over key files
gcloud config set auth/impersonate_service_account SA_EMAIL

# NOT: gcloud auth activate-service-account --key-file=key.json

3. Principle of Least Privilege

# Grant minimal required roles
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/compute.instanceAdmin.v1"  # Specific role, not "owner"

4. Rotate Keys Regularly

# Create new key
gcloud iam service-accounts keys create new-key.json \
  --iam-account=SA_EMAIL

# Delete old key
gcloud iam service-accounts keys delete KEY_ID \
  --iam-account=SA_EMAIL

B. Performance

1. Use Server-Side Filtering

# Good: Filter on server
gcloud compute instances list --filter="zone:us-central1"

# Bad: Filter locally with grep
gcloud compute instances list | grep us-central1

2. Limit Output

# Only fetch what you need
gcloud compute instances list --limit=10

# Project only needed fields
gcloud compute instances list --format="value(name,zone)"

3. Batch Operations

# Use --async for parallel operations
gcloud compute instances create instance-1 --async
gcloud compute instances create instance-2 --async
gcloud compute instances create instance-3 --async

C. Maintainability

1. Use Named Configurations

# Separate dev/staging/prod configurations
gcloud config configurations create dev
gcloud config configurations create prod

2. Document Commands

#!/bin/bash
# Purpose: Deploy application to Cloud Run
# Usage: ./deploy.sh [environment]
# Example: ./deploy.sh production

ENV=${1:-staging}
gcloud config configurations activate "$ENV"
gcloud run deploy my-service --image=gcr.io/project/image:latest

3. Use Environment Variables

# Make scripts portable
PROJECT_ID=${GCP_PROJECT_ID:-default-project}
REGION=${GCP_REGION:-us-central1}

gcloud config set project "$PROJECT_ID"
gcloud config set compute/region "$REGION"

D. Monitoring & Logging

# Enable audit logging
gcloud logging read "resource.type=gce_instance" \
  --limit=10 \
  --format=json

# Track command history
gcloud info --show-log

# Verbose output for debugging
gcloud compute instances create my-instance --verbosity=debug

---

VI. TROUBLESHOOTING

Common Issues

1. Authentication Failures

# Check current authentication
gcloud auth list

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

# Re-authenticate
gcloud auth login
gcloud auth application-default login

2. Permission Denied

# Check IAM permissions
gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:user@example.com"

# Check service account permissions
gcloud iam service-accounts get-iam-policy SA_EMAIL

3. Quota Exceeded

# Check quota usage
gcloud compute project-info describe --project=PROJECT_ID

# Request quota increase via Cloud Console

4. Network Issues

# Check connectivity
gcloud info

# Use proxy
gcloud config set proxy/type http
gcloud config set proxy/address PROXY_HOST
gcloud config set proxy/port PROXY_PORT

5. Configuration Issues

# View current configuration
gcloud config list

# Reset configuration
gcloud config configurations delete default
gcloud init

---

VII. QUICK REFERENCE

Essential Commands

Global Flags

Common Properties

# Core
gcloud config set project PROJECT_ID
gcloud config set account EMAIL
gcloud config set disable_usage_reporting true

# Compute
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

# Container
gcloud config set container/cluster CLUSTER_NAME

# App Engine
gcloud config set app/cloud_build_timeout 1200

---

VIII. RESOURCES

Official Documentation

• gcloud CLI Reference: https://cloud.google.com/sdk/gcloud/reference
• Installation Guide: https://cloud.google.com/sdk/docs/install
• Authentication Guide: https://cloud.google.com/docs/authentication
• Cheatsheet: https://cloud.google.com/sdk/docs/cheatsheet
• Scripting Guide: https://cloud.google.com/sdk/docs/scripting-gcloud

Tools

• Cloud Console: https://console.cloud.google.com
• Cloud Shell: Browser-based shell with gcloud pre-installed
• Cloud Code: IDE extensions (VS Code, IntelliJ)

Best Practices Summary

1. Authentication: Use service account impersonation instead of key files 2. Configuration: Use named configurations for multiple environments 3. Security: Grant minimal IAM permissions, rotate keys regularly 4. Performance: Use server-side filtering, batch operations with --async 5. Scripting: Output JSON format, implement error handling and retries 6. Automation: Use environment variables, validate before operations 7. Monitoring: Enable Cloud Audit Logs, track command history 8. Maintenance: Keep SDK updated, document scripts thoroughly

---

Common Use Cases

Multi-Environment Deployment

• Separate configurations for dev/staging/prod
• Service account impersonation for each environment
• Automated deployments via CI/CD

Infrastructure as Code

• Create resources with gcloud in shell scripts
• Export configurations as YAML/JSON
• Version control infrastructure commands

Data Pipeline Automation

• Scheduled BigQuery jobs
• Cloud Storage file transfers
• Pub/Sub message processing

Security Compliance

• Audit logging for all operations
• Encrypted data at rest and in transit
• Regular key rotation and access reviews

---

This skill provides comprehensive gcloud CLI knowledge for implementing Google Cloud solutions, from basic authentication to advanced automation workflows. Always refer to official documentation for the latest features and service-specific details.

Google Cloud SDK Detailed Guides

This document provides links to comprehensive guides created from exploring Google Cloud SDK documentation.

Available Guides

All detailed guides are located in the /docs directory at the project root.

Installation & Setup

• Installation Guide (docs/google-cloud-sdk-installation-guide.md)
• Installation methods for all platforms (Linux, macOS, Windows)
• Prerequisites and dependencies
• Post-installation configuration
• Troubleshooting installation issues
• Complete with SHA256 checksums and package sizes

Authentication & Authorization

• Authentication Guide (docs/GOOGLE_CLOUD_AUTHENTICATION_COMPREHENSIVE_REPORT.md)
• All authentication methods (ADC, OAuth, Service Accounts, API Keys)
• Security ranking and recommendations
• Workload and Workforce Identity Federation
• Token management and best practices

• Authorization Guide (docs/gcloud-authorization-guide.md)
• User account authentication
• Service account impersonation (recommended)
• Workload/Workforce Identity Federation
• ADC setup procedures
• Best practices and troubleshooting

Configuration Management

• Initialization Guide (docs/gcloud-initialization-guide.md)
• How to initialize gcloud
• Project setup and management
• Account setup procedures
• Default settings and configuration

• Configuration Management Guide (docs/gcloud-config-management-guide.md)
• Named configurations for multiple environments
• Configuration switching methods
• Properties system (50+ properties)
• Integration with Docker, Terraform, CI/CD

Command Reference

• Cheatsheet (docs/gcloud-cheatsheet-comprehensive-guide.md)
• 60+ gcloud commands organized by service
• Command patterns and structure
• 38+ real-world usage examples
• Global flags and filtering

Scripting & Automation

• Scripting Guide (docs/gcloud-scripting-guide.md)
• Output formats (JSON, YAML, CSV, Table, Value, Custom)
• Server-side and client-side filtering
• Error handling patterns (7 distinct patterns)
• Automation best practices
• Advanced scripting patterns
• Security considerations

API Integration

• Client Libraries Best Practices (docs/google-cloud-api-client-libraries-best-practices.md)
• Authentication with client libraries
• API usage patterns
• Error handling and retry logic
• Performance optimization
• Language-specific guidance (Python, Node.js, Java, Go)
• Security best practices

Components & Tools

• Components Guide (docs/google-cloud-sdk-components-guide.md)
• Core and additional components
• Component management (install, update, remove)
• Package manager integration (APT, YUM)
• Use cases and troubleshooting

Advanced Topics

• Advanced Topics (docs/gcloud-advanced-topics.md)
• Production deployment patterns
• Security hardening
• CI/CD integration
• Enterprise deployment
• Performance optimization

Navigation

Quick Start (5 minutes)

1. Read SKILL.md (this skill file) 2. Follow Installation Guide for your platform 3. Run gcloud init to set up

Developer Setup (30 minutes)

1. Installation Guide 2. Initialization Guide 3. Authentication Guide 4. Configuration Management Guide 5. Cheatsheet for quick reference

Production Deployment (2-3 hours)

1. Installation Guide 2. Authentication Guide (focus on service accounts) 3. Authorization Guide (focus on impersonation) 4. Configuration Management Guide (multi-environment setup) 5. Advanced Topics (security and CI/CD sections)

DevOps/SRE Setup (3 hours)

1. All guides above 2. Scripting Guide (automation patterns) 3. Client Libraries Best Practices 4. Advanced Topics (complete)

Documentation Statistics

• Total Documentation: ~200+ KB across 15+ files
• Code Examples: 150+ production-ready examples
• Commands Documented: 100+ gcloud commands
• Topics Covered: 50+ major topics
• Sections: 100+ detailed sections

Key Takeaways

Authentication Priority

1. Application Default Credentials (ADC) - Recommended for applications 2. Service Account Impersonation - Recommended for development/production 3. Workload Identity Federation - For external systems (no keys) 4. User Credentials - For interactive development only 5. Avoid Service Account Keys - Static credentials are security risk

Configuration Strategy

• Use named configurations for multiple environments
• Properties have clear precedence: CLI flags > env vars > config files > defaults
• Switch configurations instantly with gcloud config configurations activate

Scripting Best Practices

• Use JSON output format for parsing
• Implement server-side filtering for efficiency
• Add error handling with exponential backoff
• Use --async for parallel operations
• Implement idempotent operations (check before create)

Security Requirements

• Never commit credentials to version control
• Use service account impersonation instead of key files
• Grant minimal IAM permissions (least privilege)
• Rotate keys regularly (90 days recommended)
• Enable Cloud Audit Logs for compliance

Additional Resources

Official Documentation

• gcloud CLI Reference: https://cloud.google.com/sdk/gcloud/reference
• Installation Guide: https://cloud.google.com/sdk/docs/install
• Authentication Guide: https://cloud.google.com/docs/authentication
• Best Practices: https://cloud.google.com/docs/enterprise/best-practices-for-enterprise-organizations

Tools

• Cloud Console: https://console.cloud.google.com
• Cloud Shell: Browser-based shell with gcloud pre-installed
• Cloud Code: IDE extensions for VS Code and IntelliJ

---

Note: All referenced documentation files are located in the /docs directory of this project. These guides are comprehensive, production-ready, and regularly updated based on official Google Cloud documentation.