v1alpha1

type AdminWebStatus struct {
	// ExternalEndpoint is the hostname or IP for the external admin web endpoint,
	// sourced from externalIPs or load balancer ingress (in that priority).
	// Empty when no external endpoint has been provisioned.
	ExternalEndpoint string `json:"externalEndpoint"`
}

type BackupConfig struct {
	// Type is the backup storage backend (filesystem or s3).
	Type BackupType `json:"type"`

	// Filesystem defines configuration for local/PVC-based backups.
	// Required when type is "filesystem".
	// +optional
	Filesystem *FilesystemBackupConfig `json:"filesystem,omitempty"`

	// S3 defines the S3-compatible storage configuration.
	// Required when type is "s3".
	// +optional
	S3 *S3BackupConfig `json:"s3,omitempty"`

	// PgBackRestTLS configures TLS certificates for pgBackRest inter-node communication.
	// Required for multi-replica shards where standbys connect to the primary's
	// pgBackRest server. When SecretName is set, the operator mounts that Secret directly.
	// When SecretName is empty, the operator auto-generates and rotates certificates.
	// +optional
	PgBackRestTLS *PgBackRestTLSConfig `json:"pgbackrestTLS,omitempty"`
}

type BackupType string

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

	Spec   CellSpec   `json:"spec,omitempty"`
	Status CellStatus `json:"status,omitempty"`
}

type CellConfig struct {
	// Name is the logical name of the cell.
	Name CellName `json:"name"`

	// Zone indicates the physical availability zone.
	// +optional
	Zone Zone `json:"zone,omitempty"`
	// Region indicates the physical region (mutually exclusive with zone via CEL validation).
	// +optional
	Region Region `json:"region,omitempty"`

	// CellTemplate refers to a CellTemplate CR.
	// +optional
	CellTemplate TemplateRef `json:"cellTemplate,omitempty"`

	// Overrides are applied on top of the template.
	// +optional
	Overrides *CellOverrides `json:"overrides,omitempty"`

	// Spec defines the inline configuration if no template is used.
	// +optional
	Spec *CellInlineSpec `json:"spec,omitempty"`
}

type CellImages struct {
	// ImagePullPolicy overrides the default image pull policy.
	// +optional
	// +kubebuilder:validation:Enum=Always;Never;IfNotPresent
	ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`

	// ImagePullSecrets is a list of references to secrets in the same namespace.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// MultiGateway is the image used for the gateway.
	MultiGateway ImageRef `json:"multigateway"`
}

type CellInlineSpec struct {
	// MultiGateway configuration.
	// +optional
	MultiGateway StatelessSpec `json:"multigateway,omitempty"`

	// MultiGatewayPlacement defines optional scheduling settings for multigateway pods.
	// +optional
	MultiGatewayPlacement *PodPlacementSpec `json:"multigatewayPlacement,omitempty"`

	// LocalTopoServer configuration (optional).
	// +optional
	LocalTopoServer *LocalTopoServerSpec `json:"localTopoServer,omitempty"`
}

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

type CellName string

type CellOverrides struct {
	// MultiGateway overrides.
	// +optional
	MultiGateway *StatelessSpec `json:"multigateway,omitempty"`

	// MultiGatewayPlacement overrides.
	// +optional
	MultiGatewayPlacement *PodPlacementSpec `json:"multigatewayPlacement,omitempty"`
}

type CellSpec struct {
	// Name is the logical name of the cell.
	Name CellName `json:"name"`
	// Zone indicates the physical availability zone.
	Zone Zone `json:"zone,omitempty"`
	// Region indicates the physical region.
	// +optional
	Region Region `json:"region,omitempty"`

	// Images defines the container images used in this cell.
	Images CellImages `json:"images"`

	// MultiGateway fully resolved config.
	MultiGateway StatelessSpec `json:"multigateway"`

	// MultiGatewayPlacement defines optional scheduling settings for multigateway pods.
	// +optional
	MultiGatewayPlacement *PodPlacementSpec `json:"multigatewayPlacement,omitempty"`

	// GlobalTopoServer reference (always populated).
	GlobalTopoServer GlobalTopoServerRef `json:"globalTopoServer"`

	// TopoServer defines the local topology config.
	// +optional
	TopoServer *LocalTopoServerSpec `json:"topoServer,omitempty"`

	// AllCells list for discovery.
	// +optional
	// +listType=set
	// +kubebuilder:validation:MaxItems=50
	AllCells []CellName `json:"allCells,omitempty"`

	// TopologyReconciliation flags.
	// +optional
	TopologyReconciliation TopologyReconciliation `json:"topologyReconciliation,omitempty"`

	// Observability configures OpenTelemetry for cell-level data-plane components.
	// Inherited from MultigresCluster.Spec.Observability by the resolver.
	// +optional
	Observability *ObservabilityConfig `json:"observability,omitempty"`

	// LogLevels is the resolved log level configuration for cell-level components.
	// Inherited from MultigresCluster.Spec.LogLevels.
	// +optional
	LogLevels ComponentLogLevels `json:"logLevels,omitempty"`
}

type CellStatus struct {
	// ObservedGeneration is the most recent generation observed.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Phase represents the aggregated lifecycle state of the cell.
	// +optional
	Phase Phase `json:"phase,omitempty"`

	// Message provides details about the current phase.
	// +optional
	Message string `json:"message,omitempty"`

	// GatewayReplicas is the total number of gateway pods.
	GatewayReplicas int32 `json:"gatewayReplicas"`

	// GatewayReadyReplicas is the number of gateway pods that are ready.
	GatewayReadyReplicas int32 `json:"gatewayReadyReplicas"`

	// GatewayServiceName is the DNS name of the gateway service.
	// +kubebuilder:validation:MaxLength=253
	GatewayServiceName string `json:"gatewayServiceName,omitempty"`
}

type CellStatusSummary struct {
	Ready           bool  `json:"ready"`
	GatewayReplicas int32 `json:"gatewayReplicas"`
}

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

	Spec CellTemplateSpec `json:"spec,omitempty"`
}

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

type CellTemplateSpec struct {
	// MultiGateway configuration.
	// +optional
	MultiGateway *StatelessSpec `json:"multigateway,omitempty"`

	// MultiGatewayPlacement defines optional scheduling settings for multigateway pods.
	// +optional
	MultiGatewayPlacement *PodPlacementSpec `json:"multigatewayPlacement,omitempty"`

	// LocalTopoServer configuration (optional).
	// +optional
	LocalTopoServer *LocalTopoServerSpec `json:"localTopoServer,omitempty"`
}

type ClusterImages struct {
	// ImagePullPolicy overrides the default image pull policy.
	// +optional
	// +kubebuilder:validation:Enum=Always;Never;IfNotPresent
	ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`

	// ImagePullSecrets is a list of references to secrets in the same namespace.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// Component Images
	// +optional
	MultiGateway ImageRef `json:"multigateway,omitempty"`
	// +optional
	MultiOrch ImageRef `json:"multiorch,omitempty"`
	// +optional
	MultiPooler ImageRef `json:"multipooler,omitempty"`
	// +optional
	MultiAdmin ImageRef `json:"multiadmin,omitempty"`
	// +optional
	MultiAdminWeb ImageRef `json:"multiadminWeb,omitempty"`
	// +optional
	Postgres ImageRef `json:"postgres,omitempty"`
}

