Mémo — accéder à Kubernetes depuis Windows

Dernière mise à jour : 1er novembre 2026.

Ce guide permet de retrouver son accès au cluster Snag depuis un PC Windows avec Git Bash. Il ne contient aucun secret, adresse de serveur ni configuration privée.

À chaque nouvelle session

1. Ouvrir WireGuard et activer le tunnel personnel Snag.
2. Ouvrir Git Bash et exécuter :

export KUBECONFIG="$HOME/.kube/snag.yaml"
kubectl config get-contexts
kubectl -n snag-staging get pods

L'export s'applique uniquement au terminal courant : le refaire dans un nouveau terminal. L'astérisque dans la liste des contextes indique le contexte actif. Vérifier que c'est le cluster attendu avant toute commande.

Ces commandes consultent l'état du cluster sans le modifier. Pour terminer, désactiver le tunnel dans WireGuard si aucun autre accès privé n'est nécessaire.

Comprendre les deux accès

Élément	Rôle	Conservation
Tunnel WireGuard	Rend le réseau privé accessible depuis le PC	Application WireGuard ; configuration personnelle confidentielle
Kubeconfig	Indique le cluster et les informations d'authentification Kubernetes	Fichier local ~/.kube/snag.yaml ; copie sécurisée dans Vaultwarden
Autorisations Kubernetes	Déterminent ce que l'utilisateur peut consulter ou modifier	Gérées par l'administrateur du cluster

Un tunnel actif ne donne pas automatiquement des droits administrateur. Le VPS possède aussi ses propres identifiants de nœud : ne pas les copier sur un PC personnel.

Première installation

Installer WireGuard pour Windows et kubectl depuis leurs distributions officielles. La version de kubectl doit rester compatible avec celle du cluster (au plus une version mineure d'écart).

Si kubectl manque, depuis PowerShell :

winget install -e --id Kubernetes.kubectl

Rouvrir le terminal puis vérifier :

kubectl version --client

Préparer le tunnel WireGuard

L'administrateur fournit une configuration personnelle avec une adresse VPN attribuée au PC. Ne pas réutiliser celle d'un collègue.

Si une paire de clés personnelle existe déjà, la conserver. Sinon, avec WireGuard installé à son emplacement Windows habituel, exécuter une seule fois dans Git Bash :

WG="/c/Program Files/WireGuard/wg.exe"
umask 077
if [ -e "$HOME/wg-private.key" ] || [ -e "$HOME/wg-public.key" ]; then
  echo "Clés déjà présentes : ne pas les écraser."
else
  "$WG" genkey | tee "$HOME/wg-private.key" | "$WG" pubkey > "$HOME/wg-public.key"
fi

Transmettre uniquement la clé publique à l'administrateur :

cat ~/wg-public.key

Pour importer un fichier complet reçu par un canal sécurisé : enregistrer en snag.conf, puis WireGuard → Ajouter un tunnel → Importer depuis un fichier.

Pour un modèle : Ajouter un tunnel vide, nommer le tunnel snag, coller le modèle et remplacer le champ PrivateKey par la clé privée personnelle correspondant à la clé publique transmise. Le tunnel vide génère sa propre clé par défaut : ne pas la conserver si une autre clé publique a déjà été enregistrée côté serveur.

Conserver les valeurs réseau fournies par l'administrateur. Enregistrer, activer et vérifier une poignée de main récente (« Latest handshake »). Une interface seulement marquée active ne prouve pas que le serveur répond.

Installer le kubeconfig reçu dans Vaultwarden

Le document commence typiquement par apiVersion: v1, kind: Config et contient clusters, contexts et users. C'est un fichier YAML Kubernetes, pas un tunnel WireGuard.

Dans Git Bash :

mkdir -p ~/.kube
notepad.exe "$(cygpath -w "$HOME/.kube/snag.yaml")"

Coller la configuration complète dans le Bloc-notes en préservant les espaces et retours à la ligne. Enregistrer sous snag.yaml (type Tous les fichiers si nécessaire), pas snag.yaml.txt. Ne pas remplacer un accès existant sans conserver sa configuration en lieu sûr.

Activer WireGuard puis suivre les commandes de début de ce mémo. Le fichier reste hors des dépôts Git. Ne jamais publier son contenu, ses jetons, certificats privés ou clés, même dans une capture de diagnostic.

Lire l'état des services

État	Interprétation
1/1 Running	Le conteneur est démarré et déclaré prêt ; cela ne remplace pas un test fonctionnel de l'application
Completed et 0/1	Une tâche ponctuelle a terminé ; c'est généralement normal
Error	Une exécution a échoué ; consulter le Job et ses événements avant de conclure
Pending	Le démarrage attend une ressource ou une décision de placement
CrashLoopBackOff	Le conteneur échoue et Kubernetes tente de le redémarrer

Lors du premier accès confirmé le 1er novembre 2026, les services principaux visibles du staging étaient prêts. Trois anciens pods pricing-daily étaient en erreur : ce constat ne signifie pas qu'ils ont été corrigés, ni qu'une exécution récente échoue encore.

Diagnostic sans modification

kubectl config current-context
kubectl auth can-i list pods -n snag-staging
kubectl -n snag-staging get deployments
kubectl -n snag-staging get jobs
kubectl -n snag-staging get cronjobs
kubectl -n snag-staging get events --sort-by=.metadata.creationTimestamp

Pour examiner un pod, remplacer NOM_DU_POD par son nom :

kubectl -n snag-staging describe pod NOM_DU_POD
kubectl -n snag-staging logs NOM_DU_POD --tail=100

Les journaux peuvent contenir des informations privées : les examiner et les expurger avant tout partage.

Problème	Action
kubectl: command not found	Installer kubectl puis rouvrir le terminal
Fichier absent ou mauvais contexte	Vérifier le nom snag.yaml, son extension et refaire l'export KUBECONFIG
Erreur YAML	Reprendre le document complet de Vaultwarden sans altérer l'indentation
Timeout / réseau inaccessible	Vérifier tunnel, poignée de main et routes avec l'administrateur
Unauthorized	Faire vérifier ou renouveler les identifiants Kubernetes
Forbidden	L'accès est authentifié mais l'opération n'est pas autorisée : demander le droit nécessaire
Erreur de certificat TLS	Faire vérifier le kubeconfig et le certificat ; ne pas désactiver la vérification TLS

Déploiements et sécurité

Garder le circuit Git → revue de PR → Argo CD pour les ressources gérées par GitOps. Ce mémo n'autorise pas de modification directe, suppression, migration ni redémarrage de production.

Ne pas confondre le namespace snag-staging avec snag-prod, ni les services Kubernetes avec une pile Docker sur le VPS. Toujours vérifier la cible réelle.

En cas de perte du PC ou de suspicion de fuite, demander la révocation de l'accès WireGuard et des identifiants Kubernetes personnels, puis leur remplacement. Supprimer uniquement les fichiers locaux ne révoque pas les accès côté serveur.