v1alpha1

type AWSProviderConfig struct {
	// Region is the AWS region.
	// +kubebuilder:validation:Required
	Region string `json:"region"`

	// VPCID is the VPC identifier.
	// +optional
	VPCID string `json:"vpcID,omitempty"`

	// SubnetIDs are the subnet identifiers for VM placement.
	// +optional
	SubnetIDs []string `json:"subnetIDs,omitempty"`

	// SecurityGroupIDs are the security group identifiers.
	// +optional
	SecurityGroupIDs []string `json:"securityGroupIDs,omitempty"`
}

type AddonCategory string

type AddonChartSpec struct {
	// Repository is the Helm repository URL.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^https?://`
	Repository string `json:"repository"`

	// Name is the chart name within the repository.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// DefaultVersion is the chart version used when TenantAddon
	// doesn't specify a version. Should be a stable, tested version.
	// +kubebuilder:validation:Required
	DefaultVersion string `json:"defaultVersion"`

	// AvailableVersions lists other versions known to work with Butler.
	// Used for version dropdown in UI. If empty, only defaultVersion shown.
	// +optional
	AvailableVersions []string `json:"availableVersions,omitempty"`
}

type AddonDefaults struct {
	// Namespace is the target namespace for installation.
	// If not specified, defaults to the addon name.
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// ReleaseName is the Helm release name.
	// If not specified, defaults to the addon name.
	// +optional
	ReleaseName string `json:"releaseName,omitempty"`

	// CreateNamespace indicates whether to create the namespace.
	// +kubebuilder:default=true
	// +optional
	CreateNamespace bool `json:"createNamespace,omitempty"`

	// Values are default Helm values applied during installation.
	// These can be overridden in TenantAddon.spec.values.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Values *ExtensionValues `json:"values,omitempty"`

	// Timeout for Helm operations.
	// +kubebuilder:default="10m"
	// +optional
	Timeout string `json:"timeout,omitempty"`
}

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

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

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

type AddonDefinitionSpec struct {
	// DisplayName is the human-readable name shown in the Butler UI.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=64
	DisplayName string `json:"displayName"`

	// Description explains what this addon provides.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=512
	Description string `json:"description"`

	// Category groups addons in the UI for easier discovery.
	// +kubebuilder:validation:Required
	Category AddonCategory `json:"category"`

	// Icon is an emoji or icon identifier for UI display.
	// +kubebuilder:validation:MaxLength=8
	// +optional
	Icon string `json:"icon,omitempty"`

	// Chart specifies the Helm chart to install.
	// +kubebuilder:validation:Required
	Chart AddonChartSpec `json:"chart"`

	// Defaults provides installation defaults.
	// These can be overridden in TenantAddon.
	// +optional
	Defaults *AddonDefaults `json:"defaults,omitempty"`

	// Platform marks this as a core platform addon.
	// Platform addons are installed during cluster bootstrap and cannot
	// be uninstalled via the UI. They appear in a separate section.
	// +kubebuilder:default=false
	// +optional
	Platform bool `json:"platform,omitempty"`

	// DependsOn lists addon names that must be installed first.
	// The TenantAddon controller will wait for these dependencies
	// to be in Installed phase before proceeding.
	// +optional
	DependsOn []string `json:"dependsOn,omitempty"`

	// Maintainer identifies who maintains this addon definition.
	// +optional
	Maintainer *AddonMaintainer `json:"maintainer,omitempty"`

	// Links provides URLs for documentation, source, etc.
	// +optional
	Links *AddonLinks `json:"links,omitempty"`
}

type AddonLinks struct {
	// Documentation URL.
	// +optional
	Documentation string `json:"documentation,omitempty"`

	// Source code URL.
	// +optional
	Source string `json:"source,omitempty"`

	// Project homepage URL.
	// +optional
	Homepage string `json:"homepage,omitempty"`
}

type AddonMaintainer struct {
	// Name of the maintainer.
	// +optional
	Name string `json:"name,omitempty"`

	// Email of the maintainer.
	// +optional
	Email string `json:"email,omitempty"`
}

type AddonStatus struct {
	// Name is the addon name.
	Name string `json:"name"`

	// Version is the installed version.
	Version string `json:"version"`

	// Status is the addon health status.
	// +kubebuilder:validation:Enum=Pending;Installing;Healthy;Degraded;Failed
	Status string `json:"status"`

	// ManagedBy indicates who manages this addon.
	// +kubebuilder:validation:Enum=butler;flux;argocd;manual
	ManagedBy string `json:"managedBy"`
}

type AddonVersions struct {
	// Cilium version.
	// +optional
	Cilium string `json:"cilium,omitempty"`

	// MetalLB version.
	// +optional
	MetalLB string `json:"metallb,omitempty"`

	// CertManager version.
	// +optional
	CertManager string `json:"certManager,omitempty"`

	// Longhorn version.
	// +optional
	Longhorn string `json:"longhorn,omitempty"`

	// Traefik version.
	// +optional
	Traefik string `json:"traefik,omitempty"`

	// FluxCD version.
	// +optional
	FluxCD string `json:"fluxcd,omitempty"`
}

type AddonsSpec struct {
	// CNI configures the Container Network Interface.
	// +optional
	CNI *CNISpec `json:"cni,omitempty"`

	// LoadBalancer configures the load balancer.
	// +optional
	LoadBalancer *LoadBalancerSpec `json:"loadBalancer,omitempty"`

	// CertManager configures cert-manager.
	// +optional
	CertManager *CertManagerSpec `json:"certManager,omitempty"`

	// Storage configures persistent storage.
	// +optional
	Storage *StorageSpec `json:"storage,omitempty"`

	// Ingress configures the ingress controller.
	// +optional
	Ingress *IngressSpec `json:"ingress,omitempty"`

	// GitOps configures GitOps (Flux or ArgoCD).
	// +optional
	GitOps *GitOpsSpec `json:"gitops,omitempty"`
}

type AzureProviderConfig struct {
	// SubscriptionID is the Azure subscription ID.
	// +kubebuilder:validation:Required
	SubscriptionID string `json:"subscriptionID"`

	// ResourceGroup is the Azure resource group.
	// +kubebuilder:validation:Required
	ResourceGroup string `json:"resourceGroup"`

	// Location is the Azure region.
	// +optional
	Location string `json:"location,omitempty"`

	// VNetName is the Azure Virtual Network name.
	// +optional
	VNetName string `json:"vnetName,omitempty"`

	// SubnetName is the subnet within the VNet.
	// +optional
	SubnetName string `json:"subnetName,omitempty"`
}

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

	Spec   ButlerConfigSpec   `json:"spec,omitempty"`
	Status ButlerConfigStatus `json:"status,omitempty"`
}

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

