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

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 :

   NAME                  SHORTNAMES   APIVERSION                     NAMESPACED   KIND
   ingresses             ing          networking.k8s.io/v1           true         Ingress
   ingressclasses                     networking.k8s.io/v1           false        IngressClass

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

La liste complète est longue. Voici les filtres les plus utiles :

# 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 (si disponible)
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, PersistentVolumeClaims (via 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

# 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 -A2 readiness

   Sortie :

      readinessProbe       <Probe>
         exec      <ExecAction>
            command  <[]string>
         httpGet   <HTTPGetAction>
            ...
         tcpSocket <TCPSocketAction>
            ...
         initialDelaySeconds  <integer>
         periodSeconds        <integer>

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 :

   FIELD: httpGet <HTTPGetAction>
   DESCRIPTION:
     HTTPGet specifies the http request to perform.
   
   FIELDS:
     host     <string>
     httpHeaders  <[]HTTPHeader>
     path     <string>
     port     <IntOrString> -required-
     scheme   <string>

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 de la catégorie all (Pods, Services, Deployments, ReplicaSets, Jobs, CronJobs, DaemonSets, StatefulSets).

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

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

• 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

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 →