Kubeconfig et contextes Kubernetes : le guide complet

Un contexte Kubernetes associe un cluster, un utilisateur et un namespace en un seul raccourci nommé. C’est grâce aux contextes que vous pouvez basculer de votre cluster de dev à la production avec une seule commande — et c’est aussi à cause d’eux que vous risquez de déployer sur le mauvais cluster si vous ne vérifiez pas. Ce guide suit le parcours réel : obtenir un kubeconfig, comprendre son contenu, l’importer proprement, puis naviguer entre vos contextes.

Ce que vous allez apprendre

À la fin de ce guide, vous saurez :

• Identifier d’où vient un kubeconfig selon votre environnement (cloud, local, entreprise)
• Lire et comprendre la structure d’un fichier kubeconfig (clusters, users, contexts)
• Vérifier le contenu d’un kubeconfig reçu avant de l’utiliser
• Importer et fusionner un kubeconfig sans écraser votre configuration existante
• Naviguer entre contextes et namespaces (basculer, renommer, nettoyer)
• Sécuriser vos kubeconfigs (permissions, bonnes pratiques, pièges à éviter)

Obtenir un kubeconfig : les cas réels

Dans la majorité des environnements, on ne crée pas un kubeconfig à la main : on le reçoit ou on le génère via un outil. Voici les 5 sources les plus courantes.

Cluster local (kind / minikube / k3d)

Ces outils génèrent et ajoutent automatiquement un contexte dans votre kubeconfig à la création du cluster :

# kind
kind create cluster --name mon-cluster
kind export kubeconfig --name mon-cluster    # si besoin de ré-exporter

# minikube
minikube start
minikube update-context                      # mettre à jour après changement

# k3d
k3d cluster create mon-cluster
k3d kubeconfig get mon-cluster               # exporter dans un fichier séparé

Après création, kubectl config get-contexts affiche immédiatement le nouveau contexte.

Cluster managé (EKS / AKS / GKE)

La CLI du provider cloud génère le kubeconfig et l’ajoute dans ~/.kube/config :

# AWS EKS
aws eks update-kubeconfig --name mon-cluster --region eu-west-1

# Azure AKS
az aks get-credentials --resource-group mon-rg --name mon-cluster

# Google GKE
gcloud container clusters get-credentials mon-cluster --region europe-west1

Noms de contextes longs

Les providers cloud génèrent des noms de contextes longs et cryptiques (gke_projet1-europe-west1_prod, arn:aws:eks:eu-west-1:123456789:cluster/...). Renommez-les immédiatement après import — voir la section Renommer un contexte plus bas.

Cluster entreprise (on-prem)

Un administrateur vous fournit un fichier kubeconfig.yaml via un portail interne, un ticket, ou un coffre-fort de secrets. Dans ce cas, votre travail est de :

1. Stocker le fichier au bon endroit (~/.kube/configs/)
2. Inspecter son contenu avant de l’importer
3. Fusionner sans écraser votre configuration existante
4. Renommer le contexte avec un nom lisible
5. Tester la connexion et vos droits

Tout cela est couvert dans la section Importer un kubeconfig reçu.

Accès via OIDC / SSO (auth dynamique)

Certains kubeconfigs ne contiennent pas de token statique. La section users utilise un mécanisme exec: qui appelle un plugin d’authentification pour obtenir un jeton à la demande :

users:
- name: oidc-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubelogin
      args:
        - get-token
        - --oidc-issuer-url=https://login.example.com
        - --oidc-client-id=kubectl

Quand kubectl rencontre ce type de configuration, il lance la commande spécifiée et utilise le token retourné. Vous serez parfois redirigé vers une page de connexion dans votre navigateur.

Plugin d'auth à installer

Le mécanisme exec: nécessite que le plugin (ici kubelogin) soit installé sur votre machine. Si kubectl affiche error: executable kubelogin not found, installez le plugin indiqué par votre équipe plateforme.

Génération manuelle (cas admin)

