Enrich ScheduledMachine status with providerID and full nodeRef

Signed-off-by: Erick Bourgeois <erick@jeb.ca>

Author: ebourgeois

.claude/CHANGELOG.md

@@ -9,6 +9,28 @@ The format is based on the regulated environment requirements:
 
 ---
 
+## [2026-04-16 17:00] - Phase 1: Enrich ScheduledMachine status with providerID and full nodeRef
+
+**Author:** Erick Bourgeois
+
+### Changed
+- `src/crd.rs`: Added `provider_id: Option<String>` (serialized as `providerID`) to `ScheduledMachineStatus`. Replaced the thin `LocalObjectReference { name }` node reference with a new `NodeRef { apiVersion, kind, name, uid }` struct mirroring CAPI's `Machine.status.nodeRef`. Removed the now-unused `LocalObjectReference` type.
+- `src/crd_tests.rs`: Added 6 TDD cases covering providerID round-trip, full `nodeRef` deserialization, optional `uid`, serialization omission, old-shape rejection, and `NodeRef` round-trip.
+- `src/bin/crddoc.rs`: Documented new `providerID` and `nodeRef` status fields.
+- `deploy/crds/scheduledmachine.yaml`: Regenerated from the updated Rust types.
+- `docs/reference/api.md`: Regenerated to reflect new status schema.
+
+### Why
+Phase 1 of the event-driven watches + status enrichment roadmap. Surfacing `providerID` and a full Node reference (with UID) on `ScheduledMachine.status` lets operators correlate a scheduled machine to a specific VM and Node from `kubectl get sm -o jsonpath=...`, without manual lookups across CAPI Machines and the Node API. This is the schema foundation that Phase 2 (reconciler populates the fields) and Phases 3–4 (event-driven watches on CAPI Machine and Node) build upon.
+
+### Impact
+- [x] Breaking change — `status.nodeRef` shape changed from `{ name }` to `{ apiVersion, kind, name, uid }`. Existing CRs with the old shape must clear `status.nodeRef` before rollout, or the controller will report deserialization errors on that field.
+- [x] Requires cluster rollout — CRD must be re-applied alongside the new controller image.
+- [ ] Config change only
+- [ ] Documentation only
+
+---
+
 ## [2026-04-17] - Bump base image to cc-debian13 and fix GLIBC_2.39 crash (issue #17)
 
 **Author:** Daniel Guns

deploy/crds/scheduledmachine.yaml

@@ -1,6 +1,3 @@
-   Compiling five_spot v0.1.0 (/Users/erick/dev/5-spot)
-    Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.57s
-     Running `target/debug/crdgen`
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
@@ -286,13 +283,27 @@ spec:
                 nullable: true
                 type: string
               nodeRef:
-                description: Reference to the Kubernetes Node (once provisioned)
+                description: |-
+                  Reference to the Kubernetes Node (once provisioned), mirroring the
+                  shape of CAPI's `Machine.status.nodeRef`.
                 nullable: true
                 properties:
+                  apiVersion:
+                    description: API version of the Node resource (typically `"v1"`)
+                    type: string
+                  kind:
+                    description: Kind of the referenced object (typically `"Node"`)
+                    type: string
                   name:
-                    description: Name of the referenced object
+                    description: Name of the Node
+                    type: string
+                  uid:
+                    description: UID of the Node, protecting against name reuse
+                    nullable: true
                     type: string
                 required:
+                - apiVersion
+                - kind
                 - name
                 type: object
               observedGeneration:
@@ -306,6 +317,13 @@ spec:
                   Values: Pending, Active, `ShuttingDown`, Inactive, Disabled, Terminated, Error
                 nullable: true
                 type: string
+              providerID:
+                description: |-
+                  Provider-assigned machine identifier, copied from the CAPI
+                  `Machine.spec.providerID`. Stable for the life of the machine and
+                  unique across the cluster.
+                nullable: true
+                type: string
             type: object
         required:
         - spec

docs/reference/api.md

