model

Documentation

Overview

Package model defines Kilter's core domain types. It is intentionally free of Kubernetes API dependencies so the whole decision engine stays pure, portable, and testable in milliseconds. Collectors translate live cluster state into these types; actuators translate decisions back.

Index

• type ClusterSnapshot
  • func (s *ClusterSnapshot) NodesByName() map[string]*NodeSpec
  • func (s *ClusterSnapshot) PodsOnNode(node string) []*PodSpec
• type ContainerKey
  • func (c ContainerKey) String() string
• type ContainerSpec
• type NodeSelectorRequirement
• type NodeSelectorTerm
• type NodeSpec
• type PDB
  • func (p *PDB) Covers(pod *PodSpec) bool
  • func (p *PDB) Matches(labels map[string]string) bool
• type PodSpec
  • func (p *PodSpec) Limits() Resources
  • func (p *PodSpec) Requests() Resources
• type Resources
  • func (r Resources) Add(o Resources) Resources
  • func (r Resources) Fits(o Resources) bool
  • func (r Resources) IsZero() bool
  • func (r Resources) Max(o Resources) Resources
  • func (r Resources) String() string
  • func (r Resources) Sub(o Resources) Resources
• type Taint
• type Toleration
  • func (t Toleration) Tolerates(taint Taint) bool
• type TopologySpreadConstraint
• type Usage
• type WorkloadInfo
• type WorkloadKind
• type WorkloadRef
  • func (w WorkloadRef) String() string

Types

type ClusterSnapshot

type ClusterSnapshot struct {
	ClusterID string         `json:"clusterID"`
	Timestamp time.Time      `json:"timestamp"`
	Nodes     []NodeSpec     `json:"nodes"`
	Pods      []PodSpec      `json:"pods"`
	Workloads []WorkloadInfo `json:"workloads,omitempty"`
	PDBs      []PDB          `json:"pdbs,omitempty"`
	Usage     []Usage        `json:"usage,omitempty"`
	// K8s server info — feature gates like InPlacePodVerticalScaling depend on it.
	ServerVersion string `json:"serverVersion,omitempty"`
}

ClusterSnapshot is the unit shipped from agent to brain: complete topology plus the usage samples gathered since the previous snapshot.

func (*ClusterSnapshot) NodesByName

func (s *ClusterSnapshot) NodesByName() map[string]*NodeSpec

NodesByName indexes nodes.

func (*ClusterSnapshot) PodsOnNode

func (s *ClusterSnapshot) PodsOnNode(node string) []*PodSpec

PodsOnNode returns pods assigned to the given node.

type ContainerKey

type ContainerKey struct {
	Workload  WorkloadRef `json:"workload"`
	Container string      `json:"container"`
}

ContainerKey identifies a container template within a workload.

func (ContainerKey) String

func (c ContainerKey) String() string

type ContainerSpec

type ContainerSpec struct {
	Name           string    `json:"name"`
	Requests       Resources `json:"requests"`
	Limits         Resources `json:"limits"`
	RestartCount   int32     `json:"restartCount,omitempty"`
	LastOOMKilled  bool      `json:"lastOOMKilled,omitempty"`
	LastTerminated string    `json:"lastTerminated,omitempty"` // reason of last termination
}

ContainerSpec is one container's declared sizing.

type NodeSelectorRequirement

type NodeSelectorRequirement struct {
	Key      string   `json:"key"`
	Operator string   `json:"operator"` // In | NotIn | Exists | DoesNotExist | Gt | Lt
	Values   []string `json:"values,omitempty"`
}

NodeSelectorRequirement is one matchExpression on node labels.

type NodeSelectorTerm

type NodeSelectorTerm struct {
	MatchExpressions []NodeSelectorRequirement `json:"matchExpressions,omitempty"`
}

NodeSelectorTerm is ANDed requirements; terms themselves are ORed.

type NodeSpec

