v1alpha1

type CapacityType string

type EgressMode string

type EgressPolicy struct {
	// Mode is required once spec.egress is set, so a half-written policy is rejected
	// rather than defaulted into a weaker one.
	Mode EgressMode `json:"mode"`

	// Targets is what mode Allowlist permits: CIDRs, bare IPs and domain names with an
	// optional wildcard, mixed in one list, e.g. ["10.0.0.0/8", "*.huggingface.co"].
	//
	// +optional
	// +kubebuilder:validation:MaxItems=64
	// +kubebuilder:validation:items:MaxLength=253
	Targets []string `json:"targets,omitempty"`
}

type FailoverPolicy struct {
	// BlocklistTTL is the BASE duration a failed placement is excluded before the
	// provider becomes a candidate for it again. The controller adds a random jitter
	// (up to 30s) on top so Pods that failed for the same reason do not all retry the
	// just-freed candidate in lockstep, so the effective exclusion is this value plus
	// that jitter.
	//
	// +kubebuilder:default="30s"
	BlocklistTTL metav1.Duration `json:"blocklistTTL,omitempty"`
}

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

	Spec   NodeClaimSpec   `json:"spec,omitempty"`
	Status NodeClaimStatus `json:"status,omitempty"`
}

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

type NodeClaimPhase string

type NodeClaimSpec struct {
	// PodRef links this claim to the Pod it serves. UID pins the exact Pod so a
	// recreated Pod of the same name gets a fresh claim rather than adopting the
	// old instance.
	PodRef PodReference `json:"podRef"`

	// Provider is the chosen NeoCloud. Immutable: a NodeClaim never migrates.
	// Recovery from preemption is delete-and-recreate. Held durably so teardown
	// knows which provider API to call even after status is lost.
	Provider string `json:"provider"`

	// CapacityType is the purchase tier placement selected (Spot/OnDemand). Stored
	// durably because it is a provisioning input that cannot be read off the Pod, and
	// Provision needs it to re-issue the request after a controller restart. Immutable,
	// like Provider. Empty means "use the provider's default" (Modal is OnDemand-only
	// and ignores it).
	// +optional
	CapacityType CapacityType `json:"capacityType,omitempty"`

	// Region is the region candidate placement selected, in the provider's own
	// vocabulary (e.g. AWS "us-east-1"). Durable and immutable for the same reason as
	// CapacityType: Provision must re-issue in the same region after a restart. Empty
	// means the provider's default — a pool that declared no region constraint.
	//
	// Not always a single region NAME: a provider whose create cannot fail over
	// collapses every declared region into ONE candidate, joined by a provider-private
	// separator (Modal uses "|", so us-east + us-west records "us-east|us-west"). Only
	// that provider can split it back. Treat the value as an opaque token.
	// +optional
	Region string `json:"region,omitempty"`

	// Accelerator is the accelerator pool this claim serves, as "type:count" (e.g.
	// "H100:8"), resolved at placement time from the Pod. It names the POOL, not the
	// SKU: a launch may span several interchangeable instance types (AWS's fleet tries
	// alternates), so this stays truthful regardless of which alternate lands. Unlike
	// Provider/CapacityType/Region it is NOT a provisioning input (the provider
	// re-derives it from the Pod) — it is recorded so `kubectl get nc` shows what each
	// instance serves. Empty for a CPU-only claim.
	// +optional
	Accelerator string `json:"accelerator,omitempty"`

	// PoolRef is the NodePool whose policy produced this claim, for reporting.
	// +optional
	PoolRef string `json:"poolRef,omitempty"`
}

