shared

package
v0.2.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 17, 2025 License: MIT Imports: 38 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// DefaultRuntimeConfigName is the name of the default AIM runtime config
	DefaultRuntimeConfigName = "default"

	// AimLabelDomain is the base domain used for AIM-specific labels.
	AimLabelDomain = "aim.silogen.ai"

	// AIM label keys.
	LabelKeyTemplate        = AimLabelDomain + "/template"
	LabelKeyModelID         = AimLabelDomain + "/model-id"
	LabelKeyDerivedTemplate = AimLabelDomain + "/derived-template"
	LabelKeyImageName       = AimLabelDomain + "/aim-image"
	LabelKeyMetric          = AimLabelDomain + "/template.metric"
	LabelKeyPrecision       = AimLabelDomain + "/template.precision"

	// AIM label values.
	LabelValueRuntimeName        = "aim-runtime"
	LabelValueRuntimeComponent   = "serving-runtime"
	LabelValueManagedBy          = "aim-controller"
	LabelValueDiscoveryName      = "aim-discovery"
	LabelValueDiscoveryComponent = "discovery-job"
	LabelValueServiceName        = "aim-service"
	LabelValueServiceComponent   = "inference-service"
	LabelValueDerivedTemplate    = "true"
)
View Source 
const (

	// DiscoveryJobBackoffLimit is the number of retries before marking the discovery job as failed
	DiscoveryJobBackoffLimit = 3

	// DiscoveryJobTTLSeconds defines how long completed discovery jobs persist
	// before automatic cleanup. This allows time for status inspection and log retrieval.
	DiscoveryJobTTLSeconds = 60
)
View Source 
const (

	// DefaultSharedMemorySize is the default size allocated for /dev/shm in inference containers.
	// This is required for efficient inter-process communication in model serving workloads.
	DefaultSharedMemorySize = "8Gi"

	// KubernetesLabelValueMaxLength is the maximum length for a Kubernetes label value
	KubernetesLabelValueMaxLength = 63
)
View Source 
const (
	// MaxRoutePathLength is the maximum allowed length for a route path.
	// This prevents excessively long paths that could cause issues with gateways or proxies.
	MaxRoutePathLength = 200
)

Variables

View Source 
var ErrImageNotFound = errors.New("image not found in catalog")

ErrImageNotFound is returned when an image is not found in the catalog

View Source 
var ErrRuntimeConfigNotFound = errors.New("runtime config not found")

ErrRuntimeConfigNotFound indicates that neither namespace nor cluster runtime config could be located.

Functions

func BuildClusterServingRuntime 

func BuildClusterServingRuntime(template aimstate.TemplateState, ownerRef metav1.OwnerReference) *servingv1alpha1.ClusterServingRuntime

BuildClusterServingRuntime creates a KServe ClusterServingRuntime for a cluster-scoped template.

func BuildDerivedTemplate 

func BuildDerivedTemplate(
	service *aimv1alpha1.AIMService,
	templateName string,
	baseSpec *aimv1alpha1.AIMServiceTemplateSpec,
) *aimv1alpha1.AIMServiceTemplate

BuildDerivedTemplate constructs an AIMServiceTemplate for a service with overrides. The template inherits from the base spec and applies service-specific customizations.

func BuildDiscoveryJob 

func BuildDiscoveryJob(spec DiscoveryJobSpec) *batchv1.Job

BuildDiscoveryJob creates a Job that runs model discovery dry-run

func BuildInferenceService 

func BuildInferenceService(serviceState aimstate.ServiceState, ownerRef metav1.OwnerReference) *servingv1beta1.InferenceService

BuildInferenceService constructs a KServe InferenceService referencing a ServingRuntime or ClusterServingRuntime.

func BuildInferenceServiceHTTPRoute 

func BuildInferenceServiceHTTPRoute(serviceState aimstate.ServiceState, ownerRef metav1.OwnerReference) *gatewayapiv1.HTTPRoute

BuildInferenceServiceHTTPRoute creates an HTTPRoute that exposes the predictor service via the provided gateway parent.

func BuildServingRuntime 

