Feature/kubebuilder style versioning

[alexlovelltroy]

This pull request introduces a comprehensive hub/spoke API versioning system, major changes to the resource code generation flow, and updates to project configuration and documentation. The main focus is on enabling Kubebuilder-style API versioning, supporting automatic conversion between versions, and enforcing a new, explicit resource envelope structure. It also deprecates legacy, non-versioned resource management and updates legal metadata files for SPDX compliance.

API Versioning and Resource Generation:

• Implements hub/spoke (Kubebuilder-style) API versioning:

  • Adds a version registry, conversion middleware, and apis.yaml configuration for managing groups, versions, and imports.
  • Enforces a single hub (storage) version per API group with automatic conversion between hub and spoke (external) versions.
  • Updates code generation to create explicit resource envelopes with apiVersion, kind, metadata, spec, and status fields, replacing the previous embedded resource.Resource approach. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

• Updates the CLI:

  • Adds subcommands for adding resources and API versions, with flags for specifying versions and force-adding to non-alpha versions.
  • Enforces versioned resource addition and deprecates legacy (non-versioned) resource mode. [1] [2] [3] [4]

Configuration and Validation:

• Updates .fabrica.yaml schema and validation:
  • Requires explicit configuration of API group, storage version, and version list for versioning.
  • Adds validation to ensure correct versioning setup and that the storage version is part of the versions list. [1] [2] [3] [4]

Documentation:

• Documents the new versioning system:
  • Adds a comprehensive Hub/Spoke Versioning Guide.
  • Updates the README with new features and migration instructions. [1] Fd5f02adL61R61, [2]

Legal and Metadata Updates:

• Migrates copyright/license metadata:
  • Replaces .reuse/dep5 with a new SPDX-compliant REUSE.toml file for better license tracking. [1] [2]

Breaking Changes:

• BREAKING: Generated resource types no longer embed resource.Resource; any custom code referencing the embedded field must be updated to use explicit fields.

---

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] Fd5f02adL61R61, [14] [15] [16]

Checklist

• My code follows the style guidelines of this project
• I have added/updated comments where needed
• I have added tests that prove my fix is effective or my feature works
• I have run make test (or equivalent) locally and all tests pass
• DCO Sign-off: All commits are signed off (git commit -s) with my real name and email
• REUSE Compliance:

Description

Please include a summary of the change and which issue is fixed.
Also include relevant motivation and context.

Fixes #(issue)

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

---

For more info, see Contributing Guidelines.

[davidallendj]

It looks like some of the main README documentation needs to be updated like the quickstart before merging.
https://github.com/OpenCHAMI/fabrica/blob/feature/kubebuilder-style-versioning/README.md#-quick-start-5-minutes

[davidallendj]

This should be apis/example.fabrica.dev/v1/device_types.go instead following the updated guide. I believe the example.fabrica.dev and the v1 portions are generated based on the contents of the apis.yaml file.

[davidallendj]

A couple of notes testing this PR at this commit:

I went through the basic CRUD example and the basics seemed to work like expected and I'm able to add multiple versions of the API with fabrica add version v2 --force. However, when I try to add a v2 Device, it returns with apiVersion: v1 in the output.

Here's the create command by default with no version specified (works as expected):

./client device create --spec '{
  "description": "Core network switch",
  "ipAddress": "192.168.1.10",
  "location": "DataCenter A",
  "rack": "R42"
}'
{
  "apiVersion": "v1",
  "kind": "Device",
  "metadata": {
    "name": "",
    "uid": "device-f260b82a",
    "createdAt": "2026-01-06T14:03:30.424022558-07:00",
    "updatedAt": "2026-01-06T14:03:30.424022558-07:00"
  },
  "spec": {
    "description": "Core network switch",
    "ipAddress": "192.168.1.10",
    "location": "DataCenter A",
    "rack": "R42"
  },
  "status": {
    "ready": false
  }
}

