add comment for interface in reconciler.v1

pkg/reconciler.v1/common/interface.go

@@ -29,32 +29,71 @@ import (
 	commonv1 "github.com/kubeflow/common/pkg/apis/common/v1"
 )
 
+// ReconcilerUtilInterface defines the abstract interface of reconciler on utility features, such like get event
+// recorder or logger
 type ReconcilerUtilInterface interface {
+	// GetRecorder CAN be overridden to customize EventRecorder
 	GetRecorder() record.EventRecorder
+
+	// GetLogger CAN be overridden to customize logger
 	GetLogger() logr.Logger
+
+	// GetScheme CAN be overridden to customize runtime scheme
 	GetScheme() *runtime.Scheme
 }
 
+// GangSchedulingInterface defines the abstract interface for gang-scheduling related actions, such like get, create or
+// delete PodGroup
 type GangSchedulingInterface interface {
 	ReconcilerUtilInterface
 
+	// GetGangSchedulerName CAN be overridden to customize the name of gang scheduler. This name will be used to check
+	// the value of podTemplateSpec.Spec.SchedulerName. For volcano, it is "volcano".
 	GetGangSchedulerName() string
+
+	// GetPodGroupName CAN be overridden to customize the name of PodGroup generated for the job. For example:
+	// podGroupName := fmt.Sprintf("%s-podgroup", job.GetName()) or podGroupName := job.GetName()
 	GetPodGroupName(job client.Object) string
+
+	// GetPodGroupForJob SHOULD be overridden if Group, APIVersion or Kind changes for PodGroup. The PodGroup is
+	// defined in different gang-scheduler as:
+	// Kube-Batch:          "scheduling.incubator.k8s.io/v1alpha1/PodGroup", "scheduling.sigs.dev/v1alpha2/PodGroup"
+	// Volcano:             "scheduling.volcano.sh/v1beta1/PodGroup"
+	// Scheduler-Framework: "scheduling.sigs.k8s.io/v1alpha1/PodGroup"
 	GetPodGroupForJob(ctx context.Context, job client.Object) (client.Object, error)
+
+	// DeletePodGroup SHOULD be overridden if Group, APIVersion and Kind changes for PodGroup.
 	DeletePodGroup(ctx context.Context, job client.Object) error
+
+	// ReconcilePodGroup CAN be overridden if the logic to reconcile PodGroup changes.
 	ReconcilePodGroup(ctx context.Context, job client.Object, runPolicy *commonv1.RunPolicy,
 		replicas map[commonv1.ReplicaType]*commonv1.ReplicaSpec) error
+
+	// DecoratePodForGangScheduling SHOULD be overridden if gang scheduler demands Pods associated with PodGroup to be
+	// decorated with specific requests.
 	DecoratePodForGangScheduling(rtype commonv1.ReplicaType, podTemplate *corev1.PodTemplateSpec, job client.Object)
 }
 