func BuildServingRuntime(template aimstate.TemplateState, ownerRef metav1.OwnerReference) *servingv1alpha1.ServingRuntime

BuildServingRuntime creates a KServe ServingRuntime for a namespace-scoped template.

func BuildServingRuntimeFromState 

func BuildServingRuntimeFromState(state aimstate.TemplateState, ownerRef metav1.OwnerReference) *servingv1alpha1.ServingRuntime

BuildServingRuntimeFromState constructs a namespaced ServingRuntime from a TemplateState snapshot. This is an adapter function that maintains compatibility with the original signature.

func BuildTemplateStateFromObservation 

func BuildTemplateStateFromObservation(
	name, namespace string,
	specCommon aimv1alpha1.AIMServiceTemplateSpecCommon,
	observation *TemplateObservation,
	runtimeConfigSpec aimv1alpha1.AIMRuntimeConfigSpec,
	status *aimv1alpha1.AIMServiceTemplateStatus,
) aimstate.TemplateState

BuildTemplateStateFromObservation constructs a TemplateState from the template specification, observation, and status. This is an adapter function that combines template metadata with observed resources.

func DefaultRoutePath 

func DefaultRoutePath(service *aimv1alpha1.AIMService) string

DefaultRoutePath returns the default HTTP route prefix.

func DerivedTemplateName 

func DerivedTemplateName(baseName, suffix string) string

DerivedTemplateName constructs a template name from a base name and suffix. Ensures the final name does not exceed Kubernetes name length limits.

func EvaluateHTTPRouteStatus 

func EvaluateHTTPRouteStatus(route *gatewayapiv1.HTTPRoute) (bool, string, string)

EvaluateHTTPRouteStatus checks the HTTPRoute status and returns readiness state.

func EvaluateInferenceServiceStatus 

func EvaluateInferenceServiceStatus(
	status *aimv1alpha1.AIMServiceStatus,
	obs *ServiceObservation,
	inferenceService *servingv1beta1.InferenceService,
	httpRoute *gatewayapiv1.HTTPRoute,
	routingEnabled bool,
	routingReady bool,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
)

EvaluateInferenceServiceStatus checks InferenceService and routing readiness. Updates status conditions based on the InferenceService and routing state.

func EvaluateRoutingStatus 

func EvaluateRoutingStatus(
	service *aimv1alpha1.AIMService,
	obs *ServiceObservation,
	status *aimv1alpha1.AIMServiceStatus,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
) (enabled bool, ready bool, hasFatalError bool)

EvaluateRoutingStatus checks routing configuration and updates status accordingly. Returns (enabled, ready, hasFatalError) to indicate if routing is enabled, if it's ready, and if there's a terminal error.

func FormatRuntimeConfigSources 

func FormatRuntimeConfigSources(resolution *RuntimeConfigResolution, namespaceLabel string) []string

FormatRuntimeConfigSources renders a human-readable list of runtime config sources for logging/events.

func GetClusterServingRuntime 

func GetClusterServingRuntime(ctx context.Context, k8sClient client.Client, name string) (*servingv1alpha1.ClusterServingRuntime, error)

GetClusterServingRuntime fetches a ClusterServingRuntime by name

func GetDiscoveryJob 

func GetDiscoveryJob(ctx context.Context, k8sClient client.Client, namespace, templateName string) (*batchv1.Job, error)

GetDiscoveryJob fetches the discovery job for a template. Returns the newest job (by CreationTimestamp) if multiple exist.

func GetOperatorNamespace 

func GetOperatorNamespace() string

GetOperatorNamespace returns the namespace where the AIM operator runs. It reads the AIM_OPERATOR_NAMESPACE environment variable; if unset, it defaults to "kaiwo-system".

func GetServingRuntime 

func GetServingRuntime(ctx context.Context, k8sClient client.Client, namespace, name string) (*servingv1alpha1.ServingRuntime, error)

GetServingRuntime fetches a ServingRuntime by namespace and name

func HandleImageMissing 

func HandleImageMissing(
	status *aimv1alpha1.AIMServiceStatus,
	obs *ServiceObservation,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
) bool