type ButlerConfigSpec struct {
	// MultiTenancy configures how multi-tenancy is handled.
	// +optional
	MultiTenancy MultiTenancyConfig `json:"multiTenancy,omitempty"`

	// DefaultNamespace is the namespace for TenantClusters when not using Teams.
	// Used in Disabled and Optional modes.
	// +kubebuilder:default="butler-tenants"
	// +optional
	DefaultNamespace string `json:"defaultNamespace,omitempty"`

	// DefaultProviderConfigRef references the default ProviderConfig.
	// Used when Teams or TenantClusters don't specify their own.
	// +optional
	DefaultProviderConfigRef *LocalObjectReference `json:"defaultProviderConfigRef,omitempty"`

	// DefaultTeamLimits are the default resource limits for new Teams.
	// Admins can override these when creating individual Teams.
	// +optional
	DefaultTeamLimits *ResourceLimits `json:"defaultTeamLimits,omitempty"`

	// DefaultAddonVersions specifies the default versions for addons.
	// Used when TenantCluster doesn't specify versions.
	// +optional
	DefaultAddonVersions *AddonVersions `json:"defaultAddonVersions,omitempty"`

	// GitProvider configures the default Git provider for GitOps operations.
	// This enables features like exporting clusters to GitOps, enabling Flux
	// on clusters, and managing addons via Git repositories.
	// +optional
	GitProvider *GitProviderConfig `json:"gitProvider,omitempty"`

	// ControlPlaneExposure configures how tenant control planes are exposed.
	// This is a platform-level setting populated from ClusterBootstrap during
	// initial setup and inherited by all TenantClusters.
	// +optional
	ControlPlaneExposure *ControlPlaneExposureSpec `json:"controlPlaneExposure,omitempty"`
}

type ButlerConfigStatus struct {
	// Conditions represent the latest available observations of the config's state.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ObservedGeneration is the last observed generation.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// TeamCount is the current number of Teams.
	// +optional
	TeamCount int32 `json:"teamCount,omitempty"`

	// ClusterCount is the current number of TenantClusters.
	// +optional
	ClusterCount int32 `json:"clusterCount,omitempty"`

	// GitProvider shows the status of the configured Git provider.
	// +optional
	GitProvider *GitProviderStatus `json:"gitProvider,omitempty"`

	// ControlPlaneExposureMode is the active control plane exposure mode.
	// +optional
	ControlPlaneExposureMode ControlPlaneExposureMode `json:"controlPlaneExposureMode,omitempty"`

	// TCPProxyRequired indicates if tcp-proxy is auto-enabled for tenants.
	// True when ControlPlaneExposureMode is Ingress or Gateway.
	// +optional
	TCPProxyRequired bool `json:"tcpProxyRequired,omitempty"`
}

type ButlerControllerAddonSpec struct {
	// Enabled controls whether butler-controller is installed
	// +kubebuilder:default=true
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// Version is the butler-controller version (image tag)
	// +kubebuilder:default="latest"
	// +optional
	Version string `json:"version,omitempty"`

	// Image is the full image reference (overrides default)
	// +optional
	// +kubebuilder:default="ghcr.io/butlerdotdev/butler-controller"
	Image string `json:"image,omitempty"`
}

type CAPIAddonSpec struct {
	// Enabled controls whether CAPI is installed
	// +kubebuilder:default=true
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// Version is the CAPI core version
	// +kubebuilder:default="v1.9.4"
	// +optional
	Version string `json:"version,omitempty"`

	// InfrastructureProviders lists additional infrastructure providers to install
	// The management cluster's provider is ALWAYS included automatically
	// +optional
	InfrastructureProviders []CAPIInfraProviderSpec `json:"infrastructureProviders,omitempty"`
}

type CAPIInfraProviderSpec struct {
	// Name is the provider name
	// +kubebuilder:validation:Enum=harvester;nutanix;proxmox
	Name string `json:"name"`

	// Version overrides the default provider version
	// +optional
	Version string `json:"version,omitempty"`

	// CredentialsSecretRef points to provider credentials
	// Required for providers other than the management cluster's provider
	// +optional
	CredentialsSecretRef *SecretReference `json:"credentialsSecretRef,omitempty"`
}

type CNIAddonSpec struct {
	// Type is the CNI type
	// +kubebuilder:validation:Enum=cilium;none
	// +kubebuilder:default=cilium
	Type string `json:"type,omitempty"`

	// Version is the addon version
	// +optional
	Version string `json:"version,omitempty"`

	// HubbleEnabled enables Hubble observability (Cilium only)
	// +optional
	// +kubebuilder:default=true
	HubbleEnabled bool `json:"hubbleEnabled,omitempty"`
}

type CNISpec struct {
	// Provider is the CNI provider.
	// +kubebuilder:validation:Enum=cilium
	// +kubebuilder:default="cilium"
	// +optional
	Provider string `json:"provider,omitempty"`

	// Version is the addon version.
	// +kubebuilder:validation:Required
	Version string `json:"version"`

	// Values are Helm values for customization.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Values *ExtensionValues `json:"values,omitempty"`
}

type CertManagerAddonSpec struct {
	// Enabled controls whether cert-manager is installed
	// +optional
	// +kubebuilder:default=true
	Enabled *bool `json:"enabled,omitempty"`

	// Version is the addon version
	// +optional
	Version string `json:"version,omitempty"`
}

type CertManagerSpec struct {
	// Enabled indicates whether cert-manager should be installed.
	// +kubebuilder:default=true
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// Version is the addon version.
	// +kubebuilder:validation:Required
	Version string `json:"version"`

	// Values are Helm values for customization.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Values *ExtensionValues `json:"values,omitempty"`
}

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

	Spec   ClusterBootstrapSpec   `json:"spec,omitempty"`
	Status ClusterBootstrapStatus `json:"status,omitempty"`
}

type ClusterBootstrapAddonsSpec struct {
	// CNI defines the CNI configuration
	// +optional
	CNI *CNIAddonSpec `json:"cni,omitempty"`

	// Storage defines storage configuration
	// +optional
	Storage *StorageAddonSpec `json:"storage,omitempty"`

	// LoadBalancer defines load balancer configuration
	// +optional
	LoadBalancer *LoadBalancerAddonSpec `json:"loadBalancer,omitempty"`

	// GitOps defines GitOps configuration
	// +optional
	GitOps *GitOpsAddonSpec `json:"gitOps,omitempty"`

	// ControlPlaneHA defines control plane HA configuration
	// +optional
	ControlPlaneHA *ControlPlaneHAAddonSpec `json:"controlPlaneHA,omitempty"`

	// CertManager defines cert-manager configuration
	// +optional
	CertManager *CertManagerAddonSpec `json:"certManager,omitempty"`

	// Ingress defines ingress controller configuration
	// +optional
	Ingress *IngressAddonSpec `json:"ingress,omitempty"`

	// ControlPlaneProvider defines hosted control plane provider (Steward)
	// +optional
	ControlPlaneProvider *ControlPlaneProviderAddonSpec `json:"controlPlaneProvider,omitempty"`

	// CAPI defines Cluster API configuration
	// +optional
	CAPI *CAPIAddonSpec `json:"capi,omitempty"`

	// ButlerController defines butler-controller configuration
	// +optional
	ButlerController *ButlerControllerAddonSpec `json:"butlerController,omitempty"`

	// Console defines Butler Console configuration
	// +optional
	Console *ConsoleAddonSpec `json:"console,omitempty"`
}

type ClusterBootstrapClusterSpec struct {
	// Name is the cluster name used for resource naming
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	Name string `json:"name"`

	// Topology defines the cluster topology
	// - "single-node": Single control plane node that also runs workloads (no workers needed)
	// - "ha": High-availability with separate control plane and worker nodes (default)
	// +kubebuilder:validation:Enum=single-node;ha
	// +kubebuilder:default=ha
	// +optional
	Topology ClusterTopology `json:"topology,omitempty"`

	// ControlPlane defines control plane node configuration
	// +kubebuilder:validation:Required
	ControlPlane ClusterBootstrapNodePool `json:"controlPlane"`

	// Workers defines worker node configuration
	// Ignored when topology is "single-node"
	// +optional
	Workers *ClusterBootstrapNodePool `json:"workers,omitempty"`
}

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

