v1alpha1

type AzureBlobStorageDownloadItem struct {
	// ConnectionString references a Kubernetes Secret containing the Azure Storage connection string. See `ValueReference`.
	ConnectionString ValueReference `json:"connectionString" yaml:"connectionString"`

	// Containers lists the Azure Blob Storage containers and the specific files/folders to download from them. See `CloudDownloadBucket`.
	Containers []CloudDownloadBucket `json:"containers"`
}

type CloudDownloadBucket struct {
	// Name is the name of the bucket or container.
	Name string `json:"name"`

	// Files lists specific files to download from this bucket/container.
	Files []CloudDownloadFile `json:"files,omitempty"`

	// Folders lists specific folders (prefixes) to download from this bucket/container.
	Folders []CloudDownloadFolder `json:"folders,omitempty"`
}

type CloudDownloadFile struct {
	// Path is the full path to the source file within the bucket/container (e.g., "models/model.bin").
	Path string `json:"path"`

	// TargetPath specifies the destination path, including the filename, relative to the data volume's mount point where the file should be saved.
	TargetPath string `json:"targetPath" yaml:"targetPath"`
}

type CloudDownloadFolder struct {
	// Path is the source path (prefix) within the bucket/container (e.g., "data/images/").
	Path string `json:"path"`
	// TargetPath specifies the destination path relative to the data volume's mount point where the folder contents should be placed.
	TargetPath string `json:"targetPath" yaml:"targetPath"`
	// Glob provides an optional pattern (e.g., "*.jpg") to filter files within the source Path.
	Glob string `json:"glob,omitempty" yaml:"glob,omitempty"`
}

type ClusterQueue struct {
	// Name specifies the name of the Kueue ClusterQueue resource.
	Name string `json:"name"`

	// Spec contains the desired Kueue `ClusterQueueSpec`. Kaiwo ensures the corresponding ClusterQueue resource matches this spec. See Kueue documentation for `ClusterQueueSpec` fields like `resourceGroups`, `cohort`, `preemption`, etc.
	Spec kueuev1beta1.ClusterQueueSpec `json:"spec,omitempty"`

	// Namespaces optionally lists Kubernetes namespaces where Kaiwo should automatically create a Kueue `LocalQueue` resource pointing to this ClusterQueue.
	Namespaces []string `json:"namespaces,omitempty"`
}

