Commandes kubectl pour bien gérer votre cluster Kubernetes

Aujourd’hui on va apprendre à gérer ses clusters Kubernetes à l’aide de l’outil officiel de commande en ligne : kubectl.

Les commandes principales mais aussi des commandes kubectl plus avancées qui sont pour certaines moins connues !

Alors déjà, kubectl est la contraction des mots Kubernetes et control. C’est un outil qui permet de dialoguer avec l’API de Kubernetes afin de créer, modifier, lire ou encore supprimer des ressources de notre cluster Kubernetes.

Avant de commencer, pour les rappels essentiels, je vous invite à faire un tour sur notre article de présentation de Kubernetes.

ℹ️ Petite anecdote avant de rentrer dans le vif du sujet, il y a de nombreuses façons de prononcer “kubectl”. Certains diront “cube cé-té-èl”, d’autres “cube keuteulle”, d’autres encore préféreront “koo-bectal”, bref, ça part dans tous les sens et il n’y a pas de consensus, on adopte plutôt la première version chez Enix mais choisissez celle que vous préférez !

Installation de kubectl

Kubectl est disponible sur Linux, Mac et Windows. Les 3 OS possèdent chacun leur méthode d’installation propre que vous pouvez retrouver sur la documentation Kubernetes.

Mise en place de l’auto-complétion

Une fois kubectl installé, il suffit de suivre ces quelques étapes (identiques pour tous les OS supportés). Le package bash-completion est requis pour faire fonctionner l’autocompletion.

source <(kubectl completion bash) # mise en place de l'autocompletion dans le shell bash en cours d'utilisation.
echo "source <(kubectl completion bash)" >> ~/.bashrc # mise en place de l'autocompletion dans vos shells bash de façon permanente

Vous pouvez également utiliser un alias qui marchera avec l’autocompletion.

alias k=kubectl
complete -F __start_kubectl k

Ça y est, on est fin prêts à commencer ! 🎉

Kubectl config et fichier kubeconfig

Avant de pouvoir lister les ressources d’un cluster, on va devoir configurer le contexte et l’accès au cluster en question. La première étape est de créer un fichier de configuration ~/.kube/config qui contiendra les informations de connexion à vos différents clusters. Il peut être édité à la main ou via les commandes kubectl décrites dans la documentation sus-citée.

Plusieurs contextes peuvent être créés au sein d’un même fichier kubeconfig.

Afin de commencer à utiliser un contexte, utilisez la commande kubectl config use-context <CONTEXT_NAME>.

ℹ️ Certains outils comme kubie permettent de gérer ces contextes plus facilement. Notamment en permettant d’utiliser facilement plusieurs fichiers kubeconfig. Il rend l’ajout d’une nouvelle entrée bien plus facile, surtout quand le fichier ~/.kube/config est déjà bien rempli.

Format des commandes kubectl

Syntaxe de kubectl

kubectl [command] [TYPE] [NAME] [flags]

La syntaxe d’une commande kubectl est relativement simple :

• Le premier argument est l’action à effectuer sur une ressource.
• L’argument TYPE correspond au type de ressource sur lequel effectuer l’action. Le nom peut être au singulier, au pluriel ou utiliser une abréviation, par exemple sts pour statefulset. La commande kubectl api-resources permet d’ailleurs de lister les types de ressources disponibles sur un cluster.
• L’argument NAME correspond au nom de la ressource Kubernetes concernée par l’action que l’on souhaite réaliser.
• Divers flags peuvent être ajoutés.

Certaines commandes ne visent pas de ressources en particulier comme la commande kubectl version qui ne prend pas de paramètre supplémentaire.

Output de kubectl et mise en forme

Kubectl dispose d’options permettant la mise en forme de l’output. le flag -o permettra par exemple de choisir le format d’output parmi un certain nombre, incluant json, yaml ou encore un affichage en colonne plus complet que celui de base via le format wide.

D’autres options avancées telles que custom-columns ou encore jsonpath sont disponibles mais ne seront pas abordées dans cet article à but plus introductif.

kubectl [command] [TYPE] [NAME] -o <output_format>

Il est courant d’utiliser l’utilitaire jq pour retravailler l’output au format json. On peut par exemple lister tous nos pods Kubernetes et le nombre de volumes présents sur ces pods avec cette loooongue commande toutefois très pratique :)

$ kubectl get pods -A -o json | \
jq -r '.items[] | [.metadata.name, (.spec.volumes | length)] | @tsv' | \
column -t -s $'\t'
cattle-node-agent-z9df5 6
kube-api-auth-xcwc5 2
cert-manager-6d6bb4f487-q25lp 1

