v1alpha1

type AuthMode string

type AuthSpec struct {
	// Mode is the authentication mode.
	Mode AuthMode `json:"mode"`

	// OIDC configures OpenID Connect. Required when mode is "openid".
	// +optional
	OIDC *OIDCSpec `json:"oidc,omitempty"`
}

type AutoStopSpec struct {
	// Enabled turns auto-stop on for this engine. Defaults to false.
	// +kubebuilder:default=false
	Enabled bool `json:"enabled"`

	// ActiveReplicas is the replica count the engine runs at while active
	// (during a Schedule window or following a wake-up). Required when Enabled
	// is true.
	// +kubebuilder:validation:Minimum=1
	ActiveReplicas int32 `json:"activeReplicas"`

	// IdleReplicas is the replica count the engine scales down to once
	// IdleTimeout elapses with no query activity. 0 fully stops the engine.
	// Defaults to 0.
	// +kubebuilder:default=0
	// +kubebuilder:validation:Minimum=0
	// +optional
	IdleReplicas *int32 `json:"idleReplicas,omitempty"`

	// IdleTimeout is how long the engine must observe zero in-flight and
	// suspended queries before it scales down to IdleReplicas. Defaults to
	// 30 minutes.
	// +kubebuilder:default="30m"
	// +optional
	IdleTimeout *metav1.Duration `json:"idleTimeout,omitempty"`

	// PollInterval is how often the operator scrapes engine metrics to
	// re-evaluate idleness. Defaults to 1 minute.
	// +kubebuilder:default="1m"
	// +optional
	PollInterval *metav1.Duration `json:"pollInterval,omitempty"`

	// Schedule is an optional list of UTC time windows during which the engine
	// is held at ActiveReplicas regardless of observed activity. Useful for
	// "always-on during business hours" policies.
	// +optional
	Schedule []ScheduleWindow `json:"schedule,omitempty"`
}

type EngineConfigOwnedSection struct {
	// Section is the top-level key in the rendered config document, or "" for
	// the document root.
	Section string

	// Keys are the immediate children of Section managed exclusively by the
	// operator. User input at any of these paths is silently stripped.
	Keys []string
}

type EngineEmptyDirSpec struct {
	// Medium is the storage medium backing the emptyDir. Leave empty
	// for the default node disk; set to "Memory" for a tmpfs-backed
	// volume sized against the pod's memory limit.
	// +kubebuilder:validation:Enum="";Memory
	// +optional
	Medium corev1.StorageMedium `json:"medium,omitempty"`

	// SizeLimit caps the volume's growth. Optional; nil means
	// unbounded (subject to node disk pressure or pod memory limits
	// for Memory medium).
	// +optional
	SizeLimit *resource.Quantity `json:"sizeLimit,omitempty"`
}

type EngineHostPathSpec struct {
	// Path is the absolute filesystem path on the host node.
	// +kubebuilder:validation:Pattern=`^/.*`
	Path string `json:"path"`

	// Type enforces a check on Path before mounting (Directory,
	// DirectoryOrCreate, …). See
	// https://kubernetes.io/docs/concepts/storage/volumes/#hostpath
	// for the full enum. Leave nil to skip the check (kubelet default).
	// +optional
	Type *corev1.HostPathType `json:"type,omitempty"`
}

type EnginePersistentVolumeClaimSpec struct {
	// Size is the requested capacity for each engine pod's PVC. Defaults to 1Gi.
	// +kubebuilder:default="1Gi"
	// +optional
	Size resource.Quantity `json:"size,omitempty"`

	// AccessModes for the PVC. Defaults to [ReadWriteOnce], which matches the
	// per-pod ownership model used by the StatefulSet VolumeClaimTemplate.
	// +kubebuilder:default={ReadWriteOnce}
	// +optional
	AccessModes []corev1.PersistentVolumeAccessMode `json:"accessModes,omitempty"`

	// StorageClassName selects the StorageClass for the PVC. Leave nil to use
	// the cluster default. An empty string disables dynamic provisioning.
	// +optional
	StorageClassName *string `json:"storageClassName,omitempty"`
}

type EnginePhase string

