feat(api): dynamic API group registration via ApplicationGroupDefinition (MVP) - #3448

What this PR does

Status: MVP / proof-of-concept. This is a working, buildable slice meant to validate the design of dynamically-registered API groups before committing to the API surface. Reviewers should calibrate accordingly: the mechanism is real end to end, but several hard parts are deliberately deferred (listed below).

Today every ApplicationDefinition is served in the single hardwired apps.cozystack.io group: the group name is baked into the scheme registration, the REST storage, the OpenAPI post-processors, the HelmRelease application.group labels, and a static helm-managed APIService. Third-party catalogs and platform extensions therefore cannot bring their own API group — everything lands in the platform's namespace.

This PR extends the ApplicationDefinition mechanism (it does not replace it) with three capabilities:

1. A new cluster-scoped CRD, ApplicationGroupDefinition, registers an additional API group to be served by the cozystack aggregated apiserver.
2. ApplicationDefinition gains an optional spec.application.group selecting the group its kind is served in. Empty keeps today's behavior exactly.
3. The cozystack apiserver serves all registered groups: it lists ApplicationGroupDefinitions at startup, resolves each ApplicationDefinition's group against them, and installs one API group per resolved group (scheme registration, REST storage, discovery, and OpenAPI v2/v3 all follow the per-kind group).

API shape

apiVersion: cozystack.io/v1alpha1
kind: ApplicationGroupDefinition
metadata:
  name: apps.example.com   # must equal spec.group (CEL-enforced)
spec:
  group: apps.example.com
---
apiVersion: cozystack.io/v1alpha1
kind: ApplicationDefinition
metadata:
  name: widget
spec:
  application:
    group: apps.example.com   # optional; empty = apps.cozystack.io
    kind: Widget
    plural: widgets
    singular: widget
    openAPISchema: "..."
  release:
    prefix: widget-
    chartRef: {kind: ExternalArtifact, name: widget, namespace: cozy-public}

The spec is deliberately minimal — one field. Requiring metadata.name == spec.group makes registrations unique (object names are unique) and the group immutable (names are immutable) without extra webhook machinery. Group names must be dotted DNS-1123 subdomains, so single-label built-in Kubernetes groups (apps, batch) are unrepresentable, and the cozystack.io / k8s.io namespaces are reserved via CEL, with the same rules re-checked in Go by every consumer of cluster state (ValidateApplicationGroup). All groups are served at the fixed version v1alpha1, matching the built-in group; a versions field can be added compatibly later.

Group selection and back-compat guarantee

spec.application.group resolves through a single helper (EffectiveGroup / GroupOrDefault): empty means apps.cozystack.io, which needs no registration and is always served. An ApplicationDefinition that does not set the field behaves bit-for-bit as today — same group, same HelmRelease labels, same discovery — and the new code paths collapse to the old ones (pinned by TestBuildResourceConfig_DefaultGroupUnchanged). The resolved group flows everywhere the old constant was baked in: REST storage gvr/gvk, the apps.cozystack.io/application.group HelmRelease label and every label-selector check against it, the HelmRelease-updating reconciler in cozystack-controller (which previously hardcoded the group), and the OpenAPI GVK stamps.

Restart-based pickup (not hot reload), and why

The apiserver picks up group changes by restart, not hot reload, riding the mechanism ApplicationDefinition changes already use today: cozystack-controller watches both CRDs, hashes their specs into the cozystack.io/config-hash pod-template annotation of the cozystack-api Deployment (debounced), and the rollout re-reads everything at startup. Hot-adding an API group to a running GenericAPIServer is not supported upstream (InstallAPIGroup after PrepareRun is unsafe), so true hot reload would mean a serving-mux indirection layer — far beyond an MVP. Nothing in this architecture precludes it later: group resolution is already a pure function of the two CRD lists (buildResourceConfig), and the serving side consumes its output. Consequence: a new group's APIService may exist briefly before the restarted apiserver serves the group; discovery for that group reports unavailable for those few seconds, then converges.

Aggregation registration (APIService)