type ComponentLogLevels struct {
	// +optional
	Pgctld LogLevel `json:"pgctld,omitempty"`
	// +optional
	Multipooler LogLevel `json:"multipooler,omitempty"`
	// +optional
	Multiorch LogLevel `json:"multiorch,omitempty"`
	// +optional
	Multiadmin LogLevel `json:"multiadmin,omitempty"`
	// +optional
	Multigateway LogLevel `json:"multigateway,omitempty"`
}

type ContainerConfig struct {
	// Resources defines the compute resource requirements.
	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`
}

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

	Spec CoreTemplateSpec `json:"spec,omitempty"`
}

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

type CoreTemplateSpec struct {
	// GlobalTopoServer configuration.
	// Uses TopoServerSpec directly (Managed Etcd only).
	// +optional
	GlobalTopoServer *TopoServerSpec `json:"globalTopoServer,omitempty"`

	// MultiAdmin configuration.
	// +optional
	MultiAdmin *StatelessSpec `json:"multiadmin,omitempty"`

	// MultiAdminWeb configuration.
	// +optional
	MultiAdminWeb *StatelessSpec `json:"multiadminWeb,omitempty"`
}

type DatabaseConfig struct {
	// Name is the logical name of the database.
	Name DatabaseName `json:"name"`

	// Default indicates if this is the system default database.
	// +optional
	Default bool `json:"default,omitempty"`

	// TableGroups is a list of table groups.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:XValidation:rule="self.filter(x, has(x.default) && x.default).size() == 1",message="every database must have exactly one tablegroup marked as default"
	// +kubebuilder:validation:MaxItems=20
	TableGroups []TableGroupConfig `json:"tablegroups,omitempty"`

	// Backup overrides the global backup configuration for this specific database.
	// +optional
	Backup *BackupConfig `json:"backup,omitempty"`

	// DurabilityPolicy overrides the cluster-level durability policy for this database.
	// See MultigresClusterSpec.DurabilityPolicy for supported values.
	// +optional
	DurabilityPolicy string `json:"durabilityPolicy,omitempty"`
}

type DatabaseName string

type DatabaseStatusSummary struct {
	ReadyShards int32 `json:"readyShards"`
	TotalShards int32 `json:"totalShards"`
}

type EndpointUrl string

type EtcdSpec struct {
	// Image is the Etcd container image.
	// +optional
	Image ImageRef `json:"image,omitempty"`

	// Replicas is the desired number of etcd members.
	// Immutable after cluster creation — etcd does not support dynamic member addition
	// with static bootstrap. Must be an odd number for proper quorum fault tolerance.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:XValidation:rule="self % 2 == 1",message="etcd replicas must be an odd number (1, 3, 5); even numbers provide no additional fault tolerance over the next lower odd number"
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// Storage configuration for Etcd data.
	// +optional
	Storage StorageSpec `json:"storage,omitempty"`

	// Resources defines the compute resource requirements.
	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`

	// RootPath is the etcd prefix for this cluster.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=512
	RootPath string `json:"rootPath,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle for etcd volumes.
	// Overrides GlobalTopoServerSpec and MultigresCluster settings.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`
}

type ExternalAdminWebConfig struct {
	// Enabled controls whether external admin web exposure is enabled.
	// The global Service remains ClusterIP; external reachability is provided
	// via explicitly assigned external IPs and platform networking.
	Enabled bool `json:"enabled"`

	// ExternalIPs are externally routable addresses assigned to the global
	// multiadmin-web Service. These are surfaced via Service.spec.externalIPs.
	// +optional
	// +kubebuilder:validation:MaxItems=10
	ExternalIPs []IPAddress `json:"externalIPs,omitempty"`

	// Annotations are applied to the global multiadmin-web Service metadata.
	// The operator owns exactly these annotation keys via SSA field ownership.
	// +optional
	// +kubebuilder:validation:MaxProperties=20
	Annotations map[string]string `json:"annotations,omitempty"`
}

type ExternalGatewayConfig struct {
	// Enabled controls whether external gateway exposure is enabled.
	// The global Service remains ClusterIP; external reachability is provided
	// via explicitly assigned external IPs and platform networking.
	Enabled bool `json:"enabled"`

	// ExternalIPs are externally routable addresses assigned to the global
	// multigateway Service. These are surfaced via Service.spec.externalIPs.
	// +optional
	// +kubebuilder:validation:MaxItems=10
	ExternalIPs []IPAddress `json:"externalIPs,omitempty"`

	// Annotations are applied to the global multigateway Service metadata.
	// The operator owns exactly these annotation keys via SSA field ownership.
	// +optional
	// +kubebuilder:validation:MaxProperties=20
	Annotations map[string]string `json:"annotations,omitempty"`
}