En tant qu’administrateur, vous pouvez créer un kubeconfig à partir d’un certificat client, d’un token de ServiceAccount ou d’un mécanisme OIDC. Ces cas avancés sortent du périmètre de ce guide — en général, la plateforme vous fournit un kubeconfig prêt à l’emploi.

Comprendre le fichier kubeconfig

Le kubeconfig est le fichier de configuration central de kubectl. Chaque commande kubectl le lit pour savoir à quel cluster se connecter, avec quelle identité et dans quel namespace. Par défaut, il se trouve dans ~/.kube/config.

Structure du fichier

Un kubeconfig se compose de quatre sections :

apiVersion: v1
kind: Config
preferences: {}

clusters:                        # ➊ Les clusters accessibles
- cluster:
    server: https://api.dev.example.com:6443
    certificate-authority: /chemin/vers/ca-dev.crt
  name: cluster-dev
- cluster:
    server: https://api.prod.example.com:6443
    certificate-authority: /chemin/vers/ca-prod.crt
  name: cluster-prod

users:                           # ➋ Les identités
- name: dev-user
  user:
    client-certificate: /chemin/vers/dev-user.crt
    client-key: /chemin/vers/dev-user.key
- name: prod-user
  user:
    token: "eyJhbGciOiJSUzI1NiIs..."

contexts:                        # ➌ Les raccourcis cluster+user+namespace
- context:
    cluster: cluster-dev
    user: dev-user
    namespace: default
  name: dev
- context:
    cluster: cluster-prod
    user: prod-user
    namespace: production
  name: prod

current-context: dev             # ➍ Le contexte actif par défaut

Section	Rôle	Contient
clusters	Définir les clusters accessibles	URL de l’API server, certificat CA
users	Définir les identités	Tokens, certificats client, plugin exec: (OIDC)
contexts	Associer cluster + utilisateur + namespace	Raccourci nommé pour une connexion complète
current-context	Contexte actif	Nom du contexte utilisé par défaut

Glissez pour voir

Comment kubectl résout la connexion

Quand vous tapez kubectl get pods, voici ce qui se passe :

1. kubectl lit le current-context → obtient le nom du contexte (ex: dev)
2. Dans le contexte dev, il trouve : cluster=cluster-dev, user=dev-user, namespace=default
3. Il se connecte à https://api.dev.example.com:6443 avec les credentials de dev-user
4. Il interroge le namespace default

Si vous spécifiez --context=prod ou -n monitoring, ces valeurs écrasent celles du contexte pour cette commande uniquement.

Afficher le kubeconfig

# Vue masquée (tokens cachés)
kubectl config view

# Vue complète (tokens en clair — attention !)
kubectl config view --raw

Importer un kubeconfig reçu

Que vous receviez un fichier d’un admin, d’un portail cloud ou d’un collègue, suivez toujours cette procédure. Ne remplacez jamais ~/.kube/config par un copier-coller brutal.

Check rapide : inspecter avant d’importer

Avant d’intégrer un kubeconfig inconnu, vérifiez ce qu’il contient :

# Inspecter sans toucher à votre config existante
KUBECONFIG=~/Downloads/kubeconfig-client-x.yaml kubectl config view

Passez en revue ces points :

Élément à vérifier	Commande / champ	Ce que vous cherchez
Quel cluster ?	clusters[].name + clusters[].cluster.server	L’URL doit correspondre au cluster attendu
Quel mécanisme d’auth ?	users[].user.token / .client-certificate / .exec	Token statique, certificat, ou plugin OIDC
Quel contexte ?	contexts[].name	Nom lisible ou nom cloud long à renommer
Quel namespace par défaut ?	contexts[].context.namespace	Souvent vide → default sera utilisé

Glissez pour voir

Kubeconfig d'origine inconnue

Ne faites jamais confiance aveuglément à un kubeconfig reçu par email ou via un canal non sécurisé. Un fichier malicieux pourrait pointer vers un faux API server. Vérifiez toujours l’URL du cluster et la source du fichier.

Recette : importer proprement

