openshift-hyperfleet · tirthct · Jul 1, 2026 · coderabbitai · Jul 1, 2026 · coderabbitai
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -83,7 +83,11 @@ Interface + `sql*Dao` implementation using SessionFactory:
 - On write errors: call `db.MarkForRollback(ctx, err)`
 
 ### Plugin Registration
-Each resource registers via `init()` function:
+Generic entity types (Channel, Version, WifConfig) are config-driven — declared in `config.yaml` under `entities:`,
+registered at startup via `registry.LoadDescriptors()`, routes auto-generated by `plugins/entities/plugin.go`.
+No per-entity Go code needed. See `plugins/CLAUDE.md` for details.
+
+Cluster and NodePool use legacy typed plugins with `init()` registration:
 - Reference: `plugins/clusters/plugin.go`
 - `registry.RegisterService()`, `server.RegisterRoutes()`, `presenters.RegisterPath()`, `presenters.RegisterKind()`
 
@@ -102,7 +106,8 @@ Each resource registers via `init()` function:
 - Read requests (GET) skip transaction creation for performance
 - OpenAPI spec and code generation: see [openapi/README.md](openapi/README.md) — run `make generate` before building; generated files in `pkg/api/openapi/` are **never edited**
 - Status aggregation: Service layer synthesizes `Available`, `Reconciled`, and `LastKnownReconciled` conditions from adapter reports
-- Plugin-based: each resource type registers routes/services in `plugins/*/plugin.go`
+- Generic entities are config-driven (`config.yaml` → `registry.LoadDescriptors` → auto-generated routes)
+- Cluster/NodePool use legacy typed plugins in `plugins/*/plugin.go`
 
 ## Boundaries
 
@@ -122,7 +127,7 @@ Subdirectories contain context-specific guidance that loads when you work in tho
 - `pkg/dao/CLAUDE.md` — DAO interface, session access, and rollback patterns
 - `pkg/db/CLAUDE.md` — SessionFactory and transaction middleware
 - `pkg/errors/CLAUDE.md` — Error constructors, codes, and RFC 9457 details
-- `plugins/CLAUDE.md` — Plugin registration (init-based)
+- `plugins/CLAUDE.md` — Plugin registration (config-driven entities + legacy init-based)
 - `test/CLAUDE.md` — Test conventions, factories, and environment variables
 - `charts/CLAUDE.md` — Helm chart testing and configuration
 - `openapi/README.md` — OpenAPI schema import, code generation, schema validation, and oapi-codegen config