type ExternalTopoServerSpec struct {
	// Endpoints is a list of client URLs.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=20
	// +kubebuilder:validation:XValidation:rule="self.all(x, x.matches('^https?://'))",message="endpoints must be valid URLs"
	// +listType=set
	Endpoints []EndpointUrl `json:"endpoints"`

	// Implementation is the topology implementation type (e.g., "etcd", "memory").
	// Defaults to "etcd" if not specified.
	// +optional
	Implementation string `json:"implementation,omitempty"`

	// CASecret is the name of the secret containing the CA certificate.
	// +optional
	// +kubebuilder:validation:MaxLength=253
	CASecret string `json:"caSecret,omitempty"`

	// ClientCertSecret is the name of the secret containing the client cert/key.
	// +optional
	// +kubebuilder:validation:MaxLength=253
	ClientCertSecret string `json:"clientCertSecret,omitempty"`

	// RootPath is the etcd prefix for this cluster.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=512
	RootPath string `json:"rootPath,omitempty"`
}

type FilesystemBackupConfig struct {
	// Path is the filesystem directory for backups.
	// Defaults to "/backups".
	// +optional
	Path string `json:"path,omitempty"`

	// Storage defines the PVC configuration for the backup volume.
	// This volume is shared by all pools in the shard (per-cell).
	// +optional
	Storage StorageSpec `json:"storage,omitempty"`
}

type GatewayStatus struct {
	// ExternalEndpoint is the hostname or IP for the external gateway endpoint,
	// sourced from externalIPs or load balancer ingress (in that priority).
	// Empty when no external endpoint has been provisioned.
	ExternalEndpoint string `json:"externalEndpoint"`
}

type GlobalTopoServerRef struct {
	// Address is the DNS address of the topology server.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=512
	Address string `json:"address"`

	// RootPath is the etcd prefix for this cluster.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=512
	RootPath string `json:"rootPath"`

	// Implementation defines the client implementation (e.g. "etcd").
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	Implementation string `json:"implementation"`
}

type GlobalTopoServerSpec struct {
	// Etcd defines an inline managed Etcd cluster.
	// +optional
	Etcd *EtcdSpec `json:"etcd,omitempty"`

	// External defines connection details for an unmanaged, external topo server.
	// +optional
	External *ExternalTopoServerSpec `json:"external,omitempty"`

	// TemplateRef refers to a CoreTemplate to load configuration from.
	// +optional
	TemplateRef TemplateRef `json:"templateRef,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle for topology server.
	// Overrides MultigresCluster setting.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`
}

type IPAddress string

type ImageRef string

type InitdbArgs string

type LocalTopoServerSpec struct {
	// Etcd defines an inline managed Etcd cluster.
	// +optional
	Etcd *EtcdSpec `json:"etcd,omitempty"`

	// External defines connection details for an unmanaged, external topo server.
	// +optional
	External *ExternalTopoServerSpec `json:"external,omitempty"`
}

type LogLevel string

type MultiAdminConfig struct {
	// Spec defines the inline configuration.
	// +optional
	Spec *StatelessSpec `json:"spec,omitempty"`

	// TemplateRef refers to a CoreTemplate to load configuration from.
	// +optional
	TemplateRef TemplateRef `json:"templateRef,omitempty"`
}

type MultiAdminWebConfig struct {
	// Spec defines the inline configuration.
	// +optional
	Spec *StatelessSpec `json:"spec,omitempty"`

	// TemplateRef refers to a CoreTemplate to load configuration from.
	// +optional
	TemplateRef TemplateRef `json:"templateRef,omitempty"`
}

type MultiOrchSpec struct {
	StatelessSpec `json:",inline"`

	// Placement defines optional scheduling settings for multiorch pods.
	// +optional
	Placement *PodPlacementSpec `json:"placement,omitempty"`

	// Cells defines the list of cells where this MultiOrch should be deployed.
	// If empty, it defaults to all cells where pools are defined.
	// +optional
	// +listType=set
	// +kubebuilder:validation:MaxItems=50
	Cells []CellName `json:"cells,omitempty"`
}

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

	Spec   MultigresClusterSpec   `json:"spec,omitempty"`
	Status MultigresClusterStatus `json:"status,omitempty"`
}

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

type MultigresClusterSpec struct {
	// Images defines the container images for all components in the cluster.
	// +optional
	Images ClusterImages `json:"images,omitempty"`

	// LogLevels configures the --log-level flag for each multigres data-plane component.
	// All fields default to "info" if not specified.
	// +optional
	LogLevels ComponentLogLevels `json:"logLevels,omitempty"`

	// TemplateDefaults defines the default templates to use for components
	// that do not have explicit specs.
	// +optional
	TemplateDefaults TemplateDefaults `json:"templateDefaults,omitempty"`

	// GlobalTopoServer defines the cluster-wide global topology server.
	// +optional
	GlobalTopoServer *GlobalTopoServerSpec `json:"globalTopoServer,omitempty"`

	// MultiAdmin defines the configuration for the MultiAdmin component.
	// +optional
	MultiAdmin *MultiAdminConfig `json:"multiadmin,omitempty"`

	// MultiAdminWeb defines the configuration for the MultiAdminWeb component.
	// +optional
	MultiAdminWeb *MultiAdminWebConfig `json:"multiadminWeb,omitempty"`

	// Cells defines the list of cells (failure domains) in the cluster.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=50
	// +kubebuilder:validation:XValidation:rule="oldSelf.all(c, c.name in self.map(x, x.name))",message="Cells cannot be removed or renamed (Append-Only)"
	Cells []CellConfig `json:"cells,omitempty"`

	// Databases defines the logical databases, table groups, and sharding.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=1
	// +kubebuilder:validation:XValidation:rule="self.all(db, db.name == 'postgres' && db.default == true)",message="in v1alpha1, only the single system database named 'postgres' (marked default: true) is supported"
	Databases []DatabaseConfig `json:"databases,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle management for all stateful components.
	// Defaults to Retain/Delete — PVCs are kept on cluster deletion but removed on scale-down.
	// +optional
	// +kubebuilder:default={whenDeleted: "Retain", whenScaled: "Delete"}
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`

	// Observability configures OpenTelemetry for data-plane components.
	// When nil, data-plane pods inherit the operator's own OTEL environment
	// variables at reconcile time. Set fields to override or disable.
	// +optional
	Observability *ObservabilityConfig `json:"observability,omitempty"`

	// Backup configures the default backup settings for the entire cluster.
	// +optional
	Backup *BackupConfig `json:"backup,omitempty"`

	// ExternalGateway controls external exposure of the global multigateway Service.
	// When nil or enabled: false, the Service remains ClusterIP.
	// +optional
	ExternalGateway *ExternalGatewayConfig `json:"externalGateway,omitempty"`

	// ExternalAdminWeb controls external exposure of the global multiadmin-web Service.
	// When nil or enabled: false, the Service remains ClusterIP.
	// +optional
	ExternalAdminWeb *ExternalAdminWebConfig `json:"externalAdminWeb,omitempty"`

	// TopologyPruning controls whether stale topology entries are pruned.
	// Default: enabled (nil means pruning is on).
	// +optional
	TopologyPruning *TopologyPruningConfig `json:"topologyPruning,omitempty"`

	// DurabilityPolicy sets the default durability policy for all databases in the cluster.
	// This value is written to the topology and determines how multiorch enforces
	// synchronous replication acknowledgment during failover.
	//
	// Currently supported values (upstream multiorch):
	//   - "AT_LEAST_2": any 2 nodes must acknowledge writes (single-cell quorum)
	//   - "MULTI_CELL_AT_LEAST_2": any 2 nodes from different cells must acknowledge (cross-AZ quorum)
	//
	// Additional user-defined policies may be supported in future upstream releases.
	// Defaults to "AT_LEAST_2" if not set.
	// +optional
	DurabilityPolicy string `json:"durabilityPolicy,omitempty"`
}

