Serve the Kubernetes API: a Day-2 collection cannot exercise a single k8s module

[stephrobert]

stephrobert.scaleway ships twenty Kubernetes modules as of its 0.8.0 cycle, and
none of them can be exercised against feint. Measured today:

GET http://127.0.0.1:4899/instance/v1/zones/fr-par-1/servers  -> 200
GET http://127.0.0.1:4899/k8s/v1/regions/fr-par/clusters      -> 501
{"type":"not_emulated","message":"feint does not serve /k8s/v1/regions/fr-par/clusters; see /_feint/routes for what it does"}

The 501 with not_emulated is exactly the right answer, and it is what let this
be measured in one command rather than guessed. This issue is about closing the
gap, not about the refusal.

What the collection would exercise

The read side is what matters most, because it is what a Day-2 collection is
made of. In rough order of value:

ListClusters · GetCluster                    the fleet of clusters
ListPools · GetPool                          what each cluster runs on
ListNodes · GetNode                          the nodes, and their status
ListVersions · ListClusterAvailableVersions  version drift, computed rather than guessed
ListClusterACLRules                          who can reach the control plane

The last two are the interesting ones. ListClusterAvailableVersions next to
GetCluster.version is what makes "am I behind" a measurement rather than an
impression, and nobody serves that question today: the official Scaleway
collection creates clusters and offers nothing to operate them afterwards.

The write side that would follow: UpgradeCluster, UpgradePool, RebootNode,
ReplaceNode, ResetClusterAdminToken, SetPoolTaints, UpdateCluster,
UpdatePool.

What would make it useful even in a first pass

Clusters and pools with a status that moves, the way Instances do. A cluster that
is ready the instant it is created would hide exactly the class of defect an
emulator is worth having for: an operation that waits on a state it never sees.

ListClusterAvailableVersions returning something other than the cluster's own
version, so a drift rule has something to find.

Why this is filed rather than worked around

The collection declares the gap rather than skipping it: the twenty modules are
listed as having no target, with this measurement as the reason, and the entry
reopens at its 0.9.0. The alternative is a Kapsule cluster on a real billed
account for every example run, which is tracked separately on our side.

[stephrobert]

Cette demande croise une décision déjà prise, et elle n'est pas tranchée par elle