1. Stockez le fichier dans un dossier dédié

   mkdir -p ~/.kube/configs
   mv ~/Downloads/kubeconfig-client-x.yaml ~/.kube/configs/client-x.yaml
   chmod 600 ~/.kube/configs/client-x.yaml

2. Inspectez ce qu’il contient

   KUBECONFIG=~/.kube/configs/client-x.yaml kubectl config get-contexts

3. Fusionnez avec votre config principale

   export KUBECONFIG=~/.kube/config:~/.kube/configs/client-x.yaml
   kubectl config view --flatten > ~/.kube/config.merged
   cp ~/.kube/config ~/.kube/config.backup
   mv ~/.kube/config.merged ~/.kube/config
   chmod 600 ~/.kube/config
   unset KUBECONFIG

4. Renommez le contexte si le nom est cryptique

   kubectl config get-contexts
   kubectl config rename-context gke_projet1-europe-west1_prod client-x-prod

5. Testez la connexion et vos droits

   kubectl --context=client-x-prod cluster-info
   kubectl --context=client-x-prod auth can-i get pods -A

Piège classique : KUBECONFIG qui persiste

Si vous exportez KUBECONFIG dans un terminal sans le remettre à zéro, toutes vos commandes kubectl utiliseront ce fichier — même si vous changez de répertoire. Faites toujours unset KUBECONFIG après la fusion.

Naviguer entre les contextes

Une fois vos kubeconfigs importés, vous avez plusieurs contextes disponibles. Voici comment les utiliser au quotidien.

Lister les contextes

kubectl config get-contexts

CURRENT   NAME              CLUSTER        AUTHINFO    NAMESPACE
*         dev               cluster-dev    dev-user    default
          prod              cluster-prod   prod-user   production
          client-x-prod     cluster-cx     cx-user     default

Le * dans la colonne CURRENT indique le contexte actif. Toutes vos commandes kubectl s’exécutent sur ce cluster.

Voir le contexte actif

kubectl config current-context

dev

Basculer de contexte

kubectl config use-context prod

Switched to context "prod".

Changement global

use-context modifie current-context dans votre fichier kubeconfig. Ce changement est global : tous vos terminaux sont affectés. Si vous travaillez avec plusieurs terminaux ouverts, pensez à kubectx/kubens ou Kubie pour plus de contrôle.

Utiliser un contexte temporairement

Pour exécuter une commande sur un autre cluster sans modifier le contexte actif :

kubectl --context=prod get pods -n monitoring

C’est la méthode la plus sûre pour une commande ponctuelle : le current-context reste inchangé.

Changer le namespace par défaut

Pour travailler par défaut dans un namespace différent sans changer de contexte :

kubectl config set-context --current --namespace=monitoring

Vérifiez le namespace actif :

kubectl config view --minify -o jsonpath='{..namespace}' && echo

Créer un contexte personnalisé

Créez un raccourci qui associe un cluster existant, un utilisateur et un namespace par défaut spécifique :

kubectl config set-context dev-monitoring \
  --cluster=cluster-dev \
  --user=dev-user \
  --namespace=monitoring

C’est utile quand vous travaillez souvent dans un namespace précis : le contexte dev-monitoring vous y place directement.

Renommer un contexte

Les noms générés par les clouds sont souvent longs et cryptiques :

gke_projet1-europe-west1_prod
arn:aws:eks:eu-west-1:123456789:cluster/my-cluster

Renommez-les pour plus de lisibilité :

kubectl config rename-context gke_projet1-europe-west1_prod prod-gke
kubectl config rename-context arn:aws:eks:eu-west-1:123456789:cluster/my-cluster staging-aws

Le cluster et l’utilisateur ne changent pas — seul le nom du contexte est modifié.

Supprimer un contexte

kubectl config delete-context ancien-contexte

Le cluster reste intact

Supprimer un contexte supprime uniquement la référence dans votre kubeconfig. Le cluster, l’utilisateur et leurs credentials restent dans le fichier. Pour nettoyer complètement, supprimez aussi le cluster et l’utilisateur :