type MultigresClusterStatus struct {
	// ObservedGeneration is the most recent generation observed.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Phase represents the aggregated lifecycle state of the cluster.
	// +optional
	Phase Phase `json:"phase,omitempty"`

	// Message provides details about the current phase (e.g. error messages).
	// +optional
	Message string `json:"message,omitempty"`

	// Cells status summary.
	// +optional
	// +kubebuilder:validation:MaxProperties=50
	Cells map[CellName]CellStatusSummary `json:"cells,omitempty"`

	// Gateway reports the external gateway state.
	// Nil when spec.externalGateway is nil or disabled.
	// +optional
	Gateway *GatewayStatus `json:"gateway,omitempty"`

	// AdminWeb reports the external admin web state.
	// Nil when spec.externalAdminWeb is nil or disabled.
	// +optional
	AdminWeb *AdminWebStatus `json:"adminWeb,omitempty"`

	// Databases status summary.
	// +optional
	// +kubebuilder:validation:MaxProperties=50
	Databases map[DatabaseName]DatabaseStatusSummary `json:"databases,omitempty"`

	// ResolvedTemplates records which templates were resolved during the last
	// successful reconciliation. Used for targeted template-change enqueuing.
	// +optional
	ResolvedTemplates *ResolvedTemplates `json:"resolvedTemplates,omitempty"`
}

type ObservabilityConfig struct {
	// OTLPEndpoint is the OTLP collector endpoint URL.
	// Maps to OTEL_EXPORTER_OTLP_ENDPOINT.
	// Example: "http://otel-collector:4318"
	// Set to "disabled" to explicitly disable telemetry.
	// +optional
	OTLPEndpoint string `json:"otlpEndpoint,omitempty"`

	// OTLPProtocol is the OTLP transport protocol.
	// Maps to OTEL_EXPORTER_OTLP_PROTOCOL.
	// +optional
	// +kubebuilder:validation:Enum="http/protobuf";"grpc"
	OTLPProtocol string `json:"otlpProtocol,omitempty"`

	// TracesExporter selects the trace exporter.
	// Maps to OTEL_TRACES_EXPORTER.
	// Upstream defaults to "none" — set to "otlp" to enable tracing.
	// +optional
	// +kubebuilder:validation:Enum=otlp;none;console
	TracesExporter string `json:"tracesExporter,omitempty"`

	// MetricsExporter selects the metrics exporter.
	// Maps to OTEL_METRICS_EXPORTER.
	// Upstream defaults to "none" — set to "otlp" to enable metrics export.
	// +optional
	// +kubebuilder:validation:Enum=otlp;none;console
	MetricsExporter string `json:"metricsExporter,omitempty"`

	// LogsExporter selects the logs exporter.
	// Maps to OTEL_LOGS_EXPORTER.
	// Upstream defaults to "none" — set to "otlp" to enable log export.
	// +optional
	// +kubebuilder:validation:Enum=otlp;none;console
	LogsExporter string `json:"logsExporter,omitempty"`

	// MetricExportInterval in milliseconds.
	// Maps to OTEL_METRIC_EXPORT_INTERVAL.
	// +optional
	MetricExportInterval string `json:"metricExportInterval,omitempty"`

	// MetricsTemporality selects the temporality preference.
	// Maps to OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE.
	// +optional
	// +kubebuilder:validation:Enum=cumulative;delta
	MetricsTemporality string `json:"metricsTemporality,omitempty"`

	// HistogramAggregation selects the default histogram aggregation.
	// Maps to OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION.
	// Use "base2_exponential_bucket_histogram" for native/exponential histograms
	// which are more compact and accurate than explicit bucket histograms.
	// +optional
	// +kubebuilder:validation:Enum=base2_exponential_bucket_histogram;explicit_bucket_histogram
	HistogramAggregation string `json:"histogramAggregation,omitempty"`

	// TracesSampler selects the sampler.
	// Maps to OTEL_TRACES_SAMPLER.
	// Standard values: always_on, always_off, parentbased_traceidratio.
	// Use "multigres_custom" for file-based sampling (requires SamplingConfigRef).
	// +optional
	TracesSampler string `json:"tracesSampler,omitempty"`

	// SamplingConfigRef references a ConfigMap containing the sampling config file.
	// Only used when tracesSampler is "multigres_custom".
	// The ConfigMap is mounted at /etc/otel/ and the file path is passed
	// via OTEL_TRACES_SAMPLER_CONFIG.
	// +optional
	SamplingConfigRef *SamplingConfigRef `json:"samplingConfigRef,omitempty"`
}