type ClusterBootstrapMachineStatus struct {
	// Name is the MachineRequest name
	Name string `json:"name"`

	// Role is the machine role (control-plane or worker)
	Role string `json:"role"`

	// Phase is the MachineRequest phase
	Phase string `json:"phase"`

	// IPAddress is the machine's IP address
	// +optional
	IPAddress string `json:"ipAddress,omitempty"`

	// TalosConfigured indicates if Talos config has been applied
	// +optional
	TalosConfigured bool `json:"talosConfigured,omitempty"`

	// Ready indicates if the node has joined the cluster
	// +optional
	Ready bool `json:"ready,omitempty"`
}

type ClusterBootstrapNetworkSpec struct {
	// PodCIDR is the CIDR for pod networking
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^([0-9]{1,3}\.){3}[0-9]{1,3}/[0-9]{1,2}$`
	PodCIDR string `json:"podCIDR"`

	// ServiceCIDR is the CIDR for service networking
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^([0-9]{1,3}\.){3}[0-9]{1,3}/[0-9]{1,2}$`
	ServiceCIDR string `json:"serviceCIDR"`

	// VIP is the virtual IP for the control plane endpoint (kube-vip)
	// This IP is used ONLY for kube-apiserver HA and must NOT be in LoadBalancerPool
	// For single-node topology, the VIP still provides a stable endpoint for the API server
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^([0-9]{1,3}\.){3}[0-9]{1,3}$`
	VIP string `json:"vip"`

	// VIPInterface is the network interface for the VIP (optional, auto-detected)
	// +optional
	VIPInterface string `json:"vipInterface,omitempty"`

	// LoadBalancerPool defines the IP range for MetalLB LoadBalancer services
	// This range must NOT include the VIP address to avoid conflicts between
	// kube-vip (control plane) and MetalLB (services)
	// +optional
	LoadBalancerPool *LoadBalancerPoolSpec `json:"loadBalancerPool,omitempty"`
}

type ClusterBootstrapNodePool struct {
	// Replicas is the number of nodes in this pool
	// For single-node topology, controlPlane.replicas is forced to 1
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=10
	Replicas int32 `json:"replicas"`

	// CPU is the number of CPU cores per node
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=128
	CPU int32 `json:"cpu"`

	// MemoryMB is the memory in MB per node (matches MachineRequest)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=2048
	MemoryMB int32 `json:"memoryMB"`

	// DiskGB is the root disk size in GB per node (matches MachineRequest)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=20
	DiskGB int32 `json:"diskGB"`

	// ExtraDisks defines additional disks to attach to each node
	// Reuses DiskSpec from machinerequest_types.go
	// +optional
	ExtraDisks []DiskSpec `json:"extraDisks,omitempty"`

	// Labels to apply to nodes in this pool
	// +optional
	Labels map[string]string `json:"labels,omitempty"`
}

type ClusterBootstrapPhase string

type ClusterBootstrapSpec struct {
	// Provider is the infrastructure provider type (harvester, nutanix, proxmox)
	// +kubebuilder:validation:Enum=harvester;nutanix;proxmox
	Provider string `json:"provider"`

	// ProviderRef references the ProviderConfig to use for provisioning
	// Reuses existing ProviderReference from common_types.go
	// +kubebuilder:validation:Required
	ProviderRef ProviderReference `json:"providerRef"`

	// Cluster defines the cluster configuration
	// +kubebuilder:validation:Required
	Cluster ClusterBootstrapClusterSpec `json:"cluster"`

	// Network defines network configuration for the cluster
	// +kubebuilder:validation:Required
	Network ClusterBootstrapNetworkSpec `json:"network"`

	// Talos defines Talos-specific configuration
	// +kubebuilder:validation:Required
	Talos ClusterBootstrapTalosSpec `json:"talos"`

	// Addons defines which addons to install
	// +optional
	Addons ClusterBootstrapAddonsSpec `json:"addons,omitempty"`

	// ControlPlaneExposure configures how tenant control planes are exposed.
	// This is a platform-level setting written to ButlerConfig after bootstrap
	// and inherited by all TenantClusters.
	// Defaults to LoadBalancer mode if not specified.
	// +optional
	ControlPlaneExposure *ControlPlaneExposureSpec `json:"controlPlaneExposure,omitempty"`

	// Paused can be set to true to pause reconciliation
	// +optional
	Paused bool `json:"paused,omitempty"`
}

type ClusterBootstrapStatus struct {
	// Phase is the current phase of bootstrap
	// +optional
	Phase ClusterBootstrapPhase `json:"phase,omitempty"`

	// ControlPlaneEndpoint is the endpoint for the control plane
	// +optional
	ControlPlaneEndpoint string `json:"controlPlaneEndpoint,omitempty"`

	// Kubeconfig contains the base64-encoded kubeconfig for the cluster
	// +optional
	Kubeconfig string `json:"kubeconfig,omitempty"`

	// TalosConfig contains the base64-encoded talosconfig for the cluster
	// +optional
	TalosConfig string `json:"talosconfig,omitempty"`

	// ConsoleURL is the URL to access the Butler Console
	// +optional
	ConsoleURL string `json:"consoleURL,omitempty"`

	// Machines contains the status of each machine
	// +optional
	Machines []ClusterBootstrapMachineStatus `json:"machines,omitempty"`

	// FailureReason indicates why bootstrap failed
	// +optional
	FailureReason string `json:"failureReason,omitempty"`

	// FailureMessage provides details about the failure
	// +optional
	FailureMessage string `json:"failureMessage,omitempty"`

	// Conditions represents the current conditions of the ClusterBootstrap
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// LastUpdated is the timestamp of the last status update
	// +optional
	LastUpdated metav1.Time `json:"lastUpdated,omitempty"`

	// ObservedGeneration is the last observed generation
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// AddonsInstalled tracks which addons have been installed
	// +optional
	AddonsInstalled map[string]bool `json:"addonsInstalled,omitempty"`
}

type ClusterBootstrapTalosSpec struct {
	// Version is the Talos version to use
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^v[0-9]+\.[0-9]+\.[0-9]+$`
	Version string `json:"version"`

	// Schematic is the Talos factory schematic ID for the image
	// +kubebuilder:validation:Required
	Schematic string `json:"schematic"`

	// ConfigPatches allows inline Talos config patches
	// +optional
	ConfigPatches []TalosConfigPatch `json:"configPatches,omitempty"`

	// InstallDisk overrides the default install disk
	// +optional
	// +kubebuilder:default="/dev/vda"
	InstallDisk string `json:"installDisk,omitempty"`
}

type ClusterDefaults struct {
	// KubernetesVersion is the default K8s version for new clusters.
	// +optional
	KubernetesVersion string `json:"kubernetesVersion,omitempty"`

	// WorkerCount is the default number of worker nodes.
	// +optional
	// +kubebuilder:validation:Minimum=0
	WorkerCount *int32 `json:"workerCount,omitempty"`

	// WorkerCPU is the default CPU cores per worker.
	// +optional
	// +kubebuilder:validation:Minimum=1
	WorkerCPU *int32 `json:"workerCPU,omitempty"`

	// WorkerMemoryGi is the default memory per worker in Gi.
	// +optional
	// +kubebuilder:validation:Minimum=1
	WorkerMemoryGi *int32 `json:"workerMemoryGi,omitempty"`

	// WorkerDiskGi is the default disk size per worker in Gi.
	// +optional
	// +kubebuilder:validation:Minimum=10
	WorkerDiskGi *int32 `json:"workerDiskGi,omitempty"`

	// DefaultAddons are addons automatically installed on new clusters.
	// +optional
	DefaultAddons []string `json:"defaultAddons,omitempty"`
}