kubectl config delete-cluster mon-cluster
kubectl config delete-user mon-user

Gérer plusieurs clusters

Quand le nombre de clusters grandit (dev, staging, prod, clients), il devient utile de séparer les kubeconfigs en fichiers distincts plutôt que de tout entasser dans ~/.kube/config.

Charger un fichier spécifique

La variable d’environnement KUBECONFIG pointe kubectl vers un fichier particulier :

Linux / macOS

# Utiliser un fichier spécifique
export KUBECONFIG=~/.kube/configs/client-x.yaml

# Fusionner plusieurs fichiers (séparés par :)
export KUBECONFIG=~/.kube/config:~/.kube/configs/client-x.yaml:~/.kube/configs/client-y.yaml

Pour rendre la fusion permanente, ajoutez la ligne export KUBECONFIG=... dans votre ~/.bashrc ou ~/.zshrc.

Windows

# Utiliser un fichier spécifique
$env:KUBECONFIG = "$HOME\.kube\configs\client-x.yaml"

# Fusionner plusieurs fichiers (séparés par ;)
$env:KUBECONFIG = "$HOME\.kube\config;$HOME\.kube\configs\client-x.yaml"

Vérification : après avoir défini KUBECONFIG, exécutez kubectl config get-contexts pour voir tous les contextes disponibles.

Organiser ses kubeconfigs

Adoptez une arborescence claire avec un nommage explicite :

~/.kube/
├── config                  # Fichier principal (contextes courants)
├── config.backup           # Sauvegarde
└── configs/
    ├── dev-k3s.yaml
    ├── staging-eks-eu.yaml
    ├── prod-gke-eu.yaml
    └── client-acme.yaml

Le nommage doit identifier l’environnement, le provider et la région : prod-gke-eu.yaml est immédiatement compréhensible.

Chargement automatique (avancé)

Pour charger automatiquement tous vos kubeconfigs au démarrage du shell, ajoutez dans votre ~/.bashrc ou ~/.zshrc :

export KUBECONFIG="$HOME/.kube/config$(find "$HOME/.kube/configs" -name '*.yaml' -printf ':%p' 2>/dev/null)"

Cette commande construit la variable KUBECONFIG avec le fichier principal suivi de tous les fichiers YAML du dossier configs/. Testez-la manuellement avant de la rendre permanente.

Sécuriser le kubeconfig

Le fichier kubeconfig contient des informations sensibles : un token ou un certificat client dans ce fichier donne un accès direct au cluster avec les permissions de l’utilisateur associé.