type PVCDeletionPolicy struct {
	// WhenDeleted controls PVC deletion when the MultigresCluster is deleted.
	// - Retain (default): PVCs are kept for manual review and recovery
	// - Delete: PVCs are automatically deleted with the cluster
	// +optional
	// +kubebuilder:default=Retain
	WhenDeleted PVCRetentionPolicyType `json:"whenDeleted,omitempty"`

	// WhenScaled controls PVC deletion when replicas are scaled down.
	// - Delete (default): PVCs are automatically deleted when pods are removed
	// - Retain: PVCs from scaled-down pods are kept for manual recovery
	// +optional
	// +kubebuilder:default=Delete
	WhenScaled PVCRetentionPolicyType `json:"whenScaled,omitempty"`
}

type PVCRetentionPolicyType string

type PgBackRestTLSConfig struct {
	// SecretName is the name of an existing Secret containing pgBackRest TLS certificates.
	// The Secret must contain three keys: ca.crt, tls.crt, tls.key.
	// This is directly compatible with cert-manager Certificate resources.
	// When empty, the operator generates and rotates certificates automatically.
	// +optional
	SecretName string `json:"secretName,omitempty"`
}

type Phase string

type PodPlacementSpec struct {
	// Tolerations defines the pod tolerations for scheduling onto tainted nodes.
	// +optional
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
}

type PoolName string

type PoolSpec struct {
	// Type of the pool. Currently only "readWrite" is supported.
	// +kubebuilder:validation:Enum=readWrite
	// +optional
	Type PoolType `json:"type,omitempty"`

	// Cells defines the list of cells where this Pool should be deployed.
	// +optional
	// +listType=set
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=10
	// +kubebuilder:validation:XValidation:rule="oldSelf.all(c, c in self)",message="Cells cannot be removed from a pool (Append-Only)"
	Cells []CellName `json:"cells,omitempty"`

	// ReplicasPerCell is the desired number of Postgres data pods PER CELL in this pool.
	// Sidecars (like Multipooler) will scale alongside the Postgres pods.
	// Minimum 1 is required; readWrite pools need at least 3 for zero-downtime rolling upgrades
	// (AT_LEAST_2 durability requires 1 primary + 2 standbys to maintain quorum during drain).
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=32
	// +optional
	ReplicasPerCell *int32 `json:"replicasPerCell,omitempty"`

	// Storage defines the storage configuration for the pool's data volumes.
	// +optional
	Storage StorageSpec `json:"storage,omitempty"`

	// Postgres container configuration.
	// +optional
	Postgres ContainerConfig `json:"postgres,omitempty"`

	// Multipooler container configuration.
	// +optional
	Multipooler ContainerConfig `json:"multipooler,omitempty"`

	// Affinity defines the pod's scheduling constraints.
	// +optional
	Affinity *corev1.Affinity `json:"affinity,omitempty"`

	// Tolerations defines the pod tolerations for scheduling onto tainted nodes.
	// +optional
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`

	// FSGroup sets the pod-level fsGroup for shared volume and socket access across
	// pool containers. When unset, runtime defaults apply.
	// +optional
	// +kubebuilder:validation:Minimum=1
	FSGroup *int64 `json:"fsGroup,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle for this pool.
	// Overrides Shard, TableGroup, and MultigresCluster settings.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`
}

type PoolType string

type PostgresConfigRef struct {
	// Name is the name of the ConfigMap.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`

	// Key is the key within the ConfigMap's data that contains the postgresql.conf content.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	Key string `json:"key"`
}

type Region string

type ResolvedTemplates struct {
	// CoreTemplates is the deduplicated set of CoreTemplate names resolved.
	// +optional
	CoreTemplates []TemplateRef `json:"coreTemplates,omitempty"`

	// CellTemplates is the deduplicated set of CellTemplate names resolved.
	// +optional
	CellTemplates []TemplateRef `json:"cellTemplates,omitempty"`

	// ShardTemplates is the deduplicated set of ShardTemplate names resolved.
	// +optional
	ShardTemplates []TemplateRef `json:"shardTemplates,omitempty"`
}

type S3BackupConfig struct {
	// +kubebuilder:validation:MinLength=1
	Bucket string `json:"bucket"`
	// +kubebuilder:validation:MinLength=1
	Region            string `json:"region"`
	Endpoint          string `json:"endpoint,omitempty"`
	KeyPrefix         string `json:"keyPrefix,omitempty"`
	UseEnvCredentials bool   `json:"useEnvCredentials,omitempty"`

	// CredentialsSecret is the name of the Secret containing AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
	// +optional
	CredentialsSecret string `json:"credentialsSecret,omitempty"`

	// ServiceAccountName is the name of the ServiceAccount to use for IRSA-based S3 authentication.
	// The ServiceAccount must exist in the same namespace and be annotated with
	// eks.amazonaws.com/role-arn pointing to an IAM role with S3 permissions.
	// The operator does NOT create this ServiceAccount — the user must create it externally.
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`
}

type SamplingConfigRef struct {
	// Name is the ConfigMap name (must be in the same namespace as the CR).
	Name string `json:"name"`

	// Key is the data key within the ConfigMap.
	// +kubebuilder:default="sampling-config.yaml"
	// +optional
	Key string `json:"key,omitempty"`
}

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

	Spec   ShardSpec   `json:"spec,omitempty"`
	Status ShardStatus `json:"status,omitempty"`
}

type ShardConfig struct {
	// Name is the identifier of the shard (e.g., "0", "1").
	// +kubebuilder:validation:XValidation:rule="self == '0-inf'",message="shardName must be strictly equal to '0-inf' in this version"
	Name ShardName `json:"name"`

	// ShardTemplate refers to a ShardTemplate CR.
	// +optional
	ShardTemplate TemplateRef `json:"shardTemplate,omitempty"`

	// Overrides are applied on top of the template.
	// +optional
	Overrides *ShardOverrides `json:"overrides,omitempty"`

	// Spec defines the inline configuration if no template is used.
	// +optional
	Spec *ShardInlineSpec `json:"spec,omitempty"`

	// Backup overrides the table group backup configuration for this specific shard.
	// +optional
	Backup *BackupConfig `json:"backup,omitempty"`
}

type ShardImages struct {
	// ImagePullPolicy overrides the default image pull policy.
	// +optional
	// +kubebuilder:validation:Enum=Always;Never;IfNotPresent
	ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`

	// ImagePullSecrets is a list of references to secrets in the same namespace.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// MultiOrch is the image for the shard orchestrator.
	MultiOrch ImageRef `json:"multiorch"`

	// MultiPooler is the image for the connection pooler sidecar.
	MultiPooler ImageRef `json:"multipooler"`

	// Postgres is the image for the postgres database.
	Postgres ImageRef `json:"postgres"`
}

