kubectl api-resources et explain : explorer l'API Kubernetes

Vous ne savez pas quel type de ressource utiliser, quelle apiVersion écrire, ou quels champs mettre dans votre manifest YAML ? Les deux commandes kubectl api-resources et kubectl explain répondent à ces questions en interrogeant directement votre cluster. Ce guide vous montre comment les utiliser au quotidien pour explorer l'API, découvrir des CRD et écrire des manifests sans deviner.

Ce que vous allez apprendre

À la fin de ce guide, vous saurez :

• Trouver n'importe quel type de ressource dans l'API Kubernetes (nom, shortname, groupe, kind)
• Déterminer le kind et l'apiVersion corrects pour écrire un manifest YAML
• Explorer la structure d'un objet et comprendre chaque champ avec kubectl explain
• Découvrir les CRD (Custom Resource Definitions) installées sur votre cluster
• Lister toutes les ressources d'un namespace (au-delà de kubectl get all)
• Filtrer par catégorie, groupe d'API ou portée (namespaced vs cluster-wide)

Les 3 commandes à retenir

Avant d'aller plus loin, voici les trois commandes que vous utiliserez le plus souvent :

# 1) Chercher une ressource (type, shortname, apiGroup, namespaced)
kubectl api-resources | grep -i ingress

# 2) Explorer les champs d'un objet pour écrire un manifest
kubectl explain deployment.spec.template.spec.containers --recursive

# 3) Filtrer par famille (workloads, RBAC, stockage…)
kubectl api-resources --api-group=apps

Pourquoi c'est fiable

kubectl explain interroge le schéma OpenAPI exposé par votre serveur API. Les informations sont donc alignées avec votre version de Kubernetes, pas une doc générique sur internet. Si un champ a été ajouté ou déprécié dans votre version, explain le reflète.

kubectl api-resources : trouver le bon type de ressource

kubectl api-resources affiche tous les types de ressources disponibles sur votre cluster, y compris les CRD installées par des opérateurs.

Ce que la sortie vous apprend

La commande ne prend aucun argument et interroge le serveur API de votre cluster courant. Comptez entre 60 et 250 lignes selon le nombre d'opérateurs installés : ne cherchez pas à tout lire, la sortie sert à être filtrée. Les lignes sont triées par groupe d'API puis par nom, ce qui explique que les ressources d'un même opérateur se retrouvent regroupées.

kubectl api-resources

Exemple de sortie (extrait) :

NAME                  SHORTNAMES   APIVERSION                     NAMESPACED   KIND
deployments           deploy       apps/v1                        true         Deployment
services              svc          v1                             true         Service
ingresses             ing          networking.k8s.io/v1           true         Ingress
nodes                 no           v1                             false        Node
clusterroles                       rbac.authorization.k8s.io/v1   false        ClusterRole

Chaque colonne a un rôle précis :

Colonne	Ce que ça vous donne	Où vous l'utilisez
NAME	Le nom au pluriel de la ressource	kubectl get <NAME>
SHORTNAMES	L'abréviation utilisable en CLI	kubectl get deploy au lieu de deployments
APIVERSION	Le groupe + version de l'API	Champ apiVersion: dans un manifest YAML
NAMESPACED	true = vit dans un namespace, false = cluster-wide	Savoir si -n s'applique
KIND	Le type exact	Champ kind: dans un manifest YAML

Glissez pour voir

Recette : trouver le kind et l'apiVersion pour un manifest

Vous voulez écrire un manifest mais vous ne connaissez pas le kind exact ni l'apiVersion ? Voici la méthode :

1. Cherchez la ressource par nom

   kubectl api-resources | grep -i ingress

   Sortie :

   ingressclasses                     networking.k8s.io/v1   false   IngressClass
   ingresses             ing          networking.k8s.io/v1   true    Ingress

   Le grep filtre l'en-tête : relancez sans grep si vous avez besoin du nom des colonnes. Sur un cluster équipé d'un ingress controller, attendez-vous à voir apparaître en plus les CRD de ce dernier (ingressroutes.traefik.io par exemple).

2. Lisez le kind et l'apiVersion

   • kind: Ingress
   • apiVersion: networking.k8s.io/v1

3. Commencez votre manifest

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: mon-ingress
     namespace: production
   spec:
     # → utilisez kubectl explain ingress.spec pour les champs