diff --git a/charts/CLAUDE.md b/charts/CLAUDE.md
@@ -14,6 +14,12 @@ Adapter arrays are required — templates fail without them:
 --set 'adapters.nodepool=["validation"]'
 ```
 
+## Entity Registration
+
+Entity descriptors are configured in `config.entities`. Default values include Channel, Version, and WifConfig.
+Override with `--set-json 'config.entities=[...]'` for custom entity sets. An empty list disables all
+generic entity routes.
+
 ## Database Modes
 
 Two database configurations supported:

diff --git a/charts/README.md b/charts/README.md
@@ -44,7 +44,7 @@ helm install hyperfleet-api oci://REGISTRY/hyperfleet-api \
 | ports.api | int | `8000` | API server port |
 | ports.health | int | `8080` | Health check endpoint port |
 | ports.metrics | int | `9090` | Prometheus metrics endpoint port |
-| config | object | `{"adapters":{"required":{"cluster":[],"nodepool":[]}},"database":{"debug":false,"dialect":"postgres","host":"","name":"hyperfleet","pool":{"conn_max_idle_time":"1m","conn_max_lifetime":"5m","conn_retry_attempts":10,"conn_retry_interval":"3s","max_connections":50,"max_idle_connections":10,"request_timeout":"30s"},"port":5432,"ssl":{"mode":"disable","root_cert_file":""}},"existingConfigMap":"","health":{"db_ping_timeout":"2s","host":"0.0.0.0","port":8080,"shutdown_timeout":"20s","tls":{"enabled":false}},"logging":{"format":"json","level":"info","masking":{"enabled":true,"fields":["password","secret","token","api_key","access_token","refresh_token","client_secret"],"headers":["Authorization","X-API-Key","Cookie","X-Auth-Token","X-Forwarded-Authorization","X-HyperFleet-Identity"]},"otel":{"enabled":false},"output":"stdout"},"metrics":{"host":"0.0.0.0","label_metrics_inclusion_duration":"168h","port":9090,"reconciliation_stuck_threshold":"10m","tls":{"enabled":false}},"server":{"host":"0.0.0.0","hostname":"","identity_header":"","jwk":{"cert_file":"","cert_url":""},"jwt":{"audience":"","enabled":false,"identity_claim":"email","issuer_url":""},"port":8000,"timeouts":{"read":"5s","write":"30s"},"tls":{"cert_file":"","enabled":false,"key_file":""}}}` | Application configuration. All settings in this section generate the ConfigMap consumed by the API server. Set `config.existingConfigMap` to use a pre-existing ConfigMap instead. |
+| config | object | `{"adapters":{"required":{"cluster":[],"nodepool":[]}},"database":{"debug":false,"dialect":"postgres","host":"","name":"hyperfleet","pool":{"conn_max_idle_time":"1m","conn_max_lifetime":"5m","conn_retry_attempts":10,"conn_retry_interval":"3s","max_connections":50,"max_idle_connections":10,"request_timeout":"30s"},"port":5432,"ssl":{"mode":"disable","root_cert_file":""}},"entities":[{"kind":"Channel","plural":"channels","search_disallowed_fields":["spec"],"spec_schema_name":"ChannelSpec"},{"kind":"Version","on_parent_delete":"restrict","parent_kind":"Channel","plural":"versions","search_disallowed_fields":["spec"],"spec_schema_name":"VersionSpec"},{"kind":"WifConfig","plural":"wifconfigs","search_disallowed_fields":["spec"],"spec_schema_name":"WifConfigSpec"}],"existingConfigMap":"","health":{"db_ping_timeout":"2s","host":"0.0.0.0","port":8080,"shutdown_timeout":"20s","tls":{"enabled":false}},"logging":{"format":"json","level":"info","masking":{"enabled":true,"fields":["password","secret","token","api_key","access_token","refresh_token","client_secret"],"headers":["Authorization","X-API-Key","Cookie","X-Auth-Token","X-Forwarded-Authorization","X-HyperFleet-Identity"]},"otel":{"enabled":false},"output":"stdout"},"metrics":{"host":"0.0.0.0","label_metrics_inclusion_duration":"168h","port":9090,"reconciliation_stuck_threshold":"10m","tls":{"enabled":false}},"server":{"host":"0.0.0.0","hostname":"","identity_header":"","jwk":{"cert_file":"","cert_url":""},"jwt":{"audience":"","enabled":false,"identity_claim":"email","issuer_url":""},"port":8000,"timeouts":{"read":"5s","write":"30s"},"tls":{"cert_file":"","enabled":false,"key_file":""}}}` | Application configuration. All settings in this section generate the ConfigMap consumed by the API server. Set `config.existingConfigMap` to use a pre-existing ConfigMap instead. |
 | config.existingConfigMap | string | `""` | Use an existing ConfigMap instead of generating one. When set, all other `config.*` values are ignored. |
 | config.server | object | `{"host":"0.0.0.0","hostname":"","identity_header":"","jwk":{"cert_file":"","cert_url":""},"jwt":{"audience":"","enabled":false,"identity_claim":"email","issuer_url":""},"port":8000,"timeouts":{"read":"5s","write":"30s"},"tls":{"cert_file":"","enabled":false,"key_file":""}}` | HTTP server settings |
 | config.server.hostname | string | `""` | Public hostname advertised by the API (leave empty for auto-detect) |
@@ -111,6 +111,7 @@ helm install hyperfleet-api oci://REGISTRY/hyperfleet-api \
 | config.adapters.required | object | `{"cluster":[],"nodepool":[]}` | Adapters required for cluster resources |
 | config.adapters.required.cluster | list | `[]` | Required cluster adapters (e.g. `["validation", "dns", "pullsecret", "hypershift"]`) |
 | config.adapters.required.nodepool | list | `[]` | Required nodepool adapters (e.g. `["validation", "hypershift"]`) |
+| config.entities | list | `[{"kind":"Channel","plural":"channels","search_disallowed_fields":["spec"],"spec_schema_name":"ChannelSpec"},{"kind":"Version","on_parent_delete":"restrict","parent_kind":"Channel","plural":"versions","search_disallowed_fields":["spec"],"spec_schema_name":"VersionSpec"},{"kind":"WifConfig","plural":"wifconfigs","search_disallowed_fields":["spec"],"spec_schema_name":"WifConfigSpec"}]` | Entity descriptors registered at startup. Each entry auto-generates REST endpoints, spec validation, and delete policies. Cluster and NodePool use legacy typed handlers and are NOT listed here. |
 | serviceAccount | object | `{"annotations":{},"create":true,"name":""}` | ServiceAccount configuration |
 | serviceAccount.create | bool | `true` | Create a ServiceAccount for the API server |
 | serviceAccount.annotations | object | `{}` | Annotations added to the ServiceAccount (e.g. for Workload Identity) |

diff --git a/charts/templates/configmap.yaml b/charts/templates/configmap.yaml
@@ -136,4 +136,48 @@ data:
 {{- else }}
           []
 {{- end }}
+
+    # NOTE: When EntityDescriptor gains many more fields, consider replacing
+    # the explicit range below with: {{ .Values.config.entities | toYaml | indent 6 }}
+{{- if .Values.config.entities }}
+    entities:
+{{- range .Values.config.entities }}
+      - kind: {{ .kind }}
+        plural: {{ .plural }}
+{{- if .parent_kind }}
+        parent_kind: {{ .parent_kind }}
+{{- end }}
+{{- if .on_parent_delete }}
+        on_parent_delete: {{ .on_parent_delete }}
+{{- end }}
+        spec_schema_name: {{ .spec_schema_name }}
+{{- if .search_disallowed_fields }}
+        search_disallowed_fields:
+{{- range .search_disallowed_fields }}
+          - {{ . }}
+{{- end }}
+{{- end }}
+{{- if .required_adapters }}
+        required_adapters:
+{{- range .required_adapters }}
+          - {{ . }}
+{{- end }}
+{{- end }}
+{{- if .references }}
+        references:
+{{- range .references }}
+          - ref_type: {{ .ref_type }}
+            target_kind: {{ .target_kind }}
+{{- if .min }}
+            min: {{ .min }}
+{{- end }}
+{{- if .max }}
+            max: {{ .max }}
+{{- end }}
+{{- end }}
+{{- end }}
+{{- end }}
+{{- else }}
+    entities: []
+{{- end }}
 {{- end }}
diff --git a/charts/values.schema.json b/charts/values.schema.json
@@ -414,6 +414,73 @@
               }
             }
           }
+        },
+        "entities": {
+          "type": "array",
+          "description": "Entity descriptors registered at startup. Each entry auto-generates REST endpoints, spec validation, and delete policies.",
+          "items": {
+            "type": "object",
+            "required": ["kind", "plural"],
+            "properties": {
+              "kind": {
+                "type": "string",
+                "description": "Discriminator value stored in Resource.Kind (e.g. Channel, Version)"
+              },
+              "plural": {
+                "type": "string",
+                "description": "URL path segment for this entity (e.g. channels, versions)"
+              },
+              "parent_kind": {
+                "type": "string",
+                "description": "Kind of the parent entity (empty for top-level entities)"
+              },
+              "on_parent_delete": {
+                "type": "string",
+                "enum": ["restrict", "cascade"],
+                "description": "Child behavior when parent is deleted (restrict or cascade)"
+              },
+              "spec_schema_name": {
+                "type": "string",
+                "description": "OpenAPI component name for spec field validation (e.g. ChannelSpec)"
+              },
+              "search_disallowed_fields": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Fields blocked from TSL search queries"
+              },
+              "required_adapters": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Adapters that must finalize before hard-delete"
+              },
+              "references": {
+                "type": "array",
+                "description": "Non-ownership associations to other entity types (HYPERFLEET-1156)",
+                "items": {
+                  "type": "object",
+                  "required": ["ref_type", "target_kind"],
+                  "properties": {
+                    "ref_type": {
+                      "type": "string",
+                      "description": "Key in the references map (e.g. wif_config)"
+                    },
+                    "target_kind": {
+                      "type": "string",
+                      "description": "Kind of the referenced entity (e.g. WifConfig)"
+                    },
+                    "min": {
+                      "type": "integer",
+                      "description": "Minimum references of this type (0 = optional)"
+                    },
+                    "max": {
+                      "type": "integer",
+                      "description": "Maximum references of this type (0 = unlimited)"
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },

diff --git a/charts/values.yaml b/charts/values.yaml
@@ -208,6 +208,25 @@ config:
       # -- Required nodepool adapters (e.g. `["validation", "hypershift"]`)
       nodepool: []
 
+  # -- Entity descriptors registered at startup. Each entry auto-generates
+  # REST endpoints, spec validation, and delete policies.
+  # Cluster and NodePool use legacy typed handlers and are NOT listed here.
+  entities:
+    - kind: Channel
+      plural: channels
+      spec_schema_name: ChannelSpec
+      search_disallowed_fields: [spec]
+    - kind: Version
+      plural: versions
+      parent_kind: Channel
+      on_parent_delete: restrict
+      spec_schema_name: VersionSpec
+      search_disallowed_fields: [spec]
+    - kind: WifConfig
+      plural: wifconfigs
+      spec_schema_name: WifConfigSpec
+      search_disallowed_fields: [spec]
+
 # -- ServiceAccount configuration
 serviceAccount:
   # -- Create a ServiceAccount for the API server

diff --git a/cmd/hyperfleet-api/main.go b/cmd/hyperfleet-api/main.go
@@ -17,13 +17,11 @@ import (
 	// Import plugins to trigger their init() functions
 	// _ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/events" // REMOVED: Events plugin no longer exists
 	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/adapterStatus"
-	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/channels"
 	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/clusters"
+	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/entities"
 	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/generic"
 	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/nodePools"
 	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/resources"
-	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/versions"
-	_ "github.com/openshift-hyperfleet/hyperfleet-api/plugins/wifconfigs"
 )
 
 // nolint

diff --git a/cmd/hyperfleet-api/servecmd/cmd.go b/cmd/hyperfleet-api/servecmd/cmd.go
@@ -19,6 +19,7 @@ import (
 	"github.com/openshift-hyperfleet/hyperfleet-api/pkg/health"
 	"github.com/openshift-hyperfleet/hyperfleet-api/pkg/logger"
 	"github.com/openshift-hyperfleet/hyperfleet-api/pkg/metrics"
+	"github.com/openshift-hyperfleet/hyperfleet-api/pkg/registry"
 	"github.com/openshift-hyperfleet/hyperfleet-api/pkg/telemetry"
 )
 
@@ -55,6 +56,13 @@ func runServe(cmd *cobra.Command, args []string) {
 	// and ensure SessionFactory, clients, services, handlers all use the correct config
 	environments.Environment().Config = cfg
 
+	// Load entity descriptors from config before services and routes are built.
+	// Descriptors must be registered before Initialize() because services call
+	// registry.MustGet() at construction time.
+	registry.LoadDescriptors(cfg.Entities)
+	registry.Validate()
+	registry.ValidateSchemas(cfg.Server.OpenAPISchemaPath)
+
 	// Initialize environment (applies overrides, creates SessionFactory, loads clients, services, handlers)
 	err = environments.Environment().Initialize()
 	if err != nil {

diff --git a/configs/config.yaml.example b/configs/config.yaml.example
@@ -115,6 +115,28 @@ adapters:
       - validation
       - hypershift
 
+# Entity Registration
+# Generic resource types registered at startup. Each entry auto-generates
+# REST endpoints, spec validation, and delete policies.
+# Cluster and NodePool use legacy typed handlers and are NOT listed here.
+entities:
+  - kind: Channel
+    plural: channels
+    spec_schema_name: ChannelSpec
+    search_disallowed_fields: [spec]
+
+  - kind: Version
+    plural: versions
+    parent_kind: Channel
+    on_parent_delete: restrict
+    spec_schema_name: VersionSpec
+    search_disallowed_fields: [spec]
+
+  - kind: WifConfig
+    plural: wifconfigs
+    spec_schema_name: WifConfigSpec
+    search_disallowed_fields: [spec]
+
 # ----------------------------------------------------------------------------
 # Configuration Priority (highest to lowest):
 # 1. Command-line flags (e.g., --server-host=0.0.0.0 --server-port=8000)

diff --git a/pkg/config/config.go b/pkg/config/config.go
@@ -1,14 +1,17 @@
 package config
 
+import "github.com/openshift-hyperfleet/hyperfleet-api/pkg/registry"
+
 // ApplicationConfig holds all application configuration
 // Follows HyperFleet Configuration Standard with validation and structured marshaling
 type ApplicationConfig struct {
-	Server   *ServerConfig              `mapstructure:"server" json:"server" validate:"required"`
-	Metrics  *MetricsConfig             `mapstructure:"metrics" json:"metrics" validate:"required"`
-	Health   *HealthConfig              `mapstructure:"health" json:"health" validate:"required"`
-	Database *DatabaseConfig            `mapstructure:"database" json:"database" validate:"required"`
-	Logging  *LoggingConfig             `mapstructure:"logging" json:"logging" validate:"required"`
-	Adapters *AdapterRequirementsConfig `mapstructure:"adapters" json:"adapters" validate:"required"`
+	Server   *ServerConfig               `mapstructure:"server" json:"server" validate:"required"`
+	Metrics  *MetricsConfig              `mapstructure:"metrics" json:"metrics" validate:"required"`
+	Health   *HealthConfig               `mapstructure:"health" json:"health" validate:"required"`
+	Database *DatabaseConfig             `mapstructure:"database" json:"database" validate:"required"`
+	Logging  *LoggingConfig              `mapstructure:"logging" json:"logging" validate:"required"`
+	Adapters *AdapterRequirementsConfig  `mapstructure:"adapters" json:"adapters" validate:"required"`
+	Entities []registry.EntityDescriptor `mapstructure:"entities" json:"entities"`
 }
 
 // NewApplicationConfig returns default ApplicationConfig with all sub-configs initialized

diff --git a/pkg/config/dump.go b/pkg/config/dump.go
@@ -2,6 +2,8 @@ package config
 
 import (
 	"fmt"
+
+	"github.com/openshift-hyperfleet/hyperfleet-api/pkg/registry"
 )
 
 // DumpConfig returns a human-readable string representation of configuration
@@ -35,6 +37,7 @@ func DumpConfig(config *ApplicationConfig) string {
   Adapters:
     ClusterAdapters: %v
     NodePoolAdapters: %v
+  Entities: %d registered (kinds: %v)
 `,
 		config.Server.BindAddress(),
 		config.Server.TLS.Enabled,