HandleImageMissing checks for missing image and updates status. Returns true if the image is missing.

func HandleMissingModelSource 

func HandleMissingModelSource(
	status *aimv1alpha1.AIMServiceStatus,
	obs *ServiceObservation,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
) bool

HandleMissingModelSource checks if the template is available but has no model sources. Returns true if model sources are missing (discovery succeeded but produced no usable sources).

func HandleReconcileErrors 

func HandleReconcileErrors(
	status *aimv1alpha1.AIMServiceStatus,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
	errs controllerutils.ReconcileErrors,
) bool

HandleReconcileErrors processes reconciliation errors and updates service status. Returns true if errors were found and handled.

func HandleRouteTemplateError 

func HandleRouteTemplateError(
	status *aimv1alpha1.AIMServiceStatus,
	service *aimv1alpha1.AIMService,
	obs *ServiceObservation,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
) bool

HandleRouteTemplateError checks for route template errors and updates status. Returns true if there is a route template error.

func HandleRuntimeConfigMissing 

func HandleRuntimeConfigMissing(
	status *aimv1alpha1.AIMServiceStatus,
	obs *ServiceObservation,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
) bool

HandleRuntimeConfigMissing checks for missing runtime config and updates status. Returns true if the runtime config is missing.

func HandleTemplateDegraded 

func HandleTemplateDegraded(
	status *aimv1alpha1.AIMServiceStatus,
	obs *ServiceObservation,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
) bool

HandleTemplateDegraded checks if the template is degraded or failed and updates status. Returns true if the template is degraded or failed.

func HandleTemplateNotAvailable 

func HandleTemplateNotAvailable(
	status *aimv1alpha1.AIMServiceStatus,
	obs *ServiceObservation,
	setCondition func(conditionType string, conditionStatus metav1.ConditionStatus, reason, message string),
) bool

HandleTemplateNotAvailable checks if the template is not available and updates status. Returns true if the template is not yet available (Pending or Progressing). Sets the service to Pending state because it's waiting for a dependency (the template).

func HasOwnerReference 

func HasOwnerReference(refs []metav1.OwnerReference, uid types.UID) bool

HasOwnerReference checks if the given UID exists in the owner references list.

func InferenceServiceRouteName 

func InferenceServiceRouteName(serviceName string) string

InferenceServiceRouteName returns the canonical HTTPRoute name for an InferenceService.

func IsDerivedTemplate 

func IsDerivedTemplate(labels map[string]string) bool

IsDerivedTemplate returns true when the provided labels indicate a controller-managed derived template.

func IsJobComplete 

func IsJobComplete(job *batchv1.Job) bool

IsJobComplete returns true if the job has completed (successfully or failed)

func IsJobFailed 

func IsJobFailed(job *batchv1.Job) bool

IsJobFailed returns true if the job failed

func IsJobSucceeded 

func IsJobSucceeded(job *batchv1.Job) bool

IsJobSucceeded returns true if the job completed successfully

func JoinRuntimeConfigSources 

func JoinRuntimeConfigSources(resolution *RuntimeConfigResolution, namespaceLabel string) string

JoinRuntimeConfigSources joins runtime config sources for concise logging.

func LookupDefaultServiceTemplate 

func LookupDefaultServiceTemplate(ctx context.Context, k8sClient client.Client, service *aimv1alpha1.AIMService) (string, error)

LookupDefaultServiceTemplate searches for a default template name from the service's AIMImage or AIMClusterImage.

func NormalizeRuntimeConfigName 

func NormalizeRuntimeConfigName(name string) string

NormalizeRuntimeConfigName returns the effective name to use for lookups when the user omits the field.

func ObserveDerivedTemplate 

func ObserveDerivedTemplate(
	ctx context.Context,
	k8sClient client.Client,
	service *aimv1alpha1.AIMService,
	resolution TemplateResolution,
	obs *ServiceObservation,
) error

ObserveDerivedTemplate handles observation for services with derived templates. It fetches the derived template if it exists, or loads the base template spec for creation.

func ObserveNonDerivedTemplate 