type NodeSpec struct {
	Name          string            `json:"name"`
	Labels        map[string]string `json:"labels,omitempty"`
	Taints        []Taint           `json:"taints,omitempty"`
	Capacity      Resources         `json:"capacity"`
	Allocatable   Resources         `json:"allocatable"`
	Ready         bool              `json:"ready"`
	Unschedulable bool              `json:"unschedulable,omitempty"`
	CreatedAt     time.Time         `json:"createdAt,omitempty"`

	// Pricing identity — resolved by pkg/pricing.
	InstanceType string  `json:"instanceType,omitempty"` // from node.kubernetes.io/instance-type
	Zone         string  `json:"zone,omitempty"`         // topology.kubernetes.io/zone
	Region       string  `json:"region,omitempty"`
	Provider     string  `json:"provider,omitempty"` // aws | gcp | azure | custom
	Spot         bool    `json:"spot,omitempty"`
	HourlyCost   float64 `json:"hourlyCost,omitempty"` // resolved cost, USD/h
}

NodeSpec captures a node's capacity and scheduling surface.

type PDB

type PDB struct {
	Namespace          string            `json:"namespace"`
	Name               string            `json:"name"`
	Selector           map[string]string `json:"selector,omitempty"`
	DisruptionsAllowed int32             `json:"disruptionsAllowed"`
	CurrentHealthy     int32             `json:"currentHealthy"`
	DesiredHealthy     int32             `json:"desiredHealthy"`
	// CoveredPodUIDs is the exact pod set the PDB selected at collection time.
	// Collectors fill it using full Kubernetes selector semantics (including
	// matchExpressions, which Selector cannot express). When present it takes
	// precedence over Selector.
	CoveredPodUIDs []string `json:"coveredPodUIDs,omitempty"`
}

PDB captures a PodDisruptionBudget's current arithmetic.

func (*PDB) Covers

func (p *PDB) Covers(pod *PodSpec) bool

Covers reports whether the PDB applies to the pod, preferring exact collection-time coverage over label matching.

func (*PDB) Matches

func (p *PDB) Matches(labels map[string]string) bool

Matches reports whether the PDB selector matches the given labels.

type PodSpec

type PodSpec struct {
	UID       string            `json:"uid"`
	Name      string            `json:"name"`
	Namespace string            `json:"namespace"`
	Workload  WorkloadRef       `json:"workload"`
	Labels    map[string]string `json:"labels,omitempty"`

	NodeName string `json:"nodeName,omitempty"`

	Containers []ContainerSpec `json:"containers"`

	NodeSelector     map[string]string          `json:"nodeSelector,omitempty"`
	RequiredAffinity []NodeSelectorTerm         `json:"requiredAffinity,omitempty"` // ORed terms
	Tolerations      []Toleration               `json:"tolerations,omitempty"`
	AntiAffinityKeys []string                   `json:"antiAffinityKeys,omitempty"` // topology keys with self-anti-affinity
	TopologySpread   []TopologySpreadConstraint `json:"topologySpread,omitempty"`
	PriorityClass    string                     `json:"priorityClass,omitempty"`
	Priority         int32                      `json:"priority,omitempty"`
	QOSClass         string                     `json:"qosClass,omitempty"` // Guaranteed | Burstable | BestEffort
	Phase            string                     `json:"phase,omitempty"`    // Running | Pending | ...
	CreatedAt        time.Time                  `json:"createdAt,omitempty"`

	// HasLocalStorage marks pods using node-local data (local PVs); draining
	// such a pod loses state, so consolidation treats it as pinned.
	HasLocalStorage bool `json:"hasLocalStorage,omitempty"`
	// DoNotEvict mirrors the kilter.dev/do-not-evict pod annotation (also
	// honored: cluster-autoscaler.kubernetes.io/safe-to-evict=false).
	DoNotEvict bool `json:"doNotEvict,omitempty"`
}

PodSpec captures the scheduling- and sizing-relevant parts of a pod.

func (*PodSpec) Limits

func (p *PodSpec) Limits() Resources

Limits sums container limits (0 means unlimited for that dimension).

func (*PodSpec) Requests

func (p *PodSpec) Requests() Resources

Requests sums container requests.

type Resources

