fieldManager: portal-dawap
API
Intégrateur Kubernetes API : relier état désiré, état observé et action métier
Kubernetes API est un plan de contrôle convergent, pas une base CRUD. Dawap relie vos portails, outils internes et workflows DevOps à la paire spec/status, aux versions de ressources, aux contrôleurs et aux droits réels pour qu’une action demandée reste observable jusqu’à son résultat.
APIs, données et infrastructures que nos projets savent connecter
Conception, intégration et maintenance
01
Contrat
versionné
02
Sécurité
explicite
03
Reprise
testée
04
Supervision
avec alertes
Réponse courte
Kubernetes n’exécute pas une commande : ses contrôleurs font converger un état.
Dawap cadre l’identité de l’objet, la lecture list-watch, les écritures concurrentes, les droits du service account et la preuve de convergence. Aucun projet client Kubernetes nommé n’est publié : les références plus bas prouvent des garde-fous adjacents, pas une réalisation Kubernetes.
- Identifier apiVersion, kind, namespace, name, UID, generation et resourceVersion.
- Relancer un list-watch après expiration sans conserver un cache silencieusement incomplet.
- Relire status, conditions, événements utiles et effet métier avant de clore.
La boucle de contrôle rendue lisible
État désiré, état observé, décision métier.
Cette vue sépare ce que le portail demande, ce que le contrôleur observe et ce que le métier peut réellement considérer comme terminé. Les identifiants, conditions et propriétaires de champs restent attachés au parcours.
List-watchCache certifiable
exemple de reprise
- 01ListSnapshot initialcomplet
Objets, selectors et resourceVersion enregistrés.
- 02WatchÉvénements appliquéssuivi
Chaque mutation est idempotente dans le cache.
- 03Rupture410 Gonerelist
L’ancienne resourceVersion n’est plus disponible.
- 04ReconstructionNouveau snapshotattendu
Aucune décision sensible avant rapprochement.
- 05RepriseWatch relancécertifié
La nouvelle version devient le point de départ.
Signaux Kubernetes
Trois faux succès qui apparaissent quand le control plane est traité comme du CRUD
Une ressource acceptée, un cache silencieux ou un DELETE 202 ne prouvent ni la convergence, ni l’exhaustivité, ni le nettoyage externe.
01
Convergence
La spec est écrite, mais observedGeneration reste en retard
Le workflow annonce un succès avant que le contrôleur ait rendu la condition attendue.
02
Watch
Une expiration 410 laisse le portail avec un inventaire troué
Sans relist complet, les décisions suivantes s’appuient sur un cache qui ne peut plus être certifié.
03
Suppression
202 Accepted masque un finalizer bloqué
L’objet et sa dépendance externe restent présents tant que le contrôleur de nettoyage n’a pas terminé.
Architecture Kubernetes API
Une réponse API valide ne prouve ni le bon objet, ni la convergence, ni la fin de la suppression
Les contrôleurs réconcilient continuellement l’état réel vers l’état désiré. L’intégration doit respecter cette mécanique, ses versions et ses propriétaires de champs au lieu de transformer chaque endpoint en commande impérative.
Objet sans ambiguïté
Conserver cluster, apiVersion, kind, namespace, name et UID. La generation suit les évolutions désirées ; resourceVersion sert à détecter les changements et les conflits, pas d’identifiant métier.
Spec, status et conditions
Écrire la spec autorisée, puis relire status, observedGeneration et conditions propres au type. Un HTTP 200 ou 201 signifie traitement API, pas disponibilité de l’application.
List-watch reconstructible
Initialiser le cache, suivre les événements et conserver la resourceVersion. Sur 410 Gone, refaire une liste cohérente et reconstruire l’état avant de reprendre le watch.
Champs et concurrence
Choisir update, patch ou Server-Side Apply. Nommer fieldManager, traiter le conflit de propriété et réserver force à une décision explicite : forcer transfère le champ au nouvel acteur.
Identité et RBAC effectif
Utiliser un service account dédié et un token projeté à durée bornée. Les règles RBAC sont additives : éviter wildcards, accès transverse aux secrets et cluster-admin par commodité.
Suppression et nettoyage
DELETE peut seulement poser deletionTimestamp et renvoyer 202. Lire finalizers, ownerReferences et dépendances ; retirer un finalizer inconnu peut laisser une ressource externe orpheline.
Méthode
On dessine d’abord demande–objet–contrôleur–effet sur un seul namespace
Le pilote utilise un service account borné, reconstruit son cache après une watch expirée, refuse un conflit de champ, suit status et conditions, puis attend la fin réelle d’une suppression. Les chemins 403, 409, 410, 429, timeout et finalizer bloqué sont traités avant toute extension.
Décision 1
Objet et cluster sans ambiguïté
Décision 2
Cache list-watch reconstructible
Décision 3
Champs et gestionnaires compatibles
Décision 4
RBAC réellement minimal
Premier lot Kubernetes
Prouver une action bornée sur un namespace non critique.
On part d’une demande autorisée, on cible un objet sans ambiguïté, on provoque un conflit et une expiration de watch, puis on vérifie la convergence ou la suppression jusqu’à l’effet métier attendu.
Entrée : demande autorisée
Sortie : état observé réconcilié
Suite : étendre par namespace
Le périmètre à définir
Matrice cluster × environnement × API group/version × kind × namespace × owner métier et plateforme.
Contrat spec, status, generation, observedGeneration, conditions, UID et resourceVersion par objet.
Service account dédié, token court, Role/ClusterRole et bindings relus en permissions effectives.
Recette 401, 403, 404, 409, 410, 429, timeout, watch interrompu, finalizer bloqué et reprise.
Recette Kubernetes API
Trois contre-tests qui révèlent les faux succès du control plane
La recette porte sur les ruptures propres à Kubernetes : cache de watch incomplet, champ possédé par un autre gestionnaire et objet encore présent après DELETE.
Le watch expire et le portail continue avec un inventaire incomplet
Le serveur n’est pas tenu de conserver toutes les anciennes resourceVersion et peut répondre 410 Gone. Reprendre aveuglément le flux ou considérer le silence comme un état stable fait disparaître des objets et des transitions du cache local.
- Entrée
- Cluster, resource type, selectors, limit/continue, resourceVersion initiale, dernier événement traité, code 410/429, Retry-After, date du relist et checksum de l’état reconstruit.
- Sortie
- Boucle list-watch avec reprise bornée, backoff, relist complet sur version expirée, déduplication des événements et alerte si le cache ne peut plus être certifié.
- Décision
- Interdire toute décision sensible tant que le cache n’a pas été reconstruit et rapproché après une rupture.
Le portail force un conflit et reprend un champ géré par GitOps
Server-Side Apply suit la propriété des champs avec managedFields et exige un fieldManager. Un champ différent déjà géré par un autre acteur provoque un conflit ; force l’écrase et transfère sa propriété.
- Entrée
- Objet et UID, resourceVersion, generation, patch, fieldManager, managedFields avant/après, conflit, acteur, justification, diff, contrôleur concurrent et résultat observé.
- Sortie
- Contrat de champs autorisés, nom de gestionnaire stable, refus par défaut du conflit, lecture avant reprise et procédure d’exception qui ne transforme jamais force en retry automatique.
- Décision
- Faire arbitrer le propriétaire légitime du champ ; ne forcer qu’un transfert explicitement approuvé et traçable.
DELETE renvoie 202, mais la ressource et sa dépendance externe restent présentes
Avec un finalizer, Kubernetes pose deletionTimestamp puis attend le nettoyage du contrôleur. Supprimer manuellement une clé incomprise débloque l’objet sans garantir la suppression de la ressource externe qu’elle protégeait.
- Entrée
- Objet, UID, propagation policy, ownerReferences, deletionTimestamp, grace period, finalizers, contrôleur responsable, logs, dépendance externe et délai attendu.
- Sortie
- Suivi de suppression jusqu’à disparition confirmée, alerte de blocage, runbook par finalizer et contrôle séparé de la dépendance avant toute intervention manuelle.
- Décision
- Ne jamais assimiler 202 à une suppression terminée ni retirer un finalizer dont le contrat de nettoyage n’est pas compris.
Connexions complémentaires
Relier les autres outils de votre SI
Ces prestations couvrent les connexions avec les outils qui interviennent en amont ou en aval de vos flux.
Notre intervention
Ce que l’on sécurise avec Kubernetes API
État qualifié
Spec, status, generation, conditions et effet métier ne sont pas confondus.
Autorité bornée
Service account, token, RBAC, fieldManager et exceptions restent attribuables.
Reprise démontrée
Watch expiré, conflit, suppression bloquée et Job rejoué ont un chemin opérable.
Pour Branchassist, passer du SSO historique à Keycloak ne devait pas transférer aveuglément les autorisations. Dawap a séparé la connexion externe des droits internes : échange du code, contrôle de l’utilisateur actif, rôles Symfony, accès par ressource, révocation des jetons et trace des connexions. Une migration IAM ancrée dans l’application métier.
Webhook, polling et rattrapage ne servent pas le même objectif : l’un pousse le signal, l’autre contrôle la reprise. Cette carte montre comment tenir commandes, stocks et tickets sans confondre latence, quota et cohérence métier, tout en gardant un flux lisible pour le support et pour le run. Un vrai repère pour le run.
Audit trail API garde la preuve utile quand le support, la conformité et le run doivent reconstituer une action sans fouiller tout le système. La trace doit montrer qui a fait quoi, quand, sur quel endpoint et avec quel contexte, puis rester exploitable après incident. Il reste utile quand un incident tombe après coup.
Questions fréquentes
Questions fréquentes sur l’intégration Kubernetes API
Questions fréquentes sur Kubernetes API, list-watch, Server-Side Apply, service accounts, RBAC, secrets, finalizers et convergence.
01Pourquoi une réponse Kubernetes API 200, 201 ou 202 ne suffit-elle pas ?
Elle confirme le traitement de la requête par l’API, pas l’effet final. Les contrôleurs doivent encore rapprocher spec et état réel. On suit generation, observedGeneration, status et conditions adaptées au type, puis le résultat métier attendu.
02Comment reprendre un watch Kubernetes interrompu ?
Le client conserve la dernière resourceVersion et traite les événements de façon idempotente. Si cette version n’est plus disponible et que le serveur renvoie 410 Gone, il refait une liste cohérente, reconstruit son cache puis reprend le watch. Les 429 respectent Retry-After et un backoff.
03Quand utiliser Server-Side Apply ?
Quand plusieurs workflows doivent déclarer leurs champs sans écraser silencieusement ceux des autres. Chaque apply fournit un fieldManager. Un conflit se résout en partageant, abandonnant ou transférant explicitement la propriété ; force ne doit pas être un retry automatique.
04Comment limiter les droits du connecteur Kubernetes ?
On dédie un service account, privilégie TokenRequest ou un token projeté à durée bornée, limite Role ou ClusterRole aux verbes, ressources et namespaces nécessaires, puis vérifie les permissions effectives. Les règles RBAC sont additives et il n’existe pas de deny qui annule un grant trop large.
05Un Secret Kubernetes est-il chiffré parce que sa valeur est en base64 ?
Non. Base64 est un encodage. On limite lecture et création de Pods, active le chiffrement au repos du datastore selon l’exploitation du cluster, évite les secrets dans logs ou tickets et préfère une référence vers le gestionnaire de secrets adapté.
06Quel premier lot Kubernetes recommandez-vous ?
Une action à faible rayon d’impact dans un namespace non critique : lecture list-watch, mutation d’un champ autorisé, refus d’un conflit, observation de la convergence et suppression avec finalizer de test. Le lot inclut RBAC minimal, audit, alertes et reprise.
API cloud & infrastructure
Vous voulez connecter Kubernetes sans transformer le cluster en API métier ouverte ?
On peut cadrer un premier workflow, livrer son intégration et rendre chaque identité, permission, mutation, convergence et reprise vérifiable.
Cadrer mon workflow Kubernetes