type EngineResourceBounds struct {
	// MaxCPU caps spec.resources.requests[cpu] and spec.resources.limits[cpu].
	// IsZero() disables the bound.
	MaxCPU resource.Quantity
	// MaxMemory caps spec.resources.requests[memory] and
	// spec.resources.limits[memory]. IsZero() disables the bound.
	MaxMemory resource.Quantity
	// MaxEphemeralStorage caps
	// spec.resources.requests[ephemeral-storage] and
	// spec.resources.limits[ephemeral-storage]. IsZero() disables the
	// bound.
	MaxEphemeralStorage resource.Quantity
}

type EngineStorageSpec struct {
	// PersistentVolumeClaim opts the engine into a per-pod
	// PersistentVolumeClaim synthesized by the StatefulSet controller
	// from a VolumeClaimTemplate. Set the field (even to an empty
	// struct) to enable the PVC backend; the kubebuilder defaults
	// (1Gi, ReadWriteOnce, cluster-default StorageClass) on
	// EnginePersistentVolumeClaimSpec fill in any omitted inner field.
	// When this field is nil the engine falls back to the default
	// emptyDir backend (see the EngineStorageSpec doc above).
	// +optional
	PersistentVolumeClaim *EnginePersistentVolumeClaimSpec `json:"persistentVolumeClaim,omitempty"`

	// EmptyDir backs the engine's data mount with a pod-scoped emptyDir
	// Volume. The mount holds regenerable cache only; authoritative
	// data lives in the metadata service and the managed-table S3
	// bucket (see EngineStorageSpec for the full picture), so volume
	// contents being lost on pod restart is normal engine behavior
	// rather than a durability regression.
	// +optional
	EmptyDir *EngineEmptyDirSpec `json:"emptyDir,omitempty"`

	// HostPath backs the engine's data mount with a directory on the
	// node filesystem. Pods are implicitly node-pinned (the directory only
	// exists where it was created); the path must pre-exist on every
	// node the engine pod could be scheduled onto, with permissions
	// readable by the engine web UID. Use to expose instance-store NVMe on
	// the node.
	// +optional
	HostPath *EngineHostPathSpec `json:"hostPath,omitempty"`
}

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

	Spec   FireboltEngineSpec   `json:"spec,omitempty"`
	Status FireboltEngineStatus `json:"status,omitempty"`
}

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

	Spec   FireboltEngineClassSpec   `json:"spec,omitempty"`
	Status FireboltEngineClassStatus `json:"status,omitempty"`
}

type FireboltEngineClassCustomValidator struct {
	// Reader is an uncached API client used by ValidateDelete to list
	// FireboltEngines at admission time. Wired from mgr.GetAPIReader() so
	// the gate is consistent with API-server state and not subject to
	// status / cache staleness.
	Reader client.Reader
}

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

