Google Cloud

Installs the Google Cloud CLI (gcloud) and configures shell aliases and functions.

What it does

• Auto-installs and updates Google Cloud CLI to the latest release
• Installs the gke-gcloud-auth-plugin component for GKE authentication
• Adds ~/google-cloud-sdk/bin to PATH via ~/.profile.d/googlecloud.sh (available in login shells and WSL shims)
• Pins the gcloud configuration to default (guarded CLOUDSDK_ACTIVE_CONFIG_NAME export plus active_config normalization) so account and project selection stays env-var driven
• Keeps account, project, and region selection per-shell (CLOUDSDK_CORE_*) so terminals never collide, see Per-shell isolation
• Flags an expired gcloud login when you activate an account with gcp-account, pointing you at gcp-authenticate, see Expired credentials
• Bash tab completion for gcloud
• Shell functions for account, project, region, and kubeconfig management

Variables

Variable	Default	Description
googlecloud_cli_tmp_path	/tmp/gcloud/	Temporary directory for downloads
googlecloud_cli_install_path	~/google-cloud-sdk	Installation directory for Google Cloud SDK

Aliases

Alias	Command	Description
googlecloud	gcp-account	Show current GCP account info
gcp	gcp-account	Show current GCP account info

Functions

Function	Description
gcp-account	Show current account/project/region info (warns on expired credentials) or switch to a named account
gcp-authenticate	Authenticate with gcloud auth login and set active account
gcp-project	Show available projects or switch to a named project
gcp-region	Show available regions or switch to a named region
gcp-kubernetes	List GKE clusters in the current project
gcp-kubeconfig	Save a kubeconfig for a GKE cluster to ~/.kube/configs/<cluster>.yaml (--activate also switches the current shell to it)

Usage

Authenticate and switch accounts:

gcp-authenticate
gcp-account user@example.com my-project europe-west1

Save a kubeconfig for a GKE cluster:

gcp-kubeconfig my-cluster

Per-shell isolation

Account, project, and region selection lives in the CLOUDSDK_CORE_ACCOUNT, CLOUDSDK_CORE_PROJECT, and CLOUDSDK_CORE_REGION environment variables scoped to the current shell, never in gcloud's mutable active_config. The role pins the active configuration to default (a ~/.config/gcloud/active_config file plus a guarded CLOUDSDK_ACTIVE_CONFIG_NAME export), so a stray gcloud config set in one terminal cannot bleed into another. gcp-account, gcp-project, and gcp-region set those variables rather than writing to the shared config.

Because selection is env-var driven, every terminal holds its own account, project, and region. You can run several sessions at once, one terminal authenticated as your work account on a prod project, another on a personal account, a coding agent like Claude Code on a third, with no global gcloud config state for them to fight over. gcp-kubeconfig even bakes the active account into the kubeconfig's exec.env, so a saved GKE config keeps authenticating as the shell that created it. The starship prompt reads the same CLOUDSDK_CORE_* variables and shows the account, project, and region (☁️ <account> (<project>) (<region>)), so each shell visibly shows the Google Cloud it is on. This is the per-shell context isolation concept applied to Google Cloud.

Troubleshooting

My account or project keeps reverting

This role deliberately makes account and project selection env-var driven rather than relying on gcloud's mutable active_config file. It pins the active configuration to default (a ~/.config/gcloud/active_config file plus a guarded CLOUDSDK_ACTIVE_CONFIG_NAME export in ~/.profile.d/googlecloud.sh), so a stray gcloud config configurations activate won't stick across shells.

Switch account, project, and region with gcp-account, gcp-project, and gcp-region (which set the relevant CLOUDSDK_* variables) rather than gcloud config set. To use a different configuration for one command, set CLOUDSDK_ACTIVE_CONFIG_NAME in that shell; the guarded export only fills it in when unset.

Expired credentials

A saved GKE kubeconfig refreshes its own token through gke-gcloud-auth-plugin, but that only works while the account's gcloud login is still valid. Refresh tokens lapse when an org session-length policy expires them, when they are revoked, or after long inactivity, and until then gcloud fails silently and only a kubectl call makes it obvious.

gcp-account <account> forces a token refresh (gcloud auth print-access-token) every time you select an account, so a stale login surfaces then rather than mid-command. When a session policy has expired the login, gcloud runs its own reauth challenge inline at that point; if it can't prompt (a non-interactive shell, or a fully revoked token) gcp-account falls back to telling you to run gcp-authenticate <account>.

gke-gcloud-auth-plugin: executable not found

GKE auth needs the gke-gcloud-auth-plugin component, which this role installs, and it must be on the PATH. In a login shell that PATH comes from ~/.profile.d/googlecloud.sh; if the plugin still isn't found, source it (. ~/.profile.d/googlecloud.sh) or start a fresh login shell. When the caller is a Windows tool such as Lens, the lookup happens through the WSL shim instead, see the wsl role's troubleshooting for shims and WSLENV.