type NodeClaimStatus struct {
	// Phase is the coarse lifecycle state.
	// +optional
	Phase NodeClaimPhase `json:"phase,omitempty"`

	// InstanceID is the provider's identifier for the external instance (e.g. a
	// RunPod pod id). This is the field that must not be lost: the terminate
	// finalizer uses it to reclaim the instance.
	// +optional
	InstanceID string `json:"instanceID,omitempty"`

	// NodeName is the virtual Node created for this instance, once it exists.
	// +optional
	NodeName string `json:"nodeName,omitempty"`

	// Endpoint is the reachable address (e.g. SSH host:port) once ready.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// PriceUSDPerHour is what this instance costs per hour in USD, as a decimal string
	// ("7.9000"), resolved from the provider's catalog against the served Pod's shape.
	// Status, not spec: it is a derived result nobody can declare up front. A string
	// because it is written to be READ — a print column can only echo a field, never
	// scale a fixed-point integer back into currency.
	//
	// Empty means UNPRICED, not free: the provider implements no provider.Pricer, or its
	// catalog has no row for this candidate. Consumers must skip such a claim rather than
	// count it as $0.
	//
	// Written once and never refreshed, so a catalog edit cannot retroactively reprice a
	// running instance and rewrite the cost history it has already reported.
	// +optional
	PriceUSDPerHour string `json:"priceUSDPerHour,omitempty"`

	// EstimatedCostUSD is what this instance has cost SO FAR, as a decimal string ("412.94000000")
	// — PriceUSDPerHour integrated over the time it has held an instance. A string for the same
	// reason the rate is one: it exists to be read off a print column.
	//
	// More decimals than the rate, and they are not decoration: each checkpoint re-reads this field
	// to measure the next window, so digits dropped here are money dropped, and a cheap enough claim
	// would round back to where it started every minute and never accrue at all. Round it for
	// display; never round it back into this field.
	//
	// ESTIMATED, and the name says so on purpose: it is our own arithmetic over a list price
	// (see PriceUSDPerHour), not a figure any provider has confirmed. Nothing here has been
	// invoiced. Reconcile against the provider's billing export before anyone is charged.
	//
	// Within those limits it is the AUTHORITATIVE total, not the Prometheus counter: it is
	// written exactly once per window and survives a restart. It is also only LIVE cost — it
	// dies with the claim, so it is not a history. The metric is what outlives an instance.
	// +optional
	EstimatedCostUSD string `json:"estimatedCostUSD,omitempty"`

	// LastAccruedAt is how far cost accrual has counted: an ANCHOR for the next measurement,
	// not a note about the last one. "Accrued" in the accounting sense — cost incurred but not
	// yet invoiced, which is all EstimatedCostUSD ever holds.
	//
	// It is the reason a restart loses nothing: the next window is rate x (now - LastAccruedAt),
	// so time that passed while Nebula was down is still counted on recovery instead of vanishing
	// with the in-memory total.
	//
	// The invariant that makes it safe: this NEVER moves past cost that has been durably
	// recorded, because it advances only in the same patch that writes EstimatedCostUSD. A
	// failed write therefore loses nothing — the same window is counted next time.
	//
	// Unset means "not counting yet". Never treat it as the epoch, which would charge decades
	// on the first tick.
	// +optional
	LastAccruedAt *metav1.Time `json:"lastAccruedAt,omitempty"`

	// CostLabels attributes this claim's spend to whoever asked for it: the values the served
	// Pod carried for the label keys the operator configured (--cost-labels). Keyed by the POD
	// label key, verbatim — so this map reads like the Pod it came from. The metric emits under a
	// derived name Prometheus accepts ("example.com/org-id" here is example_com_org_id there), so
	// do not expect the two to match by string.
	//
	// Status rather than spec because it is observed from the Pod, and it sits with the rest of
	// the billing record for a reason: it is stamped in the SAME patch that opens the accrual
	// anchor, so no window can ever be charged before its attribution is known.
	//
	// Written once, on first observation, and never refreshed — relabeling a Pod must not
	// retroactively re-attribute spend already reported under the old values. A name the
	// current --cost-labels no longer lists is ignored rather than cleaned up; one it lists but
	// this map lacks reports as "none".
	//
	// Nil and EMPTY differ, which is why this field has no omitempty: nil means nothing has been
	// observed yet (or --cost-labels is unset), while an empty map is the settled fact that the
	// Pod carried none of the configured keys. With omitempty an empty map would not survive the
	// write, so every reconcile would re-read the Pod and a label added later could still move
	// the claim's attribution.
	// +optional
	// +kubebuilder:validation:Nullable
	CostLabels map[string]string `json:"costLabels"`
}

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

	Spec   NodePoolSpec   `json:"spec,omitempty"`
	Status NodePoolStatus `json:"status,omitempty"`
}

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