A new ApplicationGroupDefinitionReconciler in cozystack-controller materializes an APIService v1alpha1.<group> per registration, cloning the backend service reference and the cert-manager CA-injection annotation from the helm-managed v1alpha1.apps.cozystack.io reference APIService, so custom groups always target the same cozystack-api backend regardless of installation layout. The APIService carries an ownerReference to its ApplicationGroupDefinition, so deleting the registration garbage-collects the APIService. Only reconciler-owned fields are enforced on update; the cert-manager-injected caBundle is preserved. APIServices are managed as unstructured objects to avoid growing a kube-aggregator dependency for one object shape.

Dangling references and collisions

• ApplicationGroupDefinition deleted while ApplicationDefinitions still reference it: on the next config rollout those definitions are skipped with an error log and simply stop being served; their HelmReleases (and tenant workloads) are untouched, and serving resumes if the group is re-registered. No panic, no startup failure — one bad reference cannot take down healthy groups.
• Kind collisions across groups: kinds must be unique across all groups because the published OpenAPI schema refs are keyed by kind alone (...apps.v1alpha1.<Kind>); the second group claiming a kind is skipped with an error log.
• Invalid or reserved groups that bypass CRD validation: re-validated in Go on both the serving and the APIService-creating paths, skipped with error logs.

Deferred (named, not stubbed silently)

• RBAC for new groups: cluster admins must grant tenant roles access to the new group themselves (apiGroups: ["apps.example.com"]); the tenant RBAC the platform ships only covers apps.cozystack.io. A follow-up could stamp aggregated ClusterRoles per registered group.
• Hot reload (see above): restart-based by design for now.
• Per-group versions: v1alpha1 fixed; a versions field is a compatible future addition.
• Status/conditions on ApplicationGroupDefinition (e.g. surfacing "APIService created", "N definitions served"): the CRD has no status subresource yet, matching ApplicationDefinition.
• Dashboard/UI awareness of non-default groups.
• Reporting skipped definitions (dangling group, kind collision) somewhere more visible than apiserver logs.

Verification

• go build ./... and go vet ./... clean; make generate re-run to convergence (zero drift — deepcopy, CRD YAML, and openapi are all tool-generated).
• New unit tests: group resolution incl. the default/back-compat path, dangling-reference skip, cross-group kind-collision skip, reserved/malformed group rejection (pkg/cmd/server/groups_test.go); multi-group scheme registration (pkg/apis/apps/v1alpha1/register_test.go); per-group OpenAPI v3 document filtering and v2 GVK stamping (pkg/cmd/server/openapi_groups_test.go); APIService create/update-preserving-caBundle/invalid-group paths and the config-hash extension (internal/controller/applicationgroupdefinition_controller_test.go).
• Full test sweep over every touched package passes; e2e not extended (MVP).

Downstream repositories

• No downstream repository is affected by this change
• cozystack/website - follow-up:
• cozystack/terraform-provider-cozystack - follow-up:
• cozystack/ansible-cozystack - follow-up:
• cozystack/ccp - follow-up:
• cozystack/talm - follow-up:
• cozystack/cozyhr - follow-up:
• cozystack/cozy-proxy - follow-up:
• cozystack/cozystack-telemetry-server - follow-up:
• cozystack/external-apps-example - follow-up:
• cozystack/examples - follow-up:

Boxes are deliberately left empty rather than ticked: this is a draft MVP and filing downstream PRs now would be premature. Walking the trigger map against the diff, if this merges as-is two repositories are reached: cozystack/website (content/en/docs/next/cozystack-api/application-definitions.md documents ApplicationDefinition semantics, which gain the group field and the new companion CRD) and cozystack/external-apps-example (the ApplicationDefinition CRD in packages/system/application-definition-crd/definition/ changed — additively only, an optional field and a new CRD file, so nothing there breaks, but the example is the natural place to demonstrate a third-party group). Follow-ups should be filed when this graduates from proof-of-concept.

Release note

feat(api): ApplicationGroupDefinition CRD (MVP) — register custom API groups served by the cozystack apiserver; ApplicationDefinition gains optional spec.application.group, defaulting to apps.cozystack.io with unchanged behavior