/gcloud

gcloud CLI Usage

This document provides reference information for installing, authorizing, and configuring the Google Cloud SDK (gcloud CLI) in local and automated environments.

Installation

If the gcloud binary is not installed in the execution environment, refer to the authoritative Google Cloud CLI Installation Guide for platform-specific installation instructions (Linux, macOS, Windows, package managers, and container images).

Component Management

The gcloud components command group manages optional CLI components (such as additional tools, emulators, and language runtimes):

• List available components:

  gcloud components list

• Install a component:

  gcloud components install {component_id} --quiet

• Update all installed components:

  gcloud components update --quiet

(Note: If gcloud was installed via a system package manager like APT or DNF, use the system package manager to install components instead of gcloud components install.)

Authorization & Authentication

Authenticate the CLI with Google Cloud according to the operational environment:

• User Account (Interactive):

  gcloud auth login

  Follow the browser prompts to sign in and grant access.

• User Account (Headless Flow):

  For environments without an accessible web browser (containers, remote SSH):

  gcloud auth login --no-browser

  Copy the generated URL, open it on another machine to complete sign-in, and paste the authorization code back into the terminal.

• Application Default Credentials (ADC):

  Configures credentials for client libraries and local applications:

  gcloud auth application-default login

  Append --no-browser in headless environments.

• Service Account Key (Headless Automation):

  gcloud auth activate-service-account --key-file=path/to/key.json

  Security note: Restrict file permissions on JSON keys or prefer Workload Identity / Impersonation.

• Service Account Impersonation (Preferred for Development & Agents):

  Allows a user identity to temporarily assume a service account identity without storing long-lived private key files:

  gcloud config set auth/impersonate_service_account {service_account_email}

  Requires the roles/iam.serviceAccountTokenCreator role on the target service account. This enforces least privilege and ensures audited access under the target identity.

• Workload Identity Federation:

  For CI/CD and external compute environments (GitHub Actions, AWS, on-prem), authenticate using federated tokens without managing service account keys. See Authorizing the gcloud CLI.

Local Configuration Management

The gcloud config command group manages local configuration settings, profiles, and default properties.

Named Configurations

Configurations allow maintaining multiple isolated sets of properties (e.g., dev, staging, prod):

• Create a new configuration:

  gcloud config configurations create {config_name}

• List existing configurations:

  gcloud config configurations list

• Activate a configuration:

  gcloud config configurations activate {config_name}

Setting Common Properties

Properties set default values for flags across gcloud invocations:

• Set active project:

  gcloud config set core/project {project_id}

• Set default compute region and zone:

  gcloud config set compute/region {region}
  gcloud config set compute/zone {zone}

• View all active configuration properties:

  gcloud config list