4. Explorez les champs avec explain

   kubectl explain ingress.spec.rules

Filtrer les ressources

Ces filtres se combinent entre eux et évitent le grep, qui reste un filtre textuel aveugle. --api-group est le plus discriminant : il isole toute une famille fonctionnelle d'un coup. --namespaced=false répond à une question opérationnelle précise, celle de savoir quelles ressources vous manipulez à l'échelle du cluster entier, donc avec un impact potentiel sur toutes les équipes qui le partagent.

# Par groupe d'API (workloads)
kubectl api-resources --api-group=apps

# Par groupe d'API (RBAC)
kubectl api-resources --api-group=rbac.authorization.k8s.io

# Par groupe d'API (réseau)
kubectl api-resources --api-group=networking.k8s.io

# Uniquement les ressources cluster-wide (non namespaced)
kubectl api-resources --namespaced=false

# Uniquement les ressources namespaced
kubectl api-resources --namespaced=true

# Par catégorie : ici, les types couverts par kubectl get all
kubectl api-resources --categories=all

Groupes d'API courants

Groupe	Ce qu'il contient
(vide, core)	Pods, Services, ConfigMaps, Secrets, Namespaces, Nodes
apps	Deployments, StatefulSets, DaemonSets, ReplicaSets
batch	Jobs, CronJobs
networking.k8s.io	Ingress, IngressClass, NetworkPolicy
rbac.authorization.k8s.io	Roles, ClusterRoles, RoleBindings
storage.k8s.io	StorageClasses, CSIDrivers, VolumeAttachments (les PersistentVolumeClaims restent dans le groupe core)
autoscaling	HorizontalPodAutoscaler

Glissez pour voir

Découvrir les CRD installées

Sur un cluster réel, des opérateurs ajoutent souvent des types de ressources personnalisés via des CRD (Custom Resource Definitions). Ces ressources apparaissent dans api-resources comme les ressources natives :

# Lister toutes les CRD installées
kubectl get crd

# Exemple de sortie
# NAME                                    CREATED AT
# certificates.cert-manager.io            2026-01-15T10:00:00Z
# issuers.cert-manager.io                 2026-01-15T10:00:00Z
# prometheusrules.monitoring.coreos.com   2026-01-20T08:00:00Z

Pour voir les nouveaux types qu'une CRD ajoute :

# Chercher les ressources cert-manager
kubectl api-resources | grep -i cert-manager

# Chercher les ressources d'un opérateur par domaine
kubectl api-resources | grep monitoring.coreos.com

Vous pouvez ensuite utiliser kubectl explain sur ces CRD exactement comme sur les ressources natives :

kubectl explain certificate.spec

kubectl explain : explorer la structure d'un objet

kubectl explain affiche la documentation d'un type de ressource ou d'un champ précis. C'est votre documentation intégrée pour écrire des manifests YAML sans quitter le terminal.

Syntaxe

La notation pointée est le point clé : elle suit exactement la hiérarchie de votre YAML. Le chemin deployment.spec.template.spec.containers reproduit les niveaux d'indentation que vous écrirez dans le manifest, ce qui permet de descendre champ par champ sans jamais afficher l'objet entier. La forme longue avec --recursive fait l'inverse : tout d'un coup, à réserver au grep.

# Vue d'ensemble d'un type
kubectl explain <type>

# Un champ précis (notation pointée)
kubectl explain <type>.<champ>.<sous-champ>

# L'arbre complet (tous les champs, récursif)
kubectl explain <type> --recursive

# Avec une version d'API spécifique
kubectl explain <type> --api-version=<version>

Recette : trouver comment écrire un readinessProbe

Vous savez qu'un Deployment a des readinessProbe, mais vous ne vous souvenez plus de la syntaxe exacte :

1. Trouvez le chemin dans l'arbre

   kubectl explain deployment.spec.template.spec.containers --recursive | grep -A9 readinessProbe

   Sortie :

     readinessProbe  <Probe>
       exec  <ExecAction>
         command  <[]string>
       failureThreshold  <integer>
       grpc  <GRPCAction>
         port  <integer> -required-
         service  <string>
       httpGet  <HTTPGetAction>
         host  <string>
         httpHeaders  <[]HTTPHeader>

   Les sous-champs sont triés par ordre alphabétique, pas par ordre d'importance : httpGet, le mode de sonde le plus courant, arrive après exec et grpc. Ajustez le nombre de lignes de -A selon la profondeur que vous voulez voir.