type ClusterTopology string

type ConsoleAddonSpec struct {
	// Enabled controls whether butler-console is installed
	// +kubebuilder:default=false
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// Version is the console version (image tag)
	// +kubebuilder:default="latest"
	// +optional
	Version string `json:"version,omitempty"`

	// Ingress defines ingress configuration for the console
	// +optional
	Ingress *ConsoleIngressSpec `json:"ingress,omitempty"`
}

type ConsoleIngressSpec struct {
	// Enabled controls whether to create an Ingress resource
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// Host is the hostname for the console (e.g., "butler.example.com")
	// If not set and ingress is enabled, uses "butler.<cluster-name>.local"
	// +optional
	Host string `json:"host,omitempty"`

	// ClassName is the ingress class (e.g., "traefik", "nginx")
	// +optional
	ClassName string `json:"className,omitempty"`

	// TLS enables TLS termination
	// +kubebuilder:default=false
	// +optional
	TLS bool `json:"tls,omitempty"`

	// TLSSecretName is the name of the TLS secret
	// +optional
	TLSSecretName string `json:"tlsSecretName,omitempty"`
}

type ControlPlaneExposureMode string

type ControlPlaneExposureSpec struct {
	// Mode determines how tenant API servers are exposed.
	// LoadBalancer: 1 IP per tenant, direct access (default)
	// Ingress: L7 proxy via Ingress controller with TLS passthrough, shared IP
	// Gateway: L4/L7 via Gateway API TLSRoute, shared IP
	// +kubebuilder:default="LoadBalancer"
	// +optional
	Mode ControlPlaneExposureMode `json:"mode,omitempty"`

	// Hostname is the wildcard domain for tenant API servers.
	// Required when Mode is Ingress or Gateway.
	// Example: "*.k8s.platform.example.com"
	// Tenant clusters get: "{cluster}.{namespace}.k8s.platform.example.com"
	// +optional
	Hostname string `json:"hostname,omitempty"`

	// IngressClassName specifies the Ingress class when Mode is Ingress.
	// +optional
	IngressClassName string `json:"ingressClassName,omitempty"`

	// ControllerType specifies the ingress controller type for automatic TLS passthrough.
	// Used when Mode is Ingress. Supported values:
	// - "haproxy": Uses haproxy.org/ssl-passthrough annotation
	// - "nginx": Uses nginx.ingress.kubernetes.io/ssl-passthrough annotation
	// - "traefik": Creates IngressRouteTCP instead of standard Ingress
	// - "generic": No automatic annotations, use custom annotations in Steward config
	// +kubebuilder:validation:Enum=haproxy;nginx;traefik;generic
	// +optional
	ControllerType string `json:"controllerType,omitempty"`

	// GatewayRef references the Gateway resource when Mode is Gateway.
	// Format: "namespace/name"
	// +optional
	GatewayRef string `json:"gatewayRef,omitempty"`
}

type ControlPlaneHAAddonSpec struct {
	// Type is the control plane HA type
	// +kubebuilder:validation:Enum=kube-vip;none
	// +kubebuilder:default=kube-vip
	Type string `json:"type,omitempty"`

	// Version is the addon version
	// +optional
	Version string `json:"version,omitempty"`
}

type ControlPlaneProviderAddonSpec struct {
	// Type is the control plane provider type
	// +kubebuilder:validation:Enum=steward;kamaji;none
	// +kubebuilder:default=steward
	Type string `json:"type,omitempty"`

	// Enabled controls whether Steward is installed
	// +optional
	// +kubebuilder:default=true
	Enabled *bool `json:"enabled,omitempty"`

	// Version is the addon version
	// +optional
	Version string `json:"version,omitempty"`
}

type ControlPlaneSpec struct {
	// Replicas is the number of API server replicas.
	// Steward manages high availability automatically.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3
	// +optional
	Replicas int32 `json:"replicas,omitempty"`

	// DataStoreRef references the Steward DataStore to use.
	// If not specified, the default DataStore is used.
	// +optional
	DataStoreRef *LocalObjectReference `json:"dataStoreRef,omitempty"`

	// ServiceType for the control plane endpoint.
	// If not specified, inherits from ButlerConfig.spec.controlPlaneExposure.mode.
	// Only set this to override the platform-level setting for this specific cluster.
	// +kubebuilder:validation:Enum=LoadBalancer;NodePort;ClusterIP
	// +optional
	ServiceType string `json:"serviceType,omitempty"`

	// CertSANs are additional Subject Alternative Names for the API server certificate.
	// Use this to add custom DNS names or IPs for API server access.
	// +optional
	CertSANs []string `json:"certSANs,omitempty"`

	// ExternalCloudProvider enables --cloud-provider=external on apiserver and controller-manager.
	// Required for Harvester, vSphere, and other infrastructure providers.
	// +kubebuilder:default=true
	// +optional
	ExternalCloudProvider *bool `json:"externalCloudProvider,omitempty"`
}

type DiskSpec struct {
	// SizeGB is the disk size in gigabytes.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=1
	SizeGB int32 `json:"sizeGB"`

	// StorageClass is the provider-specific storage class or tier.
	// +optional
	StorageClass string `json:"storageClass,omitempty"`
}

type ExtensionValues struct {
	// Raw is the raw JSON/YAML values.
	// +optional
	Raw []byte `json:"-"`
}

type GCPProviderConfig struct {
	// ProjectID is the GCP project identifier.
	// +kubebuilder:validation:Required
	ProjectID string `json:"projectID"`

	// Region is the GCP region.
	// +kubebuilder:validation:Required
	Region string `json:"region"`

	// Network is the VPC network name.
	// +optional
	Network string `json:"network,omitempty"`

	// Subnetwork is the subnetwork name.
	// +optional
	Subnetwork string `json:"subnetwork,omitempty"`
}

type GitOpsAddonSpec struct {
	// Type is the GitOps type
	// +kubebuilder:validation:Enum=flux;none
	// +kubebuilder:default=flux
	Type string `json:"type,omitempty"`

	// Enabled controls whether GitOps is installed
	// +optional
	// +kubebuilder:default=true
	Enabled *bool `json:"enabled,omitempty"`
}

type GitOpsDirectoryLayout struct {
	// ClustersPath is the path for cluster-specific configurations.
	// +kubebuilder:default="clusters"
	// +optional
	ClustersPath string `json:"clustersPath,omitempty"`

	// InfrastructurePath is the path for infrastructure components.
	// +kubebuilder:default="infrastructure"
	// +optional
	InfrastructurePath string `json:"infrastructurePath,omitempty"`

	// AppsPath is the path for application workloads.
	// +kubebuilder:default="apps"
	// +optional
	AppsPath string `json:"appsPath,omitempty"`

	// PlatformPath is the path for platform components (observability, security, etc).
	// +kubebuilder:default="platform"
	// +optional
	PlatformPath string `json:"platformPath,omitempty"`
}

type GitOpsExportFormat string

type GitOpsSpec struct {
	// Provider is the GitOps provider.
	// +kubebuilder:validation:Enum=fluxcd;argocd
	// +optional
	Provider string `json:"provider,omitempty"`

	// Version is the addon version.
	// +optional
	Version string `json:"version,omitempty"`

	// Repository configures the Git repository for GitOps.
	// +optional
	Repository *GitRepositorySpec `json:"repository,omitempty"`
}

