Maîtriser les APIs Kubernetes pour le développement d'applications

L'API Kubernetes constitue le cœur de toute interaction avec un cluster. Chaque commande kubectl, chaque déploiement, chaque scaling passe par cette API REST. Pour le développeur Backend Kubernetes, comprendre et maîtriser l'API Kubernetes représente la différence entre subir l'orchestrateur et le contrôler programmatiquement.

TL;DR : Ce guide vous accompagne étape par étape dans la maîtrise de l'API Kubernetes : architecture, interactions via kubectl et client-go, création de Custom Resources, et construction de contrôleurs personnalisés. Chaque étape inclut du code exécutable et des commandes de vérification.

Ces compétences sont au cœur de la formation LFD459 Kubernetes pour les développeurs d'applications.

---

Prérequis

Avant de commencer, vérifiez que votre environnement répond à ces exigences :

Vérifiez votre accès au cluster :

kubectl cluster-info
# Résultat attendu :
# Kubernetes control plane is running at https://127.0.0.1:6443
# CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

À retenir : 82% des utilisateurs de conteneurs exécutent Kubernetes en production (CNCF Annual Survey 2025). Maîtriser l'API vous positionne sur un standard industriel incontournable.

---

Étape 1 : Comprendre l'architecture de l'API Kubernetes

L'API Kubernetes est une API REST organisée en groupes et versions. Chaque ressource appartient à un groupe API spécifique.

1.1 Explorer les groupes d'API disponibles

Listez tous les groupes d'API de votre cluster :

kubectl api-versions
# Résultat attendu (extrait) :
# apps/v1
# batch/v1
# networking.k8s.io/v1
# rbac.authorization.k8s.io/v1
# v1

Les ressources core (pods, services, configmaps) appartiennent au groupe vide, accessible via /api/v1. Les ressources étendues utilisent /apis//.

1.2 Découvrir les ressources d'un groupe

Explorez les ressources du groupe apps/v1 :

kubectl api-resources --api-group=apps
# Résultat attendu :
# NAME                  SHORTNAMES   APIVERSION   NAMESPACED   KIND
# deployments           deploy       apps/v1      true         Deployment
# replicasets           rs           apps/v1      true         ReplicaSet
# statefulsets          sts          apps/v1      true         StatefulSet
# daemonsets            ds           apps/v1      true         DaemonSet

Vérification : Chaque ressource expose des verbes (create, get, list, watch, update, delete). Consultez-les avec :

kubectl api-resources --api-group=apps -o wide

Cette compréhension est essentielle pour le design d'applications conteneurisées pour Kubernetes.

---

Étape 2 : Interagir avec l'API via kubectl proxy

kubectl agit comme client HTTP vers l'API. Pour des interactions directes, utilisez kubectl proxy.

2.1 Démarrer le proxy local

Lancez le proxy dans un terminal séparé :

kubectl proxy --port=8080
# Résultat attendu :
# Starting to serve on 127.0.0.1:8080

2.2 Interroger l'API directement

Listez les pods du namespace default via curl :

curl http://localhost:8080/api/v1/namespaces/default/pods
# Résultat attendu (JSON) :
# {
#   "kind": "PodList",
#   "apiVersion": "v1",
#   "items": [...]
# }

Créez un pod via l'API :

curl -X POST http://localhost:8080/api/v1/namespaces/default/pods \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "v1",
    "kind": "Pod",
    "metadata": {"name": "api-test-pod"},
    "spec": {
      "containers": [{
        "name": "nginx",
        "image": "nginx:1.25"
      }]
    }
  }'

Vérification :

kubectl get pod api-test-pod
# Résultat attendu :
# NAME           READY   STATUS    RESTARTS   AGE
# api-test-pod   1/1     Running   0          30s

À retenir : Chaque commande kubectl traduit vos intentions en requêtes HTTP vers l'API. Comprendre cette mécanique vous permet de déboguer efficacement et d'automatiser via n'importe quel langage.