2. Affichez le détail du champ

   kubectl explain deployment.spec.template.spec.containers.readinessProbe

   Vous obtenez la description, le type, et si le champ est requis ou optionnel.

3. Explorez un sous-champ

   kubectl explain deployment.spec.template.spec.containers.readinessProbe.httpGet

   Sortie :

   GROUP:      apps
   KIND:       Deployment
   VERSION:    v1
   
   FIELD: httpGet <HTTPGetAction>
   
   DESCRIPTION:
       HTTPGet specifies the http request to perform.
       HTTPGetAction describes an action based on HTTP Get requests.
   
   FIELDS:
     host  <string>
     httpHeaders  <[]HTTPHeader>
     path  <string>
     port  <IntOrString> -required-
     scheme  <string>

   Le bloc d'en-tête GROUP / KIND / VERSION confirme sur quelle version de l'API vous travaillez. La mention -required- sur port est l'information à repérer : c'est le seul champ que vous ne pouvez pas omettre.

4. Écrivez votre YAML

   readinessProbe:
     httpGet:
       path: /healthz
       port: 8080
     initialDelaySeconds: 5
     periodSeconds: 10

Explorer l'arbre complet d'un objet

L'option --recursive affiche tous les champs d'un type, présentés en arbre indenté. C'est utile pour avoir une vue d'ensemble ou pour chercher un champ dont vous avez oublié le chemin :

# Arbre complet d'un Pod
kubectl explain pod.spec --recursive | less

# Arbre complet d'un Deployment (très long)
kubectl explain deployment --recursive | less

# Chercher un champ spécifique dans l'arbre
kubectl explain deployment --recursive | grep -i toleration

Combiner grep et explain

L'arbre récursif peut faire des centaines de lignes. Combinez --recursive avec grep -B2 -A5 pour trouver rapidement un champ et son contexte :

kubectl explain deployment --recursive | grep -B2 -A5 "affinity"

Le piège kubectl get all

kubectl get all est souvent la première commande qu'on apprend. Mais elle ne montre pas tout : elle n'affiche que les types portant la catégorie all. Pour connaître la liste exacte sur votre cluster, demandez-la plutôt que de la supposer :

kubectl api-resources --categories=all

Sur un cluster récent, elle renvoie dix types : Pods, ReplicationControllers, Services, DaemonSets, Deployments, ReplicaSets, StatefulSets, HorizontalPodAutoscalers, CronJobs et Jobs.

kubectl get all ment par omission

kubectl get all n'affiche pas : ConfigMaps, Secrets, Ingress, PersistentVolumeClaims, NetworkPolicies, ServiceAccounts, Roles, ni aucune CRD. C'est un piège classique qui fait passer des ressources critiques sous le radar.

Lister vraiment toutes les ressources d'un namespace

Pour obtenir une vue complète, itérez sur tous les types namespaced :

# Liste exhaustive des ressources d'un namespace
kubectl api-resources --namespaced=true --verbs=list -o name \
  | xargs -I {} kubectl get {} -n <namespace> --no-headers 2>/dev/null \
  | grep -v "^$"

Cette commande :

1. Récupère tous les types de ressources namespaced qui supportent list
2. Exécute kubectl get pour chacun
3. Supprime les erreurs (certains types sont vides) et les lignes vides

Pour une version plus lisible qui affiche le type de ressource devant chaque ligne :

kubectl api-resources --namespaced=true --verbs=list -o name \
  | while read kind; do
      output=$(kubectl get "$kind" -n <namespace> --no-headers 2>/dev/null)
      if [ -n "$output" ]; then
        echo "--- $kind ---"
        echo "$output"
      fi
    done

Cheat sheet

Ce tableau condense le guide en dix lignes, à garder ouvert le temps que les commandes deviennent un réflexe. Les deux dernières entrées sont celles qui répondent aux questions posées en situation réelle : « quel apiVersion j'écris ? » et « qu'est-ce qui tourne vraiment dans ce namespace ? ».

