Operators et CRDs pour développeurs

Les Custom Resource Definitions (CRDs) étendent Kubernetes avec de nouveaux types de ressources. En tant que développeur, vous n’avez pas besoin de créer des opérateurs — mais vous devez savoir utiliser les ressources custom que d’autres ont créées. Ce guide vous montre comment découvrir, manipuler et diagnostiquer les CRDs dans votre cluster.

Ce guide est orienté utilisation

Ce guide couvre l’utilisation des CRDs et opérateurs, pas leur développement. Pour créer vos propres opérateurs, consultez le guide Operators complet.

Ce que vous allez apprendre

• Comprendre le modèle CRD/Operator sans entrer dans le développement
• Découvrir les CRDs disponibles dans votre cluster
• Manipuler des ressources custom avec kubectl
• Installer un opérateur depuis OperatorHub
• Diagnostiquer les problèmes courants liés aux CRDs

CRD et Operator : l’essentiel pour un développeur

Qu’est-ce qu’une CRD ?

Une Custom Resource Definition (CRD) ajoute un nouveau type d’objet à Kubernetes. Au lieu de manipuler uniquement des Pods, Services ou Deployments, vous pouvez manipuler des objets métier comme PostgresCluster, Certificate ou GitRepository.

Concept	Analogie	Exemple
CRD	Définition de table SQL	kind: PostgresCluster
Custom Resource (CR)	Ligne dans la table	Un cluster PostgreSQL spécifique
Operator	Application qui réagit aux CRs	Crée les Pods, Services, Secrets nécessaires

Glissez pour voir

Le pattern Controller

L’opérateur est un controller qui observe les ressources custom et agit pour atteindre l’état désiré :

┌─────────────────────────────────────────────────────────────┐
│                    Boucle de réconciliation                 │
├─────────────────────────────────────────────────────────────┤
│  1. OBSERVER : L'opérateur watch les CRs                    │
│  2. COMPARER : État actuel vs état désiré                   │
│  3. AGIR : Créer/modifier/supprimer des ressources          │
│  4. RÉPÉTER : En continu                                    │
└─────────────────────────────────────────────────────────────┘

Vous n'avez pas à comprendre le code de l'opérateur

En tant que développeur applicatif, vous interagissez avec les CRs (les objets YAML). L’opérateur gère la complexité derrière. C’est comme utiliser une base de données sans savoir comment elle fonctionne en interne.

Découvrir les CRDs de votre cluster

Lister toutes les CRDs

# Toutes les CRDs installées
kubectl get crds

# Exemple de sortie :
# NAME                                  CREATED AT
# certificates.cert-manager.io          2026-03-20T10:00:00Z
# issuers.cert-manager.io               2026-03-20T10:00:00Z
# postgresclusters.postgres-operator.crunchydata.com  2026-03-15T08:30:00Z

Explorer une CRD spécifique

# Détails d'une CRD
kubectl describe crd certificates.cert-manager.io

# Structure YAML de la CRD
kubectl get crd certificates.cert-manager.io -o yaml

Découvrir les API groups

# Tous les types de ressources disponibles (natifs + custom)
kubectl api-resources

# Filtrer par API group
kubectl api-resources --api-group=cert-manager.io

# Exemple de sortie :
# NAME           SHORTNAMES   APIVERSION              NAMESPACED   KIND
# certificates   cert         cert-manager.io/v1      true         Certificate
# issuers                     cert-manager.io/v1      true         Issuer

Shortnames

De nombreuses CRDs définissent des shortnames. Au lieu de kubectl get certificates, vous pouvez écrire kubectl get cert. Utilisez kubectl api-resources pour les découvrir.

Lister les ressources custom

# Lister les instances d'une CR
kubectl get certificates -n mon-namespace

# Dans tous les namespaces
kubectl get certificates -A

# Avec plus de détails
kubectl get certificates -o wide

Interagir avec des ressources custom

Créer une ressource custom

Le format est identique aux ressources natives. Exemple avec cert-manager :

certificate.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: mon-app-tls
  namespace: production
spec:
  secretName: mon-app-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - mon-app.example.com
    - www.mon-app.example.com

kubectl apply -f certificate.yaml

Inspecter une ressource custom

# Détails complets
kubectl describe certificate mon-app-tls -n production

# YAML brut
kubectl get certificate mon-app-tls -n production -o yaml

# JSONPath pour extraire un champ
kubectl get certificate mon-app-tls -n production \
  -o jsonpath='{.status.conditions[0].status}'

Comprendre le champ status

Les CRs bien conçues exposent un champ .status mis à jour par l’opérateur :

status:
  conditions:
    - type: Ready
      status: "True"
      reason: CertificateIssued
      message: Certificate is up to date and has been issued
      lastTransitionTime: "2026-03-25T10:30:00Z"
  notAfter: "2026-06-25T10:30:00Z"
  notBefore: "2026-03-25T10:30:00Z"
  renewalTime: "2026-05-25T10:30:00Z"

Conditions : le pattern standard

La plupart des CRs utilisent le pattern conditions pour indiquer leur état. Cherchez status.conditions[?(@.type=="Ready")].status pour savoir si la ressource est prête.

Modifier une ressource custom

# Édition interactive
kubectl edit certificate mon-app-tls -n production

# Patch (modifier un champ)
kubectl patch certificate mon-app-tls -n production \
  --type=merge \
  -p '{"spec":{"dnsNames":["mon-app.example.com","api.example.com"]}}'