func ObserveNonDerivedTemplate(
	ctx context.Context,
	k8sClient client.Client,
	service *aimv1alpha1.AIMService,
	templateName string,
	obs *ServiceObservation,
) error

ObserveNonDerivedTemplate handles observation for services with non-derived templates. It searches for namespace-scoped templates first, then falls back to cluster-scoped templates. Does not set ShouldCreateTemplate - that decision is made in the controller based on whether an explicit templateRef was provided.

func OverridesSuffix 

func OverridesSuffix(overrides *aimv1alpha1.AIMServiceOverrides) string

OverridesSuffix computes a hash suffix for service overrides.

func PlanTemplateResources 

func PlanTemplateResources(ctx TemplatePlanContext, builders TemplatePlanBuilders) []client.Object

PlanTemplateResources produces desired objects based on the observation and controller-provided builders.

func PopulateObservationFromClusterTemplate 

func PopulateObservationFromClusterTemplate(
	ctx context.Context,
	k8sClient client.Client,
	service *aimv1alpha1.AIMService,
	template *aimv1alpha1.AIMClusterServiceTemplate,
	obs *ServiceObservation,
) error

PopulateObservationFromClusterTemplate extracts data from a cluster-scoped template into the observation.

func PopulateObservationFromNamespaceTemplate 

func PopulateObservationFromNamespaceTemplate(
	ctx context.Context,
	k8sClient client.Client,
	service *aimv1alpha1.AIMService,
	template *aimv1alpha1.AIMServiceTemplate,
	obs *ServiceObservation,
) error

PopulateObservationFromNamespaceTemplate extracts data from a namespace-scoped template into the observation.

func ProjectServiceStatus 

func ProjectServiceStatus(
	service *aimv1alpha1.AIMService,
	obs *ServiceObservation,
	inferenceService *servingv1beta1.InferenceService,
	httpRoute *gatewayapiv1.HTTPRoute,
	errs controllerutils.ReconcileErrors,
)

ProjectServiceStatus computes and updates the service status based on observations and errors. This is a high-level orchestrator that calls the individual status handler functions.

func ProjectTemplateStatus 

func ProjectTemplateStatus(
	ctx context.Context,
	k8sClient client.Client,
	clientset kubernetes.Interface,
	recorder record.EventRecorder,
	template TemplateWithStatus,
	obs *TemplateObservation,
	errs controllerutils.ReconcileErrors,
	imageNotFoundMessage string,
) error

ProjectTemplateStatus computes status from observation and errors. This is shared between cluster and namespace-scoped template controllers. Modifies templateStatus directly and emits events for discovery phase changes.

func RequestsForServices 

func RequestsForServices(services []aimv1alpha1.AIMService) []reconcile.Request

RequestsForServices converts a list of AIMServices to reconcile requests.

func ResolveServiceRoutePath 

func ResolveServiceRoutePath(service *aimv1alpha1.AIMService, runtimeConfig aimv1alpha1.AIMRuntimeConfigSpec) (string, error)

ResolveServiceRoutePath renders the HTTP route prefix using service and runtime config context.

func RuntimeConfigNameForService 

func RuntimeConfigNameForService(service *aimv1alpha1.AIMService, templateSpec aimv1alpha1.AIMServiceTemplateSpecCommon) string

RuntimeConfigNameForService determines the effective runtime config name for a service.

func TemplateNameFromSpec 

func TemplateNameFromSpec(service *aimv1alpha1.AIMService) string

TemplateNameFromSpec returns the template name from the service spec or status. Falls back to service name if no template reference is found.

Types

type DiscoveryJobSpec 

type DiscoveryJobSpec struct {
	TemplateName     string
	TemplateSpec     aimv1alpha1.AIMServiceTemplateSpecCommon
	Namespace        string
	ModelID          string
	Image            string
	Env              []corev1.EnvVar
	ImagePullSecrets []corev1.LocalObjectReference
	ServiceAccount   string
	OwnerRef         metav1.OwnerReference
}

DiscoveryJobSpec defines parameters for creating a discovery job

type ImageLookupResult 

