Dépannage des Certificate Signing Request Kubernetes : guide pratique

Introduction

Le dépannage des Certificate Signing Request (CSR) Kubernetes est une compétence essentielle pour les opérateurs qui gèrent des clusters sécurisés. Les CSR sont le mécanisme par lequel les nœuds, les services et les utilisateurs obtiennent des certificats signés par le plan de contrôle Kubernetes. Lorsqu’une CSR reste bloquée à l’état Pending, est rejetée ou ne produit pas un certificat valide, l’impact peut aller d’un simple pod qui échoue à s’authentifier à un nœud entier incapable de rejoindre le cluster.

Ce guide propose une approche structurée et pratique pour diagnostiquer et résoudre les problèmes de CSR. Il couvre l’inventaire de la version et de l’environnement, les chemins de configuration sûrs, les étapes de vérification, les modes de défaillance courants et une liste de contrôle opérationnelle finale. Chaque recommandation inclut des commandes concrètes, les sorties attendues, les signaux d’échec et les décisions de récupération.

Le public visé est constitué des développeurs, des ingénieurs DevOps et des équipes techniques de startups qui doivent passer d’un problème observé à une résolution vérifiée sans deviner. L’objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d’impact, protéger les données sensibles, vérifier les résultats et documenter les chemins de récupération.

Inventaire de la version et de l’environnement

Avant de toucher à une CSR, vous devez connaître votre version de Kubernetes, l’implémentation du cycle de vie des CSR et l’état précis du cluster. Commencez par des observations en lecture seule. Notez la sortie et l’horodatage. Ne modifiez jamais de ressources avant de comprendre le rayon d’impact.

Étape 1 : Identifier la version de Kubernetes et l’API CSR

La fonctionnalité CSR a évolué. Dans Kubernetes v1.19 et versions ultérieures, l’API certificates.k8s.io/v1 est stable. Dans les versions antérieures, v1beta1 peut encore être utilisée. Le champ signerName est obligatoire en v1. Exécutez :

kubectl version --short

Sortie attendue (exemple) :

Client Version: v1.27.3
Kustomize Version: v4.5.7
Server Version: v1.27.3

Si la version du serveur est inférieure à v1.19, vous utilisez peut-être des CSR v1beta1. Vérifiez avec :

kubectl api-versions | grep certificates.k8s.io

Attendu :

certificates.k8s.io/v1

Si seul v1beta1 apparaît, prévoyez une mise à niveau ou utilisez la version d’API appropriée dans vos manifestes.

Étape 2 : Vérifier les prérequis du cluster

L’approbation des CSR nécessite que le contrôleur de gestion ait des signataires configurés. Exécutez :

kubectl get clusterrolebinding system:node -o yaml | grep -A5 roleRef

Vous devriez voir une liaison vers le rôle de cluster system:node. Vérifiez également les journaux du contrôleur de gestion pour les erreurs de signataire :

kubectl logs -n kube-system kube-controller-manager-<master-node> | grep -i csr

Remplacez <master-node> par le nom de votre nœud maître. Notez toute erreur concernant des noms de signataires non reconnus.

Étape 3 : Inventorier les CSR actuelles

Listez toutes les CSR et leurs états :

kubectl get csr --sort-by=.metadata.creationTimestamp

Sortie attendue (exemple) :

NAME        AGE   SIGNERNAME                     REQUESTOR          CONDITION
csr-abcde   30m   kubernetes.io/kube-apiserver-client   system:admin      Approved,Issued
csr-fghij   5m    kubernetes.io/kubelet-serving    system:node:node1   Pending

Vérifiez l’état détaillé d’une CSR en attente :

kubectl describe csr csr-fghij

Recherchez les événements et les conditions. Une CSR en attente sans événements signifie souvent qu’aucun approbateur n’est configuré.

Étape 4 : Vérifier le support des signataires

Chaque signataire a des exigences spécifiques. Listez les signataires disponibles dans le cluster :

kubectl get --raw /apis/certificates.k8s.io/v1/signers

Cela peut ne pas être autorisé dans tous les clusters. Sinon, vérifiez les indicateurs du contrôleur de gestion :

kubectl get pods -n kube-system kube-controller-manager-<master-node> -o yaml | grep -A2 'cluster-signing-cert-file'

Si aucun certificat de signature n’est configuré, les CSR ne peuvent pas être signées. C’est un problème d’environnement critique.

Contrôle pratique pour l’inventaire de la version et de l’environnement

• Commencez par des commandes en lecture seule : kubectl version, kubectl get csr.
• Capturez l’état actuel dans un fichier : kubectl get csr -o yaml > csr-backup-$(date +%Y%m%d%H%M%S).yaml.
• Protégez les identifiants : n’incluez jamais --token ou --certificate-authority dans les journaux.
• Modifiez un élément ciblé à la fois, par exemple, appliquez un seul manifeste de CSR.

Chemin de configuration sûr

