feat(api): v1alpha2 CRD types with typed provider slices (Phase 1)

[rhuss]

Summary

Phase 1 implementation of the v1alpha2 CRD schema for operator-generated config. This PR adds the complete type definitions with CEL validation rules, ready for team review before proceeding to Phase 2 (config generation engine).

What's included

The api/v1alpha2/ package with:

• ProvidersSpec with typed []ProviderConfig slices (no polymorphic JSON)
• ProviderConfig with explicit secretRefs field (no heuristic secret detection)
• ResourcesSpec with typed []ModelConfig (only name required)
• StateStorageSpec with KV (sqlite/redis) and SQL (sqlite/postgres) backends
• NetworkingSpec with typed ExposeConfig (enabled + hostname fields)
• WorkloadSpec consolidating all deployment settings from v1alpha1
• Status types, condition constants, and event type definitions
• +kubebuilder:storageversion marker (v1alpha2 is the hub)

15 CEL validation rules

All compiled and verified with controller-gen:

• 4 mutual exclusivity (providers/resources/storage/disabled vs overrideConfig)
• 5 provider ID required (per API type, when list has > 1 element)
• 2 distribution (name/image mutual exclusivity + at-least-one)
• TLS secretName required when enabled: true
• Redis endpoint required when type: redis
• Postgres connectionString required when type: postgres

How to test

Apply the CRD and try creating invalid CRs to verify CEL validation:

kubectl apply -f config/crd/bases/llamastack.io_llamastackdistributions.yaml

# Should succeed:
cat <<YAML | kubectl apply -f -
apiVersion: llamastack.io/v1alpha2
kind: LlamaStackDistribution
metadata:
  name: test
spec:
  distribution:
    name: starter
  providers:
    inference:
      - provider: vllm
        endpoint: "http://vllm:8000"
YAML

# Should fail (both name and image):
cat <<YAML | kubectl apply -f -
apiVersion: llamastack.io/v1alpha2
kind: LlamaStackDistribution
metadata:
  name: test-invalid
spec:
  distribution:
    name: starter
    image: "registry/image:tag"
YAML

Review focus

• Does api/v1alpha2/llamastackdistribution_types.go feel right for Kubernetes users?
• Is inference: [{provider: vllm}] (always-list syntax) acceptable?
• Are the CEL error messages clear and actionable?
• Is the secretRefs map[string]SecretKeyRef design intuitive?

Task progress

This project uses beads for task tracking:

bd backup restore       # restore state from git
bd list                 # all tasks with status
bd list --status closed # Phase 1: 13/13 complete
bd list --status open   # Phase 2-12: 78 tasks remaining

Current: Phase 1 complete (13/13). Waiting for review before Phase 2 (config generation engine).

Spec reference