Un peu compliqué à lire/écrire n’est-ce pas ? 🥵 Heureusement, dans de nombreux cas on peut faire bien plus simple en utilisant le flag -o custom-columns, par exemple pour afficher le propriétaire (owner) d’une ressource en plus des colonnes de base :

$ kubectl get pod -o custom-columns=\
NAME:.metadata.name,\
OWNER-KIND:.metadata.ownerReferences[0].kind,\
OWNER-NAME:.metadata.ownerReferences[0].name
NAME                     OWNER-KIND   OWNER-NAME
my-rs-6fb78fd4c8-pql9f   ReplicaSet   my-rs-6fb78fd4c8

Principales commandes kubectl

Commandes kubectl de base

On va maintenant voir quelques commandes courantes. Premièrement, observons ce set de commandes très basiques :

kubectl apply

kubectl apply -f ./deployment.yaml # créer ou mettre à jour des ressources depuis un fichier

Sachez que plusieurs fichiers peuvent être utilisés en même temps. Par exemple, pour créer un groupe de ressources : kubectl apply -f foo.yaml -f bar.yaml, ou pour appliquer un dossier entier récursivement : kubectl apply -f ./foobar. On peut également appliquer directement des ressources depuis l’entrée standard avec kubectl apply -f-.

kubectl create

kubectl create -f ./deployment.yaml # créer des ressources depuis un fichier (la commande échoue si la ressource existe déjà)

kubectl get pods

kubectl get pods [...pod_name] # lister un type de ressource, on peut préciser un nombre arbitraire de nom de ressources ou laisser l'argument vide pour tout lister

kubectl delete pod

kubectl delete pod <pod_name> # détruire une ressource

kubectl describe

La commande kubectl describe permet de décrire les ressources créées, c’est-à-dire d’afficher les informations essentielles d’une ressource, notamment les évènements liés à cette dernière.

kubectl describe <TYPE> [...NAME] # permet d'afficher les informations essentielles d'une ressource

kubectl logs

kubectl logs <pod_name> <container_name> # permet d'afficher les logs d'un conteneur

Kubectl et les namespaces

On sait maintenant interagir avec nos ressources Kubernetes, cependant, ces commandes ne sont exécutées par défaut que dans le cadre du namespace courant.

Pour sélectionner un autre namespace, ajoutez à votre commande kubectl le flag --namespace ou son short-hand -n, suivi du nom du namespace désiré. On peut aussi utiliser l’outil kubie dont j’ai parlé plus haut avec la commande kubie ns <NAMESPACE> qui permet de configurer son contexte pour effectuer toutes les commandes suivantes dans un namespace donné.

Et pour effectuer votre action sur tous les namespace (généralement utilisé pour lister toutes les ressources d’un même type rapidement), il suffit d’utiliser le flag --all-namespaces ou son short-hand -A.

kubectl port-forward

Cette commande kubectl peut être particulièrement utile pour débugger.

kubectl port-forward <pod_name> [PORT_LOCAL:]PORT_DISTANT # expose le port PORT_DISTANT du pod sur notre port PORT_LOCAL

Commandes kubectl avancées

Nous allons maintenant voir quelques exemples d’opérations kubectl plus avancées.

kubectl --watch

Commençons par les commandes Kubectl permettant d’observer les ressources. On utilisera le flag --watch :

kubectl get pods --watch # permet de "watch" une ressource

kubectl get pods --watch --output-watch-events # permet de "watch" une ressource avec en addition le type d'event reçu (ADDED, MODIFIED, DELETED…)

L’utilisation des deux flags --watch et --output-watch-events permettent d’observer en temps réel toutes les modifications apportées à un type de ressource et le type de modification apporté. Étonnamment, ces deux flags en supplément du flag -o json permettent d’écrire un opérateur Kubernetes en bash 🤯 Eh ouais, ça à l’air dingo dit comme ça, mais c’est bien réel. On retrouve notamment cette technique dans le projet nsplease de notre bon vieux Jérôme Petazzoni.

kubectl explain

Une commande très utile quand vous écrivez une nouvelle ressource dont vous n’avez pas l’habitude : la commande explain. Elle permet d’afficher la documentation d’un type de ressource et de ses différents champs.