type FireboltEngineClassSpec struct {
	// Template is the pod template merged into engines that reference this
	// class. See the type-level doc for the precedence rules and the list
	// of operator-owned paths the validating webhook rejects.
	//
	// The CRD schema for template.metadata is patched post-controller-gen
	// (scripts/patch-crd-template-metadata.py, invoked by `make manifests`)
	// to set x-kubernetes-preserve-unknown-fields on the embedded
	// ObjectMeta. Without that injection, structural-schema pruning would
	// strip template.metadata.labels and template.metadata.annotations at
	// admission time and any GitOps controller re-applying them would
	// drift forever. A +kubebuilder:pruning:PreserveUnknownFields marker
	// on this Go field is not sufficient: controller-gen lands it on the
	// template schema, but the marker does not propagate into a child
	// that has its own typed sub-schema (metadata: {type: object}).
	Template corev1.PodTemplateSpec `json:"template"`

	// UISidecar is the default UI sidecar setting for referencing engines
	// that leave spec.uiSidecar unset. When true, the operator injects a
	// built-in, operator-owned nginx container named "engine-web" (serving the
	// Firebolt Engine Web UI, pointed at the local engine) into each pod. The
	// operator default (false) applies when neither side sets it; nil here
	// means the class does not override.
	// +optional
	UISidecar *bool `json:"uiSidecar,omitempty"`

	// Storage is the default per-pod data-volume configuration for engines
	// that reference this class and do not declare a storage backend of
	// their own. An engine that sets any backend on spec.storage
	// (persistentVolumeClaim, emptyDir, or hostPath) owns its storage
	// wholesale and ignores this value; otherwise the class value applies,
	// falling through to the operator default (an emptyDir) when neither
	// side selects a backend. See EngineStorageSpec for the backend choice
	// and its mutual-exclusion rule, which this field inherits.
	// +kubebuilder:default={}
	// +optional
	Storage EngineStorageSpec `json:"storage,omitempty"`

	// CustomEngineConfig is deep-merged beneath each referencing engine's
	// own spec.customEngineConfig into the rendered config.yaml: operator
	// defaults first, then this class config, then the engine config on top
	// (engine keys win on conflict). Operator-owned paths (see
	// OperatorOwnedEngineConfigPaths) are stripped from this value before
	// the merge, exactly as they are from the engine's own config, so the
	// class cannot override identity, routing, or topology.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +kubebuilder:validation:Type=object
	// +optional
	CustomEngineConfig *apiextensionsv1.JSON `json:"customEngineConfig,omitempty"`

	// Rollout is the default rollout strategy for referencing engines that
	// leave spec.rollout unset. The operator default (graceful) applies when
	// neither the engine nor the class sets it; an empty value here means
	// the class does not override. The graceful/recreate enum is inherited
	// from RolloutStrategy.
	// +optional
	Rollout RolloutStrategy `json:"rollout,omitempty"`

	// DrainCheckEnabled is the default drain-check setting for referencing
	// engines that leave spec.drainCheckEnabled unset. The operator default
	// (true) applies when neither side sets it; nil here means the class
	// does not override.
	// +optional
	DrainCheckEnabled *bool `json:"drainCheckEnabled,omitempty"`

	// DrainCheckInterval is the default drain-poll interval for referencing
	// engines that leave spec.drainCheckInterval unset. The operator default
	// applies when neither side sets it; nil here means the class does not
	// override.
	// +optional
	DrainCheckInterval *metav1.Duration `json:"drainCheckInterval,omitempty"`

	// AutoStop is the default autoStop policy for referencing engines
	// that leave spec.autoStop unset. Resolution is whole-struct: an
	// engine that sets spec.autoStop owns the entire policy and this
	// value is not field-merged into it; when the engine omits it, the
	// class policy applies; when neither sets it, autoStop is disabled.
	// +optional
	AutoStop *AutoStopSpec `json:"autoStop,omitempty"`
}

type FireboltEngineClassStatus struct {
	// ObservedGeneration is the metadata.generation last reconciled by the
	// FireboltEngineClass controller. Lets tooling detect stale status.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// BoundEngines counts the FireboltEngines in the same namespace that
	// reference this class via spec.engineClassRef. Surfaced for
	// visibility (printcolumn, kubectl describe); both the FireboltEngineClass
	// deletion webhook and the reconciler's deletion-guard finalizer
	// do their own live List against the namespace rather than trusting
	// this cached value, so a class bound between reconciler runs
	// (status still at zero) is still protected from deletion.
	// +optional
	BoundEngines int32 `json:"boundEngines,omitempty"`

	// Conditions surface the FireboltEngineClass's high-level state.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type FireboltEngineCustomValidator struct {
	Reader         client.Reader
	ResourceBounds EngineResourceBounds
}

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