type GitProviderConfig struct {
	// Type is the Git provider type.
	// +kubebuilder:validation:Required
	Type GitProviderType `json:"type"`

	// URL is the Git provider API URL.
	// For GitHub: https://api.github.com (or https://github.example.com/api/v3 for enterprise)
	// For GitLab: https://gitlab.com (or self-hosted URL)
	// +kubebuilder:default="https://api.github.com"
	// +optional
	URL string `json:"url,omitempty"`

	// Organization is the default organization/group for repositories.
	// When set, repository listings will be scoped to this org.
	// +optional
	Organization string `json:"organization,omitempty"`

	// SecretRef references the Secret containing credentials.
	// Required keys depend on provider type:
	// - GitHub: "token" (Personal Access Token with repo scope)
	// - GitLab: "token" (Personal Access Token with api scope)
	// - Bitbucket: "username" and "app-password"
	// +kubebuilder:validation:Required
	SecretRef LocalObjectReference `json:"secretRef"`
}

type GitProviderStatus struct {
	// Connected indicates whether the provider credentials are valid.
	// +optional
	Connected bool `json:"connected,omitempty"`

	// Username is the authenticated username (from token validation).
	// +optional
	Username string `json:"username,omitempty"`

	// LastValidated is when the credentials were last validated.
	// +optional
	LastValidated *metav1.Time `json:"lastValidated,omitempty"`

	// Message provides additional status information.
	// +optional
	Message string `json:"message,omitempty"`
}

type GitProviderType string

type GitRepositorySpec struct {
	// URL is the Git repository URL.
	// +kubebuilder:validation:Required
	URL string `json:"url"`

	// Branch is the branch to use.
	// +kubebuilder:default="main"
	// +optional
	Branch string `json:"branch,omitempty"`

	// Path is the path within the repository for this cluster's manifests.
	// +optional
	Path string `json:"path,omitempty"`

	// SecretRef references the Secret containing Git credentials.
	// +optional
	SecretRef *LocalObjectReference `json:"secretRef,omitempty"`
}

type GoogleWorkspaceConfig struct {
	// ServiceAccountSecretRef references a Secret containing the service account
	// JSON key file. The Secret must contain a key named "service-account.json".
	// +kubebuilder:validation:Required
	ServiceAccountSecretRef SecretReference `json:"serviceAccountSecretRef"`

	// AdminEmail is the email address of a Google Workspace super admin.
	// The service account will impersonate this user to access the Admin SDK.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Format=email
	AdminEmail string `json:"adminEmail"`
}

type HarvesterOverride struct {
	// Namespace is the Harvester namespace for VMs.
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// NetworkName is the Harvester network to use (format: namespace/name).
	// +optional
	NetworkName string `json:"networkName,omitempty"`

	// ImageName is the VM image to use (format: namespace/name).
	// +optional
	ImageName string `json:"imageName,omitempty"`
}

type HarvesterProviderConfig struct {
	// Endpoint is the Harvester API server URL.
	// If not specified, extracted from the kubeconfig.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// Namespace is the Harvester namespace for VM resources.
	// +kubebuilder:default="default"
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// NetworkName is the VM network in "namespace/name" format.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^[a-z0-9-]+/[a-z0-9-]+$`
	NetworkName string `json:"networkName"`

	// ImageName is the default OS image in "namespace/name" format.
	// Used when MachineRequest doesn't specify an image.
	// +optional
	ImageName string `json:"imageName,omitempty"`

	// StorageClassName is the default storage class for VM disks.
	// +optional
	StorageClassName string `json:"storageClassName,omitempty"`
}

type HelmChartSpec struct {
	// Repository is the Helm repository URL.
	// +kubebuilder:validation:Required
	Repository string `json:"repository"`

	// Chart is the chart name within the repository.
	// +kubebuilder:validation:Required
	Chart string `json:"chart"`

	// ReleaseName is the Helm release name.
	// If not specified, defaults to the TenantAddon name.
	// +optional
	ReleaseName string `json:"releaseName,omitempty"`

	// Namespace is the target namespace for the Helm release.
	// If not specified, a namespace is chosen based on the chart.
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// CreateNamespace creates the namespace if it doesn't exist.
	// +kubebuilder:default=true
	// +optional
	CreateNamespace bool `json:"createNamespace,omitempty"`
}

type HelmReleaseStatus struct {
	// Name is the name of the Helm release
	// +optional
	Name string `json:"name,omitempty"`

	// Namespace is the namespace where the release is installed
	// +optional
	Namespace string `json:"namespace,omitempty"`

	// Version is the chart version
	// +optional
	Version string `json:"version,omitempty"`

	// Revision is the Helm release revision number
	// +optional
	Revision int `json:"revision,omitempty"`

	// Status is the Helm release status (deployed, failed, etc.)
	// +optional
	Status string `json:"status,omitempty"`
}

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

	Spec   IPAllocationSpec   `json:"spec,omitempty"`
	Status IPAllocationStatus `json:"status,omitempty"`
}

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

type IPAllocationPhase string

type IPAllocationSpec struct {
	// PoolRef references the NetworkPool to allocate from.
	// +kubebuilder:validation:Required
	PoolRef LocalObjectReference `json:"poolRef"`

	// TenantClusterRef references the TenantCluster this allocation is for.
	// +kubebuilder:validation:Required
	TenantClusterRef NamespacedObjectReference `json:"tenantClusterRef"`

	// Type specifies the purpose of the allocation.
	// +kubebuilder:validation:Required
	Type IPAllocationType `json:"type"`

	// Count is the number of IPs to allocate.
	// If not specified, defaults from the NetworkPool are used.
	// Ignored when PinnedRange is set.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Count *int32 `json:"count,omitempty"`

	// PinnedRange requests a specific IP range instead of automatic allocation.
	// Used for migrating existing clusters to IPAM or reserving well-known addresses.
	// The allocator validates the range is within the pool and not already allocated.
	// +optional
	PinnedRange *PinnedIPRange `json:"pinnedRange,omitempty"`
}

type IPAllocationStatus struct {
	// Phase represents the current phase of the allocation.
	// +optional
	Phase IPAllocationPhase `json:"phase,omitempty"`

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

	// CIDR is the allocated range in CIDR notation if power-of-2 aligned.
	// +optional
	CIDR string `json:"cidr,omitempty"`

	// StartAddress is the first IP in the allocated range.
	// +optional
	StartAddress string `json:"startAddress,omitempty"`

	// EndAddress is the last IP in the allocated range.
	// +optional
	EndAddress string `json:"endAddress,omitempty"`

	// Addresses lists all individual IPs in the allocated range.
	// +optional
	Addresses []string `json:"addresses,omitempty"`

	// AllocatedCount is the number of IPs allocated.
	// +optional
	AllocatedCount int32 `json:"allocatedCount,omitempty"`

	// ObservedGeneration is the last observed generation.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// AllocatedAt is the timestamp when IPs were assigned.
	// +optional
	AllocatedAt *metav1.Time `json:"allocatedAt,omitempty"`

	// AllocatedBy identifies the controller that fulfilled the allocation.
	// +optional
	AllocatedBy string `json:"allocatedBy,omitempty"`

	// ReleasedAt is the timestamp when IPs were released.
	// +optional
	ReleasedAt *metav1.Time `json:"releasedAt,omitempty"`
}

type IPAllocationType string

type IPPool struct {
	// Start is the first IP in the pool.
	// +kubebuilder:validation:Required
	Start string `json:"start"`

	// End is the last IP in the pool.
	// +kubebuilder:validation:Required
	End string `json:"end"`
}

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

	Spec   IdentityProviderSpec   `json:"spec,omitempty"`
	Status IdentityProviderStatus `json:"status,omitempty"`
}

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