Par exemple, kubectl explain pods expliquera le type pod, ce qui nous permet de savoir qu’il est composé d’une apiVersion, d’un kind, de metadata, spec et enfin d’un status. Mais on peut aller un peu plus loin encore, en demandant d’expliquer par exemple un initContainer dans un pod : kubectl explain pods.spec.initContainer. Grâce à cette commande, vous n’aurez même plus à chercher sur internet comment se configure cette custom resource définie par cet opérateur complexe et peu documenté dont vous ne pouvez pas vous passer 🥳 (à condition que la Custom Resource Definition en question soit elle-même un minimum documenté). Plus d’infos sur les opérateurs et les CRDs dans notre blogpost sur Kubernetes (lien en tout début d’article).

Générer des templates avec kubectl

Une autre technique pour commencer à écrire une nouvelle ressource est de partir d’un template de base, et ça tombe bien, kubectl permet de générer des templates pré remplis assez simples pour pas mal de types de ressources différentes.

Par exemple, pour créer un deployment, on fera kubectl create deployment my-nginx --image=nginx:1.21 --dry-run=client -o yaml. Cela aura pour effet d’effectuer un dry-run local et d’en afficher le résultat en yaml, c’est-à-dire le yaml qui aurait été appliqué si on n’avait pas fait de dry-run.

Chaque type est légèrement différent à configurer, vous pouvez donc consulter l’aide pour connaître les flags et options disponibles et/ou requis (kubectl create <TYPE> –help ou encore kubectl create --help pour consulter la liste des types disponibles via cette commande).

kubectl wait

Enfin, je vous conseille ce court article sur la commande kubectl wait, particulièrement utile, un article rédigé par mon joyeux acolyte Antoine Millet 😉

Plugins kubectl

Kubectl présente également une interface de plugins. Ceux-ci sont créés par la communauté et peuvent être divers et variés. On va voir dans cette partie un exemple de plugin avec kubectl neat, puis découvrir comment installer un nouveau plugin.

Kubectl neat

Un exemple de plugin que j’utilise particulièrement souvent : kubectl neat. Comme son nom l’indique, le but est de produire une sortie soignée et claire. Ce que le plugin fait, c’est venir filtrer les informations non essentielles lorsque l’on récupère la configuration d’une ressource. Le statut par exemple est retiré, les seules informations gardées sont celles qui sont essentielles pour recréer cette ressource à l’identique. Toutes les informations temporaires et redondantes sont donc retirées.

Pour l’utiliser, rien de plus simple : kubectl get pods -o yaml | kubectl neat. Le plugin fonctionne sur tout type de ressource et aussi bien sur les formats yaml que json.

Installer un plugin kubectl

Maintenant que l’on comprend le principe, essayons d’installer ce plugin ! Il existe plusieurs façons d’installer un plugin, et la méthode recommandée est d’utiliser le package manager krew qui est lui-même… un plugin kubectl !

Commençons par installer krew. Pour celà, je vous invite à suivre la procédure décrite dans la documentation krew. Maintenant que nous avons krew installé sur notre machine, il ne nous reste plus qu’à mettre à jour la liste des plugins (l’équivalent d’un apt update) puis à installer le plugin.

kubectl krew update
kubectl krew install neat

Kubectl neat est maintenant installé et peut être utilisé via la command-line kubectl, ou en standalone via le binaire kubectl-neat.

kubectl get pods -o yaml | kubectl neat # via kubectl
kubectl get pods -o yaml | kubectl-neat # en standalone (notez le tiret entre kubectl et neat)

Vous pouvez également obtenir la liste des plugins disponibles : kubectl krew search (seulement ceux référencés via krew, certains peuvent ne pas avoir été packagés). La liste se trouve également sur le site officiel avec leurs descriptions.

Conclusion

Voilà ! Vous savez maintenant comment interagir avec votre cluster Kubernetes directement depuis votre CLI. On a vu que vous pouviez utiliser kubectl pour effectuer toutes les tâches d’administration basiques d’un cluster, mais aussi quelques opérations plus avancées.

Kubectl est très pratique dans de nombreux cas car il est relativement simple et rapide à utiliser. Cependant, si vous gérez des clusters k8s à longueur de journée, un outil en GUI peut être plus agréable à utiliser. Dans ce cas on préfèrera souvent des outils comme Lens ou comme K9s, qui présentent globalement les mêmes fonctionnalités que kubectl mais au travers d’une GUI exécutable directement depuis votre terminal ou une GUI web. Évidemment, ces outils n’éclipseront jamais totalement kubectl qui reste l’outil à privilégier pour des tâches simples et un accès rapide.

Allez, maintenant c’est à vous de jouer avec les commandes kubectl pour gérer avec talent vos clusters Kubernetes ! 😉

Ne ratez pas nos prochains articles DevOps et Cloud Native! Suivez Enix sur Twitter!