type FireboltEngineSpec struct {
	// InstanceRef is the name of the FireboltInstance in the same namespace
	// that this engine depends on. The engine reconciler will not proceed
	// until the referenced instance has a populated metadata endpoint and
	// instance ID. This field is immutable after creation.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="instanceRef is immutable"
	InstanceRef string `json:"instanceRef"`

	// EngineClassRef is the name of a FireboltEngineClass in this engine's
	// own namespace whose pod template is merged underneath this engine's
	// pod template when the engine's StatefulSet is built. Engine spec
	// fields take precedence over class fields; operator defaults sit
	// beneath both. FireboltEngineClass is namespaced because its template
	// carries namespace-resolved identifiers (ServiceAccount names,
	// Secret / ConfigMap / PVC volume references, per-tenant IAM
	// annotations); the class and the engines that reference it must
	// live together in the same namespace.
	//
	// Mutable: changing the reference (or editing the referenced
	// class's spec) triggers a new blue-green generation, just like any
	// other pod-template-affecting spec change. The change participates
	// in stsMatchesSpec via an annotation hash so drift is detected
	// deterministically.
	//
	// The validating webhook rejects Create and Update when the
	// referenced class does not exist in the engine's namespace, so
	// users see the typo (or a class-in-the-wrong-namespace mistake)
	// immediately instead of via engine status. Apply ordering matters:
	// GitOps tooling must apply the FireboltEngineClass before any
	// engine that references it (Argo sync-waves / Flux dependsOn).
	// +kubebuilder:validation:MinLength=1
	// +optional
	EngineClassRef *string `json:"engineClassRef,omitempty"`

	// Replicas is the number of engine nodes. Set to 0 to stop the
	// engine: the operator tears down the active generation (honoring
	// spec.rollout for drain behavior) and leaves the CR in the
	// Stopped phase. Setting replicas back to a non-zero value resumes
	// the engine via a new blue-green generation.
	// +kubebuilder:validation:Minimum=0
	Replicas int32 `json:"replicas"`

	// Template is the pod template the operator merges with its
	// own-rendered engine container, data volume, projected ConfigMap,
	// probes, and pod-level securityContext to produce the engine
	// StatefulSet's pod spec. Most users set only
	// template.spec.containers[name=="engine"].image and
	// .resources, plus scheduling fields (nodeSelector / tolerations /
	// affinity / topologySpreadConstraints / priorityClassName /
	// podSecurityContext) and any sidecars / init containers / extra
	// volumes they need.
	//
	// When spec.engineClassRef is also set, the operator first merges
	// the class's spec.template underneath the operator defaults, then
	// this template on top — engine wins on conflict (whole-struct
	// ownership for pointer fields; list-type fields like tolerations
	// / initContainers / sidecars / volumes concatenate class-first
	// then engine). The same field-by-field precedence the
	// FireboltEngineClass merge layer has always used now applies to
	// the engine's own template as the topmost layer.
	//
	// The validating webhook rejects user input on paths the operator
	// owns end-to-end — see FireboltEngineClassPodTemplateRules in
	// operatorauthority.go for the authoritative allowlist. Notably,
	// terminationGracePeriodSeconds is rejected: TGPS is operator-stamped
	// from an internal default (60s), matching the same rejection on the
	// class template.
	//
	// Changes to this field trigger a new blue-green generation.
	// +optional
	Template *corev1.PodTemplateSpec `json:"template,omitempty"`

	// UISidecar enables a built-in UI sidecar (an operator-owned nginx
	// container named "engine-web" serving the Firebolt Engine Web UI, pointed at
	// this engine on localhost) in every pod of this engine. It exposes
	// container port 9100 ("web-ui"); the per-engine headless Service resolves
	// to pod IPs, so the UI is reachable at <pod-ip>:9100 without listing an
	// extra Service port. The "engine-web" container name is reserved: a
	// user-supplied container or init container with that name is rejected.
	//
	// Resolution is engine-if-set → FireboltEngineClass-if-set → operator
	// default (false). The default is applied by the controller, not the CRD,
	// so an unset value here falls through to the referenced class instead of
	// being materialized to false at admission.
	//
	// Toggling this changes the pod template and therefore triggers a new
	// blue-green generation.
	// +optional
	UISidecar *bool `json:"uiSidecar,omitempty"`

	// DrainCheckEnabled controls whether the operator performs a SQL-based drain
	// check on old-generation pods during graceful rollouts. When false, the
	// operator skips directly to cleaning after switching traffic, without
	// verifying that in-flight queries have completed. Requires a running
	// node that can execute the drain-check query when enabled.
	//
	// Resolution is engine-if-set → FireboltEngineClass-if-set → operator
	// default (true). The default is applied by the controller, not the CRD,
	// so an unset value here falls through to the referenced class instead of
	// being materialized to true at admission.
	// +optional
	DrainCheckEnabled *bool `json:"drainCheckEnabled,omitempty"`

	// DrainCheckInterval controls how often to check if old pods have finished serving queries.
	// Only used when drainCheckEnabled is true.
	// +optional
	DrainCheckInterval *metav1.Duration `json:"drainCheckInterval,omitempty"`

	// Rollout strategy for transitions: "graceful" waits for drain, "recreate"
	// deletes immediately. Resolution is engine-if-set →
	// FireboltEngineClass-if-set → operator default (graceful). The default is
	// applied by the controller, not the CRD, so an unset value here falls
	// through to the referenced class instead of being materialized to
	// graceful at admission.
	// +optional
	Rollout RolloutStrategy `json:"rollout,omitempty"`

	// MetadataEndpointOverride overrides the metadata endpoint for this engine.
	// If nil, the engine uses Instance.status.metadataEndpoint (with intra-cluster
	// topology-aware routing). Set this for cross-cluster scenarios where the engine
	// connects to a metadata service in a different cluster via private link.
	//
	// Immutable once set: see the struct-level CEL rule on FireboltEngineSpec.
	// +optional
	MetadataEndpointOverride *string `json:"metadataEndpointOverride,omitempty"`

	// Storage configures the per-pod data volume mounted into each engine
	// container. See EngineStorageSpec for the backend choice (emptyDir is
	// the default; persistentVolumeClaim or hostPath are opt-ins). Changes
	// to any field — including switching backends — force a new blue-green
	// generation, because the StatefulSet's VolumeClaimTemplates are
	// immutable and a backend swap necessarily reshapes the pod-template
	// data Volume.
	//
	// Not a Kubernetes pod-template concern: the operator owns the data
	// volume name and the StatefulSet's VolumeClaimTemplates, so this stays
	// on the spec wrapper rather than under spec.template.spec.volumes.
	// +kubebuilder:default={}
	// +optional
	Storage EngineStorageSpec `json:"storage,omitempty"`

	// CustomEngineConfig is a free-form object deep-merged into the rendered
	// engine config.yaml at the root. The rendered document follows the
	// structured schema consumed by `firebolt server` (top-level sections:
	// `auth`, `engine`, `instance`, `logging`, `schema_version`); keys
	// placed in customEngineConfig at the same paths are merged into the
	// corresponding sections, overriding the operator's defaults (e.g.
	// `logging.format`, `logging.level`, `auth.*`). Any additional sections
	// understood by the engine binary may be set at the root.
	//
	// The operator retains authority over identity, routing, and topology
	// paths. The following are silently stripped from user input before the
	// merge and cannot be overridden via this field:
	//
	//   - schema_version
	//   - instance.id
	//   - instance.type
	//   - instance.multi_engine (entire subtree, including metadata_endpoint)
	//   - engine.id
	//   - engine.nodes
	//   - engine.termination_grace_period
	//
	// Changes to this field trigger a new blue-green generation, since the
	// rendered config.yaml content changes.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +kubebuilder:validation:Type=object
	// +optional
	CustomEngineConfig *apiextensionsv1.JSON `json:"customEngineConfig,omitempty"`

	// AutoStop configures automatic stop and wake-up for this engine. When
	// omitted or with Enabled=false, spec.replicas is governed entirely by the
	// user. When enabled, the operator owns spec.replicas and drives it between
	// IdleReplicas and ActiveReplicas based on idleness, wake-up requests, and
	// Schedule windows. It is an activity-gated toggle, not proportional
	// autoscaling.
	// +optional
	AutoStop *AutoStopSpec `json:"autoStop,omitempty"`
}