And the corresponding v1 device specification defined in apis/example.fabrica.dev/v1/device_types.go:

type DeviceSpec struct {
  Description string `json:"description,omitempty" validate:"max=200"`
  IPAddress   string `json:"ipAddress,omitempty" validate:"omitempty,ip"`
  Location    string `json:"location,omitempty"`
  Rack        string `json:"rack,omitempty"`
}

Here's the command again, but specifying the --version flag with a value of v2. I would expect this to either give me an error or only return the fields defined by the v2 spec in apis/example.fabrica.dev/v2/device_types.go.

./client device create --spec '{
  "description": "Core network switch",
  "ipAddress": "192.168.1.10",
  "location": "DataCenter A",
  "rack": "R42"
}' --version v2
{
  "apiVersion": "v1",
  "kind": "Device",
  "metadata": {
    "name": "",
    "uid": "device-1ab74b62",
    "createdAt": "2026-01-06T14:03:44.894932171-07:00",
    "updatedAt": "2026-01-06T14:03:44.894932171-07:00"
  },
  "spec": {
    "description": "Core network switch",
    "ipAddress": "192.168.1.10",
    "location": "DataCenter A",
    "rack": "R42"
  },
  "status": {
    "ready": false
  }
}

Here's the v2 device specification in the apis/example.fabrica.dev/v2/device_types.go file:

type DeviceSpec struct {
  Description string `json:"description,omitempty" validate:"max=200"`
}

I made sure to run fabrica generate, go mod tidy, and then restart the server.

I'm guessing that some of this field validation should probably be handled in Validate() in the generated apis/example.fabrica.dev/v{1,2}/device_types.go files by default. I also noticed that it's possible to specify any arbitrary version using this command like --version whatever and it creates a new device even though the version does not exist. I suspect that there needs to be some --version flag validation behavior to check if the version of the API actually exists.

I built the binary using make build on the feature/kubebuilder-style-versioning branch so I was using a locally built binary. I noticed that the file paths for the generated files are outdated in the example README that I was following.

I also had to add replace github.com/openchami/fabrica => .. to the generated go.mod for the development version to work on this branch. I'm not sure if this would be necessary after this is merged to main, but I suspect it would be any time we're cloning and testing a local version fabrica.

Edit 1:

I noticed running fabrica add resource Device --version v1 produces the following output after fabrica init Device even though v1 is in the apis.yaml and the directory already exists at apis/example.fabrica.dev/v1.

fabrica add resource Device --version v1       
Error: adding resource to non-alpha version v1 requires --force flag

Stable versions should not have new resources added after release.
Use --force if you understand the implications, or consider adding to an alpha version first.
Usage:
  fabrica add resource [name] [flags]

Flags:
      --force             Force adding to non-alpha version
  -h, --help              help for resource
      --package string    Package name (defaults to lowercase resource name)
      --version string    API version (required for versioned projects, e.g., v1alpha1)
      --with-status       Include Status struct (default true)
      --with-validation   Include validation tags (default true)
      --with-versioning   Enable per-resource spec versioning (snapshots). Status is never versioned.

adding resource to non-alpha version v1 requires --force flag

Stable versions should not have new resources added after release.
Use --force if you understand the implications, or consider adding to an alpha version first.

The apis.yaml after fabrica init Device:

cat apis.yaml
groups:
    - name: example.fabrica.dev
      storageVersion: v1
      versions:
        - v1

Removing the --version v1 creates the resource like expected.

[davidallendj]

These files look slightly different. Would it be better to only reference the generated file at apis/example.fabrica.dev/v1/fru_types.go?

Diff output of files