type IdentityProviderPhase string

type IdentityProviderSpec struct {
	// Type specifies the identity provider type.
	// Currently only "oidc" is supported.
	// +kubebuilder:validation:Required
	Type IdentityProviderType `json:"type"`

	// DisplayName is a human-readable name for this provider.
	// Shown in the login UI when multiple providers are configured.
	// +optional
	DisplayName string `json:"displayName,omitempty"`

	// OIDC contains OpenID Connect configuration.
	// Required when type is "oidc".
	// +optional
	OIDC *OIDCConfig `json:"oidc,omitempty"`
}

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

	// Phase represents the current phase of the provider.
	// +optional
	Phase IdentityProviderPhase `json:"phase,omitempty"`

	// ObservedGeneration is the last observed generation.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// LastValidatedTime is when the provider was last successfully validated.
	// +optional
	LastValidatedTime *metav1.Time `json:"lastValidatedTime,omitempty"`

	// DiscoveredEndpoints contains endpoints discovered via OIDC Discovery.
	// +optional
	DiscoveredEndpoints *OIDCDiscoveredEndpoints `json:"discoveredEndpoints,omitempty"`

	// Message provides additional status information.
	// +optional
	Message string `json:"message,omitempty"`
}

type IdentityProviderType string

type InfrastructureOverride struct {
	// Harvester contains Harvester-specific overrides.
	// +optional
	Harvester *HarvesterOverride `json:"harvester,omitempty"`

	// Nutanix contains Nutanix-specific overrides.
	// +optional
	Nutanix *NutanixOverride `json:"nutanix,omitempty"`

	// Proxmox contains Proxmox-specific overrides.
	// +optional
	Proxmox *ProxmoxOverride `json:"proxmox,omitempty"`
}

type IngressAddonSpec struct {
	// Type is the ingress controller type
	// +kubebuilder:validation:Enum=traefik;nginx;none
	// +kubebuilder:default=traefik
	Type string `json:"type,omitempty"`

	// Enabled controls whether the ingress controller is installed
	// +optional
	// +kubebuilder:default=true
	Enabled *bool `json:"enabled,omitempty"`

	// Version is the addon version
	// +optional
	Version string `json:"version,omitempty"`
}

type IngressSpec struct {
	// Provider is the ingress provider.
	// +kubebuilder:validation:Enum=traefik;nginx
	// +optional
	Provider string `json:"provider,omitempty"`

	// Version is the addon version.
	// +kubebuilder:validation:Required
	Version string `json:"version"`

	// Values are Helm values for customization.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Values *ExtensionValues `json:"values,omitempty"`
}

type LoadBalancerAddonSpec struct {
	// Type is the load balancer type
	// +kubebuilder:validation:Enum=metallb;none
	// +kubebuilder:default=metallb
	Type string `json:"type,omitempty"`

	// AddressPool is the IP address range for MetalLB
	// DEPRECATED: Use network.loadBalancerPool instead for proper validation
	// +optional
	AddressPool string `json:"addressPool,omitempty"`
}

type LoadBalancerPoolSpec struct {
	// Start is the first IP in the pool (inclusive)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^([0-9]{1,3}\.){3}[0-9]{1,3}$`
	Start string `json:"start"`

	// End is the last IP in the pool (inclusive)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^([0-9]{1,3}\.){3}[0-9]{1,3}$`
	End string `json:"end"`
}

type LoadBalancerSpec struct {
	// Provider is the load balancer provider.
	// +kubebuilder:validation:Enum=metallb
	// +kubebuilder:default="metallb"
	// +optional
	Provider string `json:"provider,omitempty"`

	// Version is the addon version.
	// +kubebuilder:validation:Required
	Version string `json:"version"`

	// Values are Helm values for customization.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Values *ExtensionValues `json:"values,omitempty"`
}

type LocalObjectReference struct {
	// Name is the name of the resource.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`
}

type MachinePhase string

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

	Spec   MachineRequestSpec   `json:"spec,omitempty"`
	Status MachineRequestStatus `json:"status,omitempty"`
}

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

type MachineRequestSpec struct {
	// ProviderRef references the ProviderConfig to use for this machine.
	// +kubebuilder:validation:Required
	ProviderRef ProviderReference `json:"providerRef"`

	// MachineName is the desired name for the virtual machine.
	// Must be unique within the provider's namespace/project.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	MachineName string `json:"machineName"`

	// Role indicates the intended role of this machine in the cluster.
	// +kubebuilder:validation:Required
	Role MachineRole `json:"role"`

	// CPU is the number of virtual CPU cores.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=128
	CPU int32 `json:"cpu"`

	// MemoryMB is the amount of memory in megabytes.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=1024
	MemoryMB int32 `json:"memoryMB"`

	// DiskGB is the root disk size in gigabytes.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=10
	DiskGB int32 `json:"diskGB"`

	// ExtraDisks defines additional disks to attach to the machine.
	// +optional
	ExtraDisks []DiskSpec `json:"extraDisks,omitempty"`

	// Image overrides the default OS image from ProviderConfig.
	// Format is provider-specific:
	// - harvester: "namespace/image-name"
	// - nutanix: UUID
	// - proxmox: template ID or image name
	// +optional
	Image string `json:"image,omitempty"`

	// UserData is cloud-init user data to configure the machine.
	// This typically contains the Talos machine configuration.
	// +optional
	UserData string `json:"userData,omitempty"`

	// NetworkData is cloud-init network configuration.
	// +optional
	NetworkData string `json:"networkData,omitempty"`

	// Labels are key-value pairs to apply to the VM in the provider.
	// +optional
	Labels map[string]string `json:"labels,omitempty"`
}

type MachineRequestStatus struct {
	// Phase represents the current lifecycle phase of the machine.
	// +optional
	Phase MachinePhase `json:"phase,omitempty"`

	// ProviderID is the provider-specific identifier for the machine.
	// Format is provider-specific (e.g., Harvester VM UID, Nutanix VM UUID).
	// +optional
	ProviderID string `json:"providerID,omitempty"`

	// IPAddress is the primary IP address of the machine.
	// This is set when the machine reaches the Running phase.
	// +optional
	IPAddress string `json:"ipAddress,omitempty"`

	// IPAddresses contains all IP addresses assigned to the machine.
	// +optional
	IPAddresses []string `json:"ipAddresses,omitempty"`

	// MACAddress is the primary MAC address of the machine.
	// +optional
	MACAddress string `json:"macAddress,omitempty"`

	// FailureReason provides a machine-readable failure reason.
	// +optional
	FailureReason string `json:"failureReason,omitempty"`

	// FailureMessage provides a human-readable failure message.
	// +optional
	FailureMessage string `json:"failureMessage,omitempty"`

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

	// LastUpdated is the timestamp of the last status update.
	// +optional
	LastUpdated *metav1.Time `json:"lastUpdated,omitempty"`

	// ObservedGeneration is the generation most recently observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type MachineRole string

type MachineTemplateSpec struct {
	// CPU is the number of CPU cores.
	// +kubebuilder:default=4
	// +kubebuilder:validation:Minimum=1
	// +optional
	CPU int32 `json:"cpu,omitempty"`

	// Memory is the amount of RAM.
	// +kubebuilder:default="16Gi"
	// +optional
	Memory resource.Quantity `json:"memory,omitempty"`

	// DiskSize is the root disk size.
	// +kubebuilder:default="100Gi"
	// +optional
	DiskSize resource.Quantity `json:"diskSize,omitempty"`

	// OS configures the operating system.
	// +optional
	OS OSSpec `json:"os,omitempty"`
}

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

	Spec   ManagementAddonSpec   `json:"spec,omitempty"`
	Status ManagementAddonStatus `json:"status,omitempty"`
}

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