type CommonMetaSpec struct {
	// User specifies the owner or creator of the workload. It should typically be the user's email address. This value is primarily used for labeling (`kaiwo.silogen.ai/user`) the generated resources (like Pods, Jobs, Deployments) for identification and filtering (e.g., with `kaiwo list --user <email>`).
	//
	// In the future, if authentication is enabled, this must be the email address which is checked against authenticated user for match.
	User string `json:"user,omitempty"`

	// PodTemplateSpecLabels allows you to specify custom labels that will be added to the `template.metadata.labels` section of the generated Pods (within Jobs, Deployments, or RayCluster specs). Standard Kaiwo system labels (like `kaiwo.silogen.ai/user`, `kaiwo.silogen.ai/name`, etc.) are added automatically and take precedence if there are conflicts.
	PodTemplateSpecLabels map[string]string `json:"podTemplateSpecLabels,omitempty"`

	// Gpus specifies the total number of GPUs allocated to the workload. See [here](/scientist/scheduling#replicas-gpus-gpusperreplica-and-gpuvendor) for more details on how this field impacts scheduling.
	// +kubebuilder:default=0
	Gpus int `json:"gpus,omitempty"`

	// GpuVendor specifies the GPU vendor (e.g., amd, nvidia, etc.). See [here](/scientist/scheduling#replicas-gpus-gpusperreplica-and-gpuvendor) for more details on how this field impacts scheduling.
	// +kubebuilder:default=amd
	GpuVendor string `json:"gpuVendor,omitempty"`

	// Version allows you to specify an optional version string for the workload. This can be useful for tracking different iterations or configurations of the same logical workload. It does not directly affect resource creation but serves as metadata.
	Version string `json:"version,omitempty"`

	// Replicas specifies the number of replicas for the workload. See [here](/scientist/scheduling#replicas-gpus-gpusperreplica-and-gpuvendor) for more details on how this field impacts scheduling.
	// +kubebuilder:default=1
	Replicas *int `json:"replicas,omitempty"`

	// GpusPerReplica specifies the number of GPUs allocated per replica. See [here](/scientist/scheduling#replicas-gpus-gpusperreplica-and-gpuvendor) for more details on how this field impacts scheduling.
	//
	// If you specify `gpusPerReplica`, you must also specify `replicas`.
	GpusPerReplica int `json:"gpus-per-replica,omitempty"`

	// Resources specify the default resource requirements applied for all pods inside the workflow.
	//
	// This field defines default Kubernetes `ResourceRequirements` (requests and limits for CPU,
	// memory, ephemeral-storage) applied to *all* containers (including init containers) within
	// the workload's pods.
	//
	// **Behavior:**
	//
	// These values act as **defaults**. If a container within the underlying Job, Deployment,
	// or Ray spec (if provided by the user) already defines a specific request or limit
	// (e.g., `memory` limit), the value from `resources` for that specific metric **will not** override it.
	//
	// **Interaction with GPU fields:** The GPU requests/limits (`amd.com/gpu` or `nvidia.com/gpu`)
	// are controlled exclusively by the `gpus`, `gpusPerReplica`, and `gpuVendor` fields
	// (and the associated calculation logic described above). Any GPU specifications within
	// the `resources` field are **ignored**.
	//
	// **Default CPU/Memory with GPUs:** When Kaiwo *generates* the underlying
	// Job/Deployment/RayCluster spec (i.e., the user did *not* provide `spec.job`,
	// `spec.deployment`, or `spec.rayService`/`spec.rayJob`), and GPUs are requested
	// (`gpusPerReplica` > 0), Kaiwo applies default CPU and Memory requests/limits
	// based on the GPU count (e.g., 4 CPU cores and 32Gi Memory per GPU).
	// These GPU-derived defaults *will* override any CPU/Memory settings defined in
	// the `resources` field in this specific scenario. If the user *does* provide
	// the underlying spec, these GPU-derived CPU/Memory defaults are not applied,
	// respecting the user's definition or the values from the `resources` field.
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// Image specifies the default container image to be used for the primary workload container(s).
	//
	// - If containers defined within the underlying Job, Deployment, or Ray spec do *not* specify an image, this image will be used.
	// - If this field is also empty, the latest tag of ghcr.io/silogen/rocm-ray is used
	Image string `json:"image,omitempty"`

	// ImagePullSecrets is a list of Kubernetes `LocalObjectReference` (containing just the secret `name`) referencing secrets needed to pull the container image(s). These are added to the `imagePullSecrets` field of the PodSpec for all generated pods.
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// Env is a list of Kubernetes `EnvVar` structs. These environment variables are added to the primary workload container(s) in the generated pods. They are appended to any environment variables already defined in the underlying Job, Deployment, or Ray spec.
	Env []corev1.EnvVar `json:"env,omitempty"`

	// SecretVolumes allows you to mount specific keys from Kubernetes Secrets as files into the workload containers.
	SecretVolumes []SecretVolume `json:"secretVolumes,omitempty"`

	// Ray determines whether the operator should use RayCluster for workload execution.
	// If `true`, Kaiwo will create Ray-specific resources.
	// If `false` (default), Kaiwo will create standard Kubernetes resources (BatchJob for `KaiwoJob`, Deployment for `KaiwoService`).
	// This setting dictates which underlying spec (`job`/`rayJob` or `deployment`/`rayService`) is primarily used.
	// +kubebuilder:default=false
	Ray bool `json:"ray,omitempty"`

	// Storage configures persistent storage using Kubernetes PersistentVolumeClaims (PVCs).
	//
	// Enabling `storage.data.download` or `storage.huggingFace.preCacheRepos` will cause Kaiwo to create a temporary Kubernetes Job (the "download job") before starting the main workload. This job runs a container that performs the downloads into the respective PVCs. The main workload only starts after the download job completes successfully.
	Storage *StorageSpec `json:"storage,omitempty"`

	// Dangerous, if when set to `true`, Kaiwo will *not* add the default `PodSecurityContext` (which normally sets `runAsUser: 1000`, `runAsGroup: 1000`, `fsGroup: 1000`) to the generated pods. Use this only if you need to run containers as root or a different specific user and understand the security implications.
	// +kubebuilder:default=false
	Dangerous bool `json:"dangerous,omitempty"`
}