type FireboltEngineStatus struct {
	// ObservedGeneration is the metadata.generation that was last fully reconciled to stable.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// CurrentGeneration is the latest generation number created.
	CurrentGeneration int `json:"currentGeneration"`

	// ActiveGeneration is the generation currently serving traffic.
	ActiveGeneration int `json:"activeGeneration"`

	// DrainingGeneration is the generation being drained, if any.
	// +optional
	DrainingGeneration *int `json:"drainingGeneration,omitempty"`

	// Phase is the current lifecycle phase of the engine.
	// +optional
	Phase EnginePhase `json:"phase,omitempty"`

	// LastReconciled is the timestamp of the last reconciliation.
	// +optional
	LastReconciled *metav1.Time `json:"lastReconciled,omitempty"`

	// LastActivityTime is the timestamp of the most recent auto-stop
	// observation that recorded in-flight or suspended queries. The engine
	// scales down once now() - LastActivityTime exceeds
	// spec.autoStop.idleTimeout. Cleared when auto-stop is disabled.
	// +optional
	LastActivityTime *metav1.Time `json:"lastActivityTime,omitempty"`

	// LastScaledAt is the timestamp of the most recent auto-stop-driven
	// mutation of spec.replicas. Distinguishes auto-stop scale events from
	// user edits in audit trails.
	// +optional
	LastScaledAt *metav1.Time `json:"lastScaledAt,omitempty"`

	// AutoStopReason is a short token describing the most recent auto-stop
	// decision: "Idle", "ScheduleActive", "ActivityObserved", "ScrapeFailed",
	// "Disabled", "Stopped", "Initializing", "WakeRequested".
	// +optional
	AutoStopReason string `json:"autoStopReason,omitempty"`

	// Conditions represent the latest available observations of the engine's state.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

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

	Spec   FireboltInstanceSpec   `json:"spec"`
	Status FireboltInstanceStatus `json:"status,omitempty"`
}

