feat: use generateName for leases to allow alias reuse after deletion

Lease names now use K8s generateName instead of fixed names, allowing
custom lease IDs (aliases) to be reused after deletion. The user-provided
alias is stored as a label and resolved transparently in Get/Delete/Update.

Assisted-by: claude-opus-4.6
Signed-off-by: Benny Zlotnik <bzlotnik@redhat.com>

Author: bennyz

controller/api/v1alpha1/lease_helpers.go

@@ -323,6 +323,9 @@ func (l *Lease) ToProtobuf() *cpb.Lease {
 			Name:      l.Status.ExporterRef.Name,
 		}))
 	}
+	if alias, ok := l.Labels[string(LeaseLabelName)]; ok {
+		lease.Alias = ptr.To(alias)
+	}
 
 	return &lease
 }

controller/api/v1alpha1/lease_helpers_test.go

@@ -574,4 +574,44 @@ var _ = Describe("Lease.ToProtobuf", func() {
 
 		Expect(pb.Tags).To(BeEmpty())
 	})
+
+	It("should populate alias from lease-name label", func() {
+		lease := &Lease{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "demo-x7k2q",
+				Namespace: "default",
+				Labels: map[string]string{
+					string(LeaseLabelName): "demo",
+				},
+			},
+			Spec: LeaseSpec{
+				ClientRef: corev1.LocalObjectReference{Name: "test-client"},
+				Duration:  &metav1.Duration{Duration: time.Hour},
+				Selector:  metav1.LabelSelector{MatchLabels: map[string]string{"board": "rpi4"}},
+			},
+		}
+
+		pb := lease.ToProtobuf()
+
+		Expect(pb.Alias).NotTo(BeNil())
+		Expect(*pb.Alias).To(Equal("demo"))
+	})
+
+	It("should not set alias when lease-name label is absent", func() {
+		lease := &Lease{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "lease-m9p3r",
+				Namespace: "default",
+			},
+			Spec: LeaseSpec{
+				ClientRef: corev1.LocalObjectReference{Name: "test-client"},
+				Duration:  &metav1.Duration{Duration: time.Hour},
+				Selector:  metav1.LabelSelector{MatchLabels: map[string]string{"board": "rpi4"}},
+			},
+		}
+
+		pb := lease.ToProtobuf()
+
+		Expect(pb.Alias).To(BeNil())
+	})
 })

controller/api/v1alpha1/lease_types.go

@@ -82,6 +82,7 @@ type LeaseLabel string
 const (
 	LeaseLabelEnded        LeaseLabel = "jumpstarter.dev/lease-ended"
 	LeaseLabelEndedValue   string     = "true"
+	LeaseLabelName         LeaseLabel = "jumpstarter.dev/lease-name"
 	LeaseTagMetadataPrefix string     = "metadata.jumpstarter.dev/"
 )
 

controller/internal/protocol/jumpstarter/client/v1/client.pb.go