Supprimer une ressource custom

kubectl delete certificate mon-app-tls -n production

Finalizers et suppression

Certaines CRs ont des finalizers qui retardent la suppression le temps que l’opérateur nettoie les ressources associées. Si une CR reste en état Terminating, vérifiez les logs de l’opérateur.

Exemples de CRDs courantes

cert-manager : Certificats TLS

certificate-letsencrypt.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: api-tls
  namespace: production
spec:
  secretName: api-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - api.example.com

Prometheus : ServiceMonitor

servicemonitor.yaml

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: mon-app
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: mon-app
  endpoints:
    - port: metrics
      interval: 30s

Argo CD : Application

argo-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mon-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/mon-org/mon-app
    path: k8s
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

External Secrets : Intégration vault

external-secret.yaml

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db-credentials
  namespace: production
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: db-credentials
  data:
    - secretKey: username
      remoteRef:
        key: secret/data/database
        property: username
    - secretKey: password
      remoteRef:
        key: secret/data/database
        property: password

Installer un opérateur

Option 1 : Helm (recommandé)

La plupart des opérateurs sont distribués via Helm :

# Exemple : cert-manager
helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

Option 2 : kubectl apply

Certains opérateurs fournissent un manifest unique :

# Exemple : metrics-server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Option 3 : OperatorHub (OpenShift / OLM)

Si votre cluster utilise Operator Lifecycle Manager :

# Installer OLM (si pas déjà présent)
curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.28.0/install.sh | bash -s v0.28.0

# Installer un opérateur depuis OperatorHub
kubectl create -f https://operatorhub.io/install/prometheus.yaml

Vérifiez la compatibilité

Avant d’installer un opérateur, vérifiez :

• La version Kubernetes requise
• Les permissions RBAC nécessaires
• Les CRDs qui seront créées
• La documentation officielle

Diagnostiquer les problèmes

La CR reste en état Pending/Unknown

# 1. Vérifier les événements de la CR
kubectl describe <kind> <name> -n <namespace>

# 2. Vérifier que l'opérateur tourne
kubectl get pods -n <operator-namespace>

# 3. Lire les logs de l'opérateur
kubectl logs -n <operator-namespace> deployment/<operator-name>

Erreur “no matches for kind” lors du kubectl apply

# Le CRD n'est pas installé
kubectl get crd | grep <kind>

# Solution : installer l'opérateur d'abord

La CR est bloquée en Terminating

# Vérifier les finalizers
kubectl get <kind> <name> -o jsonpath='{.metadata.finalizers}'

# Si l'opérateur ne tourne plus, retirer le finalizer manuellement
kubectl patch <kind> <name> \
  --type=json \
  -p='[{"op": "remove", "path": "/metadata/finalizers"}]'

Retirer un finalizer manuellement

Ne retirez un finalizer que si l’opérateur n’existe plus ou est définitivement cassé. Sinon, vous risquez de laisser des ressources orphelines.

Problème de permissions

L’opérateur n’a pas les droits nécessaires :

# Vérifier les logs pour des erreurs RBAC
kubectl logs -n <operator-namespace> deployment/<operator-name> | grep -i forbidden

# Vérifier les Roles/ClusterRoles de l'opérateur
kubectl get clusterrole | grep <operator-name>
kubectl describe clusterrole <operator-role>

Utiliser kubectl explain

La commande kubectl explain fonctionne aussi avec les CRDs :

# Structure générale
kubectl explain certificate

# Champ spécifique
kubectl explain certificate.spec.issuerRef

# Liste des champs disponibles
kubectl explain certificate.spec --recursive

Documentation intégrée

kubectl explain est votre meilleur ami pour comprendre la structure d’une CR sans chercher dans la documentation web.

Bonnes pratiques développeur

Avant de créer une CR

1. Vérifiez que la CRD existe : kubectl get crd <name>
2. Lisez la documentation : Les CRDs ont souvent des exemples
3. Utilisez kubectl explain : Pour comprendre les champs disponibles
4. Validez avec --dry-run : kubectl apply -f cr.yaml --dry-run=client

Nommage et organisation

1. Préfixez par application : mon-app-certificate plutôt que certificate-1
2. Utilisez des labels : Facilitez le filtrage et le monitoring
3. Documentez : Ajoutez des annotations expliquant le but

Surveillance

1. Surveillez les status : Les CRs exposent leur état dans .status
2. Alertez sur les échecs : Conditions Ready=False ou Failed=True
3. Tracez les changements : Activez l’audit logging pour les CRs sensibles

À retenir

Concept	Ce qu’il faut retenir
CRD	Nouveau type de ressource Kubernetes
CR (Custom Resource)	Instance d’une CRD
Operator	Controller qui gère les CRs
kubectl api-resources	Découvrir les types disponibles
kubectl explain	Comprendre la structure d’une CR
.status.conditions	État de la ressource
Finalizers	Retardent la suppression pour nettoyage

Glissez pour voir

Règle d’or : En tant que développeur, vous utilisez les CRs — vous n’avez pas besoin de comprendre le code de l’opérateur, seulement la spec que vous fournissez et le status qu’il retourne.

Testez vos connaissances

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

8 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Prochaines étapes

Operators Kubernetes Guide complet pour créer vos propres opérateurs

Helm Installer des opérateurs via Helm

ServiceAccounts Permissions pour vos applications

Debug applications Diagnostiquer les problèmes

×

📖 Voir la documentation →