type FireboltInstanceCustomValidator struct{}

type FireboltInstanceDefaulter struct{}

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

type FireboltInstanceSpec struct {
	// ID is a stable unique identifier for this instance, used as the metadata
	// account ID. If empty on creation, a ULID is generated automatically by
	// the defaulting webhook. Once set, this field is immutable.
	//
	// The CEL rule allows the one-time "" -> <ulid> transition because when
	// the mutating webhook is disabled (local dev, kind, some E2E setups),
	// the controller Reconcile has a fallback that generates an ID and
	// Updates the CR. A plain `self == oldSelf` would reject that Update at
	// admission time and leave the instance permanently stuck without an ID.
	// Once ID is non-empty, subsequent Updates are still blocked from
	// changing it.
	// +optional
	// +kubebuilder:validation:XValidation:rule="oldSelf == ” || self == oldSelf",message="spec.id is immutable once set"
	ID string `json:"id,omitempty"`

	// Metadata configures the metadata service.
	Metadata MetadataSpec `json:"metadata"`

	// Gateway configures the query routing gateway (Envoy proxy).
	Gateway GatewaySpec `json:"gateway"`

	// Auth configures authentication for engine nodes.
	// TODO: not enforced yet; will be propagated to engine configuration in a future release.
	// +optional
	Auth *AuthSpec `json:"auth,omitempty"`

	// MetricScrapeMode selects the transport the operator uses to scrape
	// engine pod /metrics for the drain probe and autoStop activity
	// poll. Read fresh on every scrape so it can be flipped without a
	// controller restart. Defaults to PodIP; flip to ApiserverProxy
	// only when in-cluster pod IPs aren't reachable from the controller
	// (out-of-cluster `make run`, or networks that block node-to-node
	// on MetricsPort but allow apiserver-proxy).
	// +kubebuilder:default=PodIP
	// +optional
	MetricScrapeMode MetricScrapeMode `json:"metricScrapeMode,omitempty"`
}

type FireboltInstanceStatus struct {
	// Phase is the current lifecycle phase of the Instance.
	// +optional
	Phase InstancePhase `json:"phase,omitempty"`

	// MetadataReady indicates whether the metadata service is healthy.
	// +optional
	MetadataReady bool `json:"metadataReady,omitempty"`

	// MetadataEndpoint is the resolved Service address.
	// The Engine reconciler uses this to write engine ConfigMaps.
	// +optional
	MetadataEndpoint string `json:"metadataEndpoint,omitempty"`

	// GatewayReady indicates whether the gateway is healthy.
	// +optional
	GatewayReady bool `json:"gatewayReady,omitempty"`

	// GatewayEndpoint is the resolved gateway Service address.
	// +optional
	GatewayEndpoint string `json:"gatewayEndpoint,omitempty"`

	// Conditions represent the latest available observations of the Instance's state.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type GatewaySpec struct {
	// Replicas is the number of gateway pods. Defaults to 2 when nil.
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// MetricsPort is the container port exposing Envoy's Prometheus
	// metrics endpoint. Defaults to 9090 if zero. The operator
	// stamps a corresponding "metrics" port entry on the container.
	// +kubebuilder:default=9090
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	MetricsPort int32 `json:"metricsPort,omitempty"`

	// Template is the pod template the operator merges with its
	// own-rendered Envoy container, config volume mount, hardcoded
	// probes, and preStop drain hook to produce the gateway
	// Deployment's pod spec. Most users set only
	// template.spec.containers[name=="envoy"].image and .resources,
	// plus scheduling fields (nodeSelector / tolerations / affinity /
	// topologySpreadConstraints / priorityClassName).
	//
	// template.metadata is unpruned by a post-controller-gen patch (see
	// the matching note on FireboltEngineClassSpec.Template for the full
	// rationale).
	// +optional
	Template *corev1.PodTemplateSpec `json:"template,omitempty"`
}