type ManagementAddonPhase string

type ManagementAddonSpec struct {
	// Addon is the name of the addon to install (must match an AddonDefinition)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Addon string `json:"addon"`

	// Version is the specific version to install. If not specified, uses the
	// default version from the AddonDefinition.
	// +optional
	Version string `json:"version,omitempty"`

	// Values are the Helm values to use for installation.
	// These are merged with any default values from the AddonDefinition.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	Values *runtime.RawExtension `json:"values,omitempty"`

	// Paused indicates whether reconciliation of this addon is paused.
	// When paused, the controller will not make any changes to the addon.
	// +optional
	Paused bool `json:"paused,omitempty"`
}

type ManagementAddonStatus struct {
	// Phase represents the current phase of the addon installation
	// +optional
	Phase ManagementAddonPhase `json:"phase,omitempty"`

	// InstalledVersion is the currently installed version of the addon
	// +optional
	InstalledVersion string `json:"installedVersion,omitempty"`

	// HelmRelease contains information about the Helm release
	// +optional
	HelmRelease *HelmReleaseStatus `json:"helmRelease,omitempty"`

	// Message provides additional information about the current state
	// +optional
	Message string `json:"message,omitempty"`

	// LastAttemptedVersion is the version that was last attempted to install
	// +optional
	LastAttemptedVersion string `json:"lastAttemptedVersion,omitempty"`

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

	// ObservedGeneration is the last observed generation of the ManagementAddon
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type ManagementMode string

type ManagementPolicySpec struct {
	// Mode determines how Butler manages addons.
	// +kubebuilder:default="Active"
	// +optional
	Mode ManagementMode `json:"mode,omitempty"`
}

type MultiTenancyConfig struct {
	// Mode determines how multi-tenancy is enforced.
	// +kubebuilder:default="Disabled"
	// +optional
	Mode MultiTenancyMode `json:"mode,omitempty"`
}

type MultiTenancyMode string

type NamespacedObjectReference struct {
	// Name is the name of the resource.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name"`

	// Namespace is the namespace of the resource.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Namespace string `json:"namespace"`
}

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

	Spec   NetworkPoolSpec   `json:"spec,omitempty"`
	Status NetworkPoolStatus `json:"status,omitempty"`
}

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

type NetworkPoolSpec struct {
	// CIDR is the network range in CIDR notation.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^(\d{1,3}\.){3}\d{1,3}/\d{1,2}$`
	CIDR string `json:"cidr"`

	// Reserved defines ranges excluded from allocation.
	// +optional
	Reserved []ReservedRange `json:"reserved,omitempty"`

	// TenantAllocation configures the allocatable sub-range and defaults.
	// If not specified, the entire CIDR (minus reserved ranges) is allocatable.
	// +optional
	TenantAllocation *TenantAllocationConfig `json:"tenantAllocation,omitempty"`
}

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

	// TotalIPs is the total number of usable IPs (excluding reserved).
	// +optional
	TotalIPs int32 `json:"totalIPs,omitempty"`

	// AllocatedIPs is the number of currently allocated IPs.
	// +optional
	AllocatedIPs int32 `json:"allocatedIPs,omitempty"`

	// AvailableIPs is the number of available IPs.
	// +optional
	AvailableIPs int32 `json:"availableIPs,omitempty"`

	// AllocationCount is the total number of IPAllocations from this pool.
	// +optional
	AllocationCount int32 `json:"allocationCount,omitempty"`

	// FragmentationPercent indicates how fragmented the free space is (0-100).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=100
	FragmentationPercent *int32 `json:"fragmentationPercent,omitempty"`

	// LargestFreeBlock is the size of the largest contiguous free block.
	// +optional
	LargestFreeBlock int32 `json:"largestFreeBlock,omitempty"`

	// ObservedGeneration is the last observed generation.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

type NetworkQuota struct {
	// MaxNodeIPs limits the number of node IPs per tenant.
	// +optional
	// +kubebuilder:validation:Minimum=1
	MaxNodeIPs *int32 `json:"maxNodeIPs,omitempty"`

	// MaxLoadBalancerIPs limits the number of LB IPs per tenant.
	// +optional
	// +kubebuilder:validation:Minimum=1
	MaxLoadBalancerIPs *int32 `json:"maxLoadBalancerIPs,omitempty"`
}

type NetworkingSpec struct {
	// PodCIDR is the CIDR for pod IPs.
	// +kubebuilder:default="10.244.0.0/16"
	// +optional
	PodCIDR string `json:"podCIDR,omitempty"`

	// ServiceCIDR is the CIDR for service IPs.
	// +kubebuilder:default="10.96.0.0/12"
	// +optional
	ServiceCIDR string `json:"serviceCIDR,omitempty"`

	// LoadBalancerPool defines the IP pool for LoadBalancer services.
	// When IPAM is active, this is populated automatically from IPAllocation.
	// +optional
	LoadBalancerPool *IPPool `json:"loadBalancerPool,omitempty"`

	// LBPoolSize overrides the default load balancer pool size from the provider.
	// Only used when the provider has network.mode=ipam.
	// +optional
	// +kubebuilder:validation:Minimum=1
	LBPoolSize *int32 `json:"lbPoolSize,omitempty"`
}

type NutanixOverride struct {
	// ClusterUUID is the Nutanix cluster UUID.
	// +optional
	ClusterUUID string `json:"clusterUUID,omitempty"`

	// SubnetUUID is the Nutanix subnet UUID.
	// +optional
	SubnetUUID string `json:"subnetUUID,omitempty"`

	// ImageUUID is the Nutanix image UUID.
	// +optional
	ImageUUID string `json:"imageUUID,omitempty"`

	// StorageContainerUUID is the Nutanix storage container UUID.
	// +optional
	StorageContainerUUID string `json:"storageContainerUUID,omitempty"`
}

type NutanixProviderConfig struct {
	// Endpoint is the Prism Central API URL.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^https?://`
	Endpoint string `json:"endpoint"`

	// Port is the Prism Central API port.
	// +kubebuilder:default=9440
	// +optional
	Port int32 `json:"port,omitempty"`

	// Insecure allows insecure TLS connections.
	// +kubebuilder:default=false
	// +optional
	Insecure bool `json:"insecure,omitempty"`

	// ClusterUUID is the target Nutanix cluster UUID.
	// +kubebuilder:validation:Required
	ClusterUUID string `json:"clusterUUID"`

	// SubnetUUID is the network subnet UUID for VMs.
	// +kubebuilder:validation:Required
	SubnetUUID string `json:"subnetUUID"`

	// ImageUUID is the default OS image UUID.
	// Used when MachineRequest doesn't specify an image.
	// +optional
	ImageUUID string `json:"imageUUID,omitempty"`

	// StorageContainerUUID is the storage container for VM disks.
	// +optional
	StorageContainerUUID string `json:"storageContainerUUID,omitempty"`
}