docs/limits.md porte depuis le 19 août 2026 une section explicite : « Managed
Kubernetes is not emulated, and a CRUD-only version is refused (#283) ». Le
501 que tu mesures n'est donc pas un oubli, c'est un refus écrit, et il est servi
là où un client le rencontre.

L'argument de #283, en une ligne : servir l'API sans plan de contrôle revient à
répondre ready pour un serveur d'API qui n'existe pas et à délivrer un
kubeconfig qui ne pointe nulle part. Un 501 qui nomme le produit est honnête ;
un cluster « prêt » sans serveur d'API ne l'est pas.

Pourquoi cette issue n'est pas close pour autant

#283 a mesuré une population, et ce n'est pas la tienne.

	ce que #283 a mesuré	ce que cette issue décrit
client	Terraform, kubernetes/helm/kubectl en aval	une collection Ansible de jour 2
geste	créer un cluster pour lui parler	lire une flotte qui existe déjà
verdict	3 stacks sondées sur 3 continuent au-delà de Terraform ; ~50 % de Kapsule et 2/3 de SKS dans la population sauvage	non mesuré

La phrase qui porte le refus est « a cluster is created to be talked to », et
elle est vraie de la population mesurée. Elle ne dit rien d'un module qui ne crée
rien et demande ListClusters sur des clusters existants.

C'est exactement le piège de population que le CLAUDE.md de ce dépôt décrit :
un verdict sur « cette exécution » doit être éprouvé sur la population la plus
pauvre qui le déclenche. Ici l'inverse s'est produit : un verdict mesuré sur la
population Terraform est invoqué pour une population Ansible que personne n'a
regardée.

Ce qui distingue vraiment les deux, et ce qui ne les distingue pas

Ne les distingue pas : la liste des opérations. ListClusters, GetCluster,
ListPools renvoient des attributs stockés, et le pack sait déjà faire ça pour
douze autres produits.

Les distingue : ce que le client fait de la réponse.

• ListClusters sur une flotte : le client affiche un inventaire. Rien ne ment.
• GetCluster.status = ready : le client peut enchaîner sur un kubeconfig,
  et c'est là que Decide: how far must an emulated SKS or Kapsule cluster actually work #283 mord. Le mensonge n'est pas dans le champ, il est dans ce
  que le champ autorise l'étape suivante à croire.
• ListClusterAvailableVersions face à GetCluster.version : c'est l'argument
  le plus fort de cette issue, et il ne consomme aucun plan de contrôle. « Suis-je
  en retard » est une comparaison de deux chaînes que l'API publie. Personne ne
  sert cette question aujourd'hui, y compris la collection officielle.

Ce qu'il faudrait mesurer pour trancher

#283 a été décidée sur une mesure, pas sur une intuition, et sa révision mérite
la même chose. Deux chiffres suffiraient :

1. Combien des vingt modules k8s de la collection lisent sans jamais créer,
   et lesquels d'entre eux consomment un status ou un kubeconfig ensuite. Un
   module qui s'arrête à l'inventaire ne peut pas être trompé par un cluster sans
   plan de contrôle ; un module qui enchaîne le peut.
2. Ce que la cible emulateur de la collection ferait d'un status. Si elle
   l'affiche, le refus de Decide: how far must an emulated SKS or Kapsule cluster actually work #283 ne s'applique pas. Si elle branche dessus, il
   s'applique entièrement.

Tant que ces deux chiffres n'existent pas, servir la lecture serait prendre le
risque précis que #283 a écarté, et refuser serait appliquer un verdict hors de
sa population. Aucune des deux n'est défendable sur mesure aujourd'hui.

Une remarque sur le périmètre

L'issue liste 9 opérations en lecture et 8 en écriture. Le SDK Scaleway en
publie 41 pour k8s/v1. Les 8 opérations d'écriture nommées
(UpgradeCluster, RebootNode, ReplaceNode, ResetClusterAdminToken…) sont
précisément celles que #283 range dans « reproducing the managed service »,
refusé de façon permanente. Si cette issue avance, elle avance sur la moitié
lecture, et le découpage mérite d'être fait dans l'issue avant d'être chiffré.

[stephrobert]

Première transcription reçue, et elle répond à la moitié de la question

collection-scaleway a produit le premier enregistrement au proxy le
14 septembre 2026 (leur issue #251, greffée sur leur #249). 325 échanges, dont
44 sur /k8s/v1, tous en 200.

Ce que le transcript prouve

Un seul User-Agent, et il finit par terraform. L'enregistrement couvre le
terraform apply en entier, pas les playbooks.

Les opérations k8s qu'il porte :

opération	appels
GET /regions/{r}/pools/{id}	22 (attente de convergence)
GET /regions/{r}/clusters/{id}	4
POST /regions/{r}/clusters	1
POST /regions/{r}/clusters/{id}/pools	1
GET /regions/{r}/clusters/{id}/pools	1
GET /regions/{r}/versions	1
GET /regions/{r}/clusters/{id}/kubeconfig	1

Le corps de GetCluster est complet, 29 champs, et deux sont exactement ceux
que #283 nomme :

status       'pool_required'      (pas `ready` : le statut bouge vraiment)
cluster_url  'https://<uuid>.api.k8s.fr-par.scw.cloud:6443'
version      '1.37.0'             upgrade_available: False

cluster_url est l'adresse d'un serveur d'API. C'est la valeur précise dont
#283 dit qu'un émulateur ne peut pas la servir honnêtement, et elle est là.

Le point qui compte : rien ne joint le plan de contrôle

Le kubeconfig est appelé (seq 115). Cela ressemble à ce que #283 redoute,
et ce n'en est pas : l'appel vient du provider Terraform, qui remplit l'attribut
de la ressource à chaque lecture. Ce qui décide, c'est ce que la stack en fait,
et la réponse est dans examples/stack/outputs.tf :

output "kapsule" {
  value = {
    cluster_id = …
    pool_id    = …
    region     = var.region
  }
}

Trois identifiants, et rien d'autre. Pas de kubeconfig, pas de cluster_url,
pas de status. Et examples/stack/providers.tf ne déclare qu'un seul
provider, scaleway/scaleway : aucun kubernetes, aucun helm, aucun
kubectl.

C'est la différence exacte que #283 mesure. Les 3 stacks sondées sur 3 en
août 2026 enchaînaient sur kubernetes/helm depuis kubeconfig[0]. Celle-ci
sort trois identifiants pour que des modules de lecture les interrogent ensuite.
Elle appartient à la colonne « stop at cluster + pool + outputs », celle que
#283 qualifiait de plancher dominé par des exercices de classe. En voici une qui
ne l'est pas.

Ce que le transcript ne prouve pas, et je ne vais pas faire semblant

Aucun module Ansible n'a appelé l'API dans ce run. L'unique User-Agent est
celui de Terraform, et les opérations que #763 nomme comme décisives sont
absentes :

ListClusters                     absent
ListNodes · GetNode              absent
ListClusterAvailableVersions     absent
ListClusterACLRules              absent

Donc la question « que font les modules de lecture du status » reste ouverte.
Ce qui est tranché, c'est la question sœur : ce que la stack en fait, à savoir
rien.

Ce que ça change pour cette issue

La moitié du refus de #283 ne s'applique pas ici. L'argument « un cluster créé
pour qu'on lui parle » est faux de cette stack, mesuré plutôt qu'argumenté.

Reste l'autre moitié : les dix modules _info. Il faut un enregistrement qui
les couvre, c'est-à-dire un run où les playbooks passent aussi par le proxy. Je
le redemande chez eux plutôt que de conclure sur une population que je n'ai pas
vue.

Et un fait à garder pour quand la décision se prendra : GetCluster porte
cluster_url et status, tous deux servis dans le même corps. Servir la lecture
voudra dire décider quoi répondre dans ces deux champs, et « ce que le cloud
répond » n'est pas une réponse ici, puisque l'un désigne un serveur qui n'existe
pas localement.

[stephrobert]

La transcription complète est arrivée, et elle tranche

Le fichier a doublé depuis mon relevé précédent : 748 échanges au lieu de 325.
La première moitié était le terraform apply ; la seconde porte les playbooks.

542  scaleway-sdk-go … terraform      la stack
195  scaleway-sdk-python/2.11.0       les modules de la collection
 11  python-requests/2.34.2           l'inventaire

Les modules ont appelé les sept opérations que cette issue nomme

22 échanges k8s côté Ansible, et la liste demandée y est en entier :

opération	appels
GET /clusters	1	ListClusters
GET /clusters/{id}	4	GetCluster
GET /clusters/{id}/pools · GET /pools/{id}	1 · 4	ListPools, GetPool
GET /clusters/{id}/nodes · GET /nodes/{id}	1 · 1	ListNodes, GetNode
GET /versions	1	ListVersions
GET /clusters/{id}/available-versions	1	ListClusterAvailableVersions
GET /clusters/{id}/acls	1	ListClusterACLRules

Plus cluster-types, available-types, et cinq actions : PATCH sur cluster et
pool, POST /acls, POST /reset-admin-token, POST /nodes/{id}/reboot.

Statuts : 20 × 200, 1 × 204, 1 × 409.

Le point qui décide : aucun module ne demande le kubeconfig

C'est la question que j'avais posée, et la réponse est nette.

GET /clusters/{id}/kubeconfig est appelé une fois dans toute la
transcription, par Terraform, qui remplit l'attribut de sa ressource à chaque
lecture. Les 195 appels des modules ne le demandent jamais.

Sans kubeconfig, on ne joint pas un plan de contrôle. Ce n'est pas une intention
déclarée, c'est une absence dans une transcription de 748 échanges.

Et la stack le confirme de son côté : examples/stack/outputs.tf ne sort que
cluster_id, pool_id et region, tandis que providers.tf ne déclare qu'un
seul provider, scaleway/scaleway. Aucun kubernetes, aucun helm, aucun
kubectl.

Ce que les modules font du status

Ils le lisent, et le cluster était ready aux quatre lectures, ses pools
aussi. Aucune de ces lectures n'est suivie d'un appel à autre chose que l'API
Scaleway : les 749 échanges visent tous le même hôte.

La comparaison qui fait l'intérêt de cette collection est visible telle quelle :

GetCluster.version              1.37.0
available-versions              (l'appel juste après)
upgrade_available               False

« Suis-je en retard » est ici une comparaison de deux chaînes que l'API publie, et
rien dans ce parcours ne suppose qu'un serveur d'API réponde.

Ce que ça fait à l'argument de #283

servir l'API sans plan de contrôle revient à répondre ready pour un serveur
d'API qui n'existe pas et à délivrer un kubeconfig qui ne pointe nulle part

Les deux moitiés de cette phrase se comportent différemment sur cette population.

Le kubeconfig : personne ne le demande. Un émulateur qui ne servirait pas
cette route ne gênerait aucun de ces 195 appels. La moitié « délivrer un
kubeconfig qui ne pointe nulle part » ne s'applique pas, parce qu'il suffit de ne
pas le servir.

Le status : il est lu, et GetCluster le sert dans le même corps que
cluster_url, l'adresse du serveur d'API. C'est là que la prudence de #283 garde
sa valeur, et ce n'est pas une question de population : c'est une question de
ce qu'on choisit de répondre.

Un cadeau que la transcription fait au passage

Le 409, corps exact :

{"current_state": "updating",
 "message": "resource is in a transient state",
 "resource": "cluster",
 "resource_id": "…",
 "type": "transient_state"}

C'est la forme que le jalon 0.13.0 « Failure is part of the API » traite, et que
vpcgw sert déjà (« 409 the state refuses the transition »). Mesurée, pas devinée.

Ce que je propose, et ce que je ne propose pas

Servable : les dix lectures ci-dessus, plus le 409 sur un état transitoire.
Elles ne supposent aucun plan de contrôle et sont consommées par des modules qui
n'enchaînent sur rien.

À trancher explicitement, pas à laisser passer : cluster_url et
status. Servir status: ready est exact d'un plan de contrôle émulé qui n'a
rien à faire ; servir cluster_url désigne un serveur qui n'existe pas. Ma
proposition est de servir le premier et de refuser le second, ou de le servir
vide, mais c'est une décision à écrire dans docs/limits.md, pas un détail
d'implémentation.

Toujours refusé : kubeconfig, les montées de version, les remplacements de
nœuds. #283 les range dans « reproducing the managed service », et rien dans cette
transcription ne conteste ce classement.