Aperçu de kubectl

kubectl référence

Kubectl est un outil en ligne de commande pour contrôler des clusters Kubernetes. kubectl recherche un fichier appelé config dans le répertoire $HOME/.kube. Vous pouvez spécifier d'autres fichiers [kubeconfig](https://kube rnetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) en définissant la variable d'environnement KUBECONFIG ou en utilisant le paramètre --kubeconfig.

Cet aperçu couvre la syntaxe kubectl, décrit les opérations et fournit des exemples classiques. Pour des détails sur chaque commande, incluant toutes les options et sous-commandes autorisées, voir la documentation de référence de kubectl. Pour des instructions d'installation, voir installer kubectl.

Syntaxe

Utilisez la syntaxe suivante pour exécuter des commandes kubectl depuis votre fenêtre de terminal :

kubectl [commande] [TYPE] [NOM] [flags]

commande, TYPE, NOM et flags sont :

  • commande: Indique l'opération que vous désirez exécuter sur une ou plusieurs ressources, par exemple create, get, describe, delete.

  • TYPE: Indique le type de ressource. Les types de ressources sont insensibles à la casse et vous pouvez utiliser les formes singulier, pluriel ou abrégé. Par exemple, les commandes suivantes produisent le même résultat :

    ```shell
    $ kubectl get pod pod1
    $ kubectl get pods pod1
    $ kubectl get po pod1
    ```
    
  • NOM: Indique le nom de la ressource. Les noms sont sensibles à la casse. Si le nom est omis, des détails pour toutes les ressources sont affichés, par exemple $ kubectl get pods.

    En effectuant une opération sur plusieurs ressources, vous pouvez soit indiquer chaque ressource par leur type et nom soit indiquer un ou plusieurs fichiers :

    • Pour indiquer des ressources par leur type et nom :

      • Pour regrouper des ressources si elles ont toutes le même type : TYPE1 nom1 nom2 nom<#>.
        Example: $ kubectl get pod exemple-pod1 exemple-pod2

      • Pour indiquer plusieurs types de ressources individuellement : TYPE1/nom1 TYPE1/nom2 TYPE2/nom3 TYPE<#>/nom<#>.
        Exemple: $ kubectl get pod/exemple-pod1 replicationcontroller/exemple-rc1

    • Pour indiquer des ressources avec un ou plusieurs fichiers : -f fichier1 -f fichier2 -f fichier<#>

      • Utilisez YAML plutôt que JSON, YAML tendant à être plus facile à utiliser, particulièrement pour des fichiers de configuration.
        Exemple: $ kubectl get pod -f ./pod.yaml
  • flags: Indique des flags optionnels. Par exemple, vous pouvez utiliser les flags -s ou --server pour indiquer l'adresse et le port de l'API server Kubernetes.

Si vous avez besoin d'aide, exécutez kubectl help depuis la fenêtre de terminal.

Opérations

Le tableau suivant inclut une courte description et la syntaxe générale pour chaque opération kubectl :