Je veux…	Commande
Chercher une ressource par nom	kubectl api-resources | grep -i <nom>
Filtrer par groupe d'API	kubectl api-resources --api-group=apps
Voir uniquement les ressources cluster-wide	kubectl api-resources --namespaced=false
Voir les CRD installées	kubectl get crd
Voir la structure d'un type	kubectl explain <type>
Explorer un champ précis	kubectl explain <type>.<champ>.<sous-champ>
Afficher l'arbre complet	kubectl explain <type> --recursive
Chercher un champ dans l'arbre	kubectl explain <type> --recursive | grep <champ>
Trouver le kind + apiVersion	kubectl api-resources | grep -i <nom> → colonnes KIND et APIVERSION
Lister tout dans un namespace (pas juste get all)	Boucle sur api-resources --namespaced=true

Glissez pour voir

Bonnes pratiques

Le fil conducteur de ces six points est le même : votre cluster est la source de vérité, pas un article trouvé en ligne ni le souvenir d'un manifest écrit l'an dernier. Les groupes d'API bougent d'une version de Kubernetes à l'autre, et un manifest copié depuis un tutoriel de 2021 peut cibler une apiVersion qui n'existe plus.

• Utilisez explain avant d'écrire un manifest, c'est plus fiable qu'une recherche web, car aligné avec votre version du cluster.
• Vérifiez l'apiVersion avec api-resources, les groupes d'API changent entre versions (ex: extensions/v1beta1 → networking.k8s.io/v1 pour les Ingress).
• Ne faites pas confiance à kubectl get all, utilisez la boucle sur api-resources pour un audit complet.
• Explorez les CRD, sur un cluster entreprise, la moitié des ressources sont souvent des CRD installées par des opérateurs.
• Combinez --recursive et grep, pour naviguer dans les grandes structures sans se perdre.
• Passez --api-version à explain, si votre cluster propose plusieurs versions d'une même ressource, précisez laquelle vous ciblez.

Dépannage

Avant de parcourir ce tableau, écartez la cause la plus banale : le mauvais contexte. Un kubectl config current-context confirme que vous interrogez bien le cluster que vous croyez. La troisième ligne mérite une attention particulière : une ressource absente de api-resources peut aussi être une ressource sur laquelle vos droits RBAC ne vous accordent pas le verbe list, auquel cas elle existe mais reste invisible pour vous.

Symptôme	Cause probable	Solution
kubectl explain retourne error: couldn't find resource	Nom de la ressource incorrect	Vérifiez avec kubectl api-resources | grep -i <nom>
explain montre des champs qui n'existent pas dans votre YAML	Vous regardez la mauvaise version de l'API	Ajoutez --api-version=apps/v1 (ou la version correcte)
api-resources ne montre pas un type attendu	CRD pas installée ou droits insuffisants	Vérifiez kubectl get crd et vos permissions RBAC
api-resources affiche deux lignes pour le même type	La ressource existe dans plusieurs groupes d'API	Utilisez --api-group= pour cibler le bon groupe
kubectl get all ne montre pas mes Ingress/Secrets	get all ne couvre pas tous les types	Utilisez la boucle sur api-resources ou ciblez le type directement
explain --recursive est trop long	Type complexe (Deployment, Pod)	Pipez dans less ou combinez avec grep

Glissez pour voir

À retenir

• kubectl api-resources liste tous les types de ressources de votre cluster, y compris les CRD, c'est votre annuaire.
• kubectl explain affiche la documentation d'un type ou d'un champ, directement depuis le schéma OpenAPI du serveur, c'est votre dictionnaire.
• Pour écrire un manifest, la méthode : api-resources | grep pour trouver le kind et l'apiVersion, puis explain pour explorer les champs.
• kubectl get all ne montre pas tout, itérez sur api-resources --namespaced=true pour un inventaire complet.
• L'option --recursive affiche l'arbre complet d'un objet, combinez avec grep pour naviguer efficacement.
• Les informations de explain sont spécifiques à votre cluster : elles reflètent la version exacte de votre serveur API.

Prochaines étapes

Créer et déployer avec create et apply Utilisez les types trouvés pour créer vos ressources en impératif ou déclaratif.

Écrire des manifests Kubernetes Les bonnes pratiques pour structurer et valider vos fichiers YAML.

Diagnostiquer avec kubectl Runbook de diagnostic : get, describe, logs et top en situation d'incident.

Labels et annotations Organiser et filtrer vos ressources avec les labels et annotations.

Cheat sheet kubectl Toutes les commandes kubectl essentielles sur une page.

×

📖 Voir la documentation →