type ShardInlineSpec struct {
	// MultiOrch configuration.
	// +optional
	MultiOrch MultiOrchSpec `json:"multiorch,omitempty"`

	// InitdbArgs specifies extra arguments passed to initdb during PostgreSQL
	// data directory initialization (e.g., "--locale-provider=icu --icu-locale=en_US.UTF-8").
	// Applied uniformly to all pool pods in this shard.
	// Only takes effect when a pod initializes a new data directory.
	// +optional
	InitdbArgs InitdbArgs `json:"initdbArgs,omitempty"`

	// PostgresConfigRef references a ConfigMap containing custom postgresql.conf overrides.
	// The ConfigMap must exist in the same namespace. When set, the operator mounts it
	// and passes --postgres-config-template to pgctld.
	// +optional
	PostgresConfigRef *PostgresConfigRef `json:"postgresConfigRef,omitempty"`

	// Pools configuration. Keyed by pool name.
	// +optional
	// +kubebuilder:validation:MaxProperties=8
	// +kubebuilder:validation:XValidation:rule="self.all(key, size(key) <= 25)",message="pool names must be <= 25 chars"
	// +kubebuilder:validation:XValidation:rule="oldSelf.all(k, k in self)",message="Pools cannot be removed or renamed in this version (Append-Only)"
	Pools map[PoolName]PoolSpec `json:"pools,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle for pools in this shard.
	// Overrides TableGroup and MultigresCluster settings.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`
}

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

type ShardName string

type ShardOverrides struct {
	// MultiOrch overrides.
	// +optional
	MultiOrch *MultiOrchSpec `json:"multiorch,omitempty"`

	// InitdbArgs overrides the template's initdb arguments.
	// +optional
	InitdbArgs InitdbArgs `json:"initdbArgs,omitempty"`

	// PostgresConfigRef references a ConfigMap containing custom postgresql.conf overrides.
	// The ConfigMap must exist in the same namespace. When set, the operator mounts it
	// and passes --postgres-config-template to pgctld.
	// +optional
	PostgresConfigRef *PostgresConfigRef `json:"postgresConfigRef,omitempty"`

	// Pools overrides. Keyed by pool name.
	// +optional
	// +kubebuilder:validation:MaxProperties=8
	// +kubebuilder:validation:XValidation:rule="self.all(key, size(key) <= 25)",message="pool names must be <= 25 chars"
	// +kubebuilder:validation:XValidation:rule="oldSelf.all(k, k in self)",message="Pools cannot be removed or renamed in this version (Append-Only)"
	Pools map[PoolName]PoolSpec `json:"pools,omitempty"`
}

type ShardResolvedSpec struct {
	// Name is the identifier of the shard.
	// +kubebuilder:validation:MaxLength=63
	Name string `json:"name"`

	// MultiOrch is the fully resolved configuration for the orchestrator.
	MultiOrch MultiOrchSpec `json:"multiorch"`

	// InitdbArgs is the resolved initdb arguments for this shard.
	// +optional
	InitdbArgs InitdbArgs `json:"initdbArgs,omitempty"`

	// PostgresConfigRef references a ConfigMap containing custom postgresql.conf overrides.
	// When set, the operator mounts it and passes --postgres-config-template to pgctld.
	// +optional
	PostgresConfigRef *PostgresConfigRef `json:"postgresConfigRef,omitempty"`

	// Pools is the map of fully resolved data pool configurations.
	// +kubebuilder:validation:MaxProperties=8
	// +kubebuilder:validation:XValidation:rule="self.all(key, size(key) < 63)",message="pool names must be < 63 chars"
	Pools map[PoolName]PoolSpec `json:"pools"`

	// PVCDeletionPolicy controls PVC lifecycle for pools in this shard.
	// Overrides TableGroup and MultigresCluster settings.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`

	// Backup is the backup configuration inherited from MultigresCluster.
	// +optional
	Backup *BackupConfig `json:"backup,omitempty"`
}