@@ -17,29 +17,37 @@ automatically added to and removed from a k0smotron cluster based on a time sche
 apiVersion: 5spot.finos.org/v1alpha1
 kind: ScheduledMachine
 metadata:
-  name: example-machine
+  name: example-spot-machine
   namespace: default
 spec:
+  clusterName: my-cluster
   schedule:
     daysOfWeek:
       - mon-fri
     hoursOfDay:
-      - "9-17"
+      - 9-17
     timezone: America/New_York
     enabled: true
-  clusterName: my-cluster
   bootstrapSpec:
     apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
     kind: K0sWorkerConfig
     spec:
-      version: v1.30.0+k0s.0
+      version: v1.32.8+k0s.0
+      downloadURL: https://github.com/k0sproject/k0s/releases/download/v1.32.8+k0s.0/k0s-v1.32.8+k0s.0-amd64
   infrastructureSpec:
     apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
     kind: RemoteMachine
     spec:
       address: 192.168.1.100
       port: 22
-      user: admin
+      user: root
+      sshKeyRef:
+        name: my-ssh-key
+  machineTemplate:
+    labels:
+      node-role.kubernetes.io/worker: spot
+    annotations:
+      example.com/scheduled-by: 5spot
   priority: 50
   gracefulShutdownTimeout: 5m
   nodeDrainTimeout: 5m
@@ -52,63 +60,55 @@ spec:
 
 Machine scheduling configuration.
 
-- **daysOfWeek** (optional, array of strings, default: `[]`): Days when machine should be active.
+- **daysOfWeek** (required, array of strings): Days when machine should be active.
   Supports ranges (`mon-fri`) and combinations (`mon-wed,fri-sun`).
 
-- **hoursOfDay** (optional, array of strings, default: `[]`): Hours when machine should be active (0-23).
+- **hoursOfDay** (required, array of strings): Hours when machine should be active (0-23).
   Supports ranges (`9-17`) and combinations (`0-9,18-23`).
 
 - **timezone** (optional, string, default: `UTC`): Timezone for the schedule.
   Must be a valid IANA timezone (e.g., `America/New_York`, `Europe/London`).
 
-- **enabled** (optional, boolean, default: `true`): Whether the schedule is active.
-
-*At least one of `daysOfWeek` or `hoursOfDay` must be non-empty.*
+- **enabled** (optional, boolean, default: `true`): Whether the schedule is enabled.
 
 #### clusterName
 
 (required, string) Name of the CAPI cluster this machine belongs to.
 
 #### bootstrapSpec
 
-(required, object) Inline bootstrap configuration. 5-Spot creates this resource when the
-schedule window opens. The `apiVersion`, `kind`, and `spec` map directly to the
-bootstrap provider's resource type (e.g., `K0sWorkerConfig`).
+(required, object) Inline bootstrap configuration that will be created when the schedule is active.
+This is a fully unstructured object that must contain:
 
-```yaml
-bootstrapSpec:
-  apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
-  kind: K0sWorkerConfig
-  spec:
-    version: v1.30.0+k0s.0
-```
+- **apiVersion** (required, string): API version of the bootstrap resource (e.g., `bootstrap.cluster.x-k8s.io/v1beta1`)
+- **kind** (required, string): Kind of the bootstrap resource (e.g., `K0sWorkerConfig`, `KubeadmConfig`)
+- **spec** (required, object): Provider-specific configuration for the bootstrap resource
+
+The controller validates that the apiVersion belongs to an allowed bootstrap API group.
 
 #### infrastructureSpec
 
-(required, object) Inline infrastructure configuration. 5-Spot creates this resource when
-the schedule window opens. The `apiVersion`, `kind`, and `spec` map directly to the
-infrastructure provider's resource type (e.g., `RemoteMachine`).
+(required, object) Inline infrastructure configuration that will be created when the schedule is active.
+This is a fully unstructured object that must contain:
 