type ImageSpec struct {
	// Repository is the container image repository. When empty, the
	// operator's default repository for this component is used; pair with
	// Tag to override the full reference, or set on its own to pull the
	// operator-default tag from a different repository (e.g. a mirror).
	// +kubebuilder:validation:MinLength=1
	// +optional
	Repository string `json:"repository,omitempty"`

	// Tag is the container image tag. When empty, the operator's default
	// tag for this component is used; set on its own to pin a specific
	// version while keeping the operator-default repository.
	// +kubebuilder:validation:MinLength=1
	// +optional
	Tag string `json:"tag,omitempty"`

	// PullPolicy defines when to pull the image.
	// +kubebuilder:validation:Enum=Always;Never;IfNotPresent
	// +kubebuilder:default=IfNotPresent
	// +optional
	PullPolicy corev1.PullPolicy `json:"pullPolicy,omitempty"`
}

type InstancePhase string

type MetadataSpec struct {
	// Replicas is the number of metadata pods. Pinned to 1 today by
	// the CEL rule above and the validating webhook; the surface is
	// kept on the spec for the day a multi-writer metadata story
	// lands.
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// Template is the pod template the operator merges with its
	// own-rendered metadata container, config volume, credentials
	// mount, probes, and pod-level securityContext to produce the
	// metadata Deployment's pod spec. Most users set only
	// template.spec.containers[name=="metadata"].image and
	// .resources, plus scheduling fields (nodeSelector / tolerations /
	// affinity / topologySpreadConstraints / priorityClassName).
	//
	// template.metadata is unpruned by a post-controller-gen patch (see
	// the matching note on FireboltEngineClassSpec.Template for the full
	// rationale).
	// +optional
	Template *corev1.PodTemplateSpec `json:"template,omitempty"`

	// Postgres configures the external PostgreSQL connection.
	// If nil, the operator deploys an internal PostgreSQL instance.
	// +optional
	Postgres *PostgresSpec `json:"postgres,omitempty"`

	// EngineRegistration enables registration of Engine objects in the metadata service for SQL-level RBAC.
	// +kubebuilder:default=false
	// +optional
	EngineRegistration bool `json:"engineRegistration,omitempty"`
}

type MetricScrapeMode string

type OIDCSpec struct {
	// IssuerURL is the OIDC provider's issuer URL.
	// +kubebuilder:validation:MinLength=1
	IssuerURL string `json:"issuerURL"`

	// ClientID is the OIDC client identifier.
	// +kubebuilder:validation:MinLength=1
	ClientID string `json:"clientID"`

	// ClientSecretRef references a Secret containing the OIDC client secret.
	// +optional
	ClientSecretRef *corev1.LocalObjectReference `json:"clientSecretRef,omitempty"`

	// ClaimMappings maps OIDC claims to Firebolt user attributes (e.g. {"username": "email"}).
	// +optional
	ClaimMappings map[string]string `json:"claimMappings,omitempty"`
}

