## 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 : ```bash 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 : ```bash 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 : ```bash 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 : ```bash kubectl logs -n kube-system kube-controller-manager- | grep -i csr ``` Remplacez `` 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 : ```bash 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 : ```bash 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 : ```bash 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 : ```bash kubectl get pods -n kube-system kube-controller-manager- -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 : ```bash 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 : ```bash cat test-user.csr | base64 | tr -d '\n' ``` Créez un manifeste Kubernetes CSR `test-user-csr.yaml` : ```yaml apiVersion: certificates.k8s.io/v1 kind: CertificateSigningRequest metadata: name: test-user-csr spec: request: signerName: kubernetes.io/kube-apiserver-client usages: - client auth ``` Appliquez-le : ```bash kubectl apply -f test-user-csr.yaml ``` Vérifiez : ```bash 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` : ```bash kubectl certificate approve test-user-csr ``` Sortie attendue : ``` certificatesigningrequest.certificates.k8s.io/test-user-csr approved ``` Vérifiez l’état : ```bash 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 : ```bash kubectl get csr test-user-csr -o jsonpath='{.status.certificate}' | base64 --decode > test-user.crt ``` Inspectez-le : ```bash 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 : ```bash 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 : ```bash kubectl get csr -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 ```bash kubectl describe csr ``` 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 : ```bash kubectl get pod -n kube-system kube-controller-manager- -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 : ```bash 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 :** ```bash kubectl get csr -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 `. - 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 `. ### 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 :** ```bash kubectl describe csr ``` 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 : ```bash kubectl delete csr # 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 :** ```bash kubectl get csr -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 : ```bash kubectl get csr | grep node- ``` Si les CSR des nœuds sont en attente, approuvez-les manuellement : ```bash kubectl certificate approve ``` **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 -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é. | Étape | Action | Commande | Résultat attendu | |------|--------|---------|------------------| | 1 | Enregistrer la version du cluster | `kubectl version --short` | Serveur v1.19+ pour API stable | | 2 | Lister les CSR actuelles | `kubectl get csr` | Toutes les CSR dans des états connus | | 3 | Sauvegarder les manifestes des CSR | `kubectl get csr -o yaml > csr-backup-$(date +%Y%m%d).yaml` | Fichier créé | | 4 | Créer une CSR avec le bon signataire/utilisations | Appliquer le manifeste | La CSR apparaît comme Pending | | 5 | Approuver ou refuser selon le besoin | `kubectl certificate approve ` | La sortie confirme l’approbation | | 6 | Vérifier l’émission | `kubectl get csr -o jsonpath='{.status.conditions}'` | Les conditions montrent Approved et Issued | | 7 | Récupérer et valider le certificat | `kubectl get csr -o jsonpath='{.status.certificate}' \| base64 --decode > cert.crt; openssl x509 -in cert.crt -noout -text` | Les détails du certificat correspondent aux attentes | | 8 | Surveiller les journaux du contrôleur de gestion | `kubectl logs -n kube-system kube-controller-manager- \| grep -i csr` | Aucune erreur de signature | | 9 | Nettoyer les CSR obsolètes | `kubectl delete csr ` | Ressource supprimée | | 10 | Documenter tout échec et récupération | Écrire dans le runbook | Runbook mis à jour | ### 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.