type ShardSpec struct {
	// DatabaseName is the name of the logical database this shard belongs to.
	DatabaseName DatabaseName `json:"databaseName"`

	// TableGroupName is the name of the table group this shard belongs to.
	TableGroupName TableGroupName `json:"tableGroupName"`

	// ShardName is the specific identifier for this shard (e.g. "0").
	ShardName ShardName `json:"shardName"`

	// Images defines the container images to be used by this shard (defined globally at MultigresCluster).
	Images ShardImages `json:"images"`

	// GlobalTopoServer is a reference to the global topology server.
	GlobalTopoServer GlobalTopoServerRef `json:"globalTopoServer"`

	// MultiOrch is the fully resolved configuration for the shard orchestrator.
	MultiOrch MultiOrchSpec `json:"multiorch"`

	// InitdbArgs specifies extra arguments for initdb, propagated from the cluster spec.
	// +optional
	InitdbArgs InitdbArgs `json:"initdbArgs,omitempty"`

	// PostgresConfigRef references a ConfigMap containing custom postgresql.conf overrides.
	// When set, the operator mounts it and passes --postgres-config-template to pgctld.
	// +optional
	PostgresConfigRef *PostgresConfigRef `json:"postgresConfigRef,omitempty"`

	// Pools is the map of fully resolved data pool configurations.
	// +kubebuilder:validation:MaxProperties=8
	// +kubebuilder:validation:XValidation:rule="self.all(key, size(key) < 63)",message="pool names must be < 63 chars"
	Pools map[PoolName]PoolSpec `json:"pools"`

	// PVCDeletionPolicy controls PVC lifecycle for this shard's pools.
	// Inherited from MultigresCluster.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`

	// Observability configures OpenTelemetry for shard-level data-plane components.
	// Inherited from MultigresCluster.Spec.Observability by the resolver.
	// +optional
	Observability *ObservabilityConfig `json:"observability,omitempty"`

	// LogLevels is the resolved log level configuration for shard-level components.
	// Inherited from MultigresCluster.Spec.LogLevels.
	// +optional
	LogLevels ComponentLogLevels `json:"logLevels,omitempty"`

	// Backup is the fully resolved backup configuration for this shard.
	// Inherited from MultigresCluster.Spec.Backup by the resolver.
	// +optional
	Backup *BackupConfig `json:"backup,omitempty"`

	// TopologyPruning controls whether stale topology entries are pruned.
	// Inherited from MultigresCluster.
	// +optional
	TopologyPruning *TopologyPruningConfig `json:"topologyPruning,omitempty"`

	// DurabilityPolicy is the resolved durability policy for this shard's database.
	// Inherited from MultigresCluster → Database.
	// +optional
	DurabilityPolicy string `json:"durabilityPolicy,omitempty"`

	// CellTopologyLabels maps cell names to their topology nodeSelector labels.
	// Each entry is a map like {"topology.kubernetes.io/zone": "us-east-1a"}.
	// Propagated from the cluster's cell configs so the shard controller
	// can inject nodeSelector without looking up Cell CRs.
	// +optional
	CellTopologyLabels map[CellName]map[string]string `json:"cellTopologyLabels,omitempty"`

	// Replicas is the total number of desired replicas across all pools in this shard.
	// This field is used by the scale subresource to support HPA and PDBs.
	// It is automatically populated by the cluster-handler based on the sum of ReplicasPerCell.
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`
}

type ShardStatus struct {
	// ObservedGeneration is the most recent generation observed.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Phase represents the aggregated lifecycle state of the shard.
	// +optional
	Phase Phase `json:"phase,omitempty"`

	// Message provides details about the current phase.
	// +optional
	Message string `json:"message,omitempty"`

	// Cells is a list of cells this shard is currently deployed to.
	// +optional
	// +listType=set
	// +kubebuilder:validation:MaxItems=50
	Cells []CellName `json:"cells,omitempty"`

	// OrchReady indicates if the MultiOrch component is ready.
	OrchReady bool `json:"orchReady"`

	// PoolsReady indicates if all data pools are ready.
	PoolsReady bool `json:"poolsReady"`

	// LastBackupTime is the timestamp of the most recent completed backup.
	// +optional
	LastBackupTime *metav1.Time `json:"lastBackupTime,omitempty"`

	// LastBackupType is the type of the most recent completed backup (full, diff, incr).
	// +optional
	// +kubebuilder:validation:Enum=full;diff;incr
	LastBackupType string `json:"lastBackupType,omitempty"`

	// PodRoles maps pod names to their database roles (e.g. PRIMARY, REPLICA, DRAINED).
	// +optional
	PodRoles map[string]string `json:"podRoles,omitempty"`

	// ReadyReplicas is the total number of ready pods across all pools in this shard.
	// +optional
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
}

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

	Spec ShardTemplateSpec `json:"spec,omitempty"`
}

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

type ShardTemplateSpec struct {
	// MultiOrch configuration.
	// +optional
	MultiOrch *MultiOrchSpec `json:"multiorch,omitempty"`

	// InitdbArgs specifies extra arguments passed to initdb during PostgreSQL
	// data directory initialization (e.g., "--locale-provider=icu --icu-locale=en_US.UTF-8").
	// Applied to all pool pods in shards using this template.
	// Only takes effect when a pod initializes a new data directory.
	// +optional
	InitdbArgs InitdbArgs `json:"initdbArgs,omitempty"`

	// PostgresConfigRef references a ConfigMap containing custom postgresql.conf overrides.
	// The ConfigMap must exist in the same namespace. When set, the operator mounts it
	// and passes --postgres-config-template to pgctld.
	// +optional
	PostgresConfigRef *PostgresConfigRef `json:"postgresConfigRef,omitempty"`

	// +optional
	// +kubebuilder:validation:MaxProperties=8
	// +kubebuilder:validation:XValidation:rule="self.all(key, size(key) < 63)",message="pool names must be < 63 chars"
	// +kubebuilder:validation:XValidation:rule="oldSelf.all(k, k in self)",message="Pools cannot be removed or renamed in this version (Append-Only)"
	Pools map[PoolName]PoolSpec `json:"pools,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle management for this shard template.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`
}