OpérationSyntaxeDescription
alphakubectl alpha SOUS-COMMANDE [flags]Liste les commandes disponibles qui correspondent à des fonctionnalités alpha, qui ne sont pas activées par défaut dans les clusters Kubernetes.
annotatekubectl annotate (-f FICHIER | TYPE NOM | TYPE/NOM) CLE_1=VAL_1 ... CLE_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]Ajoute ou modifie les annotations d'une ou plusieurs ressources.
api-resourceskubectl api-resources [flags]Liste les ressources d'API disponibles.
api-versionskubectl api-versions [flags]Liste les versions d'API disponibles.
applykubectl apply -f FICHIER [flags]Applique un changement de configuration à une ressource depuis un fichier ou stdin.
attachkubectl attach POD -c CONTENEUR [-i] [-t] [flags]Attache à un conteneur en cours d'exécution soit pour voir la sortie standard soit pour interagir avec le conteneur (stdin).
authkubectl auth [flags] [options]Inspecte les autorisations.
autoscalekubectl autoscale (-f FICHIER | TYPE NOM | TYPE/NOM) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags]Scale automatiquement l'ensemble des pods gérés par un replication controller.
certificatekubectl certificate SOUS-COMMANDE [options]Modifie les ressources de type certificat.
cluster-infokubectl cluster-info [flags]Affiche les informations des endpoints du master et des services du cluster.
completionkubectl completion SHELL [options]Affiche le code de complétion pour le shell spécifié (bash ou zsh).
configkubectl config SOUS-COMMANDE [flags]Modifie les fichiers kubeconfig. Voir les sous-commandes individuelles pour plus de détails.
convertkubectl convert -f FICHIER [options]Convertit des fichiers de configuration entre différentes versions d'API. Les formats YAML et JSON sont acceptés.
cordonkubectl cordon NOEUD [options]Marque un nœud comme non programmable.
cpkubectl cp <ficher-src> <fichier-dest> [options]Copie des fichiers et des répertoires vers et depuis des conteneurs.
createkubectl create -f FICHIER [flags]Crée une ou plusieurs ressources depuis un fichier ou stdin.
deletekubectl delete (-f FICHIER | TYPE [NOM | /NOM | -l label | --all]) [flags]Supprime des ressources soit depuis un fichier ou stdin, ou en indiquant des sélecteurs de label, des noms, des sélecteurs de ressources ou des ressources.
describekubectl describe (-f FICHIER | TYPE [PREFIXE_NOM | /NOM | -l label]) [flags]Affiche l'état détaillé d'une ou plusieurs ressources.
diffkubectl diff -f FICHIER [flags]Diff un fichier ou stdin par rapport à la configuration en cours
drainkubectl drain NOEUD [options]Vide un nœud en préparation de sa mise en maintenance.
editkubectl edit (-f FICHIER | TYPE NOM | TYPE/NOM) [flags]Édite et met à jour la définition d'une ou plusieurs ressources sur le serveur en utilisant l'éditeur par défaut.
execkubectl exec POD [-c CONTENEUR] [-i] [-t] [flags] [-- COMMANDE [args...]]Exécute une commande à l'intérieur d'un conteneur dans un pod.
explainkubectl explain [--recursive=false] [flags]Obtient des informations sur différentes ressources. Par exemple pods, nœuds, services, etc.
exposekubectl expose (-f FICHIER | TYPE NOM | TYPE/NOM) [--port=port] [--protocol=TCP|UDP] [--target-port=nombre-ou-nom] [--name=nom] [--external-ip=ip-externe-ou-service] [--type=type] [flags]Expose un replication controller, service ou pod comme un nouveau service Kubernetes.
getkubectl get (-f FICHIER | TYPE [NOM | /NOM | -l label]) [--watch] [--sort-by=CHAMP] [[-o | --output]=FORMAT_AFFICHAGE] [flags]Liste une ou plusieurs ressources.
kustomizekubectl kustomize <répertoire> [flags] [options]Liste un ensemble de ressources d'API généré à partir d'instructions d'un fichier kustomization.yaml. Le paramètre doit être le chemin d'un répertoire contenant ce fichier, ou l'URL d'un dépôt git incluant un suffixe de chemin par rapport à la racine du dépôt.
labelkubectl label (-f FICHIER | TYPE NOM | TYPE/NOM) CLE_1=VAL_1 ... CLE_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]Ajoute ou met à jour les labels d'une ou plusieurs ressources.
logskubectl logs POD [-c CONTENEUR] [--follow] [flags]Affiche les logs d'un conteneur dans un pod.
optionskubectl optionsListe des options globales, s'appliquant à toutes commandes.
patchkubectl patch (-f FICHIER | TYPE NOM | TYPE/NOM) --patch PATCH [flags]Met à jour un ou plusieurs champs d'une resource en utilisant le processus de merge patch stratégique.
pluginkubectl plugin [flags] [options]Fournit des utilitaires pour interagir avec des plugins.
port-forwardkubectl port-forward POD [PORT_LOCAL:]PORT_DISTANT [...[PORT_LOCAL_N:]PORT_DISTANT_N] [flags]Transfère un ou plusieurs ports locaux vers un pod.
proxykubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]Exécute un proxy vers un API server Kubernetes.
replacekubectl replace -f FICHIERRemplace une ressource depuis un fichier ou stdin.
rolloutkubectl rollout SOUS-COMMANDE [options]Gère le rollout d'une ressource. Les types de ressources valides sont : deployments, daemonsets et statefulsets.
runkubectl run NOM --image=image [--env="cle=valeur"] [--port=port] [--replicas=replicas] [--dry-run=server&#124;client&#124;none] [--overrides=inline-json] [flags]Exécute dans le cluster l'image indiquée.
scalekubectl scale (-f FICHIER | TYPE NOM | TYPE/NOM) --replicas=QUANTITE [--resource-version=version] [--current-replicas=quantité] [flags]Met à jour la taille du replication controller indiqué.
setkubectl set SOUS-COMMANDE [options]Configure les ressources de l'application.
taintkubectl taint NOEUD NNOM CLE_1=VAL_1:EFFET_TAINT_1 ... CLE_N=VAL_N:EFFET_TAINT_N [options]Met à jour les marques (taints) d'un ou plusieurs nœuds.
topkubectl top [flags] [options]Affiche l'utilisation des ressources (CPU/Mémoire/Stockage).
uncordonkubectl uncordon NOEUD [options]Marque un noeud comme programmable.
versionkubectl version [--client] [flags]Affiche la version de Kubernetes du serveur et du client.
waitkubectl wait ([-f FICHIER] | ressource.groupe/ressource.nom | ressource.groupe [(-l label | --all)]) [--for=delete|--for condition=available] [options]Expérimental : Attend un condition spécifique sur une ou plusieurs ressources.

Rappelez-vous : Pour tout savoir sur les opérations, voir la documentation de référence de kubectl.

Types de ressources

Le tableau suivant inclut la liste de tous les types de ressources pris en charge et leurs alias abrégés.

(cette sortie peut être obtenue depuis kubectl api-resources, et correspond à Kubernetes 1.13.3.)

Nom de la ressourceNoms abrégésGroupe APIPar namespaceGenre de la ressource
bindingstrueBinding
componentstatusescsfalseComponentStatus
configmapscmtrueConfigMap
endpointseptrueEndpoints
limitrangeslimitstrueLimitRange
namespacesnsfalseNamespace
nodesnofalseNode
persistentvolumeclaimspvctruePersistentVolumeClaim
persistentvolumespvfalsePersistentVolume
podspotruePod
podtemplatestruePodTemplate
replicationcontrollersrctrueReplicationController
resourcequotasquotatrueResourceQuota
secretstrueSecret
serviceaccountssatrueServiceAccount
servicessvctrueService
mutatingwebhookconfigurationsadmissionregistration.k8s.iofalseMutatingWebhookConfiguration
validatingwebhookconfigurationsadmissionregistration.k8s.iofalseValidatingWebhookConfiguration
customresourcedefinitionscrd, crdsapiextensions.k8s.iofalseCustomResourceDefinition
apiservicesapiregistration.k8s.iofalseAPIService
controllerrevisionsappstrueControllerRevision
daemonsetsdsappstrueDaemonSet
deploymentsdeployappstrueDeployment
replicasetsrsappstrueReplicaSet
statefulsetsstsappstrueStatefulSet
tokenreviewsauthentication.k8s.iofalseTokenReview
localsubjectaccessreviewsauthorization.k8s.iotrueLocalSubjectAccessReview
selfsubjectaccessreviewsauthorization.k8s.iofalseSelfSubjectAccessReview
selfsubjectrulesreviewsauthorization.k8s.iofalseSelfSubjectRulesReview
subjectaccessreviewsauthorization.k8s.iofalseSubjectAccessReview
horizontalpodautoscalershpaautoscalingtrueHorizontalPodAutoscaler
cronjobscjbatchtrueCronJob
jobsbatchtrueJob
certificatesigningrequestscsrcertificates.k8s.iofalseCertificateSigningRequest
leasescoordination.k8s.iotrueLease
eventsevevents.k8s.iotrueEvent
ingressesingextensionstrueIngress
networkpoliciesnetpolnetworking.k8s.iotrueNetworkPolicy
poddisruptionbudgetspdbpolicytruePodDisruptionBudget
podsecuritypoliciespsppolicyfalsePodSecurityPolicy
clusterrolebindingsrbac.authorization.k8s.iofalseClusterRoleBinding
clusterrolesrbac.authorization.k8s.iofalseClusterRole
rolebindingsrbac.authorization.k8s.iotrueRoleBinding
rolesrbac.authorization.k8s.iotrueRole
priorityclassespcscheduling.k8s.iofalsePriorityClass
csidriversstorage.k8s.iofalseCSIDriver
csinodesstorage.k8s.iofalseCSINode
storageclassesscstorage.k8s.iofalseStorageClass
volumeattachmentsstorage.k8s.iofalseVolumeAttachment

Options de sortie

Utilisez les sections suivantes pour savoir comment vous pouvez formater ou ordonner les sorties de certaines commandes. Pour savoir exactement quelles commandes prennent en charge quelles options de sortie, voir la documentation de référence de kubectl.

Formater la sortie

Le format de sortie par défaut pour toutes les commandes kubectl est le format texte lisible par l'utilisateur. Pour afficher des détails dans votre fenêtre de terminal dans un format spécifique, vous pouvez ajouter une des options -o ou --output à une des commandes kubectl les prenant en charge.

Syntaxe

kubectl [commande] [TYPE] [NOM] -o <format_sortie>

Selon l'opération kubectl, les formats de sortie suivants sont pris en charge :

Format de sortieDescription
-o custom-columns=<spec>Affiche un tableau en utilisant une liste de colonnes personnalisées séparées par des virgules.
-o custom-columns-file=<fichier>Affiche un tableau en utilisant un modèle de colonnes personnalisées dans le fichier <fichier>.
-o jsonAffiche un objet de l'API formaté en JSON.
-o jsonpath=<modèle>Affiche les champs définis par une expression jsonpath.
-o jsonpath-file=<ffichier>Affiche les champs définis par une expression jsonpath dans le fichier <fichier>.
-o nameAffiche uniquement le nom de la ressource et rien de plus.
-o wideAffiche dans le format texte avec toute information supplémentaire. Pour les pods, le nom du nœud est inclus.
-o yamlAffiche un objet de l'API formaté en YAML.
Exemple

Dans cet exemple, la commande suivante affiche les détails d'un unique pod sous forme d'un objet formaté en YAML :

$ kubectl get pod web-pod-13je7 -o yaml

Souvenez-vous : Voir la documentation de référence de kubectl pour voir quels formats de sortie sont pris en charge par chaque commande.

Colonnes personnalisées

Pour définir des colonnes personnalisées et afficher uniquement les détails voulus dans un tableau, vous pouvez utiliser l'option custom-columns. Vous pouvez choisir de définir les colonnes personnalisées soit en ligne soit dans un fichier modèle : -o custom-columns=<spec> ou -o custom-columns-file=<fichier>.

Exemples

En ligne :

$ kubectl get pods <nom-pod> -o custom-columns=NOM:.metadata.name,RSRC:.metadata.resourceVersion

Fichier modèle :

$ kubectl get pods <nom-pod> -o custom-columns-file=modele.txt

où le fichier modele.txt contient :

NOM           RSRC
metadata.name metadata.resourceVersion

Le résultat de ces commandes est :

NOM            RSRC
submit-queue   610995

Colonnes côté serveur

kubectl est capable de recevoir des informations de colonnes spécifiques d'objets depuis le serveur. Cela veut dire que pour toute ressource donnée, le serveur va retourner les colonnes et lignes pour cette ressource, que le client pourra afficher. Cela permet un affichage de sortie lisible par l'utilisateur cohérent entre les clients utilisés sur le même cluster, le serveur encapsulant les détails d'affichage.

Cette fonctionnalité est activée par défaut dans kubectl version 1.11 et suivantes. Pour la désactiver, ajoutez l'option --server-print=false à la commande kubectl get.

Exemples

Pour afficher les informations sur le status d'un pod, utilisez une commande similaire à :

kubectl get pods <nom-pod> --server-print=false

La sortie ressemble à :

NAME       AGE
nom-pod    1m

Ordonner les listes d'objets

Pour afficher les objets dans une liste ordonnée dans une fenêtre de terminal, vous pouvez ajouter l'option --sort-by à une commande kubectl qui la prend en charge. Ordonnez vos objets en spécifiant n'importe quel champ numérique ou textuel avec l'option --sort-by. Pour spécifier un champ, utilisez une expression jsonpath.

Syntaxe

kubectl [commande] [TYPE] [NOM] --sort-by=<exp_jsonpath>
Exemple

Pour afficher une liste de pods ordonnés par nom, exécutez :

$ kubectl get pods --sort-by=.metadata.name

Exemples : Opérations courantes

Utilisez les exemples suivants pour vous familiariser avec les opérations de kubectl fréquemment utilisées :

kubectl apply - Créer une ressource depuis un fichier ou stdin.

# Crée un service en utilisant la définition dans exemple-service.yaml.
$ kubectl apply -f exemple-service.yaml

# Crée un replication controller en utilisant la définition dans exemple-controller.yaml.
$ kubectl apply -f exemple-controller.yaml

# Crée les objets qui sont définis dans les fichiers .yaml, .yml ou .json du répertoire <répertoire>.
$ kubectl apply -f <répertoire>

kubectl get - Liste une ou plusieurs ressources.

# Liste tous les pods dans le format de sortie texte.
$ kubectl get pods

# Liste tous les pods dans le format de sortie texte et inclut des informations additionnelles (comme le nom du nœud).
$ kubectl get pods -o wide

# Liste le replication controller ayant le nom donné dans le format de sortie texte.
# Astuce : Vous pouvez raccourcir et remplacer le type de ressource 'replicationcontroller' avec l'alias 'rc'.
$ kubectl get replicationcontroller <nom-rc>

# Liste ensemble tous les replication controller et les services dans le format de sortie texte.
$ kubectl get rc,services

# Liste tous les daemon sets dans le format de sortie texte.
kubectl get ds

# Liste tous les pods s'exécutant sur le nœud serveur01
$ kubectl get pods --field-selector=spec.nodeName=serveur01

kubectl describe - Affiche l'état détaillé d'une ou plusieurs ressources, en incluant par défaut les ressources non initialisées.

# Affiche les détails du nœud ayant le nom <nom-nœud>.
$ kubectl describe nodes <nom-nœud>

# Affiche les détails du pod ayant le nom <nom-pod>.
$ kubectl describe pods/<nom-pod>

# Affiche les détails de tous les pods gérés par le replication controller dont le nom est <nom-rc>.
# Rappelez-vous : les noms des pods étant créés par un replication controller sont préfixés par le nom du replication controller.
$ kubectl describe pods <nom-rc>

# Décrit tous les pods
$ kubectl describe pods

kubectl delete - Supprime des ressources soit depuis un fichier, stdin, ou en spécifiant des sélecteurs de labels, des noms, des sélecteurs de ressource ou des ressources.

# Supprime un pod en utilisant le type et le nom spécifiés dans le fichier pod.yaml.
$ kubectl delete -f pod.yaml

# Supprime tous les pods et services ayant le label <clé-label>=<valeur-label>
$ kubectl delete pods,services -l <clé-label>=<valeur-label>

# Supprime tous les pods, en incluant les non initialisés.
$ kubectl delete pods --all

kubectl exec - Exécute une commande depuis un conteneur d'un pod.

# Affiche la sortie de la commande 'date' depuis le pod <nom-pod>. Par défaut, la sortie se fait depuis le premier conteneur.
$ kubectl exec <nom-pod> -- date

# Affiche la sortie de la commande 'date' depuis le conteneur <nom-conteneur> du pod <nom-pod>.
$ kubectl exec <nom-pod> -c <nom-conteneur> -- date

# Obtient un TTY interactif et exécute /bin/bash depuis le pod <nom-pod>. Par défaut, la sortie se fait depuis le premier conteneur.
$ kubectl exec -ti <nom-pod> -- /bin/bash

kubectl logs - Affiche les logs d'un conteneur dans un pod.

# Retourne un instantané des logs du pod <nom-pod>.
$ kubectl logs <nom-pod>

# Commence à streamer les logs du pod <nom-pod>. Ceci est similaire à la commande Linux 'tail -f'.
$ kubectl logs -f <nom-pod>

kubectl diff - Affiche un diff des mises à jour proposées au cluster.

# Diff les ressources présentes dans "pod.json".
kubectl diff -f pod.json

# Diff les ressources présentes dans le fichier lu sur l'entrée standard.
cat service.yaml | kubectl diff -f -

Exemples : Créer et utiliser des plugins

Utilisez les exemples suivants pour vous familiariser avec l'écriture et l'utilisation de plugins kubectl :

# créez un plugin simple dans n'importe quel langage et nommez
# l'exécutable de telle sorte qu'il commence par "kubectl-"
$ cat ./kubectl-hello
#!/bin/bash

# ce plugin affiche les mots "hello world"
echo "hello world"

# une fois votre plugin écrit, rendez-le exécutable
$ sudo chmod +x ./kubectl-hello

# et déplacez-le dans un répertoire de votre PATH
$ sudo mv ./kubectl-hello /usr/local/bin

# vous avez maintenant créé et "installé" un plugin kubectl.
# vous pouvez commencer à l'utiliser en l'invoquant depuis kubectl
# comme s'il s'agissait d'une commande ordinaire
$ kubectl hello
hello world

# vous pouvez "désinstaller" un plugin,
# simplement en le supprimant de votre PATH
$ sudo rm /usr/local/bin/kubectl-hello

Pour voir tous les plugins disponibles pour kubectl, vous pouvez utiliser la sous-commande kubectl plugin list :

$ kubectl plugin list
The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar

# cette commande peut aussi vous avertir de plugins qui ne sont pas exécutables,
# ou qui sont cachés par d'autres plugins, par exemple :
$ sudo chmod -x /usr/local/bin/kubectl-foo
$ kubectl plugin list
The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
  - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
/usr/local/bin/kubectl-bar

error: one plugin warning was found

Vous pouvez voir les plugins comme un moyen de construire des fonctionnalités plus complexes au dessus des commandes kubectl existantes :

$ cat ./kubectl-whoami
#!/bin/bash

# ce plugin utilise la commande `kubectl config` pour afficher
# l'information sur l'utilisateur courant, en se basant sur
# le contexte couramment sélectionné
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'

Exécuter le plugin ci-dessus vous donne une sortie contenant l'utilisateur du contexte couramment sélectionné dans votre fichier KUBECONFIG :

# rendre le fichier exécutable executable
$ sudo chmod +x ./kubectl-whoami

# et le déplacer dans le PATH
$ sudo mv ./kubectl-whoami /usr/local/bin

$ kubectl whoami
Current user: plugins-user

Pour en savoir plus sur les plugins, examinez l'exemple de plugin CLI.

A suivre

Commencez à utiliser les commandes kubectl.

Dernière modification March 24, 2023 at 3:04 PM PST: Fixed typo (a8705b2f24)