-```yaml
-infrastructureSpec:
-  apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
-  kind: RemoteMachine
-  spec:
-    address: 192.168.1.100
-    port: 22
-    user: admin
-```
+- **apiVersion** (required, string): API version of the infrastructure resource (e.g., `infrastructure.cluster.x-k8s.io/v1beta1`)
+- **kind** (required, string): Kind of the infrastructure resource (e.g., `RemoteMachine`, `AWSMachine`)
+- **spec** (required, object): Provider-specific configuration for the infrastructure resource
+
+The controller validates that the apiVersion belongs to an allowed infrastructure API group.
 
 #### machineTemplate
 
-(optional, object) Labels and annotations applied to the created CAPI Machine resource.
+(optional, object) Configuration for the created CAPI Machine resource.
+
+- **labels** (optional, map of string to string): Labels to apply to the created Machine
+- **annotations** (optional, map of string to string): Annotations to apply to the created Machine
 
-- **labels** (optional, map): Labels to apply to the created Machine.
-- **annotations** (optional, map): Annotations to apply to the created Machine.
+Note: Labels and annotations using reserved prefixes (`5spot.finos.org/`, `cluster.x-k8s.io/`) are rejected.
 
 #### priority
 
-(optional, integer 0-255, default: `50`) Priority for machine scheduling.
+(optional, integer 0-100, default: `50`) Priority for machine scheduling.
 Higher values indicate higher priority. Used for resource distribution across
 operator instances.
 
