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]

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]

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

[davidallendj]

Nitpick, but groups.resources was not generated with the above command.

[davidallendj]

I'm going to go ahead and resolve the documentation format issues for now and fix them in a future PR.

[davidallendj]

Getting a device requires the UID in the URL params instead of the name like in the documentation. This command needs to be updated in API versioning example.
https://github.com/OpenCHAMI/fabrica/tree/feature/kubebuilder-style-versioning/examples/08-api-versioning#get-a-device

Likewise, the delete example needs to be update to use the UID as well.
https://github.com/OpenCHAMI/fabrica/tree/feature/kubebuilder-style-versioning/examples/08-api-versioning#delete-a-device

For example, create a device.

curl -X POST http://localhost:8080/devices \
  -H "Content-Type: application/json" \
  -d @data.json

This will give this output. Notice that the uid is device-9e44d386 and the name is device-1.

{"apiVersion":"v1","kind":"Device","metadata":{"name":"device-1","uid":"device-9e44d386","createdAt":"2026-01-16T14:57:15.816284969-07:00","updatedAt":"2026-01-16T14:57:15.816284969-07:00"},"spec":{"ipAddress":"192.168.1.100","location":"DataCenter A","deviceType":"server","tags":{"env":"prod"}},"status":{"ready":false}}

With name in the URL:

curl http://localhost:8080/devices/device-1
# ...
{"error":"Device not found: failed to load Device device-1: resource not found","code":404}

With uid in the URL:

curl http://localhost:8080/devices/device-9e44d386 
# ...
{"apiVersion":"v1","kind":"Device","metadata":{"name":"device-1","uid":"device-9e44d386","createdAt":"2026-01-16T14:57:15.816284969-07:00","updatedAt":"2026-01-16T14:57:15.816284969-07:00"},"spec":{"ipAddress":"192.168.1.100","location":"DataCenter A","deviceType":"server","tags":{"env":"prod"}},"status":{"ready":false}}

[davidallendj]

I'm able to create a device with an arbitrary apiVersion and the response returns v1 still.

curl -X POST http://localhost:8080/devices \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "infra.example.io/v2asdasda",
    "kind": "Device",
    "metadata": {"name": "device-100"},
    "spec": {
      "ipAddress": "192.168.1.100",
      "location": "DataCenter A",
      "deviceType": "server",
      "tags": {"env": "prod"}
    }
  }'

And the output:

{"apiVersion":"v1","kind":"Device","metadata":{"name":"device-100","uid":"device-2e57421b","createdAt":"2026-01-20T13:20:23.289968826-07:00","updatedAt":"2026-01-20T13:20:23.289968826-07:00"},"spec":{"ipAddress":"192.168.1.100","location":"DataCenter A","deviceType":"server","tags":{"env":"prod"}},"status":{"ready":false}}

I have a spec for both v1 and v2 devices and I would expect to be able to create a Device for both.

[davidallendj]

LGTM. Tried, tested, and worked like expected.