diff apis/example.fabrica.dev/v1/fru_types.go ../pkg/resources/fru/fru.go
0a1,4
> //go:build ignore
> 
> // The line above is necessary to prevent this file from being included in the main build of fabrica.  You may need to remove it to succeed with the example.
> //
5c9,15
< package v1
---
> // Package fru provides resource definitions for Field Replaceable Units (FRUs).
> //
> // This package defines the FRU resource type for managing hardware components
> // that can be replaced in a system, such as CPUs, memory modules, storage devices,
> // power supplies, and network cards. FRUs track hardware inventory, location,
> // status, and lifecycle information for data center equipment management.
> package fru
8,9c18
<       "context"
<       "github.com/openchami/fabrica/pkg/fabrica"
---
>       "github.com/openchami/fabrica/pkg/resource"
12,18c21,25
< // FRU represents a fru resource
< type FRU struct {
<       APIVersion string           `json:"apiVersion"`
<       Kind       string           `json:"kind"`
<       Metadata   fabrica.Metadata `json:"metadata"`
<       Spec       FRUSpec   `json:"spec" validate:"required"`
<       Status     FRUStatus `json:"status,omitempty"`
---
> // FRU represents a Field Replaceable Unit
> type FRU struct { //nolint:revive
>       resource.Resource `json:",inline"`
>       Spec              FRUSpec   `json:"spec"`
>       Status            FRUStatus `json:"status"`
22c29
< type FRUSpec struct {
---
> type FRUSpec struct { //nolint:revive
24,35c31,45
<     FRUType      string `json:"fruType"`      // e.g., "CPU", "Memory", "Storage"
<     SerialNumber string `json:"serialNumber"`
<     PartNumber   string `json:"partNumber"`
<     Manufacturer string `json:"manufacturer"`
<     Model        string `json:"model"`
< 
<     // Location information
<     Location FRULocation `json:"location"`
< 
<     // Relationships
<     ParentUID    string   `json:"parentUID,omitempty"`
<     ChildrenUIDs []string `json:"childrenUIDs,omitempty"`
---
>       FRUType      string `json:"fruType"` // e.g., "CPU", "Memory", "Storage"
>       SerialNumber string `json:"serialNumber"`
>       PartNumber   string `json:"partNumber"`
>       Manufacturer string `json:"manufacturer"`
>       Model        string `json:"model"`
> 
>       // Location information
>       Location FRULocation `json:"location"`
> 
>       // Relationships
>       ParentUID    string   `json:"parentUID,omitempty"`    // Parent FRU
>       ChildrenUIDs []string `json:"childrenUIDs,omitempty"` // Child FRUs
> 
>       // Redfish path for management
>       RedfishPath string `json:"redfishPath,omitempty"`
37,38c47,48
<     // Redfish path for management
<     RedfishPath string `json:"redfishPath,omitempty"`
---
>       // Custom properties
>       Properties map[string]string `json:"properties,omitempty"`
56,78c66,83
< // FRUStatus defines the observed state of FRU
< type FRUStatus struct {
<     Health      string               `json:"health"`      // "OK", "Warning", "Critical", "Unknown"
<     State       string               `json:"state"`       // "Present", "Absent", "Disabled", "Unknown"
<     Functional  string               `json:"functional"`  // "Enabled", "Disabled", "Unknown"
<     LastSeen    string               `json:"lastSeen,omitempty"`
<     LastScanned string               `json:"lastScanned,omitempty"`
<     Errors      []string             `json:"errors,omitempty"`
<     Temperature float64              `json:"temperature,omitempty"`
<     Power       float64              `json:"power,omitempty"`
<     Metrics     map[string]float64   `json:"metrics,omitempty"`
<     Conditions  []resource.Condition `json:"conditions,omitempty"`
< }
< 
< // Validate implements custom validation logic for FRU
< func (r *FRU) Validate(ctx context.Context) error {
<       // Add custom validation logic here
<       // Example:
<       // if r.Spec.Description == "forbidden" {
<       //     return errors.New("description 'forbidden' is not allowed")
<       // }
< 
<       return nil
---
> type FRUStatus struct { //nolint:revive
>       // Health and operational status
>       Health     string `json:"health"`     // "OK", "Warning", "Critical", "Unknown"
>       State      string `json:"state"`      // "Present", "Absent", "Disabled", "Unknown"
>       Functional string `json:"functional"` // "Enabled", "Disabled", "Unknown"
> 
>       // Timestamps
>       LastSeen    string `json:"lastSeen,omitempty"`
>       LastScanned string `json:"lastScanned,omitempty"`
> 
>       // Error conditions
>       Errors []string `json:"errors,omitempty"`
> 
>       // Additional status information
>       Temperature float64              `json:"temperature,omitempty"`
>       Power       float64              `json:"power,omitempty"`
>       Metrics     map[string]float64   `json:"metrics,omitempty"`
>       Conditions  []resource.Condition `json:"conditions,omitempty"`
79a85
> 
81c87
< func (r *FRU) GetKind() string {
---
> func (f *FRU) GetKind() string {
86,87c92,93
< func (r *FRU) GetName() string {
<       return r.Metadata.Name
---
> func (f *FRU) GetName() string {
>       return f.Metadata.Name
91,92c97,98
< func (r *FRU) GetUID() string {
<       return r.Metadata.UID
---
> func (f *FRU) GetUID() string {
>       return f.Metadata.UID
95,96c101,104
< // IsHub marks this as the hub/storage version
< func (r *FRU) IsHub() {}
---
> func init() {
>       // Register resource type prefix for storage
>       resource.RegisterResourcePrefix("FRU", "fru")
> }

[davidallendj]

When I try to run fabrica generate after this step, I run into an error:

Error from undefined resource

fabrica generate 
🔧 Generating code...
📦 Found 1 resource(s): FRU

📝 Registration file not found, creating it...
🔍 Discovering resources...
📦 Found 1 resource(s): FRU

✅ Generated pkg/resources/register_generated.go

Next steps:
  fabrica generate                # Generate handlers and storage
  go mod tidy                     # Update dependencies
  go run ./cmd/server/       # Start the server

# github.com/example/fru-service/apis/example.fabrica.dev/v1
apis/example.fabrica.dev/v1/fru_types.go:67:19: undefined: resource
Error: failed to generate server code: code generation failed: exit status 1
Usage:
  fabrica generate [flags]

Flags:
      --client     Generate client code
      --debug      Enable debug output showing detailed generation steps
      --force      Force regeneration even with version warnings
      --handlers   Generate HTTP handlers
  -h, --help       help for generate
      --openapi    Generate OpenAPI spec
      --storage    Generate storage adapters

failed to generate server code: code generation failed: exit status 1

I noticed in both the example README and the generated code that there's a []resource.Condition field in FRUStatus but I could not find where this was defined. I would have expected it to possibly be in pkg/resources/register_generated.go or another file in that directory.

[davidallendj]

I think this line is a typo and should be deleted.

[davidallendj]

I think the first two back ticks are supposed to be asterisks here.

[davidallendj]

I think there should be closing back ticks for the YAML file here.

[davidallendj]

From a usability standpoint, I find it a bit annoying and tedious having to list and then delete all of my devices individually with ./client device delete <device-id>. Could there be a way to delete all of them at once (maybe a clear command?) or at least allow multiple UIDs with the delete subcommand?

The current way looks something like this to delete multiple devices.

./client device list
# ...show list of devices...
./client device delete device-0fc0a34f               
Device device-0fc0a34f deleted successfully
# ...scroll back up or run './client device list' again
./client device delete device-71ea3e92               
Device device-71ea3e92 deleted successfully
# ...repeat...
./client device delete device-a305f539               
Device device-a305f539 deleted successfully
# ...repeat...
./client device delete device-a9fc4c25               
Device device-a9fc4c25 deleted successfully
# ...repeat...
./client device delete device-fa6b7ef7               
Device device-fa6b7ef7 deleted successfully