type NodePoolSpec struct {
	// Providers is the ordered set of NeoClouds this pool is allowed to use.
	// A Pod bound to this pool can only ever be placed on a provider in this
	// list. Order is significant only for the Ordered strategy (it is the
	// inner, provider-ranking axis). A pool can list at most 8 providers so the
	// candidate set remains bounded while larger configurations are unproven.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=8
	Providers []ProviderSpec `json:"providers"`

	// CapacityTypes is the OUTER axis: the purchase models to try, in fallback
	// order. e.g. [Spot, OnDemand] means "use spot on any provider first; only
	// when spot is exhausted everywhere, drop to on-demand". A single-element
	// list pins the pool to that type. This replaces a spot on/off flag.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:default={OnDemand,Spot}
	CapacityTypes []CapacityType `json:"capacityTypes,omitempty"`

	// Strategy is the INNER axis: how to rank providers within the active
	// capacity tier. It never overrides the capacity tier ordering.
	//
	// Only Ordered is accepted today. LowestPrice and Weighted are defined as
	// constants (and the Weighted weight rule is already enforced above) but are
	// deliberately kept OUT of the enum until the ranking is implemented: admitting
	// a value the placement walk silently ignores would let a pool claim a policy it
	// does not get, which is worse than rejecting it at admission. Widening the enum
	// is the one change needed to enable them once selectPlacement ranks.
	// +kubebuilder:validation:Enum=Ordered
	// +kubebuilder:default=Ordered
	Strategy PlacementStrategy `json:"strategy,omitempty"`

	// Failover controls how a provider that fails at provision time (e.g.
	// RunPod reports no capacity) is temporarily excluded and re-tried.
	// +optional
	Failover *FailoverPolicy `json:"failover,omitempty"`

	// Egress restricts OUTBOUND connections from this pool's workloads; omitted means
	// Open. Inbound is never affected — a Blocked sandbox still serves its consumer's
	// tunnel and connect token, it just cannot call out.
	//
	// +optional
	Egress *EgressPolicy `json:"egress,omitempty"`
}

type NodePoolStatus struct {
	// Placed counts existing instances per provider (booting included), for
	// at-a-glance balance.
	// +optional
	Placed map[string]int32 `json:"placed,omitempty"`

	// Providers is a comma-separated list of provider names from the pool
	// spec. kubectl printcolumns cannot join array fields via JSONPath, so
	// the controller materializes this summary for `kubectl get nodepool`.
	// +optional
	Providers string `json:"providers,omitempty"`

	// Conditions follows the standard Kubernetes condition convention.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type PlacementStrategy string

type PodReference struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
	// UID pins the exact Pod object; a recreated Pod of the same name gets a new
	// NodeClaim rather than silently adopting the old instance.
	UID string `json:"uid"`
}

