Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#188 1 comentario 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
55/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
go, kubernetes
Área
api, backend

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
Go
Estrellas
25
Forks
29
Merge medio
5 d 18 h
PR fusionados (30 d)
1

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de kcp-dev/api-syncagent

Todos los issues de kcp-dev/api-syncagent

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.