---

Étape 3 : Utiliser client-go pour développer en Go

Pour le développeur Backend Kubernetes travaillant en Go, client-go est la bibliothèque officielle pour interagir avec l'API. Elle offre typage fort, watchers, et informers.

3.1 Initialiser un projet Go

Créez la structure du projet :

mkdir k8s-api-demo && cd k8s-api-demo
go mod init k8s-api-demo
go get k8s.io/client-go@v0.29.0
go get k8s.io/apimachinery@v0.29.0

3.2 Lister les pods avec client-go

Créez le fichier main.go :

package main

import (
    "context"
    "fmt"
    "os"
    "path/filepath"

    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/clientcmd"
)

func main() {
    // Charger la configuration kubeconfig
    kubeconfig := filepath.Join(os.Getenv("HOME"), ".kube", "config")
    config, err := clientcmd.BuildConfigFromFlags("", kubeconfig)
    if err != nil {
        panic(err)
    }

    // Créer le clientset
    clientset, err := kubernetes.NewForConfig(config)
    if err != nil {
        panic(err)
    }

    // Lister les pods du namespace default
    pods, err := clientset.CoreV1().Pods("default").List(
        context.TODO(),
        metav1.ListOptions{},
    )
    if err != nil {
        panic(err)
    }

    fmt.Printf("Nombre de pods: %d\n", len(pods.Items))
    for _, pod := range pods.Items {
        fmt.Printf("- %s (%s)\n", pod.Name, pod.Status.Phase)
    }
}

Exécutez le programme :

go run main.go
# Résultat attendu :
# Nombre de pods: 2
# - api-test-pod (Running)
# - another-pod (Running)

Cette approche programmatique est couverte dans les commandes kubectl essentielles pour développeurs et approfondie dans la formation LFD459.

---

Étape 4 : Créer des Custom Resources (CRD)

Les Custom Resources API Kubernetes permettent d'étendre l'API avec vos propres types. C'est le fondement des opérateurs Kubernetes.

4.1 Définir une CustomResourceDefinition

Créez le fichier backup-crd.yaml :

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: backups.example.com
spec:
  group: example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                schedule:
                  type: string
                retention:
                  type: integer
                target:
                  type: string
  scope: Namespaced
  names:
    plural: backups
    singular: backup
    kind: Backup
    shortNames:
      - bkp

Appliquez la CRD :

kubectl apply -f backup-crd.yaml
# Résultat attendu :
# customresourcedefinition.apiextensions.k8s.io/backups.example.com created

4.2 Créer une instance de Custom Resource

Créez le fichier my-backup.yaml :

apiVersion: example.com/v1
kind: Backup
metadata:
  name: database-backup
spec:
  schedule: "0 2 * * *"
  retention: 7
  target: "postgres-primary"

Appliquez et vérifiez :

kubectl apply -f my-backup.yaml
kubectl get backups
# Résultat attendu :
# NAME              AGE
# database-backup   5s

À retenir : Les CRD transforment Kubernetes en plateforme extensible. 70% des organisations utilisent Helm pour déployer des applications packagées qui exploitent souvent des CRD (Orca Security 2025).

---

Étape 5 : Configurer l'authentification et RBAC

L'accès à l'API Kubernetes nécessite authentification et autorisation. Le modèle RBAC (Role-Based Access Control) définit qui peut faire quoi.

5.1 Créer un ServiceAccount pour votre application

kubectl create serviceaccount api-client
# Résultat attendu :
# serviceaccount/api-client created

5.2 Définir un Role avec permissions limitées

Créez le fichier api-role.yaml :

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["example.com"]
    resources: ["backups"]
    verbs: ["get", "list", "create", "update"]

5.3 Lier le Role au ServiceAccount

Créez le RoleBinding :

kubectl create rolebinding api-client-binding \
  --role=pod-reader \
  --serviceaccount=default:api-client
# Résultat attendu :
# rolebinding.rbac.authorization.k8s.io/api-client-binding created

