Use field selector for active leases once KEP-4358 is stable

[raballew]

TODO Comment

// TODO: use field selector once KEP-4358 is stabilized

Location

controller/internal/controller/lease.go, line 13

Context

func MatchingActiveLeases() client.ListOption {
    // TODO: use field selector once KEP-4358 is stabilized
    // Reference: https://github.com/kubernetes/kubernetes/pull/122717
    requirement, err := labels.NewRequirement(
        string(jumpstarterdevv1alpha1.LeaseLabelEnded),
        selection.DoesNotExist,
        []string{},
    )
    utilruntime.Must(err)

Currently using label selectors as a workaround. Should switch to field selectors once KEP-4358 (kubernetes/kubernetes#122717) is stabilized.

[ambient-code]

Investigation Summary

I analyzed the label selector workaround in controller/internal/controller/lease.go and its usage across the codebase.

Current behavior:

• MatchingActiveLeases() uses a label selector checking for the absence of the jumpstarter.dev/lease-ended label to find active (non-ended) leases.
• The LeaseLabelEnded label is set to "true" in lease_controller.go:101 when lease.Status.Ended becomes true during reconciliation.
• This is a workaround because Kubernetes CRDs historically did not support field selectors on custom fields -- you could not filter by .status.ended == false server-side.
• The function is used in three places:
  • lease_controller.go:453 -- ListActiveLeases() to find active leases in a namespace.
  • exporter_controller.go:155 -- reconcileStatusLeaseRef() to find the active lease for an exporter.
  • controller_service.go:927 -- ListLeases gRPC handler to list active leases for a client.
• Additionally, client_service.go:146 independently constructs the same label requirement for paginated lease listing with user-provided filters.

KEP-4358 status: Custom Resource Field Selectors reached GA (stable) in Kubernetes 1.32, released December 2024. The project's go.mod already targets k8s.io/api v0.33.0 (Kubernetes 1.33), so the feature is fully available.

What the change enables: Instead of maintaining a synthetic jumpstarter.dev/lease-ended label mirrored from .status.ended, leases could be filtered directly on the .status.ended field using server-side field selectors. This removes the need to keep the label in sync with the status field.

Risk Assessment

Low-to-moderate risk. The change is straightforward but requires careful migration:

1. The CRD must declare selectableFields for .status.ended -- this requires updating both the CRD YAML (in deploy/helm/ and deploy/operator/config/crd/bases/) and potentially the kubebuilder markers on the Go type.
2. The label-based approach works reliably today. Removing the label too early would break rollback scenarios.
3. The client_service.go independently constructs the same label requirement and would need updating too.
4. Users might have external tooling or scripts that rely on the jumpstarter.dev/lease-ended label for filtering.
5. There is a minimum Kubernetes version concern -- clusters running < 1.30 (alpha) would not support this. However, since the project targets k8s 1.33 APIs, this is likely acceptable.

Proposed Implementation Plan

1. Add selectableFields to the Lease CRD:

   • Update the CRD definition in both deploy/helm/.../jumpstarter.dev_leases.yaml and deploy/operator/config/crd/bases/jumpstarter.dev_leases.yaml to include:

     selectableFields:
       - jsonPath: .status.ended

   • If using controller-gen, add the appropriate kubebuilder marker to the Lease type in api/v1alpha1/lease_types.go. As of controller-gen v0.16+, the marker +kubebuilder:selectablefield should be available (verify exact syntax for the version in use).

2. Update MatchingActiveLeases() in lease.go:

   • Replace the label selector with a field selector:

     func MatchingActiveLeases() client.ListOption {
         return client.MatchingFields{"status.ended": "false"}
     }

   • Or use client.MatchingFieldsSelector with fields.OneTermEqualSelector("status.ended", "false").

3. Update client_service.go:

   • Replace the label requirement at line 145-153 with the equivalent field selector approach, being careful to combine it correctly with the user's label-based filter selector (label selectors and field selectors are separate ListOption entries and are ANDed by the API server).

4. Deprecate and remove the label:

   • Phase 1: Keep setting the jumpstarter.dev/lease-ended label in lease_controller.go:101 for backward compatibility, but switch all queries to use field selectors.
   • Phase 2 (future release): Remove the label-setting code from lease_controller.go and remove the LeaseLabelEnded / LeaseLabelEndedValue constants from lease_types.go.

5. Update controller-runtime cache indexing (if needed):

   • If using a cached client, ensure the field selector is indexed in the controller-runtime cache. This may require adding a field indexer via mgr.GetFieldIndexer().IndexField() for status.ended in SetupWithManager().

6. Testing:

   • Update existing tests that reference LeaseLabelEnded to verify field selector behavior.
   • Verify that MatchingActiveLeases() correctly filters leases in integration tests.
   • Test the paginated lease listing in client_service.go with the field selector approach.

7. Documentation:

   • Note the minimum Kubernetes version requirement (1.30 for alpha with feature gate, 1.32 for GA with no feature gate needed).
   • Document the deprecation of the jumpstarter.dev/lease-ended label in release notes.