Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#188 1 comentário 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
55/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
go, kubernetes
Domínio
api, backend

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.
Linguagem predominante
Go
Estrelas
25
Forks
29
Merge médio
5d 18h
PRs com merge (30d)
1

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de kcp-dev/api-syncagent

Todas as issues de kcp-dev/api-syncagent

Issues semelhantes

Mais issues de Go

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.