CLOUDSDK_CONFIG pour l'isolation gcloud par projet

Le CLI gcloud stocke tout dans un seul répertoire : ~/.config/gcloud/. Un ensemble de credentials, une configuration active, un fichier Application Default Credentials — partagés entre toutes les fenêtres de terminal et tous les processus de votre machine. Lorsque vous exécutez gcloud config set project client-a, ce changement affecte toutes les autres sessions lisant depuis le même répertoire.

Cela fonctionne pour les configurations à projet unique. Pour le travail multi-projets, l’état partagé génère des erreurs d’authentification lors des changements de contexte.

La source du problème

L’état mutable global de gcloud signifie que changer de contexte dans un terminal affecte tous les autres terminaux. Quelques modes d’échec qui surviennent régulièrement sur des machines de conseil :

• Vous lancez un dbt build pour le Client A, vous changez votre contexte gcloud vers le Client B dans un autre terminal. Le build du Client A commence à échouer avec des erreurs de permissions à mi-chemin.
• Vous exécutez gcloud auth application-default login pour un nouveau client. Le fichier ADC est écrasé à l’échelle du système, cassant tout ce qui utilisait les credentials précédentes.
• Vous démarrez Claude Code dans un nouveau terminal et il récupère des credentials obsolètes du dernier projet contre lequel vous vous êtes authentifié.

AWS gère cela différemment — les profils sont nommés et il n’y a pas de contexte « actif » partagé qui fuit entre les sessions. Google a choisi l’état mutable global. CLOUDSDK_CONFIG est la porte de sortie.

Ce que fait CLOUDSDK_CONFIG

Définir CLOUDSDK_CONFIG vers un chemin de répertoire indique à gcloud d’utiliser ce répertoire comme intégralité de son état plutôt que ~/.config/gcloud/. Cela inclut :

• credentials.db — tokens OAuth pour le CLI gcloud
• application_default_credentials.json — fichier ADC utilisé par les bibliothèques clientes
• properties — configuration active (projet actif, compte, région)
• access_tokens.db — tokens d’accès mis en cache
• logs/ — journaux des commandes gcloud

Deux sessions de terminal utilisant des chemins CLOUDSDK_CONFIG différents ne peuvent pas interférer l’une avec l’autre. Elles utilisent un état complètement séparé. S’authentifier dans l’une n’a aucun effet sur l’autre.

# Terminal 1 : Client A
export CLOUDSDK_CONFIG="$HOME/.config/gcloud-acme"
gcloud auth login  # s'authentifie uniquement dans ~/.config/gcloud-acme/

# Terminal 2 : Client B — complètement indépendant
export CLOUDSDK_CONFIG="$HOME/.config/gcloud-globex"
gcloud auth login  # s'authentifie uniquement dans ~/.config/gcloud-globex/

Les quatre variables pour une isolation complète

CLOUDSDK_CONFIG seul ne suffit pas car gcloud et les bibliothèques clientes sont des systèmes distincts. Vous avez besoin de quatre variables fonctionnant ensemble :

Pourquoi deux variables de projet ? CLOUDSDK_CORE_PROJECT n’affecte que le CLI gcloud et ses compagnons. GOOGLE_CLOUD_PROJECT n’affecte que les bibliothèques clientes. Ce sont des systèmes indépendants. N’en définir qu’une seule fera que gcloud ciblera le bon projet tandis que dbt ciblera le mauvais, ou l’inverse. Voir GCP Application Default Credentials pour plus de détails sur l’existence séparée de ces deux systèmes d’authentification.

Configuration d’un nouveau client

Pour chaque projet client, créez un répertoire d’état gcloud dédié et activez les credentials dedans :

# Créer le répertoire de configuration isolé
mkdir -p ~/.config/gcloud-newclient

# Activer les credentials du compte de service dans ce répertoire uniquement
CLOUDSDK_CONFIG=~/.config/gcloud-newclient \
  gcloud auth activate-service-account \
  --key-file=~/.gcp-keys/newclient-sa.json

# Vérifier que ça fonctionne
CLOUDSDK_CONFIG=~/.config/gcloud-newclient \
  gcloud config list

Le préfixe inline CLOUDSDK_CONFIG= active la variable pour cette seule commande sans l’exporter vers toute votre session shell. Utile pour configurer des credentials sans charger un .envrc.

Une mise en garde

Le gke-gcloud-auth-plugin ne respecte pas CLOUDSDK_CONFIG. Si vous faites du travail Kubernetes, l’authentification GKE casse le pattern d’isolation car le plugin lit toujours depuis le ~/.config/gcloud/ global. Pour les workflows d’analytics engineering qui ne touchent pas Kubernetes, cela n’est pas pertinent. Mais si votre travail de conseil s’étend aux clusters GKE, sachez que vous avez besoin d’une stratégie séparée pour l’authentification Kubernetes.

Relation avec les configurations nommées

La documentation Google couvre les configurations nommées (gcloud config configurations create) comme mécanisme principal multi-projets, mais les configurations nommées partagent toujours le même magasin de credentials. Changer de configuration change le projet actif mais n’isole pas credentials.db ni le fichier ADC.

CLOUDSDK_CONFIG fournit une isolation plus profonde que les configurations nommées ne peuvent pas offrir. Il est couramment utilisé dans les contextes CI/CD et s’applique également aux workflows de conseil et d’agence.

La note direnv Multi-Client GCP Setup couvre l’automatisation avec direnv pour que les variables soient définies automatiquement par répertoire client.