Add guardrails orchestrator controller

api/orchestrator/v1alpha1/guardrailsorchestrator_types.go

@@ -0,0 +1,163 @@
+/*
+Copyright 2024.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
+// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
+
+// Represent an orchestrator's status
+// +kubebuilder:validation:Enum=New;Scheduled;Running;Complete;Cancelled
+type OrchestratorState string
+
+const (
+	// The orchestrator is just created
+	NewOrchestratorState OrchestratorState = "New"
+	// The orchestrator is scheduled and waiting for available resources to run it
+	ScheduledOrchestratorState OrchestratorState = "Scheduled"
+	// The orchestrator is running
+	RunningOrchestratorState OrchestratorState = "Running"
+	// The Orchestrator is complete
+	CompleteOrchestratorState OrchestratorState = "Complete"
+	// The Orchestrator is cancelled
+	CancelledOrchestratorState OrchestratorState = "Cancelled"
+)
+
+// +kubebuilder:validation:Enum=NoReason;Succeeded;Failed;Cancelled
+type Reason string
+
+const (
+	// Orchestrator is still running and no final result yet
+	NoReason Reason = "NoReason"
+	// Orchestrator finished successfully
+	SucceedReason Reason = "Succeeded"
+	// Orchestrator failed
+	FailedReason Reason = "Failed"
+	// Orchestrator is cancelled
+	CancelledReason Reason = "Cancelled"
+)
+
+type Arg struct {
+	Name  string `json:"name"`
+	Value string `json:"value,omitempty"`
+}
+
+type EnvSecret struct {
+	// Environment's name
+	Env string `json:"env"`
+	// The secret is from a secret object
+	// +optional
+	SecretRef *corev1.SecretKeySelector `json:"secretRef,omitempty"`
+	// The secret is from a plain text
+	// +optional
+	Secret *string `json:"secret,omitempty"`
+}
+
+type FileSecret struct {
+	// The secret object
+	SecretRef corev1.SecretVolumeSource `json:"secretRef,omitempty"`
+	// The path to mount the secret
+	MountPath string `json:"mountPath"`
+}
+
+// GuardrailsOrchestratorSpec defines the desired state of GuardrailsOrchestrator
+type GuardrailsOrchestratorSpec struct {
+	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// Chunker name
+	Chunker string `json:"chunker"`
+	// Args for the chunker
+	// + optional
+	ChunkerArgs []Arg `json:"chunkerArgs,omitempty"`
+	// Detector name
+	Detector string `json:"detector"`
+	// Args for the detector
+	// +optional
+	DetectorArgs []Arg `json:"detectorArgs,omitempty"`
+	// Evaluation tasks
+	Tasks []string `json:"tasks"`
+	Limit string   `json:"limit,omitempty"`
+	// Map to `--gen_kwargs` parameter for the underlying library.
+	// +optional
+	GenArgs []Arg `json:"genArgs,omitempty"`
+	// If this flag is passed, then the model's outputs, and the text fed into the
+	// model, will be saved at per-document granularity
+	// +optional
+	LogSamples *bool `json:"logSamples,omitempty"`
+	// Assign secrets to the environment variables
+	// +optional
+	EnvSecrets []EnvSecret `json:"envSecrets,omitempty"`
+	// Use secrets as files
+	FileSecrets []FileSecret `json:"fileSecrets,omitempty"`
+}
+
+// GuardrailsOrchestratobStatus defines the observed state of GuardrailsOrchestrator
+type GuardrailsOrchestratorStatus struct {
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// The name of the Pod that runs the evaluation Orchestrator
+	// +optional
+	PodName string `json:"podName,omitempty"`
+	// State of the Orchestrator
+	// +optional
+	State OrchestratorState `json:"state,omitempty"`
+	// Final result of the Orchestrator
+	// +optional
+	Reason Reason `json:"reason,omitempty"`
+	// Message about the current/final status
+	// +optional
+	Message string `json:"message,omitempty"`
+	// Information when was the last time the Orchestrator was successfully scheduled.
+	// +optional
+	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
+	// Information when the Orchestrator's state changes to Complete.
+	// +optional
+	CompleteTime *metav1.Time `json:"completeTime,omitempty"`
+	// Evaluation results
+	// +optional
+	Results string `json:"results,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+
+// GuardrailsOrchestrator is the Schema for the GuardrailsOrchestrator API
+type GuardrailsOrchestrator struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   GuardrailsOrchestratorSpec   `json:"spec,omitempty"`
+	Status GuardrailsOrchestratorStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// GuardrailsOrchestratorJobList contains a list of GuardrailsOrchestrator
+type GuardrailsOrchestratorJobList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []GuardrailsOrchestrator `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&GuardrailsOrchestrator{}, &GuardrailsOrchestratorJobList{})
+}

config/crd/bases/trustyai.opendatahub.io_guadrailsorchestrator.yaml

@@ -0,0 +1,105 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.11.1
+  creationTimestamp: null
+  name: guardrailjobs.trustyai.opendatahub.io
+spec:
+  group: trustyai.opendatahub.io
+  names:
+    kind: GuardrailJob
+    listkind: GuardrailJobList
+    plural: guardrailsjobs
+    singular: guardrailsjob
+  scope: Namespaced
+  versions:
+  - name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: GuardrailsJob is the Schema for the guardrailjobs API
+        properties:
+          apiVersion:
+            description: 'APIVersion defines the versioned schema of this representation
+              of an object. Servers should convert recognized schemas to the latest
+              internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
+            type: string
+          kind:
+            description: 'Kind is a string value representing the REST resource this
+              object represents. Servers may infer this from the endpoint the client
+              submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: 'GuardrailsJobSpec defines the desired state of GuardrailsJob'
+            properties:
+              textInput:
+                description: Text input
+                type: string
+              chunker:
+                description: Chunker name
+                type: string
+                # items:
+                #   properties:
+                #     modelID:
+                #       description: The chunker model id
+                #
+              detector:
+                description: Detector name
+                type: string
+              model:
+                description: Model name
+                type: string
+            required:
+            - textInput
+            # - orchestrator
+            - chunker
+            - detector
+            - model
+          status:
+            description: GuardrailsJobStatus defines the observed state of GuardrailsJob
+            properties:
+              completeTime:
+                description: Information when the job's state changes to Complete.
+                format: date-time
+                type: string
+              lastScheduleTime:
+                description: Information when was the last time the job was successfully
+                  scheduled.
+                format: date-time
+                type: string
+              message:
+                description: Message about the current/final status
+                type: string
+              podName:
+                description: The name of the Pod that runs the evaluation job
+                type: string
+              reason:
+                description: Final result of the job
+                enum:
+                - NoReason
+                - Succeeded
+                - Failed
+                - Cancelled
+                type:
+                  string
+              results:
+                description: Evaluation results
+                type: string
+              state:
+                description: State of the job
+                enum:
+                - New
+                - Scheduled
+                - Running
+                - Complete
+                - Cancelled
+                type: string
+            type: object
+          type: object
+      served: true
+      storage: true
+      subresources:
+        status: {}

controllers/guardrails/README.md

@@ -0,0 +1,56 @@
+# The Backend of Guardrails Orchestrator
+
+* CustomResourceDefinition: The CRD defines the components of GuardrailsOrchestator which are the generator, chunker, and detector
+    * Kind: `GuardrailsOrchestratorService`
+    * Version: `v1alpha1`
+* Controller: The controller reconciles the `GuadrailsOrchestratorSevice` custom resources, creates corresponding Pods, stores results, and cancels services.
+
+## High Level Architecture
+
+
+## State Transition of a GuardrailsOrchestrator
+
+## Design
+
+### Custom Resource Definition (CRD)
+The data structure for a GuardrailsOrchestrator contains the following fields:
+
+| GuardrailsOrchestrator | Data Type | Optional | Parameter in GuardrailsOrchestrator | Description
+| --- | --- | --- | --- | -- |
+| Generator | string | | --generator | Generator name or ID|
+| Detector | string |  | --detector | Detector name or ID |
+| DetectorArgs | []string |  | --detector_args | Configurations for the selected detector. The data is converted to a string in this format and passed to the GuardrailsOrchestrator: `arg1=val1,arg2=val2` |
+| Chunker | string | ✅ | --chunker | Chunker name or ID |
+| ChunkerArgs | []string | ✅ | --chunker_args | Configurations for the selected chunker. The data is converted to a string in this format and passed to the GuardrailsOrchestrator: `arg1=val1,arg2=val2` |
+
+The `Status` subresource of the `GuardrailsOrchestrator` CRB contains the following information:
+
+* `PodName`: the name of the Pod that runs the guardrails-orchestrator service
+* `State`: records the status of the  guardrails-orchestrator service. Possible values are:
+    * `New`: the service is created but not yet processed by the controller
+    * `Scheduled`: a Pod is created by the controller for the service
+    * `Running`: the Pod for the service is running
+    * `Complete`: the service request finishes or fails
+    * `Cancelled`: the controller canceled the service and will mark it as complete
+* `Reason`: details about the current state.
+    * `NoReason`: there is no information about the current state
+    * `Succeeded`: the service finished successfully
+    * `Failed`: the service failed
+    * `Cancelled`: the service is cancelled
+* `Message`: additional details about the final state
+* `LastScheduleTime`: timestamp of when the Pod is scheduled
+* `CompleteTime`: timestamp of when the service's state is `Complete`
+* `Results`: stores the results of the guardrails-orchestrator service results
+
+## The Controller
+The controller is responsible for monitoring the `GuardrailsOrchestratorService` CRs and reconciling the corresponding Pods. Here are the details of how the controller handles an `GuardrailsOrchestratorService` CR:
+* ConfigMap: provides the controller with instructions on how to configure the `GuardrailsOrchestrator` CR:
+    * pod-image
+    * pod-checking-interval
+    * image-pull-policy
+
+* Arguments: the controller supports the following command line arguments:
+    * --namespace: the namespace where you deploy the controller. By default, the namespace of the controller deployment is used
+    * --configmap: the name of the ConfigMap where the config settings are stored
+
+* Finalizer