api: update reservation api (#384)

Signed-off-by: saintube <saintube@foxmail.com>

apis/extension/scheduling.go

@@ -20,12 +20,17 @@ import (
 	"encoding/json"
 
 	corev1 "k8s.io/api/core/v1"
+
+	schedulingv1alpha1 "github.com/koordinator-sh/koordinator/apis/scheduling/v1alpha1"
 )
 
 const (
 	// AnnotationCustomUsageThresholds represents the user-defined resource utilization threshold.
 	// For specific value definitions, see CustomUsageThresholds
 	AnnotationCustomUsageThresholds = SchedulingDomainPrefix + "/usage-thresholds"
+
+	// AnnotationReservationAllocated represents the reservation allocated by the pod.
+	AnnotationReservationAllocated = SchedulingDomainPrefix + "/reservation-allocated"
 )
 
 // CustomUsageThresholds supports user-defined node resource utilization thresholds.
@@ -45,3 +50,36 @@ func GetCustomUsageThresholds(node *corev1.Node) (*CustomUsageThresholds, error)
 	}
 	return usageThresholds, nil
 }
+
+type ReservationAllocated struct {
+	Namespace string `json:"namespace,omitempty"`
+	Name      string `json:"name,omitempty"`
+}
+
+func GetReservationAllocated(pod *corev1.Pod) (*ReservationAllocated, error) {
+	if pod.Annotations == nil {
+		return nil, nil
+	}
+	data, ok := pod.Annotations[AnnotationReservationAllocated]
+	if !ok {
+		return nil, nil
+	}
+	reservationAllocated := &ReservationAllocated{}
+	err := json.Unmarshal([]byte(data), reservationAllocated)
+	if err != nil {
+		return nil, err
+	}
+	return reservationAllocated, nil
+}
+
+func SetReservationAllocated(pod *corev1.Pod, r *schedulingv1alpha1.Reservation) {
+	if pod.Annotations == nil {
+		pod.Annotations = map[string]string{}
+	}
+	reservationAllocated := &ReservationAllocated{
+		Namespace: r.Namespace,
+		Name:      r.Name,
+	}
+	data, _ := json.Marshal(reservationAllocated) // assert no error
+	pod.Annotations[AnnotationReservationAllocated] = string(data)
+}

apis/scheduling/v1alpha1/reservation_types.go

@@ -32,20 +32,27 @@ type ReservationSpec struct {
 	// like a normal pod.
 	// If the `template.spec.nodeName` is specified, the scheduler will not choose another node but reserve resources on
 	// the specified node.
+	// +optional
 	Template *corev1.PodTemplateSpec `json:"template,omitempty"`
 	// Specify the owners who can allocate the reserved resources.
-	// Multiple owner selectors and ANDed.
+	// Multiple owner selectors and ORed.
+	// +optional
 	Owners []ReservationOwner `json:"owners,omitempty"`
 	// By default, the resources requirements of reservation (specified in `template.spec`) is filtered by whether the
 	// node has sufficient free resources (i.e. ReservationRequest <  NodeFree).
 	// When `preAllocation` is set, the scheduler will skip this validation and allow overcommitment. The scheduled
 	// reservation would be waiting to be available until free resources are sufficient.
+	// +optional
 	PreAllocation bool `json:"preAllocation,omitempty"`
 	// Time-to-Live period for the reservation.
-	// `expires` and `ttl` are mutually exclusive. Defaults to 24h.
+	// `expires` and `ttl` are mutually exclusive. Defaults to 24h. Set 0 to disable expiration.
+	// +kubebuilder:default='24h'
+	// +optional
 	TTL *metav1.Duration `json:"ttl,omitempty"`
-	// Expired timestamp when the reservation expires.
+	// Expired timestamp when the reservation is expected to expire.
+	// If both `expires` and `ttl` are set, `expires` is checked first.
 	// `expires` and `ttl` are mutually exclusive. Defaults to being set dynamically at runtime based on the `ttl`.
+	// +optional
 	Expires *metav1.Time `json:"expires,omitempty"`
 }
 