type StatelessSpec struct {
	// Replicas is the desired number of pods.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=128
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// Resources defines the compute resource requirements.
	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`

	// Affinity defines the pod's scheduling constraints.
	// +optional
	Affinity *corev1.Affinity `json:"affinity,omitempty"`

	// PodAnnotations are annotations to add to the pods.
	// +optional
	// +kubebuilder:validation:MaxProperties=20
	// +kubebuilder:validation:XValidation:rule="self.all(k, size(k) < 64 && size(self[k]) < 256)",message="annotation keys must be <64 chars and values <256 chars"
	PodAnnotations map[string]string `json:"podAnnotations,omitempty"`

	// PodLabels are additional labels to add to the pods.
	// +optional
	// +kubebuilder:validation:MaxProperties=20
	// +kubebuilder:validation:XValidation:rule="self.all(k, size(k) < 64 && size(self[k]) < 64)",message="label keys and values must be <64 chars"
	PodLabels map[string]string `json:"podLabels,omitempty"`
}

type StorageSpec struct {
	// Size of the persistent volume.
	// +kubebuilder:validation:Pattern="^([0-9]+)(.+)$"
	// +kubebuilder:validation:MaxLength=63
	// +optional
	Size string `json:"size,omitempty"`

	// Class is the StorageClass name.
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	Class string `json:"class,omitempty"`

	// AccessModes contains the desired access modes the volume should have.
	// More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes
	// +optional
	AccessModes []corev1.PersistentVolumeAccessMode `json:"accessModes,omitempty"`
}

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

	Spec   TableGroupSpec   `json:"spec,omitempty"`
	Status TableGroupStatus `json:"status,omitempty"`
}

type TableGroupConfig struct {
	// Name is the logical name of the table group.
	Name TableGroupName `json:"name"`

	// Default indicates if this is the default/unsharded group.
	// +optional
	Default bool `json:"default,omitempty"`

	// Shards defines the list of shards.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=32
	Shards []ShardConfig `json:"shards,omitempty"`

	// Backup overrides the database backup configuration for this table group.
	// +optional
	Backup *BackupConfig `json:"backup,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle for shards in this table group.
	// Overrides MultigresCluster setting.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`
}

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

type TableGroupName string

type TableGroupSpec struct {
	// DatabaseName is the name of the logical database.
	DatabaseName DatabaseName `json:"databaseName"`

	// TableGroupName is the name of this table group.
	TableGroupName TableGroupName `json:"tableGroupName"`

	// IsDefault indicates if this is the default/unsharded group for the database.
	// +optional
	IsDefault bool `json:"default,omitempty"`

	// Images defines the container images used for child shards - defined globally in MultigresCluster.
	Images ShardImages `json:"images"`

	// GlobalTopoServer is a reference to the global topology server.
	GlobalTopoServer GlobalTopoServerRef `json:"globalTopoServer"`

	// Shards is the list of FULLY RESOLVED shard specifications.
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=32
	Shards []ShardResolvedSpec `json:"shards"`

	// PVCDeletionPolicy controls PVC lifecycle for all shards in this table group.
	// Inherited from MultigresCluster.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`

	// Observability configures OpenTelemetry for shard-level data-plane components.
	// Inherited from MultigresCluster.Spec.Observability.
	// +optional
	Observability *ObservabilityConfig `json:"observability,omitempty"`

	// LogLevels is the resolved log level configuration for shard-level components.
	// Inherited from MultigresCluster.Spec.LogLevels.
	// +optional
	LogLevels ComponentLogLevels `json:"logLevels,omitempty"`

	// Backup is the backup configuration inherited from MultigresCluster -> Database -> TableGroup.
	// +optional
	Backup *BackupConfig `json:"backup,omitempty"`

	// CellTopologyLabels maps cell names to their topology nodeSelector labels.
	// Propagated from the cluster's cell configs.
	// +optional
	CellTopologyLabels map[CellName]map[string]string `json:"cellTopologyLabels,omitempty"`

	// TopologyPruning controls whether stale topology entries are pruned.
	// Inherited from MultigresCluster.
	// +optional
	TopologyPruning *TopologyPruningConfig `json:"topologyPruning,omitempty"`

	// DurabilityPolicy is the resolved durability policy for this database.
	// Inherited from MultigresCluster → Database.
	// +optional
	DurabilityPolicy string `json:"durabilityPolicy,omitempty"`
}

type TableGroupStatus struct {
	// ObservedGeneration is the most recent generation observed.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Phase represents the aggregated lifecycle state of the table group.
	// +optional
	Phase Phase `json:"phase,omitempty"`

	// Message provides details about the current phase.
	// +optional
	Message string `json:"message,omitempty"`

	// ReadyShards is the number of shards that have reached the Healthy phase.
	ReadyShards int32 `json:"readyShards"`
	// TotalShards is the total number of shards declared for this table group.
	TotalShards int32 `json:"totalShards"`
}

type TemplateDefaults struct {
	// CoreTemplate is the default template for global components.
	// +optional
	CoreTemplate TemplateRef `json:"coreTemplate,omitempty"`
	// CellTemplate is the default template for cells.
	// +optional
	CellTemplate TemplateRef `json:"cellTemplate,omitempty"`
	// ShardTemplate is the default template for shards.
	// +optional
	ShardTemplate TemplateRef `json:"shardTemplate,omitempty"`
}

type TemplateRef string

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

	Spec   TopoServerSpec   `json:"spec,omitempty"`
	Status TopoServerStatus `json:"status,omitempty"`
}

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

type TopoServerSpec struct {
	// Etcd defines the configuration if using Etcd.
	Etcd *EtcdSpec `json:"etcd,omitempty"`

	// PVCDeletionPolicy controls PVC lifecycle for etcd.
	// Inherited from MultigresCluster.
	// +optional
	PVCDeletionPolicy *PVCDeletionPolicy `json:"pvcDeletionPolicy,omitempty"`
}

type TopoServerStatus struct {
	// ObservedGeneration is the most recent generation observed.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Phase represents the aggregated lifecycle state of the toposerver.
	// +optional
	Phase Phase `json:"phase,omitempty"`

	// Message provides details about the current phase.
	// +optional
	Message string `json:"message,omitempty"`

	// ClientService is the name of the service for clients.
	// +optional
	ClientService string `json:"clientService,omitempty"`

	// PeerService is the name of the service for peers.
	// +optional
	PeerService string `json:"peerService,omitempty"`
}

type TopologyPruningConfig struct {
	// Enabled controls whether the operator prunes stale topology entries.
	// When false, the operator still registers entries but never removes them.
	// Default: true (nil or empty means enabled).
	// +optional
	Enabled *bool `json:"enabled,omitempty"`
}

type TopologyReconciliation struct {
	// RegisterCell indicates if the cell should register itself in the topology.
	RegisterCell bool `json:"registerCell"`

	// PrunePoolers indicates if unused poolers should be removed.
	PrunePoolers bool `json:"prunePoolers"`
}

type Zone string