fix(lifecycle): clarify one-shot completion semantics

Author: syscod3

cmd/agent/main.go

@@ -120,6 +120,7 @@ func main() {
 		Metrics:  mc,
 		Net:      prodNet,
 		Alloc:    alloc,
+		Recorder: mgr.GetEventRecorderFor("imp-agent"),
 	}).SetupWithManager(mgr); err != nil {
 		log.Error(err, "Unable to set up ImpVMReconciler")
 		os.Exit(1)

internal/agent/reconciler.go

@@ -12,9 +12,11 @@ import (
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/trace"
+	corev1 "k8s.io/api/core/v1"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/client-go/tools/record"
 	"k8s.io/client-go/util/retry"
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/client"
@@ -44,6 +46,8 @@ type ImpVMReconciler struct {
 	// StartTimeout is how long a VM may remain in Starting before being
 	// transitioned to Failed. Defaults to 5 minutes when zero.
 	StartTimeout time.Duration
+	// Recorder emits lifecycle events for VM completion/failure.
+	Recorder record.EventRecorder
 }
 
 // +kubebuilder:rbac:groups=imp.dev,resources=impvms,verbs=get;list;watch;update;patch
@@ -266,8 +270,9 @@ func (r *ImpVMReconciler) handleRunning(ctx context.Context, vm *impdevv1alpha1.
 		}
 	}
 
-	log.Info("VM process exited", "lifecycle", vm.Spec.Lifecycle)
-	if vm.Spec.Lifecycle == impdevv1alpha1.VMLifecycleEphemeral {
+	lifecycle := vmLifecycleOrDefault(vm)
+	log.Info("VM process exited", "lifecycle", lifecycle)
+	if lifecycle == impdevv1alpha1.VMLifecycleEphemeral {
 		return r.finishSucceeded(ctx, vm)
 	}
 	return r.finishFailed(ctx, vm)
@@ -317,11 +322,15 @@ func (r *ImpVMReconciler) finishSucceeded(ctx context.Context, vm *impdevv1alpha
 	// Status patch — take base AFTER spec patch so resourceVersion is current.
 	base := vm.DeepCopy()
 	vm.Status.Phase = impdevv1alpha1.VMPhaseSucceeded
+	vm.Status.StartedAt = nil
 	vm.Status.IP = ""
 	vm.Status.RuntimePID = 0
 	if err := r.Status().Patch(ctx, vm, client.MergeFrom(base)); err != nil {
 		return ctrl.Result{}, err
 	}
+	if r.Recorder != nil {
+		r.Recorder.Event(vm, corev1.EventTypeNormal, "Completed", "VM exited and was marked Succeeded")
+	}
 	return ctrl.Result{}, nil
 }
 
@@ -333,9 +342,19 @@ func (r *ImpVMReconciler) finishFailed(ctx context.Context, vm *impdevv1alpha1.I
 	if err := r.Status().Patch(ctx, vm, client.MergeFrom(base)); err != nil {
 		return ctrl.Result{}, err
 	}
+	if r.Recorder != nil {
+		r.Recorder.Event(vm, corev1.EventTypeWarning, "ProcessExited", "VM process exited and was marked Failed")
+	}
 	return ctrl.Result{}, nil
 }
 
+func vmLifecycleOrDefault(vm *impdevv1alpha1.ImpVM) impdevv1alpha1.VMLifecycle {
+	if vm.Spec.Lifecycle == "" {
+		return impdevv1alpha1.VMLifecycleEphemeral
+	}
+	return vm.Spec.Lifecycle
+}
+
 // clearOwnership clears spec.nodeName + status ip/pid after Terminating stop.
 func (r *ImpVMReconciler) clearOwnership(ctx context.Context, vm *impdevv1alpha1.ImpVM) (ctrl.Result, error) {
 	specBase := vm.DeepCopy()

internal/agent/reconciler_test.go

@@ -100,6 +100,43 @@ var _ = Describe("ImpVM Agent: ephemeral exit → Succeeded", func() {
 		Expect(updated.Status.Phase).To(Equal(impdevv1alpha1.VMPhaseSucceeded))
 		Expect(updated.Spec.NodeName).To(BeEmpty())
 	})
+
+	It("treats empty lifecycle as ephemeral default and marks Succeeded", func() {
+		driver := NewStubDriver()
+
+		vm := &impdevv1alpha1.ImpVM{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "tc2-default-ephemeral", Namespace: "default",
+				Finalizers: []string{"imp/finalizer"},
+			},
+			Spec: impdevv1alpha1.ImpVMSpec{
+				NodeName: testNode,
+				// Lifecycle intentionally omitted to verify default behavior on old/un-defaulted objects.
+			},
+		}
+		Expect(k8sClient.Create(ctx, vm)).To(Succeed())
+		DeferCleanup(func() { k8sClient.Delete(ctx, vm) }) //nolint:errcheck
+
+		pid, err := driver.Start(ctx, vm)
+		Expect(err).NotTo(HaveOccurred())
+		base := vm.DeepCopy()
+		vm.Status.Phase = impdevv1alpha1.VMPhaseRunning
+		vm.Status.RuntimePID = pid
+		vm.Status.IP = "192.168.100.11"
+		Expect(k8sClient.Status().Patch(ctx, vm, client.MergeFrom(base))).To(Succeed())
+
+		Expect(driver.Stop(ctx, vm)).To(Succeed())
+
+		_, err = newReconciler(driver).Reconcile(ctx, reconcile.Request{
+			NamespacedName: types.NamespacedName{Name: "tc2-default-ephemeral", Namespace: "default"},
+		})
+		Expect(err).NotTo(HaveOccurred())
+
+		updated := &impdevv1alpha1.ImpVM{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: "tc2-default-ephemeral", Namespace: "default"}, updated)).To(Succeed())
+		Expect(updated.Status.Phase).To(Equal(impdevv1alpha1.VMPhaseSucceeded))
+		Expect(updated.Spec.NodeName).To(BeEmpty())
+	})
 })
 
 var _ = Describe("ImpVM Agent: persistent exit → Failed", func() {

internal/controller/impvm_conditions.go

@@ -41,8 +41,10 @@ func setReadyFromPhase(vm *impdevv1alpha1.ImpVM) {
 	switch vm.Status.Phase {
 	case impdevv1alpha1.VMPhaseRunning:
 		setCondition(vm, ConditionReady, metav1.ConditionTrue, "Running", "VM is running")
-	case impdevv1alpha1.VMPhaseFailed, impdevv1alpha1.VMPhaseSucceeded:
-		setCondition(vm, ConditionReady, metav1.ConditionFalse, string(vm.Status.Phase), "VM is not running")
+	case impdevv1alpha1.VMPhaseSucceeded:
+		setCondition(vm, ConditionReady, metav1.ConditionFalse, "Completed", "VM completed successfully")
+	case impdevv1alpha1.VMPhaseFailed:
+		setCondition(vm, ConditionReady, metav1.ConditionFalse, "Failed", "VM failed")
 	default:
 		setCondition(vm, ConditionReady, metav1.ConditionUnknown, "Waiting", "Waiting for VM to start")
 	}

internal/controller/impvm_coverage_test.go

@@ -117,6 +117,16 @@ var _ = Describe("setReadyFromPhase", func() {
 		Entry("Succeeded → False", impdevv1alpha1.VMPhaseSucceeded, metav1.ConditionFalse),
 		Entry("Pending → Unknown", impdevv1alpha1.VMPhasePending, metav1.ConditionUnknown),
 	)
+
+	It("sets explicit completion reason/message for Succeeded phase", func() {
+		vm := &impdevv1alpha1.ImpVM{}
+		vm.Status.Phase = impdevv1alpha1.VMPhaseSucceeded
+		setReadyFromPhase(vm)
+		c := apimeta.FindStatusCondition(vm.Status.Conditions, ConditionReady)
+		Expect(c).NotTo(BeNil())
+		Expect(c.Reason).To(Equal("Completed"))
+		Expect(c.Message).To(Equal("VM completed successfully"))
+	})
 })
 
 // ─── countRunningVMs ─────────────────────────────────────────────────────────