type ProviderSpec struct {
	// Name is the provider identifier, matching the ProviderLabel value on that
	// provider's virtual node (e.g. "runpod", "modal", "kubernetes").
	Name string `json:"name"`

	// Weight is the relative share of new placements for the Weighted strategy.
	// Ignored by other strategies, which today means ignored entirely: Strategy
	// accepts only Ordered, so setting this has no effect until Weighted is enabled.
	// +kubebuilder:validation:Minimum=1
	// +optional
	Weight *int32 `json:"weight,omitempty"`

	// Regions CONSTRAINS where this provider may place, in the provider's own
	// vocabulary. It lives here per provider because region names are
	// provider-namespaced. Three levels:
	//   - omitted/empty => every region the provider serves. For a region-simple
	//     provider (Modal) this sends no region at all, its widest and cheapest mode.
	//   - a geography GROUP token ("us", "eu", "ap", ...) => that geography's regions.
	//     The recommended way to ask for breadth with a residency boundary.
	//   - a literal region name ("us-east-1" on AWS, "us-east" on Modal) => just that.
	// Only the provider knows its own geography, so it resolves which level a value is
	// (see provider.Provider's ExpandRegions). Group tokens are shared across
	// providers; the regions behind them are not.
	//
	// A non-group value is passed through UNVALIDATED, because region names change
	// faster than Nebula ships: a bad one fails at provision time with the provider's
	// own error, which beats refusing a region that launched last week. It is also the
	// escape hatch for AWS opt-in regions, which no group contains.
	//
	// Unconstrained is the widest and costliest setting: every region becomes a
	// failover candidate and gets swept by the poll loop. Prefer a group unless the
	// workload needs global reach. Entry count is uncapped (a group already expands to
	// many); maxLength bounds each entry.
	// +optional
	// +kubebuilder:validation:items:MaxLength=32
	Regions []string `json:"regions,omitempty"`
}

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

	Spec   SandboxSpec   `json:"spec,omitempty"`
	Status SandboxStatus `json:"status,omitempty"`
}

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

type SandboxPhase string

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

	Spec   SandboxSetSpec   `json:"spec,omitempty"`
	Status SandboxSetStatus `json:"status,omitempty"`
}

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

type SandboxSetSpec struct {
	// Replicas is how many Sandboxes to maintain. Zero is legal and useful: it
	// releases every box while keeping the set's definition, which is how a set is
	// parked overnight without being forgotten.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:default=1
	Replicas int32 `json:"replicas,omitempty"`

	// Template is the shape of every Sandbox this set creates. All boxes in one set
	// are the same shape by construction — the set exists to make boxes
	// interchangeable at the point of HANDOUT, so a caller can take any ready box
	// without inspecting it. Two shapes means two sets.
	//
	// A template is right here for the same reason it is wrong on Sandbox itself:
	// this object does not describe a box, it describes how to make them.
	Template SandboxTemplateSpec `json:"template"`
}

