feat: Update sandbox status with phase

Adds a 'Phase' field to the 'SandboxStatus' to provide a more explicit
status representation of the sandbox.

The phase can be one of 'Pending', 'Running', 'Paused', 'Terminating', or
'Failed'.

This addresses issue #119.

Author: barney-s

api/v1alpha1/sandbox_types.go

@@ -19,6 +19,22 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// SandboxPhase is a simple, high-level summary of where the Sandbox is in its lifecycle.
+type SandboxPhase string
+
+const (
+	// SandboxPhasePending means the sandbox is being created
+	SandboxPhasePending SandboxPhase = "Pending"
+	// SandboxPhaseRunning means the sandbox is running
+	SandboxPhaseRunning SandboxPhase = "Running"
+	// SandboxPhasePaused means the sandbox is paused
+	SandboxPhasePaused SandboxPhase = "Paused"
+	// SandboxPhaseTerminating means the sandbox is terminating
+	SandboxPhaseTerminating SandboxPhase = "Terminating"
+	// SandboxPhaseFailed means the sandbox has failed
+	SandboxPhaseFailed SandboxPhase = "Failed"
+)
+
 // ConditionType is a type of condition for a resource.
 type ConditionType string
 
@@ -121,6 +137,23 @@ type SandboxSpec struct {
 
 // SandboxStatus defines the observed state of Sandbox.
 type SandboxStatus struct {
+	// The phase of a Sandbox is a simple, high-level summary of where the Sandbox is in its lifecycle.
+	// The conditions array, the reason and message fields, and the individual container status arrays are
+	// more detail about the pod's status.
+	// There are five possible phase values:
+	//
+	// Pending: The Sandbox has been accepted by the Kubernetes system, but one or more of the Pod
+	// startup steps is not yet complete.
+	// Running: The Sandbox has been bound to a node, and all of the Pods have been created. At least
+	// one Pod is still running, or is in the process of starting or restarting.
+	// Paused: The Sandbox has been paused.
+	// Failed: All Pods in the Sandbox have terminated, and at least one Pod has terminated in a failure
+	// (exited with a non-zero exit code or was terminated by the system).
+	// Terminating: The Sandbox is terminating.
+	//
+	// +optional
+	Phase SandboxPhase `json:"phase,omitempty"`
+
 	// FQDN that is valid for default cluster settings
 	// Limitation: Hardcoded to the domain .cluster.local
 	// e.g. sandbox-example.default.svc.cluster.local

controllers/sandbox_controller.go

@@ -95,9 +95,15 @@ func (r *SandboxReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ct
 
 	if !sandbox.ObjectMeta.DeletionTimestamp.IsZero() {
 		log.Info("Sandbox is being deleted")
+		//sandbox.Status.Phase = sandboxv1alpha1.SandboxPhaseTerminating
 		return ctrl.Result{}, nil
 	}
 
+	// Set a default phase
+	if sandbox.Status.Phase == "" {
+		sandbox.Status.Phase = sandboxv1alpha1.SandboxPhasePending
+	}
+
 	oldStatus := sandbox.Status.DeepCopy()
 	var err error
 
@@ -137,9 +143,20 @@ func (r *SandboxReconciler) reconcileChildResources(ctx context.Context, sandbox
 	if pod == nil {
 		sandbox.Status.Replicas = 0
 		sandbox.Status.LabelSelector = ""
+		if sandbox.Spec.Replicas != nil && *sandbox.Spec.Replicas == 0 {
+			sandbox.Status.Phase = sandboxv1alpha1.SandboxPhasePaused
+		}
 	} else {
 		sandbox.Status.Replicas = 1
 		sandbox.Status.LabelSelector = fmt.Sprintf("%s=%s", sandboxLabel, NameHash(sandbox.Name))
+		switch pod.Status.Phase {
+		case corev1.PodRunning:
+			sandbox.Status.Phase = sandboxv1alpha1.SandboxPhaseRunning
+		case corev1.PodPending:
+			sandbox.Status.Phase = sandboxv1alpha1.SandboxPhasePending
+		case corev1.PodFailed:
+			sandbox.Status.Phase = sandboxv1alpha1.SandboxPhaseFailed
+		}
 	}
 
 	// Reconcile Service
@@ -186,9 +203,9 @@ func (r *SandboxReconciler) computeReadyCondition(sandbox *sandboxv1alpha1.Sandb
 			}
 		}
 	} else {
-		if sandbox.Spec.Replicas != nil && *sandbox.Spec.Replicas == 0 {
-			message = "Pod does not exist, replicas is 0"
+		if sandbox.Status.Phase == sandboxv1alpha1.SandboxPhasePaused {
 			// This is intended behaviour. So marking it ready.
+			message = "Sandbox is paused"
 			podReady = true
 		} else {
 			message = "Pod does not exist"
@@ -431,6 +448,7 @@ func (r *SandboxReconciler) handleSandboxExpiry(ctx context.Context, sandbox *sa
 		Message:            "Sandbox has expired",
 	})
 
+	sandbox.Status.Phase = sandboxv1alpha1.SandboxPhaseTerminating
 	sandbox.Status.Replicas = 0
 	sandbox.Status.LabelSelector = ""
 

controllers/sandbox_controller_test.go

@@ -175,6 +175,22 @@ func TestComputeReadyCondition(t *testing.T) {
 			expectedStatus: metav1.ConditionFalse,
 			expectedReason: "DependenciesNotReady",
 		},
+		{
+			name: "sandbox paused",
+			sandbox: &sandboxv1alpha1.Sandbox{
+				ObjectMeta: metav1.ObjectMeta{
+					Generation: 1,
+				},
+				Status: sandboxv1alpha1.SandboxStatus{
+					Phase: sandboxv1alpha1.SandboxPhasePaused,
+				},
+			},
+			err:            nil,
+			svc:            &corev1.Service{},
+			pod:            nil,
+			expectedStatus: metav1.ConditionTrue,
+			expectedReason: "DependenciesReady",
+		},
 		{
 			name: "all not ready",
 			sandbox: &sandboxv1alpha1.Sandbox{
@@ -227,6 +243,7 @@ func TestReconcile(t *testing.T) {
 			},
 			// Verify Sandbox status
 			wantStatus: sandboxv1alpha1.SandboxStatus{
+				Phase:         sandboxv1alpha1.SandboxPhasePending,
 				Service:       sandboxName,
 				ServiceFQDN:   "sandbox-name.sandbox-ns.svc.cluster.local",
 				Replicas:      1,
@@ -320,6 +337,7 @@ func TestReconcile(t *testing.T) {
 			},
 			// Verify Sandbox status
 			wantStatus: sandboxv1alpha1.SandboxStatus{
+				Phase:         sandboxv1alpha1.SandboxPhasePending,
 				Service:       sandboxName,
 				ServiceFQDN:   "sandbox-name.sandbox-ns.svc.cluster.local",
 				Replicas:      1,
@@ -406,6 +424,28 @@ func TestReconcile(t *testing.T) {
 				},
 			},
 		},
+		{
+			name: "paused sandbox",
+			sandboxSpec: sandboxv1alpha1.SandboxSpec{
+				Replicas: ptr.To(int32(0)),
+			},
+			// Verify Sandbox status
+			wantStatus: sandboxv1alpha1.SandboxStatus{
+				Phase:       sandboxv1alpha1.SandboxPhasePaused,
+				Replicas:    0,
+				ServiceFQDN: "sandbox-name.sandbox-ns.svc.cluster.local",
+				Service:     "sandbox-name",
+				Conditions: []metav1.Condition{
+					{
+						Type:               "Ready",
+						Status:             "True",
+						ObservedGeneration: 1,
+						Reason:             "DependenciesReady",
+						Message:            "Sandbox is paused; Service Exists",
+					},
+				},
+			},
+		},
 	}
 
 	for _, tc := range testCases {

k8s/crds/agents.x-k8s.io_sandboxes.yaml

@@ -3971,6 +3971,8 @@ spec:
                   - type
                   type: object
                 type: array
+              phase:
+                type: string
               replicas:
                 format: int32
                 type: integer

test/e2e/basic_test.go

@@ -76,6 +76,7 @@ func TestSimpleSandbox(t *testing.T) {
 	// Assert Sandbox object status reconciles as expected
 	p := []predicates.ObjectPredicate{
 		predicates.SandboxHasStatus(sandboxv1alpha1.SandboxStatus{
+			Phase:         "Running",
 			Service:       "my-sandbox",
 			ServiceFQDN:   "my-sandbox.my-sandbox-ns.svc.cluster.local",
 			Replicas:      1,

test/e2e/replicas_test.go

@@ -42,6 +42,7 @@ func TestSandboxReplicas(t *testing.T) {
 	// Assert Sandbox object status reconciles as expected
 	p := []predicates.ObjectPredicate{
 		predicates.SandboxHasStatus(sandboxv1alpha1.SandboxStatus{
+			Phase:         "Running",
 			Service:       "my-sandbox",
 			ServiceFQDN:   "my-sandbox.my-sandbox-ns.svc.cluster.local",
 			Replicas:      1,
@@ -74,13 +75,14 @@ func TestSandboxReplicas(t *testing.T) {
 	// Wait for sandbox status to reflect new state
 	p = []predicates.ObjectPredicate{
 		predicates.SandboxHasStatus(sandboxv1alpha1.SandboxStatus{
+			Phase:         "Paused",
 			Service:       "my-sandbox",
 			ServiceFQDN:   "my-sandbox.my-sandbox-ns.svc.cluster.local",
 			Replicas:      0,
 			LabelSelector: "",
 			Conditions: []metav1.Condition{
 				{
-					Message:            "Pod does not exist, replicas is 0; Service Exists",
+					Message:            "Sandbox is paused; Service Exists",
 					ObservedGeneration: 2,
 					Reason:             "DependenciesReady",
 					Status:             "True",

test/e2e/shutdown_test.go

@@ -41,6 +41,7 @@ func TestSandboxShutdownTime(t *testing.T) {
 	// Assert Sandbox object status reconciles as expected
 	p := []predicates.ObjectPredicate{
 		predicates.SandboxHasStatus(sandboxv1alpha1.SandboxStatus{
+			Phase:         "Running",
 			Service:       "my-sandbox",
 			ServiceFQDN:   "my-sandbox.my-sandbox-ns.svc.cluster.local",
 			Replicas:      1,
@@ -75,6 +76,7 @@ func TestSandboxShutdownTime(t *testing.T) {
 	p = []predicates.ObjectPredicate{
 		predicates.SandboxHasStatus(sandboxv1alpha1.SandboxStatus{
 			// TODO: should Service/ServiceFQDN be cleared from status when the Service is deleted?
+			Phase:       "Terminating",
 			Service:     "my-sandbox",
 			ServiceFQDN: "my-sandbox.my-sandbox-ns.svc.cluster.local",
 			Replicas:    0,