Vérification des permissions :

kubectl auth can-i list pods --as=system:serviceaccount:default:api-client
# Résultat attendu : yes

kubectl auth can-i delete pods --as=system:serviceaccount:default:api-client
# Résultat attendu : no

Cette configuration RBAC est fondamentale pour la sécurité Kubernetes de vos applications.

---

Étape 6 : Implémenter un watcher avec client-go

Les watchers permettent de réagir en temps réel aux changements de ressources. C'est le pattern utilisé par tous les contrôleurs Kubernetes.

6.1 Code du watcher

Ajoutez ce code à votre projet :

package main

import (
    "context"
    "fmt"

    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/watch"
    "k8s.io/client-go/kubernetes"
)

func watchPods(clientset *kubernetes.Clientset) {
    watcher, err := clientset.CoreV1().Pods("default").Watch(
        context.TODO(),
        metav1.ListOptions{},
    )
    if err != nil {
        panic(err)
    }

    fmt.Println("Watching pods...")
    for event := range watcher.ResultChan() {
        pod := event.Object.(*corev1.Pod)
        switch event.Type {
        case watch.Added:
            fmt.Printf("[ADDED] %s\n", pod.Name)
        case watch.Modified:
            fmt.Printf("[MODIFIED] %s -> %s\n", pod.Name, pod.Status.Phase)
        case watch.Deleted:
            fmt.Printf("[DELETED] %s\n", pod.Name)
        }
    }
}

Testez en créant/supprimant un pod dans un autre terminal :

kubectl run test-watch --image=nginx:1.25
kubectl delete pod test-watch

Votre watcher affichera les événements en temps réel.

À retenir : Les informers et watchers sont le fondement des opérateurs Kubernetes. Maîtriser ce pattern ouvre la porte au développement applications Kubernetes avancé.

---

Vérification finale

Validez chaque composant de votre apprentissage :

---

Dépannage des erreurs courantes

Erreur : "Unable to connect to the server"

# Vérifiez que le cluster est accessible
kubectl cluster-info

# Si le contexte est incorrect
kubectl config get-contexts
kubectl config use-context <correct-context>

Erreur : "forbidden: User cannot list resource"

Le ServiceAccount manque de permissions. Vérifiez le RoleBinding :

kubectl get rolebindings -o wide
kubectl describe rolebinding api-client-binding

Erreur : "no matches for kind CRD"

La CRD n'est pas installée ou le groupe/version est incorrect :

kubectl get crd | grep example.com
kubectl api-resources --api-group=example.com

Erreur client-go : "unable to load kubeconfig"

# Vérifiez que KUBECONFIG est défini
echo $KUBECONFIG

# Ou que ~/.kube/config existe
ls -la ~/.kube/config

Pour des cas plus complexes, consultez les patterns de développement cloud-native pour Kubernetes.

---

Ressources complémentaires

Le marché Kubernetes croît de 21,85% par an, atteignant 8,41 milliards USD d'ici 2031 (Mordor Intelligence). Cette compétence représente un investissement durable.

Pour une étude de cas concrète, découvrez comment migrer une application monolithique vers Kubernetes en exploitant ces API.

---

Passez à l'action : développez vos compétences API Kubernetes

Vous maîtrisez maintenant les fondamentaux de l'API Kubernetes : architecture REST, interactions kubectl et client-go, Custom Resources, et RBAC. Ces compétences sont validées par la certification CKAD.

Pour approfondir avec un accompagnement structuré :

• LFD459 Kubernetes pour les développeurs d'applications : 3 jours intensifs couvrant le développement client-go, les CRD, et la préparation CKAD
• Kubernetes, les fondamentaux : 1 journée pour découvrir l'écosystème Kubernetes si vous débutez
• Formation Kubernetes : Guide Complet : explorez tous nos parcours de formation

Contactez nos conseillers pour définir le parcours adapté à vos objectifs de développeur Backend Kubernetes.