-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add guardrails orchestrator controller
- Loading branch information
1 parent
db7ae08
commit db093e5
Showing
4 changed files
with
697 additions
and
0 deletions.
There are no files selected for viewing
163 changes: 163 additions & 0 deletions
163
api/orchestrator/v1alpha1/guardrailsorchestrator_types.go
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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{}) | ||
} |
105 changes: 105 additions & 0 deletions
105
config/crd/bases/trustyai.opendatahub.io_guadrailsorchestrator.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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: {} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.