type PodTemplateRules struct {
	// Component is the short component name used in error messages
	// ("engine", "gateway", "metadata").
	Component string

	// PrimaryContainerName is the name of the operator-rendered
	// container for this component. A second container with the same
	// name is rejected as a duplicate.
	PrimaryContainerName string

	// AllowedPrimaryFields enumerates the container-level fields the
	// user may set on the primary container. Any field that the user
	// sets and is not allowed here is rejected.
	AllowedPrimaryFields PrimaryContainerFields

	// ReservedPrimaryEnvKeys are env var names the operator injects on
	// the primary container; user entries with these names are
	// rejected. Only consulted when AllowedPrimaryFields.Env is true.
	ReservedPrimaryEnvKeys []string

	// ReservedPrimaryVolumeMountNames are mount names the operator
	// renders on the primary container; user entries with these names
	// in the primary container's volumeMounts are rejected. Only
	// consulted when AllowedPrimaryFields.VolumeMounts is true.
	ReservedPrimaryVolumeMountNames []string

	// AllowSidecars permits additional containers (any container whose
	// name is not PrimaryContainerName). When false, any sidecar is
	// rejected as a whole.
	AllowSidecars bool

	// AllowInitContainers permits user-supplied initContainers. When
	// false, any init container is rejected as a whole. When true,
	// an init container named PrimaryContainerName is still rejected
	// (it would collide with the operator-rendered primary container).
	AllowInitContainers bool

	// ReservedContainerNames are additional operator-owned container names
	// (beyond PrimaryContainerName) that the operator may inject into the
	// rendered pod, e.g. the optional engine web UI sidecar. A user container
	// or init container with one of these names is rejected even when
	// AllowSidecars / AllowInitContainers is true: the operator-rendered
	// container would otherwise collide with it, and Kubernetes requires
	// container names to be unique across the regular and init lists.
	ReservedContainerNames []string
}

type PostgresSpec struct {
	// Host is the PostgreSQL server hostname or IP. Allowed characters are
	// letters, digits, ".", "-", ":", "[", and "]" (the last three for IPv6
	// literals like "[::1]"). XML metacharacters are rejected at admission
	// time to prevent injection into the rendered metadata config.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[A-Za-z0-9.\-:\[\]]+$`
	Host string `json:"host"`

	// Port is the PostgreSQL server port.
	// +kubebuilder:default=5432
	// +optional
	Port int32 `json:"port,omitempty"`

	// Database is the PostgreSQL database name. Allowed characters are
	// letters, digits, "_", ".", and "-". XML metacharacters are rejected
	// at admission time to prevent injection into the rendered metadata
	// config.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[A-Za-z0-9_.\-]+$`
	Database string `json:"database"`

	// Schema is the PostgreSQL schema used by the metadata service.
	// Defaults to "public". Allowed characters are letters, digits, "_",
	// ".", and "-". XML metacharacters are rejected at admission time to
	// prevent injection into the rendered metadata config.
	// +kubebuilder:default=public
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[A-Za-z0-9_.\-]+$`
	// +optional
	Schema string `json:"schema,omitempty"`

	// CredentialsSecretRef references a Secret containing "username" and "password" keys.
	CredentialsSecretRef corev1.LocalObjectReference `json:"credentialsSecretRef"`
}

type PrimaryContainerFields struct {
	Image                    bool // image and imagePullPolicy
	Resources                bool
	Env                      bool // entries with reserved keys still rejected
	EnvFrom                  bool
	VolumeMounts             bool // entries with reserved names still rejected
	SecurityContext          bool
	Lifecycle                bool
	WorkingDir               bool
	TerminationMessagePath   bool
	TerminationMessagePolicy bool
	VolumeDevices            bool
	ResizePolicy             bool
}

type RolloutStrategy string

type ScheduleDay string

type ScheduleWindow struct {
	// Start is the window opening time in UTC, formatted "HH:MM".
	// +kubebuilder:validation:Pattern=`^([01]\d|2[0-3]):[0-5]\d$`
	Start string `json:"start"`

	// End is the window closing time in UTC, formatted "HH:MM". An End equal
	// to Start is treated as an empty window.
	// +kubebuilder:validation:Pattern=`^([01]\d|2[0-3]):[0-5]\d$`
	End string `json:"end"`

	// Days lists the UTC weekdays the window applies to. Empty means every
	// day. The window is anchored to the day on which Start falls; if End
	// crosses midnight the trailing portion still belongs to the listed day.
	// +optional
	Days []ScheduleDay `json:"days,omitempty"`
}