@@ -66,18 +73,36 @@ type ReservationStatus struct {
 
 	// The `phase` indicates whether is reservation is waiting for process (`Pending`), available to allocate
 	// (`Available`) or expired to get cleanup (Expired).
+	// +optional
 	Phase ReservationPhase `json:"phase,omitempty"`
+	// The `expired` indicates the timestamp if the reservation is expired.
+	// +optional
+	Expired *metav1.Time `json:"expired,omitempty"`
 	// The `conditions` indicate the messages of reason why the reservation is still pending.
+	// +optional
 	Conditions []ReservationCondition `json:"conditions,omitempty"`
 	// Current resource owners which allocated the reservation resources.
+	// +optional
 	CurrentOwners []corev1.ObjectReference `json:"currentOwners,omitempty"`
+	// Name of node the reservation is scheduled on.
+	// +optional
+	NodeName string `json:"nodeName,omitempty"`
+	// Resource reserved and allocatable for owners.
+	// +optional
+	Allocatable corev1.ResourceList `json:"allocatable,omitempty"`
+	// Resource allocated by current owners.
+	// +optional
+	Allocated corev1.ResourceList `json:"allocated,omitempty"`
 }
 
 type ReservationOwner struct {
-	// Multiple field selectors are ORed.
-	Object        *corev1.ObjectReference         `json:"object,omitempty"`
-	Controller    *ReservationControllerReference `json:"controller,omitempty"`
-	LabelSelector *metav1.LabelSelector           `json:"labelSelector,omitempty"`
+	// Multiple field selectors are ANDed.
+	// +optional
+	Object *corev1.ObjectReference `json:"object,omitempty"`
+	// +optional
+	Controller *ReservationControllerReference `json:"controller,omitempty"`
+	// +optional
+	LabelSelector *metav1.LabelSelector `json:"labelSelector,omitempty"`
 }
 
 type ReservationControllerReference struct {
@@ -102,6 +127,11 @@ const (
 	ReservationExpired ReservationPhase = "Expired"
 )
 
+const (
+	ReasonReservationAvailable = "Available"
+	ReasonReservationExpired   = "Expired"
+)
+
 type ReservationCondition struct {
 	LastProbeTime      metav1.Time `json:"lastProbeTime"`
 	LastTransitionTime metav1.Time `json:"lastTransitionTime"`
@@ -110,7 +140,6 @@ type ReservationCondition struct {
 }
 
 // +genclient
-// +genclient:nonNamespaced
 // +kubebuilder:resource:scope=Cluster
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
@@ -120,12 +149,11 @@ type ReservationCondition struct {
 // +kubebuilder:printcolumn:name="TTL",type="string",JSONPath=".spec.ttl",priority=10
 // +kubebuilder:printcolumn:name="Expires",type="string",JSONPath=".spec.expires",priority=10
 
-// Reservation is the Schema for the reservation API
+// Reservation is the Schema for the reservation API.
+// A Reservation object is namespaced. But it can reserve resources for pods of any namespace. Any
+// namespaced affinity/anti-affinity of reservation scheduling can be specified with the ObjectMeta.
 type Reservation struct {
-	metav1.TypeMeta `json:",inline"`
-	// A Reservation object is non-namespaced.
-	// It can reserve resources for pods of any namespace. Any affinity/anti-affinity of reservation scheduling can be
-	// specified in the pod template.
+	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
 	Spec   ReservationSpec   `json:"spec,omitempty"`

config/crd/bases/scheduling.koordinator.sh_podmigrationjobs.yaml

@@ -214,14 +214,16 @@ spec:
                           Reservation.
                         properties:
                           expires:
-                            description: Expired timestamp when the reservation expires.
-                              `expires` and `ttl` are mutually exclusive. Defaults
-                              to being set dynamically at runtime based on the `ttl`.
+                            description: Expired timestamp when the reservation is
+                              expected to expire. If both `expires` and `ttl` are
+                              set, `expires` is checked first. `expires` and `ttl`
+                              are mutually exclusive. Defaults to being set dynamically
+                              at runtime based on the `ttl`.
                             format: date-time
                             type: string
                           owners:
                             description: Specify the owners who can allocate the reserved
-                              resources. Multiple owner selectors and ANDed.
+                              resources. Multiple owner selectors and ORed.
                             items:
                               properties:
                                 controller:
@@ -317,7 +319,7 @@ spec:
                                       type: object
                                   type: object
                                 object:
-                                  description: Multiple field selectors are ORed.
+                                  description: Multiple field selectors are ANDed.
                                   properties:
                                     apiVersion:
                                       description: API version of the referent.
@@ -8372,9 +8374,10 @@ spec:
                                 type: object
                             type: object
                           ttl:
+                            default: '''24h'''
                             description: Time-to-Live period for the reservation.
                               `expires` and `ttl` are mutually exclusive. Defaults
-                              to 24h.
+                              to 24h. Set 0 to disable expiration.
                             type: string
                         type: object
                     type: object

config/crd/bases/scheduling.koordinator.sh_reservations.yaml

@@ -38,7 +38,10 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: Reservation is the Schema for the reservation API
+        description: Reservation is the Schema for the reservation API. A Reservation
+          object is namespaced. But it can reserve resources for pods of any namespace.
+          Any namespaced affinity/anti-affinity of reservation scheduling can be specified
+          with the ObjectMeta.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -55,14 +58,15 @@ spec:
           spec:
             properties:
               expires:
-                description: Expired timestamp when the reservation expires. `expires`
-                  and `ttl` are mutually exclusive. Defaults to being set dynamically
-                  at runtime based on the `ttl`.
+                description: Expired timestamp when the reservation is expected to
+                  expire. If both `expires` and `ttl` are set, `expires` is checked
+                  first. `expires` and `ttl` are mutually exclusive. Defaults to being
+                  set dynamically at runtime based on the `ttl`.
                 format: date-time
                 type: string
               owners:
                 description: Specify the owners who can allocate the reserved resources.
-                  Multiple owner selectors and ANDed.
+                  Multiple owner selectors and ORed.
                 items:
                   properties:
                     controller:
@@ -147,7 +151,7 @@ spec:
                           type: object
                       type: object
                     object:
-                      description: Multiple field selectors are ORed.
+                      description: Multiple field selectors are ANDed.
                       properties:
                         apiVersion:
                           description: API version of the referent.
@@ -6994,12 +6998,32 @@ spec:
                     type: object
                 type: object
               ttl:
+                default: '''24h'''
                 description: Time-to-Live period for the reservation. `expires` and
-                  `ttl` are mutually exclusive. Defaults to 24h.
+                  `ttl` are mutually exclusive. Defaults to 24h. Set 0 to disable
+                  expiration.
                 type: string
             type: object
           status:
             properties:
+              allocatable:
+                additionalProperties:
+                  anyOf:
+                  - type: integer
+                  - type: string
+                  pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                  x-kubernetes-int-or-string: true
+                description: Resource reserved and allocatable for owners.
+                type: object
+              allocated:
+                additionalProperties:
+                  anyOf:
+                  - type: integer
+                  - type: string
+                  pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                  x-kubernetes-int-or-string: true
+                description: Resource allocated by current owners.
+                type: object
               conditions:
                 description: The `conditions` indicate the messages of reason why
                   the reservation is still pending.
@@ -7086,6 +7110,14 @@ spec:
                       type: string
                   type: object
                 type: array
+              expired:
+                description: The `expired` indicates the timestamp if the reservation
+                  is expired.
+                format: date-time
+                type: string
+              nodeName:
+                description: Name of node the reservation is scheduled on.
+                type: string
               phase:
                 description: The `phase` indicates whether is reservation is waiting
                   for process (`Pending`), available to allocate (`Available`) or