type DataStorageSpec struct {
	// MountPath specifies the path inside the workload containers where the data PersistentVolumeClaim will be mounted.
	//+kubebuilder:default=/workload
	MountPath string `json:"mountPath,omitempty"`

	// StorageSize specifies the requested size for the data PersistentVolumeClaim (e.g., "100Gi", "1Ti"). If set, a PVC will be created.
	StorageSize string `json:"storageSize,omitempty"`

	// Download configures optional tasks to download data from various sources into the data volume *before* the main workload starts. See `ObjectStorageDownloadSpec`.
	Download ObjectStorageDownloadSpec `json:"download,omitempty"`
}

type DownloadTaskConfig struct {
	// DownloadRoot specifies the common root directory within the download job's container where the 'data' PVC is mounted. Corresponds to `DataStorageSpec.MountPath`.
	DownloadRoot string `json:"downloadRoot" yaml:"downloadRoot"`

	// HfHome specifies the path within the download job's container where the Hugging Face cache PVC is mounted. Corresponds to `HfStorageSpec.MountPath` and sets the `$HF_HOME` environment variable.
	HfHome string `json:"hfHome" yaml:"hfHome"`

	// S3 lists S3 download tasks.
	S3 []S3DownloadItem `json:"s3,omitempty" yaml:"s3,omitempty"`

	// GCS lists Google Cloud Storage download tasks.
	GCS []GCSDownloadItem `json:"gcs,omitempty" yaml:"gcs,omitempty"`

	// HF lists Hugging Face pre-cache tasks.
	HF []HuggingFaceDownloadItem `json:"hf,omitempty" yaml:"hf,omitempty"`

	// AzureBlob lists Azure Blob Storage download tasks.
	AzureBlob []AzureBlobStorageDownloadItem `json:"azureBlob,omitempty" yaml:"azureBlob,omitempty"`

	// Git lists Git repository download tasks.
	Git []GitDownloadItem `json:"git,omitempty" yaml:"git,omitempty"`
}

type GCSDownloadItem struct {
	// ApplicationCredentials references a Kubernetes Secret containing the GCS service account key JSON file content. See `ValueReference`.
	ApplicationCredentials ValueReference `json:"applicationCredentials" yaml:"applicationCredentials"`

	// Buckets lists the GCS buckets and the specific files/folders to download from them. See `CloudDownloadBucket`.
	Buckets []CloudDownloadBucket `json:"buckets"`
}

type GitDownloadItem struct {
	// Repository specifies the Git repository URL (e.g., "https://github.com/user/repo.git").
	Repository string `json:"repository" yaml:"repository,omitempty"`

	// Branch specifies the branch to clone. This is ignored if `commit` is specified.
	Branch string `json:"branch,omitempty" yaml:"branch,omitempty"`

	// Commit specifies the exact commit hash to check out. This takes precedence over `branch`.
	Commit string `json:"commit,omitempty" yaml:"commit,omitempty"`

	// Username optionally references a Secret containing the Git username for authentication. See `ValueReference`.
	Username *ValueReference `json:"username,omitempty" yaml:"username,omitempty"`

	// Token optionally references a Secret containing the Git token (or password) for authentication. See `ValueReference`.
	Token *ValueReference `json:"token,omitempty" yaml:"token,omitempty"`

	// Path specifies a sub-path within the repository to copy. If omitted, the entire repository is copied.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// TargetPath specifies the destination path relative to the data volume's mount point (`DataStorageSpec.MountPath`) where the repository or `path` content should be copied.
	TargetPath string `json:"targetPath" yaml:"targetPath"`
}