@@ -19,9 +19,9 @@ package v1
 import (
 	"context"
 	"fmt"
+	"sync"
 
 	"github.com/golang-jwt/jwt/v5"
-	"github.com/google/uuid"
 	jumpstarterdevv1alpha1 "github.com/jumpstarter-dev/jumpstarter-controller/api/v1alpha1"
 	"github.com/jumpstarter-dev/jumpstarter-controller/internal/oidc"
 	cpb "github.com/jumpstarter-dev/jumpstarter-controller/internal/protocol/jumpstarter/client/v1"
@@ -43,8 +43,16 @@ type ClientService struct {
 	cpb.UnimplementedClientServiceServer
 	kclient.Client
 	auth.Auth
-	MaxTags int32
-	Signer  *oidc.Signer
+	MaxTags        int32
+	Signer         *oidc.Signer
+	leaseAliasLocks sync.Map
+}
+
+func (s *ClientService) lockAlias(alias string) *sync.Mutex {
+	v, _ := s.leaseAliasLocks.LoadOrStore(alias, &sync.Mutex{})
+	mu := v.(*sync.Mutex)
+	mu.Lock()
+	return mu
 }
 
 func NewClientService(client kclient.Client, auth auth.Auth, maxTags int32, signer *oidc.Signer) *ClientService {
@@ -110,6 +118,77 @@ func (s *ClientService) ListExporters(
 	return jexporters.ToProtobuf(), nil
 }
 
+func (s *ClientService) resolveLeaseByNameOrAlias(ctx context.Context, namespace, nameOrAlias string) (*jumpstarterdevv1alpha1.Lease, error) {
+	var jlease jumpstarterdevv1alpha1.Lease
+	if err := s.Get(ctx, types.NamespacedName{Namespace: namespace, Name: nameOrAlias}, &jlease); err == nil {
+		return &jlease, nil
+	}
+
+	aliasReq, err := labels.NewRequirement(
+		string(jumpstarterdevv1alpha1.LeaseLabelName),
+		selection.Equals,
+		[]string{nameOrAlias},
+	)
+	if err != nil {
+		return nil, err
+	}
+	activeReq, err := labels.NewRequirement(
+		string(jumpstarterdevv1alpha1.LeaseLabelEnded),
+		selection.DoesNotExist,
+		[]string{},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	var jleases jumpstarterdevv1alpha1.LeaseList
+	if err := s.List(ctx, &jleases,
+		kclient.InNamespace(namespace),
+		kclient.MatchingLabelsSelector{Selector: labels.Everything().Add(*aliasReq).Add(*activeReq)},
+		kclient.Limit(2),
+	); err != nil {
+		return nil, err
+	}
+
+	switch len(jleases.Items) {
+	case 0:
+		return nil, status.Errorf(codes.NotFound, "lease %q not found", nameOrAlias)
+	case 1:
+		return &jleases.Items[0], nil
+	default:
+		return nil, status.Errorf(codes.FailedPrecondition, "multiple active leases match name %q, use exact lease name", nameOrAlias)
+	}
+}
+
+func (s *ClientService) hasActiveLeaseWithAlias(ctx context.Context, namespace, alias string) (bool, error) {
+	aliasReq, err := labels.NewRequirement(
+		string(jumpstarterdevv1alpha1.LeaseLabelName),
+		selection.Equals,
+		[]string{alias},
+	)
+	if err != nil {
+		return false, err
+	}
+	activeReq, err := labels.NewRequirement(
+		string(jumpstarterdevv1alpha1.LeaseLabelEnded),
+		selection.DoesNotExist,
+		[]string{},
+	)
+	if err != nil {
+		return false, err
+	}
+
+	var jleases jumpstarterdevv1alpha1.LeaseList
+	if err := s.List(ctx, &jleases,
+		kclient.InNamespace(namespace),
+		kclient.MatchingLabelsSelector{Selector: labels.Everything().Add(*aliasReq).Add(*activeReq)},
+		kclient.Limit(1),
+	); err != nil {
+		return false, err
+	}
+	return len(jleases.Items) > 0, nil
+}
+
 func (s *ClientService) GetLease(ctx context.Context, req *cpb.GetLeaseRequest) (*cpb.Lease, error) {
 	key, err := utils.ParseLeaseIdentifier(req.Name)
 	if err != nil {
@@ -121,8 +200,8 @@ func (s *ClientService) GetLease(ctx context.Context, req *cpb.GetLeaseRequest)
 		return nil, err
 	}
 
-	var jlease jumpstarterdevv1alpha1.Lease
-	if err := s.Get(ctx, *key, &jlease); err != nil {
+	jlease, err := s.resolveLeaseByNameOrAlias(ctx, key.Namespace, key.Name)
+	if err != nil {
 		return nil, err
 	}
 
@@ -228,28 +307,38 @@ func (s *ClientService) CreateLease(ctx context.Context, req *cpb.CreateLeaseReq
 		return nil, err
 	}
 
-	// Use provided lease_id if specified, otherwise generate a UUIDv7
-	name := req.LeaseId
-	if name == "" {
-		id, err := uuid.NewV7()
-		if err != nil {
-			return nil, err
-		}
-		name = id.String()
-	}
-
 	jlease, err := jumpstarterdevv1alpha1.LeaseFromProtobuf(req.Lease, types.NamespacedName{
 		Namespace: namespace,
-		Name:      name,
 	}, corev1.LocalObjectReference{
 		Name: jclient.Name,
 	})
 	if err != nil {
 		return nil, err
 	}
 
-	if err := s.Create(ctx, jlease); err != nil {
-		return nil, err
+	if req.LeaseId != "" {
+		mu := s.lockAlias(req.LeaseId)
+		defer mu.Unlock()
+		exists, err := s.hasActiveLeaseWithAlias(ctx, namespace, req.LeaseId)
+		if err != nil {
+			return nil, err
+		}
+		if exists {
+			return nil, status.Errorf(codes.AlreadyExists, "an active lease with name %q already exists", req.LeaseId)
+		}
+		jlease.GenerateName = req.LeaseId + "-"
+		if jlease.Labels == nil {
+			jlease.Labels = make(map[string]string)
+		}
+		jlease.Labels[string(jumpstarterdevv1alpha1.LeaseLabelName)] = req.LeaseId
+		if err := s.Create(ctx, jlease); err != nil {
+			return nil, err
+		}
+	} else {
+		jlease.GenerateName = "lease-"
+		if err := s.Create(ctx, jlease); err != nil {
+			return nil, err
+		}
 	}
 
 	return jlease.ToProtobuf(), nil
@@ -280,10 +369,11 @@ func (s *ClientService) UpdateLease(ctx context.Context, req *cpb.UpdateLeaseReq
 		return nil, err
 	}
 
-	var jlease jumpstarterdevv1alpha1.Lease
-	if err := s.Get(ctx, *key, &jlease); err != nil {
+	resolved, err := s.resolveLeaseByNameOrAlias(ctx, key.Namespace, key.Name)
+	if err != nil {
 		return nil, err
 	}
+	jlease := *resolved
 
 	if jlease.Spec.ClientRef.Name != jclient.Name {
 		return nil, fmt.Errorf("UpdateLease permission denied")
@@ -293,7 +383,8 @@ func (s *ClientService) UpdateLease(ctx context.Context, req *cpb.UpdateLeaseReq
 
 	// Only parse time fields from protobuf if any are being updated
 	if req.Lease.BeginTime != nil || req.Lease.Duration != nil || req.Lease.EndTime != nil {
-		desired, err := jumpstarterdevv1alpha1.LeaseFromProtobuf(req.Lease, *key,
+		resolvedKey := types.NamespacedName{Namespace: jlease.Namespace, Name: jlease.Name}
+		desired, err := jumpstarterdevv1alpha1.LeaseFromProtobuf(req.Lease, resolvedKey,
 			corev1.LocalObjectReference{
 				Name: jclient.Name,
 			},
@@ -369,8 +460,8 @@ func (s *ClientService) DeleteLease(ctx context.Context, req *cpb.DeleteLeaseReq
 		return nil, err
 	}
 
-	var jlease jumpstarterdevv1alpha1.Lease
-	if err := s.Get(ctx, *key, &jlease); err != nil {
+	jlease, err := s.resolveLeaseByNameOrAlias(ctx, key.Namespace, key.Name)
+	if err != nil {
 		return nil, err
 	}
 
@@ -386,7 +477,7 @@ func (s *ClientService) DeleteLease(ctx context.Context, req *cpb.DeleteLeaseReq
 
 	jlease.Spec.Release = true
 
-	if err := s.Patch(ctx, &jlease, original); err != nil {
+	if err := s.Patch(ctx, jlease, original); err != nil {
 		return nil, err
 	}
 

controller/internal/service/client/v1/client_service.go

@@ -260,7 +260,7 @@ var _ = Describe("Hooks E2E Tests", Label("hooks"), Ordered, func() {
 				"--selector", "example.com/board=hooks", "j", "power", "on")
 			Expect(err).NotTo(HaveOccurred(), out)
 			Expect(out).To(ContainSubstring("BEFORE_HOOK:"))
-			Expect(out).To(MatchRegexp(`lease=[0-9a-f-]+`))
+			Expect(out).To(MatchRegexp(`lease=[a-z0-9-]+`))
 			Expect(out).To(MatchRegexp(`client=`))
 		})
 	})

e2e/test/hooks_test.go

@@ -141,6 +141,8 @@ message Lease {
   optional string exporter_name = 12 [(google.api.field_behavior) = IMMUTABLE];
   // The set of tags associated with the lease.
   map<string, string> tags = 13 [(google.api.field_behavior) = IMMUTABLE];
+  // The user-provided alias for this lease (from lease_id at creation time).
+  optional string alias = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Request to retrieve an exporter.

protocol/proto/jumpstarter/client/v1/client.proto

@@ -497,6 +497,8 @@ async def _shell_with_signal_handling(  # noqa: C901
 
 def _format_lease_display(lease) -> str:
     parts = []
+    if getattr(lease, "alias", None):
+        parts.append(f"alias={lease.alias}")
     if lease.exporter:
         parts.append(f"exporter={lease.exporter}")
     if lease.selector:

python/packages/jumpstarter-cli/jumpstarter_cli/shell.py

@@ -14,6 +14,7 @@
 
 from jumpstarter_cli.shell import (
     _attempt_token_recovery,
+    _format_lease_display,
     _monitor_token_expiry,
     _resolve_lease_from_active_async,
     _run_shell_with_lease_async,
@@ -977,3 +978,16 @@ async def fake_run_shell(*_args):
         ):
             with pytest.raises((ExporterOfflineError, BaseExceptionGroup)):
                 await _shell_with_signal_handling(config, None, None, None, timedelta(minutes=1), False, (), None)
+
+
+def test_format_lease_display_includes_alias():
+    lease = _make_lease("demo-x7k2q")
+    lease.alias = "demo"
+    result = _format_lease_display(lease)
+    assert "alias=demo" in result
+
+
+def test_format_lease_display_no_alias():
+    lease = _make_lease("lease-m9p3r")
+    result = _format_lease_display(lease)
+    assert "alias" not in result

python/packages/jumpstarter-cli/jumpstarter_cli/shell_test.py

@@ -26,7 +26,7 @@
     _setup_logging,
     create_server,
 )
-from jumpstarter_mcp.tools.leases import _lease_status
+from jumpstarter_mcp.tools.leases import _lease_status, list_leases
 
 # ---------------------------------------------------------------------------
 # Helpers / fixtures
@@ -270,6 +270,40 @@ def test_unknown_when_not_true(self):
         assert _lease_status(lease) == "unknown"
 
 
+# ---------------------------------------------------------------------------
+# list_leases (unit, mocked config)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FakeLeaseEntry:
+    name: str
+    client: str
+    exporter: str
+    selector: str
+    conditions: list
+    effective_begin_time: datetime | None = None
+    effective_end_time: datetime | None = None
+    duration: None = None
+    alias: str | None = None
+
+
+@dataclass
+class FakeLeaseListResult:
+    leases: list
+
+
+@pytest.mark.asyncio
+async def test_list_leases_includes_alias_when_present():
+    lease_with = FakeLeaseEntry(name="demo-x7k2q", client="c", exporter="e", selector="s", conditions=[], alias="demo")
+    lease_without = FakeLeaseEntry(name="lease-m9p3r", client="c", exporter="e", selector="s", conditions=[])
+    config = AsyncMock()
+    config.list_leases.return_value = FakeLeaseListResult(leases=[lease_with, lease_without])
+    result = await list_leases(config)
+    assert result[0]["alias"] == "demo"
+    assert "alias" not in result[1]
+
+
 # ---------------------------------------------------------------------------
 # ConnectionManager (unit, no real connections)
 # ---------------------------------------------------------------------------