La modification de la configuration liée aux CSR doit suivre un chemin sûr : plus petit changement, vérification et plan de restauration. Cette section couvre la création, l’approbation et la signature de CSR en toute sécurité.

Étape 1 : Créer une CSR de test avec une clé connue

Générez une clé privée et une CSR pour un utilisateur de test :

openssl req -new -newkey rsa:2048 -nodes -keyout test-user.key -out test-user.csr -subj "/CN=test-user/O=dev-team"

Encodez la CSR en base64 :

cat test-user.csr | base64 | tr -d '\n'

Créez un manifeste Kubernetes CSR test-user-csr.yaml :

apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
  name: test-user-csr
spec:
  request: <BASE64_ENCODED_CSR>
  signerName: kubernetes.io/kube-apiserver-client
  usages:
  - client auth

Appliquez-le :

kubectl apply -f test-user-csr.yaml

Vérifiez :

kubectl get csr test-user-csr

Attendu : condition Pending.

Étape 2 : Approuver la CSR (petit changement)

N’approuvez que si vous avez l’intention d’accorder le certificat. Utilisez kubectl certificate approve :

kubectl certificate approve test-user-csr

Sortie attendue :

certificatesigningrequest.certificates.k8s.io/test-user-csr approved

Vérifiez l’état :

kubectl get csr test-user-csr

Attendu :

NAME            AGE   SIGNERNAME                     REQUESTOR          CONDITION
test-user-csr   2m    kubernetes.io/kube-apiserver-client   system:admin      Approved,Issued

Étape 3 : Récupérer et vérifier le certificat

Obtenez le certificat émis :

kubectl get csr test-user-csr -o jsonpath='{.status.certificate}' | base64 --decode > test-user.crt

Inspectez-le :

openssl x509 -in test-user.crt -noout -text

Vérifiez que le CN du sujet correspond à l’utilisateur demandé et que les dates de validité sont correctes.

Étape 4 : Refuser une CSR (si nécessaire)

Pour refuser :

kubectl certificate deny test-user-csr

Attendu :

certificatesigningrequest.certificates.k8s.io/test-user-csr denied

Les CSR refusées ne peuvent pas être approuvées ultérieurement sans suppression et recréation.

Contrôle pratique pour le chemin de configuration sûr

• Testez d’abord dans un espace de noms non production si possible.
• Utilisez des noms de CSR descriptifs pour éviter toute confusion.
• Gardez les clés privées en sécurité : stockez test-user.key dans un gestionnaire de secrets, pas dans le contrôle de version.
• Vérifiez la chaîne de certificats émise avec openssl verify.

Vérification et diagnostics

Après tout changement, vérifiez que l’état attendu est atteint. Cette section fournit des commandes pour confirmer la santé des CSR et diagnostiquer les problèmes courants.

Étape 1 : Vérifier les conditions des CSR

Une CSR saine doit avoir les conditions Approved et Issued. Utilisez :

kubectl get csr <csr-name> -o jsonpath='{.status.conditions}'

Sortie attendue (exemple) :

[{"lastUpdateTime":"2023-10-01T12:00:00Z","message":"This CSR was approved by kubectl certificate approve.","reason":"KubectlApprove","status":"True","type":"Approved"},{"lastUpdateTime":"2023-10-01T12:00:01Z","message":"Certificate fetched and issued successfully","reason":"CertificateFetched","status":"True","type":"Issued"}]

Si seule Approved est présente mais pas Issued, le signataire a peut-être échoué. Vérifiez les journaux du contrôleur de gestion.

Étape 2 : Inspecter les détails d’une CSR

kubectl describe csr <csr-name>

Recherchez des événements tels que :

Events:
  Type    Reason   Age   From          Message
  ----    ------   ----  ----          -------
  Normal  Approved 10m   kube-controller-manager  Approved
  Warning SigningError 10m  kube-controller-manager  Failed to sign: x509: unknown signer

Une SigningError indique que le signerName de la CSR n’est pas pris en charge par le contrôleur.

Étape 3 : Vérifier la configuration du signataire

Vérifiez que le contrôleur de gestion possède les bons indicateurs de signature :

kubectl get pod -n kube-system kube-controller-manager-<master-node> -o yaml | grep -E 'cluster-signing'

Lignes attendues :

- --cluster-signing-cert-file=/etc/kubernetes/pki/ca.crt
- --cluster-signing-key-file=/etc/kubernetes/pki/ca.key

Si ces indicateurs sont absents, le contrôleur ne peut pas signer les CSR.

Étape 4 : Diagnostiquer les CSR en attente sans conditions

Si une CSR reste Pending sans conditions, aucun approbateur ne la surveille. Vérifiez les autorisations d’approbation :

kubectl auth can-i approve certificatesigningrequests --as=system:admin

Pour une approbation automatisée, assurez-vous qu’un contrôleur tel que cert-manager est installé et dispose des autorisations RBAC.

Contrôle pratique pour la vérification et les diagnostics