type ImageLookupResult struct {
	Image     string
	Resources corev1.ResourceRequirements
}

ImageLookupResult captures the resolved image metadata from the catalog.

func LookupImageForClusterTemplate 

func LookupImageForClusterTemplate(ctx context.Context, k8sClient client.Client, modelName string) (*ImageLookupResult, error)

LookupImageForClusterTemplate looks up the container image for a cluster-scoped template. It searches only in AIMClusterImage resources. Returns ErrImageNotFound if no image is found in the catalog.

func LookupImageForNamespaceTemplate 

func LookupImageForNamespaceTemplate(ctx context.Context, k8sClient client.Client, namespace, modelName string) (*ImageLookupResult, error)

LookupImageForNamespaceTemplate looks up the container image for a namespace-scoped template. It searches AIMImage resources in the specified namespace first, then falls back to cluster-scoped AIMClusterImage resources. Returns ErrImageNotFound if no image is found in either location.

func (*ImageLookupResult) DeepCopy 

func (r *ImageLookupResult) DeepCopy() *ImageLookupResult

DeepCopy returns a deep copy of the ImageLookupResult.

type ParsedDiscovery 

type ParsedDiscovery struct {
	ModelSources []aimv1alpha1.AIMModelSource
	Profile      *aimv1alpha1.AIMProfile
}

ParsedDiscovery holds the parsed discovery result

func ParseDiscoveryLogs 

func ParseDiscoveryLogs(ctx context.Context, k8sClient client.Client, clientset kubernetes.Interface, job *batchv1.Job) (*ParsedDiscovery, error)

ParseDiscoveryLogs parses the discovery job output to extract model sources and profile. Reads pod logs from the completed job and parses the JSON output.

type RuntimeConfigResolution 

type RuntimeConfigResolution struct {
	// Name is the runtime config name requested by the consumer.
	Name string

	// Namespace is the consumer namespace used when searching for AIMRuntimeConfig.
	Namespace string

	ClusterConfig           *aimv1alpha1.AIMClusterRuntimeConfig
	NamespaceConfig         *aimv1alpha1.AIMRuntimeConfig
	ClusterConfigNotFound   bool
	NamespaceConfigNotFound bool

	EffectiveSpec aimv1alpha1.AIMRuntimeConfigSpec
	ResolvedRef   *aimv1alpha1.AIMResolvedRuntimeConfig
}

RuntimeConfigResolution captures the resolved runtime configuration. Namespace config completely overrides cluster config when present (no merging).

func ResolveRuntimeConfig 

func ResolveRuntimeConfig(ctx context.Context, k8sClient client.Client, namespace, configName string) (*RuntimeConfigResolution, error)

ResolveRuntimeConfig resolves runtime config using complete override semantics. Namespace config completely replaces cluster config when present - no field-level merging. When configName is empty, the default runtime config name is used.

type RuntimeObservation 

type RuntimeObservation[R client.Object] struct {
	Runtime R
	TemplateObservation
}

RuntimeObservation combines TemplateObservation with a controller-specific runtime object.

func ObserveTemplate 

func ObserveTemplate[R client.Object](ctx context.Context, opts TemplateObservationOptions[R]) (*RuntimeObservation[R], error)

ObserveTemplate gathers runtime, discovery job, image, and runtime config information with common error handling.

type ServiceObservation 

type ServiceObservation struct {
	TemplateName           string
	BaseTemplateName       string
	Scope                  TemplateScope
	TemplateAvailable      bool
	TemplateOwnedByService bool
	ShouldCreateTemplate   bool
	RuntimeConfigSpec      aimv1alpha1.AIMRuntimeConfigSpec
	ResolvedRuntimeConfig  *aimv1alpha1.AIMResolvedRuntimeConfig
	ResolvedImage          *aimv1alpha1.AIMResolvedReference
	RoutePath              string
	RouteTemplateErr       error
	RuntimeConfigErr       error
	ImageErr               error
	TemplateStatus         *aimv1alpha1.AIMServiceTemplateStatus
	TemplateSpecCommon     aimv1alpha1.AIMServiceTemplateSpecCommon
	TemplateSpec           *aimv1alpha1.AIMServiceTemplateSpec
	TemplateNamespace      string
	ImageResources         *corev1.ResourceRequirements
}

