feat: Direct lifecycle control of instances

api/v1alpha/instance_types.go

@@ -26,8 +26,37 @@ type InstanceSpec struct {
 	// +kubebuilder:validation:Optional
 	// +listType=map
 	// +listMapKey=name
-
 	Volumes []InstanceVolume `json:"volumes,omitempty"`
+
+	// The location which the instance has been scheduled to
+	//
+	// +kubebuilder:validation:Optional
+	Location *networkingv1alpha.LocationReference `json:"location,omitempty"`
+
+	// Controller contains settings driven by the controller managing the instance.
+	//
+	// +kubebuilder:validation:Optional
+	Controller *InstanceController `json:"controller,omitempty"`
+}
+
+type InstanceController struct {
+	// TemplateHash is the hash of the instance template applied for this instance.
+	//
+	// +kubebuilder:validation:Required
+	TemplateHash string `json:"templateHash"`
+
+	// SchedulingGates is a list of gates that must be satisfied before the
+	// instance can be scheduled.
+	//
+	// +kubebuilder:validation:Optional
+	// +listType=map
+	// +listMapKey=name
+	SchedulingGates []SchedulingGate `json:"schedulingGates,omitempty"`
+}
+
+type SchedulingGate struct {
+	// The name of the gate.
+	Name string `json:"name"`
 }
 
 type InstanceRuntimeSpec struct {
@@ -337,8 +366,60 @@ type InstanceStatus struct {
 
 	// Network interface information
 	NetworkInterfaces []InstanceNetworkInterfaceStatus `json:"networkInterfaces,omitempty"`
+
+	// Controller contains status information about the controller managing the instance.
+	//
+	// +kubebuilder:validation:Optional
+	Controller *InstanceControllerStatus `json:"controller,omitempty"`
 }
 
+type InstanceControllerStatus struct {
+	// ObservedTemplateHash is the hash of the instance template applied for this instance.
+	//
+	// +kubebuilder:validation:Required
+	ObservedTemplateHash string `json:"observedTemplateHash"`
+}
+
+const (
+	// InstanceReady indicates that the instance is ready
+	InstanceReady = "Ready"
+
+	// InstanceRunning indicates that the instance is running
+	InstanceRunning = "Running"
+
+	// InstanceProgrammed indicates that the instance has been programmed
+	InstanceProgrammed = "Programmed"
+)
+
+const (
+	// InstanceReadyReasonSchedulingGatesPresent indicates that the instance is not ready because scheduling gates are present.
+	InstanceReadyReasonSchedulingGatesPresent = "SchedulingGatesPresent"
+
+	// InstanceReadyReasonRunning indicates that the instance is running
+	InstanceReadyReasonRunning = "Running"
+
+	// InstanceRunningReasonStopped indicates that the instance is stopped
+	InstanceRunningReasonStopped = "Stopped"
+
+	// InstanceRunningReasonStarting indicates that the instance is starting
+	InstanceRunningReasonStarting = "Starting"
+
+	// InstanceRunningReasonStopping indicates that the instance is stopping
+	InstanceRunningReasonStopping = "Stopping"
+
+	// InstanceRunningReasonRunning indicates that the instance is running
+	InstanceRunningReasonRunning = "Running"
+
+	// InstanceProgrammedReasonPendingProgramming indicates that the instance has not been programmed
+	InstanceProgrammedReasonPendingProgramming = "PendingProgramming"
+
+	// InstanceProgrammedReasonProgrammingInProgress indicates that the instance is being programmed.
+	InstanceProgrammedReasonProgrammingInProgress = "ProgrammingInProgress"
+
+	// InstanceProgrammedReasonProgrammed indicates that the instance has been programmed
+	InstanceProgrammedReasonProgrammed = "Programmed"
+)
+
 type InstanceTemplateSpec struct {
 	// Metadata of the instances created from this template
 	//
@@ -355,15 +436,21 @@ type InstanceTemplateSpec struct {
 
 // Instance is the Schema for the instances API
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
-// +kubebuilder:printcolumn:name="Available",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].status`
-// +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].reason`
-// +kubebuilder:printcolumn:name="Network IP",type=string,JSONPath=`.status.networkInterfaces[0].assignments.networkIP`,priority=1
-// +kubebuilder:printcolumn:name="External IP",type=string,JSONPath=`.status.networkInterfaces[0].assignments.externalIP`,priority=1
+// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
+// +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].reason`
+// +kubebuilder:printcolumn:name="Network IP",type=string,JSONPath=`.status.networkInterfaces[0].assignments.networkIP`
+// +kubebuilder:printcolumn:name="External IP",type=string,JSONPath=`.status.networkInterfaces[0].assignments.externalIP`
+// +kubebuilder:printcolumn:name="Message",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].message`,priority=1
 type Instance struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   InstanceSpec   `json:"spec,omitempty"`
+	// Spec defines the desired state of an Instance.
+	Spec InstanceSpec `json:"spec,omitempty"`
+
+	// Status defines the current state of an Instance.
+	//
+	// +kubebuilder:default={conditions:{{type:"Programmed",status:"Unknown",reason:"Pending", message:"Waiting for controller", lastTransitionTime: "1970-01-01T00:00:00Z"},{type:"Running",status:"Unknown",reason:"Pending", message:"Waiting for controller", lastTransitionTime: "1970-01-01T00:00:00Z"},{type:"Ready",status:"Unknown",reason:"Pending", message:"Waiting for controller", lastTransitionTime: "1970-01-01T00:00:00Z"}}}
 	Status InstanceStatus `json:"status,omitempty"`
 }
 

api/v1alpha/labels.go

@@ -5,4 +5,6 @@ const (
 
 	WorkloadUIDLabel           = LabelNamespace + "/workload-uid"
 	WorkloadDeploymentUIDLabel = LabelNamespace + "/workload-deployment-uid"
+
+	InstanceIndexLabel = LabelNamespace + "/instance-index"
 )

api/v1alpha/workload_types.go

@@ -52,17 +52,20 @@ type WorkloadStatus struct {
 	// Known condition types are: "Available", "Progressing"
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// The number of instances created by a placement
+	// The number of deployments that currently exist
+	Deployments int32 `json:"deployments"`
+
+	// The number of instances that currently exist
 	Replicas int32 `json:"replicas"`
 
-	// The number of instances created by a placement and have the latest
-	// workload generation settings applied.
+	// The number of instances which have the latest workload settings applied.
 	CurrentReplicas int32 `json:"currentReplicas"`
 
-	// The desired number of instances to be managed by a placement.
+	// The desired number of instances
 	DesiredReplicas int32 `json:"desiredReplicas"`
 
-	// TODO(jreese) ReadyReplicas?
+	// The number of instances which are ready.
+	ReadyReplicas int32 `json:"readyReplicas"`
 
 	// The current status of placemetns in a workload.
 	Placements []WorkloadPlacementStatus `json:"placements,omitempty"`
@@ -91,6 +94,11 @@ type WorkloadGatewayStatus struct {
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 // +kubebuilder:printcolumn:name="Available",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].status`
 // +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].reason`
+// +kubebuilder:printcolumn:name="Deployments",type=string,JSONPath=`.status.deployments`
+// +kubebuilder:printcolumn:name="Replicas",type=string,JSONPath=`.status.replicas`
+// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.readyReplicas`
+// +kubebuilder:printcolumn:name="Desired",type=string,JSONPath=`.status.desiredReplicas`
+// +kubebuilder:printcolumn:name="Up-to-date",type=string,JSONPath=`.status.currentReplicas`
 type Workload struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -134,17 +142,17 @@ type WorkloadPlacementStatus struct {
 	// Known condition types are: "Available", "Progressing"
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// The number of instances created by a placement
+	// The number of instances that currently exist
 	Replicas int32 `json:"replicas"`
 
-	// The number of instances created by a placement and have the latest
-	// workload generation settings applied.
+	// The number of instances which have the latest workload settings applied.
 	CurrentReplicas int32 `json:"currentReplicas"`
 
-	// The desired number of instances to be managed by a placement.
+	// The desired number of instances
 	DesiredReplicas int32 `json:"desiredReplicas"`
 
-	// TODO(jreese) ReadyReplicas?
+	// The number of instances which are ready.
+	ReadyReplicas int32 `json:"readyReplicas"`
 }
 
 type HorizontalScaleSettings struct {
@@ -165,8 +173,25 @@ type HorizontalScaleSettings struct {
 
 	// TODO(jreese) wire in behavior
 	// See https://github.com/kubernetes/kubernetes/blob/dd87bc064631354885193fc1a97d0e7b603e77b4/staging/src/k8s.io/api/autoscaling/v2/types.go#L84
+	// Defines the policy for managing instances.
+
+	// TODO(jreese) Add instance update policy? RollingUpdate vs OrderedReady
+
+	// Controls how instances are managed during scale up and down, as well as
+	// during maintenance events.
+	//
+	// +kubebuilder:validation:Required
+	// +kubebuilder:default=OrderedReady
+	InstanceManagementPolicy InstanceManagementPolicyType `json:"instanceManagementPolicy,omitempty"`
 }
 
+type InstanceManagementPolicyType string
+
+const (
+	OrderedReadyInstanceManagementPolicyType InstanceManagementPolicyType = "OrderedReady"
+	// ParallelInstanceManagementPolicyType     InstanceManagementPolicyType = "Parallel"
+)
+
 type MetricSpec struct {
 	// Resource metrics known to Datum.
 	//

api/v1alpha/workloaddeployment_types.go

@@ -46,17 +46,17 @@ type WorkloadDeploymentStatus struct {
 	// Known condition types are: "Available", "Progressing"
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// The number of instances created by a deployment
+	// The number of instances created
 	Replicas int32 `json:"replicas"`
 
-	// The number of instances created by a deployment and have the latest
-	// deployment generation settings applied.
+	// The number of instances which have the latest workload settings applied.
 	CurrentReplicas int32 `json:"currentReplicas"`
 
-	// The desired number of instances to be managed by a deployment.
+	// The desired number of instances
 	DesiredReplicas int32 `json:"desiredReplicas"`
 
-	// TODO(jreese) ReadyReplicas?
+	// The number of instances which are ready.
+	ReadyReplicas int32 `json:"readyReplicas"`
 }
 
 const (
@@ -70,10 +70,14 @@ const (
 
 // WorkloadDeployment is the Schema for the workloaddeployments API
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
-// +kubebuilder:printcolumn:name="Location Namespce",type=string,JSONPath=`.status.location.namespace`
-// +kubebuilder:printcolumn:name="Location Name",type=string,JSONPath=`.status.location.name`
 // +kubebuilder:printcolumn:name="Available",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].status`
 // +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].reason`
+// +kubebuilder:printcolumn:name="Replicas",type=string,JSONPath=`.status.replicas`
+// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.readyReplicas`
+// +kubebuilder:printcolumn:name="Desired",type=string,JSONPath=`.status.desiredReplicas`
+// +kubebuilder:printcolumn:name="Up-to-date",type=string,JSONPath=`.status.currentReplicas`
+// +kubebuilder:printcolumn:name="Location Namespace",type=string,JSONPath=`.status.location.namespace`,priority=1
+// +kubebuilder:printcolumn:name="Location Name",type=string,JSONPath=`.status.location.name`,priority=1
 type WorkloadDeployment struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

cmd/main.go

@@ -180,6 +180,11 @@ func main() {
 
 	// +kubebuilder:scaffold:builder
 
+	if err = controller.AddIndexers(ctx, mgr); err != nil {
+		setupLog.Error(err, "unable to add indexers")
+		os.Exit(1)
+	}
+
 	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
 		setupLog.Error(err, "unable to set up health check")
 		os.Exit(1)