@@ -53,9 +56,20 @@ func DumpConfig(config *ApplicationConfig) string {
 		config.Health.BindAddress(),
 		safeAdapterList(config.Adapters, true),
 		safeAdapterList(config.Adapters, false),
+		len(config.Entities),
+		entityKindNames(config.Entities),
 	)
 }
 
+// entityKindNames extracts Kind strings from entity descriptors for logging.
+func entityKindNames(entities []registry.EntityDescriptor) []string {
+	kinds := make([]string, len(entities))
+	for i, e := range entities {
+		kinds[i] = e.Kind
+	}
+	return kinds
+}
+
 // safeAdapterList safely extracts adapter list, handling nil config
 func safeAdapterList(adapters *AdapterRequirementsConfig, cluster bool) []string {
 	if adapters == nil {

diff --git a/pkg/config/loader.go b/pkg/config/loader.go
@@ -365,6 +365,9 @@ func (l *ConfigLoader) bindAllEnvVars() {
 	// Adapters config
 	l.bindEnv("adapters.required.cluster")
 	l.bindEnv("adapters.required.nodepool")
+
+	// Entities: config-file-only (complex list-of-struct type).
+	// No env var or CLI flag bindings — loaded exclusively via YAML config.
 }
 
 // bindFlags binds command-line flags to their corresponding Viper config keys