ServiceObservation holds observed state for an AIMService reconciliation.

func (*ServiceObservation) RuntimeName 

func (o *ServiceObservation) RuntimeName() string

RuntimeName returns the effective runtime name for the service.

func (*ServiceObservation) TemplateFound 

func (o *ServiceObservation) TemplateFound() bool

TemplateFound returns true if a template was resolved (namespace or cluster scope).

type TemplateObservation 

type TemplateObservation struct {
	Job              *batchv1.Job
	Image            string
	ImageResources   *corev1.ResourceRequirements
	ImagePullSecrets []corev1.LocalObjectReference
	RuntimeConfig    *RuntimeConfigResolution
}

TemplateObservation holds the common observed state for both template types

type TemplateObservationOptions 

type TemplateObservationOptions[R client.Object] struct {
	GetRuntime              func(ctx context.Context) (R, error)
	ShouldCheckDiscoveryJob bool
	GetDiscoveryJob         func(ctx context.Context) (*batchv1.Job, error)
	LookupImage             func(ctx context.Context) (*ImageLookupResult, error)
	ResolveRuntimeConfig    func(ctx context.Context) (*RuntimeConfigResolution, error)
	OnRuntimeConfigResolved func(resolution *RuntimeConfigResolution)
}

TemplateObservationOptions configures ObserveTemplate behaviour.

type TemplatePlanBuilders 

type TemplatePlanBuilders struct {
	BuildRuntime      func(input TemplatePlanInput) client.Object
	BuildDiscoveryJob func(input TemplatePlanInput) client.Object
}

TemplatePlanBuilders specifies how to render runtime and discovery job objects.

type TemplatePlanContext 

type TemplatePlanContext struct {
	Template    metav1.Object
	APIVersion  string
	Kind        string
	Status      aimv1alpha1.AIMTemplateStatusEnum
	Observation *TemplateObservation
}

TemplatePlanContext provides metadata needed during plan generation.

type TemplatePlanInput 

type TemplatePlanInput struct {
	Observation       *TemplateObservation
	RuntimeConfigSpec aimv1alpha1.AIMRuntimeConfigSpec
	OwnerReference    metav1.OwnerReference
}

TemplatePlanInput supplies builders with convenient access to observation data.

type TemplateResolution 

type TemplateResolution struct {
	BaseName  string
	FinalName string
	Derived   bool
}

TemplateResolution captures the result of resolving a template name for a service.

func ResolveTemplateNameForService 

func ResolveTemplateNameForService(ctx context.Context, k8sClient client.Client, service *aimv1alpha1.AIMService) (TemplateResolution, error)

ResolveTemplateNameForService determines the template name to use for a service. It handles default template lookup, base template resolution, and derived template naming. Returns an empty BaseName/FinalName if no template can be resolved, which indicates the service should enter a degraded state.

type TemplateScope 

type TemplateScope string

TemplateScope indicates whether a template is namespace-scoped, cluster-scoped, or unresolved. 

const (
	TemplateScopeNone      TemplateScope = ""
	TemplateScopeNamespace TemplateScope = "namespace"
	TemplateScopeCluster   TemplateScope = "cluster"
)

func LoadBaseTemplateSpec 

func LoadBaseTemplateSpec(ctx context.Context, k8sClient client.Client, service *aimv1alpha1.AIMService, baseName string) (*aimv1alpha1.AIMServiceTemplateSpec, TemplateScope, error)

LoadBaseTemplateSpec fetches the base template spec for a derived template. Searches namespace-scoped templates first, then falls back to cluster-scoped templates.

type TemplateSpec 

type TemplateSpec interface {
	GetModelName() string
}

TemplateSpec provides the common template specification

type TemplateWithStatus 

type TemplateWithStatus interface {
	TemplateSpec
	client.Object
	GetStatus() *aimv1alpha1.AIMServiceTemplateStatus
}

TemplateWithStatus extends TemplateSpec with status access

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.