type SandboxSetStatus struct {
	// Replicas is how many Sandboxes the set currently owns, ready or not. It is the
	// /scale subresource's status counterpart.
	// +optional
	Replicas int32 `json:"replicas,omitempty"`

	// ReadyReplicas is how many owned Sandboxes are Ready — the number of boxes that
	// can actually serve an exec right now.
	// +optional
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`

	// Selector is the label selector matching this set's Sandboxes, serialized in the
	// string form the /scale subresource requires. HPA and KEDA read the target's
	// selector from there, so autoscaling a set does not work without it.
	// +optional
	Selector string `json:"selector,omitempty"`

	// Sandboxes names the boxes this set owns, so the set is a usable handout list: a
	// caller reads it to find a box to use without listing and filtering Sandboxes
	// itself. Ordered by name for a stable diff.
	// +optional
	Sandboxes []string `json:"sandboxes,omitempty"`

	// Conditions follows the standard Kubernetes condition convention.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type SandboxSpec struct {
	// NodePoolRef names the NodePool whose policy places this sandbox: which
	// providers are allowed, which capacity tiers, how to rank them. Required —
	// there is no implicit default pool, because placing a paid GPU instance
	// against a guessed policy is not a safe default.
	// +kubebuilder:validation:MinLength=1
	NodePoolRef string `json:"nodePoolRef"`

	// Image is the container image the sandbox runs, defaulting to a plain Ubuntu:
	// a bare distro to exec into IS the "give me a remote shell" case, and anything
	// else can be installed from inside it. (Defaulting a paid GPU shape would be
	// guessing at spend; defaulting a shell is not.)
	//
	// It does NOT switch to a CUDA image when an accelerator is requested: a default
	// that depends on another field is not expressible in a structural schema. Ask for
	// a CUDA image explicitly.
	//
	// There is no command field and one cannot be set — the structural schema rejects
	// `command:` as unknown, no webhook needed. A sandbox has nothing to run at boot,
	// so the controller supplies a placeholder that only has to not exit (today a
	// long-running `sleep`, which the image must have). A user command would displace
	// it and take the instance down.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:default="ubuntu:24.04"
	// +optional
	Image string `json:"image,omitempty"`

	// AcceleratorType is the requested accelerator TYPE (e.g. "a100-40gb",
	// "h100"), matched case-insensitively against the provider catalog. The COUNT
	// is NOT here: it is a standard nvidia.com/gpu entry in Resources, so exactly
	// one number drives scheduling fit and provisioning. The controller stamps
	// this onto the synthesized Pod's AcceleratorTypeLabel, so a Sandbox and a
	// hand-written Nebula Pod go through identical placement.
	//
	// Empty means a CPU-only sandbox, which is a legitimate (and cheap) thing to
	// want for a shell or an agent that only needs a filesystem.
	// +optional
	AcceleratorType string `json:"acceleratorType,omitempty"`

	// Resources is the standard Kubernetes resource requirements for the sandbox
	// container, verbatim. The accelerator count rides here as an nvidia.com/gpu
	// limit (`limits: {nvidia.com/gpu: "1"}`), which is where both the placement
	// controller and the scheduler already read it from.
	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`

	// Env is passed to the sandbox container verbatim, including valueFrom
	// references — a sandbox usually needs at least a registry or Hugging Face
	// token, and re-inventing secret indirection here would be strictly worse than
	// reusing the field everyone already knows.
	// +optional
	Env []corev1.EnvVar `json:"env,omitempty"`

	// TTL bounds the sandbox's total lifetime, measured from the moment it first
	// became Ready (NOT from creation, so a slow provision does not eat into the
	// user's time). On expiry the controller releases the instance and the sandbox
	// reports phase Expired.
	//
	// This exists because the failure mode of a remote GPU box is financial: an
	// abandoned sandbox bills until someone notices. Omit it for an unbounded
	// sandbox, which is a deliberate choice rather than the default.
	// +optional
	TTL *metav1.Duration `json:"ttl,omitempty"`
}

type SandboxStatus struct {
	// Phase is the coarse lifecycle state.
	// +optional
	Phase SandboxPhase `json:"phase,omitempty"`

	// PodName is the synthesized Pod backing this sandbox. It is recorded even
	// though it currently equals the Sandbox name, so tooling (and `kubectl exec`
	// wrappers) read the pod identity from status rather than reconstructing it
	// from a naming convention this controller would then be unable to change.
	// +optional
	PodName string `json:"podName,omitempty"`

	// Endpoint is the reachable address of the external instance once it is
	// running, in the provider's own form (a public DNS name or an IP). Mirrored
	// from the Pod's EndpointAnnotation, which is where the virtual kubelet
	// publishes it.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// ReadyTime is when the sandbox first became Ready. It is the anchor TTL is
	// measured from, so it is durable status rather than a derived value: if it
	// were recomputed from the Pod, a Pod status blip could silently restart the
	// user's clock.
	// +optional
	ReadyTime *metav1.Time `json:"readyTime,omitempty"`

	// ExpiryTime is when TTL will elapse (ReadyTime + TTL), surfaced so a user can
	// see the deadline without doing the arithmetic. Absent when no TTL is set or
	// the sandbox has not become Ready yet.
	// +optional
	ExpiryTime *metav1.Time `json:"expiryTime,omitempty"`

	// Conditions follows the standard Kubernetes condition convention.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type SandboxTemplateMetadata struct {
	// Labels are applied to each created Sandbox, on top of the set-ownership
	// labels the controller adds.
	// +optional
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations are applied to each created Sandbox.
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`
}

type SandboxTemplateSpec struct {
	// Metadata is the labels and annotations applied to each created Sandbox. Only
	// labels and annotations are honoured; a name here is ignored, since names are
	// generated per box.
	// +optional
	Metadata SandboxTemplateMetadata `json:"metadata,omitempty"`

	// Spec is the SandboxSpec of every box in the set.
	Spec SandboxSpec `json:"spec"`
}