• Comparez toujours l’état actuel avec la sortie attendue.
• Utilisez kubectl describe pour les événements ; ils contiennent souvent la cause racine.
• Consultez les journaux de kube-controller-manager pour les erreurs de signataire.
• Vérifiez la validité du certificat avec openssl x509 -dates -noout.

Modes de défaillance et récupération

Les échecs de CSR peuvent être classés en quelques modèles courants. Pour chacun, nous décrivons le symptôme, le diagnostic et les étapes de récupération.

Mode de défaillance 1 : CSR bloquée à l’état Pending (aucun approbateur)

Symptôme : La CSR reste indéfiniment à l’état Pending, aucun événement.

Diagnostic :

kubectl get csr <name> -o yaml | grep -A5 conditions

Si aucune condition, aucun approbateur n’a agi.

Récupération :

• Si l’approbation manuelle est acceptable : kubectl certificate approve <name>.
• Si une approbation automatisée est nécessaire, déployez un approbateur (par exemple, cert-manager) et configurez RBAC.
• Si la CSR est obsolète, supprimez-la : kubectl delete csr <name>.

Mode de défaillance 2 : CSR rejetée pour cause d’utilisations ou de signataire invalides

Symptôme : La CSR est refusée avec un message indiquant un signataire ou des utilisations inconnus.

Diagnostic :

kubectl describe csr <name>

Recherchez reason: KubectlDeny avec un message.

Récupération :

• Corrigez le signerName et les utilisations dans le manifeste.
• Supprimez l’ancienne CSR et créez-en une nouvelle :

kubectl delete csr <name>
# modifiez le manifeste, puis réappliquez

Mode de défaillance 3 : Certificat émis mais invalide ou mal configuré

Symptôme : La CSR indique Issued, mais le certificat ne fonctionne pas pour l’authentification.

Diagnostic :

kubectl get csr <name> -o jsonpath='{.status.certificate}' | base64 --decode > cert.crt
openssl x509 -in cert.crt -noout -text

Vérifiez les points suivants :

• Le CN du sujet correspond à l’identité prévue.
• L’Extended Key Usage (EKU) correspond à l’authentification client ou serveur selon les besoins.
• La période de validité n’est pas expirée.
• L’autorité de certification (CA) signataire est approuvée par le composant consommateur.

Récupération :

• Ajustez les utilisations ou le signataire dans la spécification de la CSR.
• Recréez la CSR et approuvez à nouveau.

Mode de défaillance 4 : CSR de nœud non approuvée, le nœud ne peut pas rejoindre le cluster

Symptôme : Le kubelet du nouveau nœud signale Échec de l'authentification en raison d’un certificat manquant.

Diagnostic : Vérifiez les CSR des nœuds :

kubectl get csr | grep node-

Si les CSR des nœuds sont en attente, approuvez-les manuellement :

kubectl certificate approve <node-csr-name>

Récupération :

• Mettez en place une approbation automatique pour les CSR de nœuds en utilisant le plugin d’admission NodeRestriction et un approbateur de jeton bootstrap, ou utilisez correctement le flux bootstrap kubelet de kubeadm.

Contrôle pratique pour les modes de défaillance et la récupération

• Sauvegardez toujours le manifeste de la CSR avant suppression : kubectl get csr <name> -o yaml > csr-backup.yaml.
• Documentez les étapes de récupération dans votre runbook.
• Testez la récupération dans un environnement de préproduction d’abord.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour chaque opération liée aux CSR afin de garantir cohérence et sécurité.

Règles de sécurité supplémentaires

• Utilisez toujours des espaces réservés dans les scripts, jamais de vrais secrets.
• Limitez l’approbation aux comptes à moindre privilège.
• Vérifiez périodiquement l’expiration des certificats avec un outil de surveillance.
• Testez les changements de signataire sur un cluster non production d’abord.

Conclusion

Le dépannage des CSR Kubernetes ne consiste pas à mémoriser des commandes ; il s’agit d’un processus systématique : observer, diagnostiquer, modifier de façon minimale, vérifier et récupérer en toute sécurité. En suivant les étapes de ce guide, vous pouvez résoudre la plupart des problèmes de CSR sans escalader aux propriétaires du cluster ni provoquer de temps d’arrêt.

Commencez par inventorier votre environnement et comprendre le cycle de vie des CSR. Utilisez le chemin de configuration sûr pour créer et approuver les CSR. Vérifiez soigneusement avec les commandes fournies. Lorsque des échecs surviennent, reconnaissez les modèles et appliquez les étapes de récupération documentées.

Enfin, utilisez la liste de contrôle opérationnelle comme outil quotidien. Elle assure la cohérence, réduit les erreurs humaines et renforce la confiance. N’oubliez pas : un flux de travail technique fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu’un incident ne force la décision.

Comme prochaine étape, choisissez une vérification CSR à faible risque dans la liste de contrôle, enregistrez l’état actuel, exécutez la vérification documentée et comparez le résultat avec le signal attendu. Examinez les dépendances telles que l’authentification, les comptes de service et les certificats TLS si nécessaire. Votre futur vous remerciera.