type HfStorageSpec struct {
	// MountPath specifies the path inside workload containers where the Hugging Face cache PVC will be mounted.
	// This path is also automatically set as the `HF_HOME` environment variable in the containers.
	//+kubebuilder:default=/hf_cache
	MountPath string `json:"mountPath,omitempty"`

	// StorageSize specifies the requested size for the Hugging Face cache PersistentVolumeClaim (e.g., "50Gi", "200Gi"). If set, a PVC will be created.
	StorageSize string `json:"storageSize,omitempty"`

	// PreCacheRepos is a list of Hugging Face repositories to download into the cache volume *before* the main workload starts.
	PreCacheRepos []HuggingFaceDownloadItem `json:"preCacheRepos,omitempty"`
}

type HuggingFaceDownloadItem struct {
	// RepoID is the Hugging Face Hub repository ID (e.g., "meta-llama/Llama-2-7b-chat-hf").
	RepoID string `json:"repoId" yaml:"repoId"`

	// Files is an optional list of specific files to download from the repository. If omitted, the entire repository is downloaded.
	Files []string `json:"files,omitempty"`
}

type KaiwoJob struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// Spec defines the desired state of the KaiwoJob, including workload type (Job/RayJob), configuration, resources, and common metadata.
	Spec KaiwoJobSpec `json:"spec,omitempty"`

	// Status reflects the most recently observed state of the KaiwoJob, including its phase, start/completion times, and conditions.
	Status KaiwoJobStatus `json:"status,omitempty"`
}

type KaiwoJobList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []KaiwoJob `json:"items"`
}

type KaiwoJobSpec struct {
	CommonMetaSpec `json:",inline"`

	// ClusterQueue specifies the name of the Kueue `ClusterQueue` that the job should be submitted to for scheduling and resource management.
	//
	// This value is set as the `kueue.x-k8s.io/queue-name` label on the underlying Kubernetes Job or RayJob.
	//
	// If omitted, it defaults to the value specified by the `DEFAULT_CLUSTER_QUEUE_NAME` environment variable in the Kaiwo controller (typically "kaiwo"), which is set during installation.
	//
	// Note! If the applied KaiwoQueueConfig includes no quota for the default queue, no workload will run that tries to fall back on it.
	//
	// The `kaiwo submit` CLI command can override this using the `--queue` flag or the `clusterQueue` field in the `kaiwoconfig.yaml` file.
	ClusterQueue string `json:"clusterQueue,omitempty"`

	// PriorityClass specifies the name of a Kubernetes `PriorityClass` to be assigned to the job's pods. This influences the scheduling priority relative to other pods in the cluster.
	PriorityClass string `json:"priorityClass,omitempty"`

	// EntryPoint defines the command or script that the primary container in the job's pod(s) should execute.
	//
	// It can be a multi-line string. Shell script shebangs (`#!/bin/bash`) are detected.
	//
	// For standard Kubernetes Jobs (`ray: false`), this populates the `command` and `args` fields of the container spec (typically `["/bin/sh", "-c", "<entrypoint_script>"]`).
	//
	// For RayJobs (`ray: true`), this populates the `rayJob.spec.entrypoint` field. For RayJobs, this must reference a Python script.
	//
	// This overrides any default command specified in the container image or the underlying `job` or `rayJob` spec sections if they are also defined.
	EntryPoint string `json:"entrypoint,omitempty"`

	// RayJob defines the RayJob configuration.
	//
	// If this field is present (or if `spec.ray` is `true`), Kaiwo will create a `RayJob` resource instead of a standard `batchv1.Job`.
	//
	// Common fields like `image`, `resources`, `gpus`, `replicas`, etc., will be merged into this spec, potentially overriding values defined here unless explicitly configured otherwise.
	//
	// This provides fine-grained control over the Ray cluster configuration (head/worker groups) and Ray job submission parameters.
	// +kubebuilder:pruning:PreserveUnknownFields
	RayJob *rayv1.RayJob `json:"rayJob,omitempty"`

	// Job defines the Kubernetes Job configuration.
	//
	// If this field is present and `spec.ray` is `false`, Kaiwo will use this as the base for the created `batchv1.Job`.
	//
	// Common fields like `image`, `resources`, `gpus`, `entrypoint`, etc., will be merged into this spec, potentially overriding values defined here.
	//
	// This provides fine-grained control over standard Kubernetes Job parameters like `backoffLimit`, `ttlSecondsAfterFinished`, pod template details, etc.
	// +kubebuilder:pruning:PreserveUnknownFields
	Job *batchv1.Job `json:"job,omitempty"`
}

