Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

bug: dangling schema in an APIExport is neither removed nor reported

Ouverte
  • Quelque chose ne va pas ?
#188 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

@2mind y travaille déjà.

Depuis le 28/9/2026.

  • #189 par @2mind — ouverte

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
55/100
Type d'issue
Bug
Clarté
Plutôt claire
Activité
Active
Stack technique
go, kubernetes
Domaine
api, backend

Piste de recherche

Start in internal/controller/apiexport/reconciler.go at mergeResourceSchemas(), then read internal/controller/apiexport/controller.go where readySchemaNames is built. Reproduce the dangling reference with the APIExport and APIResourceSchema commands in the issue, and inspect existing event and condition handling. Done means a missing schema is reported on the owning APIExport with enough detail to identify the entry, without breaking managed-resource reconciliation.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

What happens

If an APIExport contains a schema name (spec.latestResourceSchemas, spec.resources[].schema
in v1alpha2) that does not resolve to an existing APIResourceSchema, nothing in the export
owner's view tells them about it:

  • the Sync Agent leaves the entry in place forever (mergeResourceSchemas() keeps every
    existing entry that belongs to a group/resource no PublishedResource manages — deliberately,
    see below), and it does not validate that the referenced ARS exists;
  • the APIExport's own status does not mention it either — it only carries IdentityValid;
  • the only signal is on the consumer side: every APIBinding to that export goes
    APIExportValid=False with reason: InternalError /
    message: Invalid APIExport. Please contact the APIExport owner to resolve: APIResourceSchema "<name>" not found,
    the API group stops being served, and the export owner is being paged with a message that
    does not name the entry they have to remove.

So the broken entry can only be found by reading the export by hand, and the export owner —
who is usually also the Sync Agent — gets no event and no condition about it.

Why it happens

internal/controller/apiexport/reconciler.go (mergeResourceSchemas()):

	// Now we include all other existing ARS that use unknown resources;
	// this both allows an APIExport to contain "unmanaged" ARS, and also
	// will purposefully leave behind ARS for deleted PublishedResources,
	// allowing cleanup to take place outside of the agent's control.

"Outside of the agent's control" means an admin has to notice — but the agent owns the export,
so that admin has no place to look. Two realistic ways to get there:

  1. A PublishedResource is deleted, and its ARS is removed later (by hand, or by re-creating
    the installation on a new cluster) — the name stays in the export.
  2. An admin-managed export, which the docs explicitly allow
    ("The APIExport above might look like it is defining all resources for the API test.example.com API
    group, but in reality it might contain resource schemas like v1.crontabs.initech.com"),
    references a schema that was never created (typo, ordering, a schema that failed to create).

Related: readySchemaNames in internal/controller/apiexport/controller.go is built from
PublishedResource.status.resourceSchemaName, so while the ARS controller cannot project a
resource (CRD missing on the service cluster, ARS creation failing), the agent leaves the whole
export untouched, broken entries included.

Reproduction

api-syncagent v0.7.0 and main (same code path). kcp v0.32.x, agent pointed at a workspace with
an APIExport/repro-export and an APIExportEndpointSlice of the same name, one
PublishedResource for widgets.repro.pax.dev on the service cluster.

  1. Publish the resource, the agent creates its schema and adds it to the export:

    $ kubectl get apiexport repro-export -o jsonpath='{.spec.resources}'
[{"group":"repro.pax.dev","name":"widgets","schema":"v4ed05578.widgets.repro.pax.dev","storage":{"crd":{}}}]

  2. Delete the PublishedResource (the resource is no longer managed by the agent) and then
    delete the ARS itself — the export now references something that does not exist:

    $ kubectl get apiresourceschemas
No resources found
$ kubectl get apiexport repro-export -o jsonpath='{.spec.resources}'
[{"group":"repro.pax.dev","name":"widgets","schema":"v4ed05578.widgets.repro.pax.dev","storage":{"crd":{}}}]

  3. The agent keeps running and reconciling; it never removes the entry and never reports it —
    no event on the export, no log line, and the export's status stays:

    $ kubectl get apiexport repro-export -o jsonpath='{.status.conditions}'
[{"status":"True","type":"IdentityValid"}]

  4. The consumer only sees the failure:

    $ kubectl get apibinding repro-export -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason} {.message}{"\n"}{end}'
Ready=True
APIExportValid=False InternalError Invalid APIExport. Please contact the APIExport owner to resolve: APIResourceSchema "v4ed05578.widgets.repro.pax.dev" not found
Recovery (verified)

Removing the entry from the export restores it — APIExportValid=True, Ready=True, and the
agent does not put the name back as long as no PublishedResource refers to that group/resource:

$ kubectl patch apiexport repro-export --type=merge -p '{"spec":{"resources":[]}}'
$ kubectl get apibinding repro-export -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'
Ready=True
APIExportValid=True

Note that this does not stick for a resource the agent still manages: the next reconcile of
that PublishedResource adds its own schema name back (and removes the entry an admin had put
there — Warning RemovingResourceSchemas), so there the underlying reason for the missing ARS
has to be fixed instead.

Suggestion
  • Have the apiexport controller (it already lists the ARS/PublishedResources of the export)
    emit a Warning event and/or a status condition like SchemaMissing on the APIExport when
    an entry in spec.latestResourceSchemas/spec.resources[] has no matching ARS. That would
    put the signal where the owner of the export actually looks, instead of only on the consumers.
  • Alternatively/additionally: document the cleanup in a troubleshooting page — I will send a
    docs PR for that in a moment, since the procedure above is not written down anywhere today.
Langage dominant
Go
Étoiles
25
Forks
32
Aucune PR mergée en 30 j

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de kcp-dev/api-syncagent

Toutes les issues de kcp-dev/api-syncagent

Issues similaires

Plus d'issues Go

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.