+// PodInterface defines the abstract interface for Pod related actions, such like get, create or delete Pod
 type PodInterface interface {
 	ReconcilerUtilInterface
 
+	// GenPodName CAN be overridden to customize Pod name.
 	GenPodName(jobName string, rtype commonv1.ReplicaType, index string) string
+
+	// GetDefaultContainerName CAN be overridden if the default container name is not "kubeflow".
 	GetDefaultContainerName() string
+
+	// GetPodsForJob list all pods with the job.
 	GetPodsForJob(ctx context.Context, job client.Object) ([]*corev1.Pod, error)
+
+	// FilterPodsForReplicaType filters out pods for specific replica type from all pods associated with the job.
 	FilterPodsForReplicaType(pods []*corev1.Pod, replicaType commonv1.ReplicaType) ([]*corev1.Pod, error)
+
+	// GetPodSlices generates pod slices.
 	GetPodSlices(pods []*corev1.Pod, replicas int, logger *logrus.Entry) [][]*corev1.Pod
+
+	// ReconcilePods CAN be overridden if the logic to reconcile all Pods for the job changes.
 	ReconcilePods(
 		ctx context.Context,
 		job client.Object,
@@ -63,39 +102,64 @@ type PodInterface interface {
 		rtype commonv1.ReplicaType,
 		spec *commonv1.ReplicaSpec,
 		replicas map[commonv1.ReplicaType]*commonv1.ReplicaSpec) error
+
+	// CreateNewPod CAN be overridden to customize how to create a new pod.
 	CreateNewPod(job client.Object, rt commonv1.ReplicaType, index string,
 		spec *commonv1.ReplicaSpec, masterRole bool, replicas map[commonv1.ReplicaType]*commonv1.ReplicaSpec) error
+
+	// DeletePod CAN be overridden to customize how to delete a pod of {name} in namespace {ns}.
 	DeletePod(ctx context.Context, ns string, name string) error
+
+	// DecoratePod CAN be overridden if customization to the pod is needed. The default implementation applies nothing
+	// to the pod.
 	DecoratePod(rtype commonv1.ReplicaType, podTemplate *corev1.PodTemplateSpec, job client.Object)
 }
 
+// ServiceInterface defines the abstract interface for Pod related actions, such like get, create or delete Service
 type ServiceInterface interface {
 	ReconcilerUtilInterface
 
+	// GetPortsFromJob CAN be overridden to customize how to find ports defined in the ReplicasSpec.
 	GetPortsFromJob(spec *commonv1.ReplicaSpec) (map[string]int32, error)
+
+	// GetServicesForJob CAN be overridden to customize how to find all services associated with this job.
 	GetServicesForJob(ctx context.Context, job client.Object) ([]*corev1.Service, error)
+
+	// FilterServicesForReplicaType CAN be overridden to customize how to filter out services for this Replica Type.
 	FilterServicesForReplicaType(services []*corev1.Service,
 		replicaType commonv1.ReplicaType) ([]*corev1.Service, error)
+
+	// GetServiceSlices CAN be overridden to customize how to generate service slices.
 	GetServiceSlices(services []*corev1.Service, replicas int, logger *logrus.Entry) [][]*corev1.Service
+
+	// ReconcileServices CAN be overridden to customize how to reconcile services for this job.
 	ReconcileServices(
 		job client.Object,
 		services []*corev1.Service,
 		rtype commonv1.ReplicaType,
 		spec *commonv1.ReplicaSpec) error
+
+	// CreateNewService CAN be overridden to customize how to create a new service.
 	CreateNewService(job metav1.Object, rtype commonv1.ReplicaType,
 		spec *commonv1.ReplicaSpec, index string) error
+
+	// DeleteService CAN be overridden to customize how to delete the service of {name} in namespace {ns}.
 	DeleteService(ns string, name string, job client.Object) error
+
+	// DecorateService CAN be overridden to customize this service right before being created
 	DecorateService(rtype commonv1.ReplicaType, podTemplate *corev1.PodTemplateSpec, job client.Object)
 }
 
+// JobInterface defines the abstract interface for Pod related actions, such like get, create or delete TFJob,
+// PyTorchJob or KFJob
 type JobInterface interface {
 	ReconcilerUtilInterface
 
 	PodInterface
 	ServiceInterface
 	GangSchedulingInterface
 
-	GetReconcilerName() string
+	// GetGroupNameLabelValue CAN be overridden to customize value used in labels regarding Group of job processed.
 	GetGroupNameLabelValue() string
 
 	// GetJob MUST be overridden to get jobs with specified kind
@@ -114,30 +178,56 @@ type JobInterface interface {
 	// MasterRole pod will have "job-role=master" set in its label
 	IsMasterRole(replicas map[commonv1.ReplicaType]*commonv1.ReplicaSpec, rtype commonv1.ReplicaType, index int) bool
 
+	// ReconcileJob CAN be overridden to customize how to reconcile a job.
 	ReconcileJob(
 		ctx context.Context,
 		job client.Object,
 		replicas map[commonv1.ReplicaType]*commonv1.ReplicaSpec,
 		status *commonv1.JobStatus,
 		runPolicy *commonv1.RunPolicy) error
+
+	// DeleteJob CAN be overridden to customize how to delete a job.
 	DeleteJob(job client.Object) error
+
+	// UpdateJobStatus CAN be overridden to customize how to update job status without submitting to APIServer.
 	UpdateJobStatus(
 		job client.Object,
 		replicas map[commonv1.ReplicaType]*commonv1.ReplicaSpec,
 		jobStatus *commonv1.JobStatus) error
+
+	// UpdateJobStatusInAPIServer CAN be overridden to customize how to update job status directly to APIServer.
 	UpdateJobStatusInAPIServer(ctx context.Context, job client.Object) error
+
+	// CleanupResources CAN be overridden to customize how to delete all resources associated with this job.
 	CleanupResources(runPolicy *commonv1.RunPolicy, status commonv1.JobStatus, job client.Object) error
+
+	// CleanupJob CAN be overridden to customize how to clean up this job.
 	CleanupJob(runPolicy *commonv1.RunPolicy, status commonv1.JobStatus, job client.Object) error
 
+	// RecordAbnormalPods CAN be overridden to customize how to record abnormal pods
 	RecordAbnormalPods(activePods []*corev1.Pod, object client.Object)
+
+	// SetStatusForSuccessJob CAN be overridden to customize how to set status for success job
 	SetStatusForSuccessJob(status *commonv1.JobStatus)
 
+	// IsFlagReplicaTypeForJobStatus CAN be overridden to customize how to determine if this ReplicaType is the
+	// flag ReplicaType for the status of this kind of job
 	IsFlagReplicaTypeForJobStatus(rtype commonv1.ReplicaType) bool
+
+	// IsJobSucceeded CAN be overridden to customize how to determine if this job is succeeded.
 	IsJobSucceeded(status commonv1.JobStatus) bool
+
+	// IsJobFailed CAN be overridden to customize how to determine if this job is failed.
 	IsJobFailed(status commonv1.JobStatus) bool
+
+	// ShouldCleanUp CAN be overridden to customize how to determine if this job should be cleaned up.
 	ShouldCleanUp(status commonv1.JobStatus) bool
+
+	// PastBackoffLimit CAN be overridden to customize how to determine if this job has past backoff limit.
 	PastBackoffLimit(jobName string, runPolicy *commonv1.RunPolicy,
 		replicas map[commonv1.ReplicaType]*commonv1.ReplicaSpec, pods []*corev1.Pod) (bool, error)
+
+	// PastActiveDeadline CAN be overridden to customize how to determine if this job has past activate deadline.
 	PastActiveDeadline(runPolicy *commonv1.RunPolicy, jobStatus *commonv1.JobStatus) bool
 }
 
@@ -146,6 +236,13 @@ type KubeflowReconcilerInterface interface {
 
 	JobInterface
 
+	// GetReconcilerName SHOULD be overridden if a new Reconciler is defined. The default implementation returns
+	// "Kubeflow Reconciler"
+	GetReconcilerName() string
+
+	// Reconcile CAN be overridden to customize how to handle a request.
 	Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
+
+	// SetupWithManager CAN be overridden to customize how to set up the reconciler with the manager.
 	SetupWithManager(mgr ctrl.Manager, obj client.Object) error
 }