type KaiwoJobStatus struct {
	// StartTime records the timestamp when the first pod associated with the KaiwoJob started running.
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime records the timestamp when the KaiwoJob finished execution (either successfully or with failure).
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

	// Conditions lists the observed conditions of the KaiwoJob resource, following standard Kubernetes conventions.
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Status reflects the current high-level phase of the KaiwoJob lifecycle (e.g., PENDING, RUNNING, COMPLETE, FAILED).
	Status Status `json:"status,omitempty"`

	// Duration indicates the total time the job ran, calculated from StartTime to CompletionTime, in seconds.
	Duration int64 `json:"duration,omitempty"`

	// ObservedGeneration records the `.metadata.generation` of the KaiwoJob resource that was last processed by the controller.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type KaiwoQueueConfig struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// Spec defines the desired state for Kueue resources managed by Kaiwo.
	Spec KaiwoQueueConfigSpec `json:"spec,omitempty"`

	// Status reflects the most recently observed state of the Kueue resource synchronization.
	Status KaiwoQueueConfigStatus `json:"status,omitempty"`
}

type KaiwoQueueConfigList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []KaiwoQueueConfig `json:"items"`
}

type KaiwoQueueConfigSpec struct {
	// ClusterQueues defines a list of Kueue ClusterQueues that Kaiwo should manage. Kaiwo ensures these ClusterQueues exist and match the provided specs.
	// +kubebuilder:validation:MaxItems=10
	ClusterQueues []ClusterQueue `json:"clusterQueues,omitempty"`

	// ResourceFlavors defines a list of Kueue ResourceFlavors that Kaiwo should manage. Kaiwo ensures these ResourceFlavors exist and match the provided specs. If omitted or empty, Kaiwo attempts to automatically discover node pools and create default flavors based on node labels.
	ResourceFlavors []ResourceFlavorSpec `json:"resourceFlavors,omitempty"`

	// WorkloadPriorityClasses defines a list of Kueue WorkloadPriorityClasses that Kaiwo should manage. Kaiwo ensures these priority classes exist with the specified values. See Kueue documentation for `WorkloadPriorityClass`.
	// +kubebuilder:validation:MaxItems=5
	WorkloadPriorityClasses []kueuev1beta1.WorkloadPriorityClass `json:"workloadPriorityClasses,omitempty"`
}

type KaiwoQueueConfigStatus struct {
	// Conditions lists the observed conditions of the KaiwoQueueConfig resource, such as whether the managed Kueue resources are synchronized and ready.
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Status reflects the overall status of the Kueue resource synchronization managed by this config (e.g., PENDING, READY, FAILED).
	Status Status `json:"status,omitempty"`
}

type KaiwoService struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// Spec defines the desired state of the KaiwoService, including workload type (Deployment/RayService), configuration, resources, and common metadata.
	Spec KaiwoServiceSpec `json:"spec,omitempty"`

	// Status reflects the most recently observed state of the KaiwoService, including its phase, start time, duration, and conditions.
	Status KaiwoServiceStatus `json:"status,omitempty"`
}

type KaiwoServiceList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []KaiwoService `json:"items"`
}