# Permissions restrictives — obligatoire
chmod 600 ~/.kube/config
chmod 600 ~/.kube/configs/*.yaml

Règles de sécurité kubeconfig

• Ne commitez jamais un kubeconfig dans un dépôt Git — un token suffit pour accéder au cluster.
• Sur machines partagées, verrouillez votre répertoire home (chmod 700 ~).
• Ne stockez pas de kubeconfigs dans ~/Downloads ou des répertoires accessibles par d’autres utilisateurs.
• Vérifiez régulièrement les tokens stockés : kubectl config view --raw montre les données sensibles en clair.
• En entreprise, stockez les kubeconfigs sensibles dans Vault, AWS Secrets Manager ou un gestionnaire de secrets équivalent.

Vérifier la connexion et les permissions

Après chaque import ou changement de contexte, testez systématiquement :

# Tester la connexion au cluster
kubectl cluster-info

# Vérifier vos permissions
kubectl auth can-i get pods
kubectl auth can-i create deployments

# Voir qui vous êtes
kubectl auth whoami

Résultat attendu pour cluster-info : l’URL de l’API server s’affiche. Si vous voyez une erreur de connexion, vérifiez que le cluster est démarré et que le kubeconfig pointe vers la bonne adresse.

Bonnes pratiques

Toujours vérifier le contexte avant une action critique

Le piège n°1 en Kubernetes : exécuter une commande sur le mauvais cluster. Prenez le réflexe de vérifier avant toute action destructive :

kubectl config current-context
# Puis seulement ensuite :
kubectl delete deployment mon-app -n production

Afficher le contexte dans le prompt

La meilleure protection est d’afficher en permanence le contexte actif dans votre prompt shell :

• kube-ps1 : plugin Bash/Zsh qui affiche (⎈|prod-cluster:monitoring) dans votre prompt
• Powerlevel10k : activez le segment kubecontext dans la configuration
• Starship : module kubernetes activé par défaut

(⎈|prod:monitoring) user@host:~$

Voir le mot prod en permanence rend les erreurs beaucoup plus difficiles.

En scripts et CI : toujours être explicite

Les contextes sont parfaits pour le travail interactif. En script ou pipeline CI, ne dépendez jamais du contexte courant :

# Mauvais : dépend de l'état global
kubectl get pods

# Bon : explicite et reproductible
kubectl --context=prod -n monitoring get pods

Mieux encore, utilisez un kubeconfig dédié en CI :

export KUBECONFIG=/path/to/ci-kubeconfig.yaml
kubectl get pods -n monitoring

Nettoyer les contextes obsolètes

Les contextes s’accumulent avec le temps. Faites le ménage régulièrement :

# Lister tous les contextes
kubectl config get-contexts -o name

# Supprimer un contexte obsolète
kubectl config delete-context ancien-contexte

# Sauvegarder avant de nettoyer
cp ~/.kube/config ~/.kube/config.bak

Dépannage

Symptôme	Commande de diagnostic	Cause probable	Solution
error: context "xxx" does not exist	kubectl config get-contexts	Nom incorrect ou kubeconfig non chargé	Vérifiez le nom exact et la variable KUBECONFIG
The connection to the server was refused	kubectl config view → vérifier server:	Cluster non démarré ou mauvaise URL	Vérifiez que le cluster tourne ; corrigez l’URL
error: You must be logged in	kubectl auth can-i get pods	Token expiré ou invalide	Régénérez le kubeconfig via le provider cloud
executable kubelogin not found	which kubelogin	Plugin OIDC/exec manquant	Installez le plugin indiqué dans la section exec:
certificate signed by unknown authority	kubectl config view --raw → vérifier CA	Certificat CA manquant ou proxy d’entreprise	Vérifiez le chemin certificate-authority
Commande sur le mauvais cluster	kubectl config current-context	Contexte non vérifié avant action	Installez kube-ps1 ; vérifiez systématiquement
Contextes manquants après merge	kubectl config get-contexts	KUBECONFIG non défini correctement	Vérifiez les chemins ; refaites --flatten
KUBECONFIG pollue un autre terminal	echo $KUBECONFIG	Variable exportée non nettoyée	unset KUBECONFIG pour revenir au défaut

Glissez pour voir

À retenir

• On ne crée presque jamais un kubeconfig à la main — on le reçoit (CLI cloud, admin plateforme, outil local).
• Avant d’utiliser un kubeconfig reçu, inspectez-le : URL du cluster, mécanisme d’auth, nom du contexte.
• Ne remplacez jamais ~/.kube/config brutalement — fusionnez avec KUBECONFIG=file1:file2 puis kubectl config view --flatten.
• Un contexte associe cluster + utilisateur + namespace — basculez avec use-context, ou utilisez --context= pour une commande ponctuelle.
• use-context est un changement global (tous les terminaux). Pour l’isolation par shell, utilisez Kubie.
• Sécurisez vos kubeconfigs : chmod 600, jamais dans Git, stockage en coffre-fort en entreprise.
• Pour basculer plus vite en interactif : kubectx/kubens.

Prochaines étapes

kubectx et kubens Basculer entre contextes et namespaces en une commande, avec alias et toggle.

Kubie : isolation par shell Alternative plus sûre pour le travail multi-terminal (contexte par shell).

Diagnostiquer avec kubectl Runbook de diagnostic : get, describe, logs et top en situation d'incident.

Installer et configurer kubectl Installation, autocomplétion et version skew policy.

×

📖 Voir la documentation →