type OIDCConfig struct {
	// IssuerURL is the OIDC provider's issuer URL.
	// Butler appends /.well-known/openid-configuration for discovery.
	// Examples:
	//   - Google: https://accounts.google.com
	//   - Microsoft: https://login.microsoftonline.com/{tenant}/v2.0
	//   - Okta: https://{domain}.okta.com
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^https://`
	IssuerURL string `json:"issuerURL"`

	// ClientID is the OAuth2 client ID from the identity provider.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	ClientID string `json:"clientID"`

	// ClientSecretRef references a Secret containing the OAuth2 client secret.
	// The Secret must contain a key named "client-secret".
	// +kubebuilder:validation:Required
	ClientSecretRef SecretReference `json:"clientSecretRef"`

	// RedirectURL is the OAuth2 callback URL.
	// Must match the redirect URI configured in the identity provider.
	// Example: https://butler.example.com/api/auth/callback
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^https?://`
	RedirectURL string `json:"redirectURL"`

	// Scopes are the OAuth2 scopes to request.
	// Defaults to ["openid", "email", "profile"] if not specified.
	// Some providers require additional scopes for group information:
	//   - Microsoft: add "groups" or use Graph API
	//   - Okta: add "groups"
	//   - Google: groups require separate Cloud Identity API call
	// +optional
	Scopes []string `json:"scopes,omitempty"`

	// GroupsClaim is the JWT claim containing group memberships.
	// Defaults to "groups". Set to empty string to disable group extraction.
	// Note: Google Workspace doesn't include groups in the ID token by default.
	// +kubebuilder:default="groups"
	// +optional
	GroupsClaim string `json:"groupsClaim,omitempty"`

	// EmailClaim is the JWT claim containing the user's email.
	// Defaults to "email".
	// +kubebuilder:default="email"
	// +optional
	EmailClaim string `json:"emailClaim,omitempty"`

	// HostedDomain restricts authentication to a specific domain.
	// Only supported by Google Workspace. Users outside this domain
	// will see an error during Google authentication.
	// Example: "butlerlabs.dev"
	// +optional
	HostedDomain string `json:"hostedDomain,omitempty"`

	// InsecureSkipVerify disables TLS certificate verification.
	// WARNING: Only use for development with self-signed certificates.
	// +kubebuilder:default=false
	// +optional
	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`

	// GoogleWorkspace contains optional Google Workspace Admin SDK configuration
	// for fetching user group memberships. Required because Google OIDC tokens
	// don't include groups by default.
	// +optional
	GoogleWorkspace *GoogleWorkspaceConfig `json:"googleWorkspace,omitempty"`
}

type OIDCDiscoveredEndpoints struct {
	// AuthorizationEndpoint is the OAuth2 authorization URL.
	// +optional
	AuthorizationEndpoint string `json:"authorizationEndpoint,omitempty"`

	// TokenEndpoint is the OAuth2 token URL.
	// +optional
	TokenEndpoint string `json:"tokenEndpoint,omitempty"`

	// UserInfoEndpoint is the OIDC userinfo URL.
	// +optional
	UserInfoEndpoint string `json:"userInfoEndpoint,omitempty"`

	// JWKSURI is the JSON Web Key Set URL for token validation.
	// +optional
	JWKSURI string `json:"jwksURI,omitempty"`
}

type OSSpec struct {
	// Type is the OS type.
	// +kubebuilder:default="rocky"
	// +optional
	Type OSType `json:"type,omitempty"`

	// Version is the OS version.
	// +kubebuilder:default="9.5"
	// +optional
	Version string `json:"version,omitempty"`

	// ImageRef references a specific image to use.
	// Overrides Type and Version if specified.
	// +optional
	ImageRef string `json:"imageRef,omitempty"`

	// Talos provides Talos-specific worker node configuration.
	// Required when type is "talos".
	// +optional
	Talos *TalosConfig `json:"talos,omitempty"`
}

type OSType string

type ObservedClusterState struct {
	// KubernetesVersion is the actual Kubernetes version running.
	// +optional
	KubernetesVersion string `json:"kubernetesVersion,omitempty"`

	// Workers shows worker node status.
	// +optional
	Workers *WorkerStatus `json:"workers,omitempty"`

	// Addons shows installed addon status.
	// +optional
	Addons []AddonStatus `json:"addons,omitempty"`
}

type PinnedIPRange struct {
	// StartAddress is the first IP of the pinned range.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^(\d{1,3}\.){3}\d{1,3}$`
	StartAddress string `json:"startAddress"`

	// EndAddress is the last IP of the pinned range.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^(\d{1,3}\.){3}\d{1,3}$`
	EndAddress string `json:"endAddress"`
}

type PoolReference struct {
	// Name is the name of the NetworkPool.
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Priority determines allocation order (lower = higher priority).
	// Pools at the same priority are tried in list order.
	// +kubebuilder:default=0
	// +optional
	Priority *int32 `json:"priority,omitempty"`
}

type ProviderCapacity struct {
	// AvailableIPs is the number of available IPs across all pools.
	// +optional
	AvailableIPs int32 `json:"availableIPs,omitempty"`

	// EstimatedTenants is the estimated number of tenants that can be provisioned.
	// +optional
	EstimatedTenants int32 `json:"estimatedTenants,omitempty"`
}

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

	Spec   ProviderConfigSpec   `json:"spec,omitempty"`
	Status ProviderConfigStatus `json:"status,omitempty"`
}

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

type ProviderConfigScope struct {
	// Type is the scope type.
	// +kubebuilder:default="platform"
	// +optional
	Type ProviderConfigScopeType `json:"type,omitempty"`

	// TeamRef references the Team when type is "team".
	// Required when type is "team".
	// +optional
	TeamRef *LocalObjectReference `json:"teamRef,omitempty"`
}

type ProviderConfigScopeType string

type ProviderConfigSpec struct {
	// Provider specifies the infrastructure provider type.
	// +kubebuilder:validation:Required
	Provider ProviderType `json:"provider"`

	// CredentialsRef references the Secret containing provider credentials.
	// The Secret must contain the appropriate keys for the provider type:
	// - harvester: "kubeconfig" (Harvester kubeconfig)
	// - nutanix: "username", "password"
	// - proxmox: "username", "password" or "token"
	// +kubebuilder:validation:Required
	CredentialsRef SecretReference `json:"credentialsRef"`

	// Harvester contains Harvester-specific configuration.
	// Required when provider is "harvester".
	// +optional
	Harvester *HarvesterProviderConfig `json:"harvester,omitempty"`

	// Nutanix contains Nutanix-specific configuration.
	// Required when provider is "nutanix".
	// +optional
	Nutanix *NutanixProviderConfig `json:"nutanix,omitempty"`

	// Proxmox contains Proxmox-specific configuration.
	// Required when provider is "proxmox".
	// +optional
	Proxmox *ProxmoxProviderConfig `json:"proxmox,omitempty"`

	// Azure contains Azure-specific configuration.
	// Required when provider is "azure".
	// +optional
	Azure *AzureProviderConfig `json:"azure,omitempty"`

	// AWS contains AWS-specific configuration.
	// Required when provider is "aws".
	// +optional
	AWS *AWSProviderConfig `json:"aws,omitempty"`

	// GCP contains GCP-specific configuration.
	// Required when provider is "gcp".
	// +optional
	GCP *GCPProviderConfig `json:"gcp,omitempty"`

	// Scope defines the visibility of this ProviderConfig.
	// Platform-scoped providers are available to all teams.
	// Team-scoped providers are restricted to a specific team.
	// +optional
	Scope *ProviderConfigScope `json:"scope,omitempty"`

	// Network configures IPAM and network settings for this provider.
	// +optional
	Network *ProviderNetworkConfig `json:"network,omitempty"`

	// Limits defines resource limits enforced per-team on this provider.
	// +optional
	Limits *ProviderLimits `json:"limits,omitempty"`
}