type KaiwoServiceSpec struct {
	CommonMetaSpec `json:",inline"`

	// ClusterQueue specifies the name of the Kueue `ClusterQueue` that the service should be submitted to for scheduling and resource management.
	//
	// This value is set as the `kueue.x-k8s.io/queue-name` label on the underlying Kubernetes Deployment or RayService.
	//
	// If omitted, it defaults to the value specified by the `DEFAULT_CLUSTER_QUEUE_NAME` environment variable in the Kaiwo controller (typically "kaiwo").
	//
	// The `kaiwo submit` CLI command can override this using the `--queue` flag or the `clusterQueue` field in the `kaiwoconfig.yaml` file.
	ClusterQueue string `json:"clusterQueue,omitempty"`

	// PriorityClass specifies the name of a Kubernetes `PriorityClass` to be assigned to the service's pods. This influences the scheduling priority relative to other pods in the cluster.
	PriorityClass string `json:"priorityClass,omitempty"`

	// EntryPoint specifies the command or script executed in a Deployment.
	// Can also be defined inside Deployment struct as regular command in the form of string array.
	//
	// It is *not* used when `ray: true` (use `serveConfigV2` or the `rayService` spec instead for Ray entrypoints).
	EntryPoint string `json:"entrypoint,omitempty"`

	// Defines the applications and deployments to deploy, should be a YAML multi-line scalar string.
	// Can also be defined inside RayService struct
	ServeConfigV2 string `json:"serveConfigV2,omitempty"`

	// RayService allows providing a full `rayv1.RayService` spec.
	//
	// If present (or `spec.ray` is `true`), Kaiwo creates a `RayService` (wrapped in an AppWrapper for Kueue integration) instead of a `Deployment`.
	//
	// Common fields are merged into the `RayClusterSpec` within this spec.
	//
	// Allows fine-grained control over the Ray cluster and Ray Serve configurations.
	// +kubebuilder:pruning:PreserveUnknownFields
	RayService *rayv1.RayService `json:"rayService,omitempty"`

	// Deployment allows providing a full `appsv1.Deployment` spec.
	//
	// If present and `spec.ray` is `false`, this is used as the base for the created `Deployment`.
	//
	// Common fields are merged into this spec.
	//
	// Allows fine-grained control over Kubernetes Deployment parameters (strategy, selectors, pod template, etc.).
	// +kubebuilder:pruning:PreserveUnknownFields
	Deployment *appsv1.Deployment `json:"deployment,omitempty"`
}

type KaiwoServiceStatus struct {
	// StartTime records the timestamp when the first pod associated with the KaiwoService started running.
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// Conditions lists the observed conditions of the KaiwoService resource, following standard Kubernetes conventions. May include conditions reflecting the underlying Deployment or RayService state.
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Status reflects the current high-level phase of the KaiwoService lifecycle (e.g., PENDING, STARTING, READY, FAILED).
	Status Status `json:"status,omitempty"`

	// Duration indicates how long the service has been running since StartTime, in seconds. Calculated periodically while running.
	Duration int64 `json:"duration,omitempty"`

	// ObservedGeneration records the `.metadata.generation` of the KaiwoService resource that was last processed by the controller.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type ObjectStorageDownloadSpec struct {
	// S3 lists any S3 downloads
	S3 []S3DownloadItem `json:"s3,omitempty"`

	// GCS lists and Google Cloud Storage downloads
	GCS []GCSDownloadItem `json:"gcs,omitempty"`

	// AzureBlob lists any Azure Blob Storage downloads
	AzureBlob []AzureBlobStorageDownloadItem `json:"azureBlob,omitempty"`

	// Git lists any Git downloads
	Git []GitDownloadItem `json:"git,omitempty"`
}

type ResourceFlavorSpec struct {
	// Name specifies the name of the Kueue ResourceFlavor resource (e.g., "amd-mi300-8gpu").
	Name string `json:"name"`

	// NodeLabels specifies the labels that pods requesting this flavor must match on nodes. This is used by Kueue for scheduling decisions. Keys and values should correspond to actual node labels. Example: `{"kaiwo/nodepool": "amd-gpu-nodes"}`
	// +kubebuilder:validation:MaxProperties=10
	NodeLabels map[string]string `json:"nodeLabels,omitempty"`

	// Taints specifies a list of taints associated with this flavor.
	// +kubebuilder:validation:MaxItems=5
	Taints []corev1.Taint `json:"taints,omitempty"`

	// Tolerations specifies a list of tolerations associated with this flavor. This is less common than using Taints; Kueue primarily uses Taints to derive Tolerations.
	// +kubebuilder:validation:MaxItems=5
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
}