Full spec: specs/002-operator-generated-config/spec.md (merged in #263)
Review guide: specs/002-operator-generated-config/REVIEW.md

Assisted-by: 🤖 Claude Code

[eoinfennessy]

Generally looks good. I added lots and lots of suggestions to strengthen our validations.

Also one question about why we use a pointer to a boolean for ExposeConfig.Enabled

[eoinfennessy]

We can also add validation here to ensure that when a list is provided it must have one or more items. This ensures empty lists cannot be provided explicitly:

Suggested change

	// Inference providers (e.g., vllm, ollama).
	// +optional
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	Inference []ProviderConfig `json:"inference,omitempty"`
	// Safety providers (e.g., llama-guard).
	// +optional
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	Safety []ProviderConfig `json:"safety,omitempty"`
	// VectorIo providers (e.g., pgvector, chromadb).
	// +optional
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	VectorIo []ProviderConfig `json:"vectorIo,omitempty"`
	// ToolRuntime providers (e.g., brave-search, rag-runtime).
	// +optional
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	ToolRuntime []ProviderConfig `json:"toolRuntime,omitempty"`
	// Telemetry providers (e.g., opentelemetry).
	// +optional
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	Telemetry []ProviderConfig `json:"telemetry,omitempty"`
	// Inference providers (e.g., vllm, ollama).
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	Inference []ProviderConfig `json:"inference,omitempty"`
	// Safety providers (e.g., llama-guard).
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	Safety []ProviderConfig `json:"safety,omitempty"`
	// VectorIo providers (e.g., pgvector, chromadb).
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	VectorIo []ProviderConfig `json:"vectorIo,omitempty"`
	// ToolRuntime providers (e.g., brave-search, rag-runtime).
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	ToolRuntime []ProviderConfig `json:"toolRuntime,omitempty"`
	// Telemetry providers (e.g., opentelemetry).
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:XValidation:rule="self.size() <= 1 || self.all(p, has(p.id))",message="each provider must have an explicit id when multiple providers are specified"
	Telemetry []ProviderConfig `json:"telemetry,omitempty"`

[eoinfennessy]

For optional strings, we can add CEL validation to ensure they are not empty if provided:

// +kubebuilder:validation:XValidation:rule="!has(self.id) || self.id != ''",message="id must not be empty if specified"

WDYT?

[eoinfennessy]

Similar validation here to gaurd against empty maps when provided:

Suggested change

	// SecretRefs are named secret references for provider-specific connection fields.
	// Each key becomes the env var field suffix: LLSD_<PROVIDER_ID>_<KEY>.
	// +optional
	SecretRefs map[string]SecretKeyRef `json:"secretRefs,omitempty"`
	// SecretRefs are named secret references for provider-specific connection fields.
	// Each key becomes the env var field suffix: LLSD_<PROVIDER_ID>_<KEY>.
	// +optional
	// +kubebuilder:validation:MinProperties=1
	SecretRefs map[string]SecretKeyRef `json:"secretRefs,omitempty"`

[eoinfennessy]

Similarly to above, MinItems gaurds against explicitly empty lists. Using MinLength also gaurds against empty strings in the Tools and Shields slices.

Suggested change

	// Models to register with inference providers.
	// +optional
	Models []ModelConfig `json:"models,omitempty"`
	// Tools are tool group names to register with the toolRuntime provider.
	// +optional
	Tools []string `json:"tools,omitempty"`
	// Shields are safety shield names to register with the safety provider.
	// +optional
	Shields []string `json:"shields,omitempty"`
	// Models to register with inference providers.
	// +optional
	// +kubebuilder:validation:MinItems=1
	Models []ModelConfig `json:"models,omitempty"`
	// Tools are tool group names to register with the toolRuntime provider.
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	Tools []string `json:"tools,omitempty"`
	// Shields are safety shield names to register with the safety provider.
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	Shields []string `json:"shields,omitempty"`

[eoinfennessy]

Like above, ensure optional strings are not empty if provided.

Suggested change

	// ModelConfig defines a model to register.
	type ModelConfig struct {
	// Name is the model identifier (e.g., llama3.2-8b).
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`
	// Provider is the provider ID to register this model with.
	// Defaults to the first inference provider when omitted.
	// +optional
	Provider string `json:"provider,omitempty"`
	// ContextLength is the model context window size.
	// +optional
	ContextLength *int `json:"contextLength,omitempty"`
	// ModelType is the model type classification.
	// +optional
	ModelType string `json:"modelType,omitempty"`
	// Quantization is the quantization method used.
	// +optional
	Quantization string `json:"quantization,omitempty"`
	}
	// ModelConfig defines a model to register.
	// +kubebuilder:validation:XValidation:rule="!has(self.provider) || self.provider != ''",message="provider must not be empty if specified"
	// +kubebuilder:validation:XValidation:rule="!has(self.modelType) || self.modelType != ''",message="modelType must not be empty if specified"
	// +kubebuilder:validation:XValidation:rule="!has(self.quantization) || self.quantization != ''",message="quantization must not be empty if specified"
	type ModelConfig struct {
	// Name is the model identifier (e.g., llama3.2-8b).
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`
	// Provider is the provider ID to register this model with.
	// Defaults to the first inference provider when omitted.
	// +optional
	Provider string `json:"provider,omitempty"`
	// ContextLength is the model context window size.
	// +optional
	ContextLength *int `json:"contextLength,omitempty"`
	// ModelType is the model type classification.
	// +optional
	ModelType string `json:"modelType,omitempty"`
	// Quantization is the quantization method used.
	// +optional
	Quantization string `json:"quantization,omitempty"`
	}

[eoinfennessy]

Ensure MountPath is not empty when provided

Suggested change

	// PVCStorageSpec configures persistent volume storage.
	type PVCStorageSpec struct {
	// Size is the PVC size (e.g., "10Gi").
	// +optional
	Size *resource.Quantity `json:"size,omitempty"`
	// MountPath is where storage is mounted in the container.
	// +optional
	// +kubebuilder:default:="/.llama"
	MountPath string `json:"mountPath,omitempty"`
	}
	// PVCStorageSpec configures persistent volume storage.
	// +kubebuilder:validation:XValidation:rule="!has(self.mountPath) || self.mountPath != ''",message="mountPath must not be empty if specified"
	type PVCStorageSpec struct {
	// Size is the PVC size (e.g., "10Gi").
	// +optional
	Size *resource.Quantity `json:"size,omitempty"`
	// MountPath is where storage is mounted in the container.
	// +optional
	// +kubebuilder:default:="/.llama"
	MountPath string `json:"mountPath,omitempty"`
	}

[eoinfennessy]

Ensure one and only one field is provided. (mutually exclusive, similar to actual k8s PDBs)

Suggested change

	// PodDisruptionBudgetSpec defines voluntary disruption controls.
	type PodDisruptionBudgetSpec struct {
	// MinAvailable is the minimum number of pods that must remain available.
	// +optional
	MinAvailable *intstr.IntOrString `json:"minAvailable,omitempty"`
	// MaxUnavailable is the maximum number of pods that can be disrupted.
	// +optional
	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`
	}
	// PodDisruptionBudgetSpec defines voluntary disruption controls.
	// +kubebuilder:validation:XValidation:rule="has(self.minAvailable) || has(self.maxUnavailable)",message="at least one of minAvailable or maxUnavailable must be specified"
	// +kubebuilder:validation:XValidation:rule="!(has(self.minAvailable) && has(self.maxUnavailable))",message="minAvailable and maxUnavailable are mutually exclusive"
	type PodDisruptionBudgetSpec struct {
	// MinAvailable is the minimum number of pods that must remain available.
	// +optional
	MinAvailable *intstr.IntOrString `json:"minAvailable,omitempty"`
	// MaxUnavailable is the maximum number of pods that can be disrupted.
	// +optional
	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable,omitempty"`
	}

[eoinfennessy]

Ensure all fields are non-empty if provided. Ensure no empty strings in lists.

Suggested change

	// WorkloadOverrides provides low-level Pod customization.
	type WorkloadOverrides struct {
	// ServiceAccountName overrides the ServiceAccount.
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`
	// Env adds environment variables to the container.
	// +optional
	Env []corev1.EnvVar `json:"env,omitempty"`
	// Command overrides the container entrypoint.
	// +optional
	Command []string `json:"command,omitempty"`
	// Args overrides the container arguments.
	// +optional
	Args []string `json:"args,omitempty"`
	// Volumes adds volumes to the Pod.
	// +optional
	Volumes []corev1.Volume `json:"volumes,omitempty"`
	// VolumeMounts adds volume mounts to the container.
	// +optional
	VolumeMounts []corev1.VolumeMount `json:"volumeMounts,omitempty"`
	}
	// WorkloadOverrides provides low-level Pod customization.
	// +kubebuilder:validation:XValidation:rule="!has(self.serviceAccountName) || self.serviceAccountName != ''",message="serviceAccountName must not be empty if specified"
	type WorkloadOverrides struct {
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`
	// +optional
	// +kubebuilder:validation:MinItems=1
	Env []corev1.EnvVar `json:"env,omitempty"`
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	Command []string `json:"command,omitempty"`
	// +optional
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:items:MinLength=1
	Args []string `json:"args,omitempty"`
	// +optional
	// +kubebuilder:validation:MinItems=1
	Volumes []corev1.Volume `json:"volumes,omitempty"`
	// +optional
	// +kubebuilder:validation:MinItems=1
	VolumeMounts []corev1.VolumeMount `json:"volumeMounts,omitempty"`
	}

[eoinfennessy]

Ensure Inference slice is not empty if provided.

Suggested change

	// ExternalProvidersSpec configures external provider injection.
	type ExternalProvidersSpec struct {
	// Inference external providers.
	// +optional
	Inference []ExternalProviderConfig `json:"inference,omitempty"`
	}
	// ExternalProvidersSpec configures external provider injection.
	type ExternalProvidersSpec struct {
	// Inference external providers.
	// +optional
	// +kubebuilder:validation:items:MinLength=1
	Inference []ExternalProviderConfig `json:"inference,omitempty"`
	}

[eoinfennessy]

Ensure all fields are non-empty strings.

Suggested change

	// ExternalProviderConfig defines an external provider sidecar.
	type ExternalProviderConfig struct {
	// ProviderID is the unique identifier for this provider.
	// +kubebuilder:validation:Required
	ProviderID string `json:"providerId"`
	// Image is the container image for the provider sidecar.
	// +kubebuilder:validation:Required
	Image string `json:"image"`
	}
	// ExternalProviderConfig defines an external provider sidecar.
	type ExternalProviderConfig struct {
	// ProviderID is the unique identifier for this provider.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	ProviderID string `json:"providerId"`
	// Image is the container image for the provider sidecar.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Image string `json:"image"`
	}

[rhuss]

Closing in favor of #266, which includes the v1alpha2 types with all review feedback from this PR incorporated (see #266 (comment) for the full list of changes).