type Resources struct {
	MilliCPU    int64 `json:"milliCPU"`
	MemoryBytes int64 `json:"memoryBytes"`
}

Resources is an amount of compute expressed in scheduler units: integer milli-CPU and bytes. Integer math only — no floating point drift.

func (Resources) Add

func (r Resources) Add(o Resources) Resources

func (Resources) Fits

func (r Resources) Fits(o Resources) bool

Fits reports whether o fits inside r (both dimensions).

func (Resources) IsZero

func (r Resources) IsZero() bool

IsZero reports whether both dimensions are zero.

func (Resources) Max

func (r Resources) Max(o Resources) Resources

Max returns the element-wise maximum.

func (Resources) String

func (r Resources) String() string

func (Resources) Sub

func (r Resources) Sub(o Resources) Resources

type Taint

type Taint struct {
	Key    string `json:"key"`
	Value  string `json:"value,omitempty"`
	Effect string `json:"effect"` // NoSchedule | PreferNoSchedule | NoExecute
}

Taint mirrors a node taint.

type Toleration

type Toleration struct {
	Key      string `json:"key,omitempty"`
	Operator string `json:"operator,omitempty"` // Exists | Equal (default Equal)
	Value    string `json:"value,omitempty"`
	Effect   string `json:"effect,omitempty"` // empty matches all effects
}

Toleration mirrors a pod toleration (subset: Exists/Equal operators).

func (Toleration) Tolerates

func (t Toleration) Tolerates(taint Taint) bool

Tolerates reports whether the toleration tolerates the taint, following Kubernetes semantics.

type TopologySpreadConstraint

type TopologySpreadConstraint struct {
	MaxSkew           int32             `json:"maxSkew"`
	TopologyKey       string            `json:"topologyKey"`
	WhenUnsatisfiable string            `json:"whenUnsatisfiable"` // DoNotSchedule | ScheduleAnyway
	LabelSelector     map[string]string `json:"labelSelector,omitempty"`
}

TopologySpreadConstraint is the scheduling-relevant subset.

type Usage

type Usage struct {
	Key         ContainerKey `json:"key"`
	PodUID      string       `json:"podUID"`
	Timestamp   time.Time    `json:"timestamp"`
	MilliCPU    int64        `json:"milliCPU"`
	MemoryBytes int64        `json:"memoryBytes"`
	// WindowSeconds is the averaging window the sample represents (metrics-server ~60s).
	WindowSeconds int32 `json:"windowSeconds,omitempty"`
}

Usage is a point-in-time measured usage sample for a container.

type WorkloadInfo

type WorkloadInfo struct {
	Ref            WorkloadRef       `json:"ref"`
	Replicas       int32             `json:"replicas"`
	Ready          int32             `json:"ready"`
	Labels         map[string]string `json:"labels,omitempty"`
	HasHPA         bool              `json:"hasHPA,omitempty"`
	HPAMinReplicas int32             `json:"hpaMinReplicas,omitempty"`
	HPAMaxReplicas int32             `json:"hpaMaxReplicas,omitempty"`
	HPATargetsCPU  bool              `json:"hpaTargetsCPU,omitempty"` // request changes shift HPA math
}

WorkloadInfo aggregates a controller and its replica intent.

type WorkloadKind

type WorkloadKind string

WorkloadKind mirrors the owning controller kind of a pod.

const (
	KindDeployment  WorkloadKind = "Deployment"
	KindStatefulSet WorkloadKind = "StatefulSet"
	KindDaemonSet   WorkloadKind = "DaemonSet"
	KindJob         WorkloadKind = "Job"
	KindCronJob     WorkloadKind = "CronJob"
	KindReplicaSet  WorkloadKind = "ReplicaSet"
	KindBarePod     WorkloadKind = "Pod"
)

type WorkloadRef

type WorkloadRef struct {
	Kind      WorkloadKind `json:"kind"`
	Namespace string       `json:"namespace"`
	Name      string       `json:"name"`
}

WorkloadRef identifies a workload (controller) in a cluster.

func (WorkloadRef) String

func (w WorkloadRef) String() string