type S3DownloadItem struct {
	// EndpointUrl specifies the S3 API endpoint URL (e.g., "https://s3.us-east-1.amazonaws.com" or a MinIO endpoint).
	EndpointUrl string `json:"endpointUrl" yaml:"endpointUrl"`

	// AccessKeyId optionally references a Kubernetes Secret containing the S3 access key ID. See `ValueReference`.
	AccessKeyId ValueReference `json:"accessKeyId,omitempty" yaml:"accessKeyId,omitempty"`

	// SecretKey optionally references a Kubernetes Secret containing the S3 secret access key. See `ValueReference`.
	SecretKey ValueReference `json:"secretKey,omitempty" yaml:"secretKey,omitempty"`

	// Buckets lists the S3 buckets and the specific files/folders to download from them. See `CloudDownloadBucket`.
	Buckets []CloudDownloadBucket `json:"buckets"`
}

type SecretVolume struct {
	// Name defines the name of the Kubernetes Volume that will be created. Should be unique within the pod.
	Name string `json:"name,omitempty"`

	// SecretName specifies the name of the Kubernetes Secret resource to mount from.
	SecretName string `json:"secretName,omitempty"`

	// Key specifies the key within the Secret whose value should be mounted. If omitted, the entire secret might be mounted as files (depending on Kubernetes behavior).
	Key string `json:"key,omitempty"`

	// SubPath defines the filename within the `MountPath` directory where the secret `Key`'s content will be placed. Useful for mounting a single secret key as a file.
	SubPath string `json:"subPath,omitempty"`

	// MountPath defines the directory path inside the container where the secret volume (or the `SubPath` file) should be mounted.
	MountPath string `json:"mountPath,omitempty"`
}

type Status string

type StorageSpec struct {
	// StorageEnabled must be `true` to enable the creation of any PersistentVolumeClaims defined within this spec. If `false`, `data` and `huggingFace` sections are ignored.
	StorageEnabled bool `json:"storageEnabled,omitempty"`

	// StorageClassName specifies the name of the Kubernetes `StorageClass` to use when creating PersistentVolumeClaims for `data` and `huggingFace` volumes. Must refer to an existing StorageClass in the cluster.
	StorageClassName string `json:"storageClassName,omitempty"`

	// AccessMode determines the access mode (e.g., `ReadWriteOnce`, `ReadWriteMany`, `ReadOnlyMany`) for the created PersistentVolumeClaims.
	//
	// In a multi-node setting, ReadWriteMany is generally required, as pods scheduled on different nodes cannot access ReadWriteOnce PVCs. This is true even when `replicas: 1` if you are using download jobs, as the download pod may get scheduled on a different pod than the main workload pod.
	// +kubebuilder:default=ReadWriteMany
	AccessMode corev1.PersistentVolumeAccessMode `json:"accessMode"`

	// Data configures the main data PersistentVolumeClaim and optional pre-download tasks for it.
	Data *DataStorageSpec `json:"data,omitempty"`

	// HuggingFace configures a PersistentVolumeClaim specifically for caching Hugging Face models and datasets, with options for pre-caching.
	HuggingFace *HfStorageSpec `json:"huggingFace,omitempty"`
}

type ValueReference struct {
	// File specifies the expected path within the download job's container where the secret value will be mounted as a file. This path is usually automatically generated by the controller based on SecretName and SecretKey.
	File string `json:"file,omitempty"`

	// SecretName is the name of the Kubernetes Secret resource containing the value.
	SecretName string `json:"secretName,omitempty" yaml:"secretName,omitempty"`

	// SecretKey is the key within the specified Secret whose value should be used.
	SecretKey string `json:"secretKey,omitempty" yaml:"secretKey,omitempty"`
}