@@ -119,36 +119,28 @@ Format: `<number><unit>` where unit is `s` (seconds), `m` (minutes), or `h` (hou
 
 #### nodeDrainTimeout
 
-(optional, string, default: `5m`) Timeout for draining the Kubernetes node before
-the CAPI Machine is deleted.
+(optional, string, default: `5m`) Timeout for draining the node before deletion.
+Format: `<number><unit>` where unit is `s` (seconds), `m` (minutes), or `h` (hours).
 
 #### killSwitch
 
 (optional, boolean, default: `false`) When true, immediately removes the machine
-from the cluster, bypassing the graceful shutdown and drain steps.
+from the cluster and takes it out of rotation, bypassing the grace period.
 
 ### Status Fields
 
 #### phase
 
 Current phase of the machine lifecycle. Possible values:
 
-- **Pending**: Initial state, schedule not yet evaluated
+- **Pending**: Initial state, awaiting schedule evaluation
 - **Active**: Machine is running and part of the cluster
-- **ShuttingDown**: Machine is being drained and removed
-- **Inactive**: Machine has been removed and is outside the schedule window
-- **Disabled**: Schedule is disabled (`schedule.enabled: false`)
-- **Terminated**: Machine was forcibly terminated (kill switch)
+- **ShuttingDown**: Machine is being gracefully removed (draining, etc.)
+- **Inactive**: Machine is outside scheduled time window and has been removed
+- **Disabled**: Schedule is disabled, machine is not active
+- **Terminated**: Machine has been permanently removed
 - **Error**: An error occurred during processing
 
-#### message
-
-Human-readable description of the current state or error.
-
-#### inSchedule
-
-Boolean. Whether the machine is currently within its scheduled time window.
-
 #### conditions
 
 Array of condition objects with the following fields:
@@ -157,47 +149,32 @@ Array of condition objects with the following fields:
 - **status**: `True`, `False`, or `Unknown`
 - **reason**: One-word reason in CamelCase
 - **message**: Human-readable message
-- **lastTransitionTime**: Last time the condition transitioned (RFC3339)
+- **lastTransitionTime**: Last time the condition transitioned
 
-#### machineRef
-
-Reference to the created CAPI Machine resource:
+#### inSchedule
 
-- **apiVersion**: API version of the Machine resource
-- **kind**: Kind of the Machine resource
-- **name**: Machine name
-- **namespace**: Machine namespace
+(boolean) Whether the machine is currently within its scheduled time window.
 
-#### bootstrapRef
+#### message
 
-Reference to the created bootstrap resource (e.g., `K0sWorkerConfig`):
+(string) Human-readable message describing the current state.
 
-- **apiVersion**, **kind**, **name**, **namespace**
+#### observedGeneration
 
-#### infrastructureRef
+(integer) The generation observed by the controller. Used for change detection.
 
-Reference to the created infrastructure resource (e.g., `RemoteMachine`):
+#### providerID
 
-- **apiVersion**, **kind**, **name**, **namespace**
+(optional, string) Provider-assigned machine identifier, copied from the CAPI Machine's
+`spec.providerID`. Stable for the life of the machine and unique across the cluster.
+Examples: `libvirt:///uuid-abc-123`, `aws:///us-east-1a/i-0abcd1234`.
 
 #### nodeRef
 
-Reference to the Kubernetes Node once the machine has joined the cluster:
-
-- **name**: Node name
-
-#### lastScheduledTime
-
-Last time a machine was created and activated (RFC3339 format).
-
-#### nextActivation
-
-Next time the machine will be activated according to its schedule (RFC3339 format).
-
-#### nextCleanup
-
-Time when the machine will be cleaned up (end of current schedule window, RFC3339 format).
-
-#### observedGeneration
+(optional, object) Reference to the Kubernetes Node once the Machine is provisioned.
+Mirrors the shape of CAPI's `Machine.status.nodeRef`:
 
-The spec generation last processed by the controller. Used for change detection.
+- **apiVersion** (required, string): API version of the Node resource (typically `v1`)
+- **kind** (required, string): Kind of the referenced object (typically `Node`)
+- **name** (required, string): Name of the Node
+- **uid** (optional, string): UID of the Node, protecting against name reuse

docs/src/concepts/machine-lifecycle.md

@@ -163,7 +163,11 @@ status:
     name: business-hours-worker-infra
     namespace: default
   nodeRef:
+    apiVersion: v1
+    kind: Node
     name: worker-node-01
+    uid: 11111111-2222-3333-4444-555555555555
+  providerID: libvirt:///uuid-abc-123
   conditions:
     - type: Ready
       status: "True"

docs/src/concepts/scheduled-machine.md

@@ -132,7 +132,8 @@ The status subresource contains the current state:
 | `machineRef` | `ObjectReference` | Reference to created CAPI Machine |
 | `bootstrapRef` | `ObjectReference` | Reference to created bootstrap resource |
 | `infrastructureRef` | `ObjectReference` | Reference to created infrastructure resource |
-| `nodeRef` | `LocalObjectReference` | Reference to the Kubernetes Node (once provisioned) |
+| `nodeRef` | `NodeRef` | Reference to the Kubernetes Node (apiVersion, kind, name, uid) once provisioned |
+| `providerID` | `string` | Provider-assigned machine identifier (copied from CAPI `Machine.spec.providerID`) |
 | `lastScheduledTime` | `Time` | Last time machine was created |
 | `nextActivation` | `Time` | Next scheduled activation time |
 | `nextCleanup` | `Time` | Time when machine will be cleaned up |

src/bin/crddoc.rs

@@ -208,4 +208,28 @@ fn main() {
     println!("#### observedGeneration");
     println!();
     println!("(integer) The generation observed by the controller. Used for change detection.");
+    println!();
+    println!("#### providerID");
+    println!();
+    println!(
+        "(optional, string) Provider-assigned machine identifier, copied from the CAPI Machine's"
+    );
+    println!(
+        "`spec.providerID`. Stable for the life of the machine and unique across the cluster."
+    );
+    println!("Examples: `libvirt:///uuid-abc-123`, `aws:///us-east-1a/i-0abcd1234`.");
+    println!();
+    println!("#### nodeRef");
+    println!();
+    println!(
+        "(optional, object) Reference to the Kubernetes Node once the Machine is provisioned."
+    );
+    println!("Mirrors the shape of CAPI's `Machine.status.nodeRef`:");
+    println!();
+    println!(
+        "- **apiVersion** (required, string): API version of the Node resource (typically `v1`)"
+    );
+    println!("- **kind** (required, string): Kind of the referenced object (typically `Node`)");
+    println!("- **name** (required, string): Name of the Node");
+    println!("- **uid** (optional, string): UID of the Node, protecting against name reuse");
 }