direnv pour la gestion des credentials GCP multi-clients

Définir quatre variables d’environnement à chaque fois que vous changez de répertoire client devient rapidement fastidieux. direnv résout ce problème en chargeant les variables d’environnement automatiquement lorsque vous entrez dans un répertoire et en les déchargeant lorsque vous en sortez. Combiné avec le pattern d’isolation à quatre variables, chaque set de credentials client se charge quand vous faites cd dans leur projet et disparaît quand vous en sortez.

Comment fonctionne direnv

direnv est une extension de shell qui surveille les fichiers .envrc. Quand vous naviguez dans un répertoire contenant un .envrc, direnv le source et définit les variables d’environnement déclarées dans votre shell. Quand vous naviguez hors du répertoire, il annule les changements.

La première fois que vous entrez dans un répertoire avec un nouveau .envrc, direnv vous demande de le valider explicitement (direnv allow). Ensuite, il se charge automatiquement. Cette étape de sécurité empêche l’exécution arbitraire de code depuis des dépôts clonés.

Le pattern .envrc

Un .envrc complet pour un seul projet client ressemble à ceci :

export CLOUDSDK_CONFIG="$HOME/.config/gcloud-acme"
export CLOUDSDK_CORE_PROJECT=acme-analytics-prod
export GOOGLE_CLOUD_PROJECT=acme-analytics-prod
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcp-keys/acme-dbt-runner.json"

# Spécifique à dbt
export DBT_TARGET=prod
export DBT_PROFILES_DIR="$HOME/.dbt"

Quand vous faites cd dans ~/projects/acme-analytics/, direnv charge ces variables. Votre CLI gcloud, les bibliothèques clientes Python, dbt et tout ce qui lit les variables d’environnement GCP standard utiliseront les credentials Acme. Quand vous en sortez, elles sont déchargées.

Chaque répertoire client a son propre .envrc avec ses propres valeurs. Changer de client revient simplement à changer de répertoire.

Pourquoi quatre variables

Deux paires de variables gèrent deux systèmes indépendants :

Paire CLI gcloud :

CLOUDSDK_CONFIG — le répertoire contenant tout l’état gcloud (credentials, configuration, fichier ADC, logs)
CLOUDSDK_CORE_PROJECT — le projet par défaut pour les commandes gcloud

Paire bibliothèque cliente :

GOOGLE_APPLICATION_CREDENTIALS — chemin vers un fichier de clé de compte de service pour ADC
GOOGLE_CLOUD_PROJECT — le projet par défaut pour Python, dbt, Terraform et autres bibliothèques clientes

Omettre l’une des paires signifie que quelque chose cible le mauvais projet. Une configuration avec uniquement la paire gcloud fera pointer gcloud vers le bon client tandis que dbt run utilisera l’ADC qui se trouve défini globalement. Une configuration avec uniquement la paire bibliothèque cliente fait l’inverse. Voir GCP Application Default Credentials pour l’image complète sur pourquoi ces deux systèmes sont séparés.

Configurer un nouveau client

L’installation complète pour un nouveau client prend environ cinq minutes :

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

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

# 3. Créer le .envrc
cat > ~/projects/newclient-dbt/.envrc << 'EOF'
export CLOUDSDK_CONFIG="$HOME/.config/gcloud-newclient"
export CLOUDSDK_CORE_PROJECT=newclient-warehouse
export GOOGLE_CLOUD_PROJECT=newclient-warehouse
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcp-keys/newclient-sa.json"
export DBT_TARGET=prod
EOF

# 4. Valider le .envrc
direnv allow ~/projects/newclient-dbt

Après cela, naviguer dans le répertoire du projet fournit automatiquement les bons credentials sans aucune action supplémentaire requise.

Les agents IA héritent de ces variables

Une propriété particulièrement utile : Claude Code, Cursor et d’autres agents basés sur IDE héritent des variables d’environnement du shell qui les a lancés. Si vous démarrez Claude Code depuis l’intérieur d’un répertoire de projet où direnv a chargé le .envrc, l’agent obtient automatiquement le bon contexte GCP.

Cela signifie qu’un agent exécutant gcloud bq query ou déclenchant un build dbt utilisera les credentials du bon client sans configuration supplémentaire. L’agent n’a pas besoin de connaître la configuration des credentials — elle est ambiante, provenant du shell.

La limitation est que les agents ne peuvent pas rafraîchir les credentials quand ils expirent. Si une session dure suffisamment longtemps pour que les tokens expirent, l’agent échoue avec des erreurs d’authentification et vous devez redémarrer. Voir Contraintes d’authentification GCP pour les agents IA pour le comportement spécifique des différents agents concernant l’expiration des credentials.

Installation

direnv est disponible via la plupart des gestionnaires de paquets :

# macOS
brew install direnv

# Puis ajoutez à la configuration de votre shell (.zshrc ou .bashrc) :
eval "$(direnv hook zsh)"   # pour zsh
eval "$(direnv hook bash)"  # pour bash

Ce qui est déchargé

Quand vous naviguez hors d’un répertoire géré par direnv, toutes les variables exportées depuis ce .envrc sont supprimées de l’environnement de votre shell. Cela signifie :

CLOUDSDK_CONFIG revient à non défini (gcloud retourne à ~/.config/gcloud/)
GOOGLE_APPLICATION_CREDENTIALS revient à non défini
GOOGLE_CLOUD_PROJECT revient à non défini

Si vous avez un fallback global défini dans votre profil shell (.zshrc), ces valeurs reprennent. Si vous n’avez rien défini globalement, l’environnement est propre sans contexte GCP. L’un ou l’autre comportement est prévisible, ce qui est l’objectif.

Sécuriser les fichiers de clés

Le .envrc contient des chemins vers les fichiers de clés mais pas les fichiers de clés eux-mêmes. Conservez les fichiers de clés réels dans ~/.gcp-keys/ avec des permissions strictes et exclus de la synchronisation cloud. Les fichiers .envrc peuvent vivre en sécurité dans le contrôle de version puisqu’ils ne référencent que des chemins.

chmod 600 ~/.gcp-keys/newclient-sa.json

Le .envrc lui-même devrait généralement être dans .gitignore car il contient une configuration spécifique au client. Ou conservez-le dans le contrôle de version si vous souhaitez que le projet soit auto-documenté — les chemins dans .envrc n’ont d’importance que sur votre machine locale de toute façon.