Documentation
¶
Overview ¶
Package resources provides host resource discovery, capacity tracking, and oversubscription-aware allocation management for CPU, memory, disk, and network.
Index ¶
- func ParseBandwidth(limit string) (int64, error)
- type AllocationBreakdown
- type CPUResource
- type DiskBreakdown
- type DiskResource
- type FullResourceStatus
- type GPUResourceStatus
- type ImageLister
- type InstanceAllocation
- type InstanceLister
- type Manager
- func (m *Manager) CPUCapacity() int64
- func (m *Manager) CanAllocate(ctx context.Context, rt ResourceType, amount int64) (bool, error)
- func (m *Manager) CurrentImageStorageBytes(ctx context.Context) (int64, error)
- func (m *Manager) DefaultDiskIOBandwidth(vcpus int) (ioBps, burstBps int64)
- func (m *Manager) DefaultNetworkBandwidth(vcpus int) (downloadBps, uploadBps int64)
- func (m *Manager) DiskIOCapacity() int64
- func (m *Manager) GetFullStatus(ctx context.Context) (*FullResourceStatus, error)
- func (m *Manager) GetOversubRatio(rt ResourceType) float64
- func (m *Manager) GetStatus(ctx context.Context, rt ResourceType) (*ResourceStatus, error)
- func (m *Manager) HasSufficientDiskForPull(ctx context.Context) error
- func (m *Manager) HasSufficientImageStorage(ctx context.Context) error
- func (m *Manager) Initialize(ctx context.Context) error
- func (m *Manager) MaxImageStorageBytes() int64
- func (m *Manager) NetworkCapacity() int64
- func (m *Manager) SetImageLister(lister ImageLister)
- func (m *Manager) SetInstanceLister(lister InstanceLister)
- func (m *Manager) SetVolumeLister(lister VolumeLister)
- type MemoryResource
- type NetworkResource
- type Resource
- type ResourceStatus
- type ResourceType
- type SourceType
- type VolumeLister
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseBandwidth ¶
ParseBandwidth parses a bandwidth string like "10Gbps", "1GB/s", "125MB/s". Handles both bit-based (bps) and byte-based (/s) formats. Returns bytes per second.
Types ¶
type AllocationBreakdown ¶
type AllocationBreakdown struct {
InstanceID string `json:"instance_id"`
InstanceName string `json:"instance_name"`
CPU int `json:"cpu"`
MemoryBytes int64 `json:"memory_bytes"`
DiskBytes int64 `json:"disk_bytes"`
NetworkDownloadBps int64 `json:"network_download_bps"` // External→VM
NetworkUploadBps int64 `json:"network_upload_bps"` // VM→External
}
AllocationBreakdown shows per-instance resource allocations.
type CPUResource ¶
type CPUResource struct {
// contains filtered or unexported fields
}
CPUResource implements Resource for CPU discovery and tracking.
func NewCPUResource ¶
func NewCPUResource() (*CPUResource, error)
NewCPUResource discovers host CPU capacity from /proc/cpuinfo.
func (*CPUResource) Allocated ¶
func (c *CPUResource) Allocated(ctx context.Context) (int64, error)
Allocated returns the total vCPUs allocated to running instances.
func (*CPUResource) Capacity ¶
func (c *CPUResource) Capacity() int64
Capacity returns the total number of vCPUs available on the host.
func (*CPUResource) SetInstanceLister ¶
func (c *CPUResource) SetInstanceLister(lister InstanceLister)
SetInstanceLister sets the instance lister for allocation calculations.
func (*CPUResource) Type ¶
func (c *CPUResource) Type() ResourceType
Type returns the resource type.
type DiskBreakdown ¶
type DiskBreakdown struct {
Images int64 `json:"images_bytes"` // Exported rootfs disk files
OCICache int64 `json:"oci_cache_bytes"` // OCI layer cache (shared blobs)
Volumes int64 `json:"volumes_bytes"`
Overlays int64 `json:"overlays_bytes"` // Rootfs overlays + volume overlays
}
DiskBreakdown shows disk usage by category.
type DiskResource ¶
type DiskResource struct {
// contains filtered or unexported fields
}
DiskResource implements Resource for disk space discovery and tracking.
func NewDiskResource ¶
func NewDiskResource(cfg *config.Config, p *paths.Paths, instLister InstanceLister, imgLister ImageLister, volLister VolumeLister) (*DiskResource, error)
NewDiskResource discovers disk capacity for the data directory. If cfg.DiskLimit is set, uses that as capacity; otherwise auto-detects via statfs.
func (*DiskResource) Allocated ¶
func (d *DiskResource) Allocated(ctx context.Context) (int64, error)
Allocated returns total disk space used by images, OCI cache, volumes, and overlays.
func (*DiskResource) Capacity ¶
func (d *DiskResource) Capacity() int64
Capacity returns the total disk space in bytes.
func (*DiskResource) GetBreakdown ¶
func (d *DiskResource) GetBreakdown(ctx context.Context) (*DiskBreakdown, error)
GetBreakdown returns disk usage broken down by category.
func (*DiskResource) Type ¶
func (d *DiskResource) Type() ResourceType
Type returns the resource type.
type FullResourceStatus ¶
type FullResourceStatus struct {
CPU ResourceStatus `json:"cpu"`
Memory ResourceStatus `json:"memory"`
Disk ResourceStatus `json:"disk"`
Network ResourceStatus `json:"network"`
DiskDetail *DiskBreakdown `json:"disk_breakdown,omitempty"`
GPU *GPUResourceStatus `json:"gpu,omitempty"` // nil if no GPU available
Allocations []AllocationBreakdown `json:"allocations"`
}
FullResourceStatus is the complete resource status for the API response.
type GPUResourceStatus ¶ added in v0.0.5
type GPUResourceStatus struct {
Mode string `json:"mode"` // "vgpu" or "passthrough"
TotalSlots int `json:"total_slots"` // VFs for vGPU, physical GPUs for passthrough
UsedSlots int `json:"used_slots"` // Slots currently in use
Profiles []devices.GPUProfile `json:"profiles,omitempty"` // vGPU mode only
Devices []devices.PassthroughDevice `json:"devices,omitempty"` // passthrough mode only
}
GPUResourceStatus represents the GPU resource status for the API response. Returns nil if no GPU is available on the host.
func GetGPUStatus ¶ added in v0.0.5
func GetGPUStatus() *GPUResourceStatus
GetGPUStatus returns the current GPU resource status. Returns nil if no GPU is available or the mode is "none".
type ImageLister ¶
type ImageLister interface {
// TotalImageBytes returns the total size of all images on disk.
TotalImageBytes(ctx context.Context) (int64, error)
// TotalOCICacheBytes returns the total size of the OCI layer cache.
TotalOCICacheBytes(ctx context.Context) (int64, error)
}
ImageLister provides access to image sizes for disk calculations.
type InstanceAllocation ¶
type InstanceAllocation struct {
ID string
Name string
Vcpus int
MemoryBytes int64 // Size + HotplugSize
OverlayBytes int64 // Rootfs overlay size
VolumeOverlayBytes int64 // Sum of volume overlay sizes
NetworkDownloadBps int64 // Download rate limit (external→VM)
NetworkUploadBps int64 // Upload rate limit (VM→external)
State string // Only count running/paused/created instances
VolumeBytes int64 // Sum of attached volume base sizes (for per-instance reporting)
}
InstanceAllocation represents the resources allocated to a single instance.
type InstanceLister ¶
type InstanceLister interface {
// ListInstanceAllocations returns resource allocations for all instances.
ListInstanceAllocations(ctx context.Context) ([]InstanceAllocation, error)
}
InstanceLister provides access to instance data for allocation calculations.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager coordinates resource discovery and allocation tracking.
func NewManager ¶
NewManager creates a new resource manager.
func (*Manager) CPUCapacity ¶
CPUCapacity returns the raw CPU capacity (number of vCPUs).
func (*Manager) CanAllocate ¶
CanAllocate checks if the requested amount can be allocated for a resource type.
func (*Manager) CurrentImageStorageBytes ¶
CurrentImageStorageBytes returns the current image storage usage (OCI cache + rootfs).
func (*Manager) DefaultDiskIOBandwidth ¶
DefaultDiskIOBandwidth calculates the default disk I/O bandwidth for an instance based on its CPU allocation proportional to host CPU capacity. Formula: (instanceVcpus / hostCpuCapacity) * diskIOCapacity * oversubRatio Returns sustained rate and burst rate (4x sustained).
func (*Manager) DefaultNetworkBandwidth ¶
DefaultNetworkBandwidth calculates the default network bandwidth for an instance based on its CPU allocation proportional to host CPU capacity. Formula: (instanceVcpus / hostCpuCapacity) * networkCapacity * oversubRatio Returns symmetric download/upload limits.
func (*Manager) DiskIOCapacity ¶
DiskIOCapacity returns the disk I/O capacity in bytes/sec. Uses configured DISK_IO_LIMIT if set, otherwise defaults to 1 GB/s.
func (*Manager) GetFullStatus ¶
func (m *Manager) GetFullStatus(ctx context.Context) (*FullResourceStatus, error)
GetFullStatus returns the complete resource status for all resource types.
func (*Manager) GetOversubRatio ¶
func (m *Manager) GetOversubRatio(rt ResourceType) float64
GetOversubRatio returns the oversubscription ratio for a resource type.
func (*Manager) GetStatus ¶
func (m *Manager) GetStatus(ctx context.Context, rt ResourceType) (*ResourceStatus, error)
GetStatus returns the current status of a specific resource type.
func (*Manager) HasSufficientDiskForPull ¶
HasSufficientDiskForPull checks if there's enough disk space for an image pull. Returns an error if available disk is below the minimum threshold (5GB).
func (*Manager) HasSufficientImageStorage ¶
HasSufficientImageStorage checks if pulling another image would exceed the image storage limit. Returns an error if current image storage >= max allowed.
func (*Manager) Initialize ¶
Initialize discovers host resources and registers them. Must be called after setting listers and before using the manager.
func (*Manager) MaxImageStorageBytes ¶
MaxImageStorageBytes returns the maximum allowed image storage (OCI cache + rootfs). Based on MaxImageStorage fraction (default 20%) of disk capacity.
func (*Manager) NetworkCapacity ¶
NetworkCapacity returns the raw network capacity in bytes/sec.
func (*Manager) SetImageLister ¶
func (m *Manager) SetImageLister(lister ImageLister)
SetImageLister sets the image lister for disk calculations.
func (*Manager) SetInstanceLister ¶
func (m *Manager) SetInstanceLister(lister InstanceLister)
SetInstanceLister sets the instance lister for allocation calculations.
func (*Manager) SetVolumeLister ¶
func (m *Manager) SetVolumeLister(lister VolumeLister)
SetVolumeLister sets the volume lister for disk calculations.
type MemoryResource ¶
type MemoryResource struct {
// contains filtered or unexported fields
}
MemoryResource implements Resource for memory discovery and tracking.
func NewMemoryResource ¶
func NewMemoryResource() (*MemoryResource, error)
NewMemoryResource discovers host memory capacity from /proc/meminfo.
func (*MemoryResource) Allocated ¶
func (m *MemoryResource) Allocated(ctx context.Context) (int64, error)
Allocated returns the total memory allocated to running instances.
func (*MemoryResource) Capacity ¶
func (m *MemoryResource) Capacity() int64
Capacity returns the total memory in bytes available on the host.
func (*MemoryResource) SetInstanceLister ¶
func (m *MemoryResource) SetInstanceLister(lister InstanceLister)
SetInstanceLister sets the instance lister for allocation calculations.
func (*MemoryResource) Type ¶
func (m *MemoryResource) Type() ResourceType
Type returns the resource type.
type NetworkResource ¶
type NetworkResource struct {
// contains filtered or unexported fields
}
NetworkResource implements Resource for network bandwidth discovery and tracking.
func NewNetworkResource ¶
func NewNetworkResource(ctx context.Context, cfg *config.Config, instLister InstanceLister) (*NetworkResource, error)
NewNetworkResource discovers network capacity. If cfg.NetworkLimit is set, uses that; otherwise auto-detects from uplink interface.
func (*NetworkResource) Allocated ¶
func (n *NetworkResource) Allocated(ctx context.Context) (int64, error)
Allocated returns total network bandwidth allocated to running instances. Uses the max of download/upload per instance since they share the physical link.
func (*NetworkResource) Capacity ¶
func (n *NetworkResource) Capacity() int64
Capacity returns the network capacity in bytes per second.
func (*NetworkResource) Type ¶
func (n *NetworkResource) Type() ResourceType
Type returns the resource type.
type Resource ¶
type Resource interface {
// Type returns the resource type identifier.
Type() ResourceType
// Capacity returns the raw host capacity (before oversubscription).
Capacity() int64
// Allocated returns current total allocation across all instances.
Allocated(ctx context.Context) (int64, error)
}
Resource represents a discoverable and allocatable host resource.
type ResourceStatus ¶
type ResourceStatus struct {
Type ResourceType `json:"type"`
Capacity int64 `json:"capacity"` // Raw host capacity
EffectiveLimit int64 `json:"effective_limit"` // Capacity * oversubscription ratio
Allocated int64 `json:"allocated"` // Currently allocated
Available int64 `json:"available"` // EffectiveLimit - Allocated
OversubRatio float64 `json:"oversub_ratio"` // Oversubscription ratio applied
Source SourceType `json:"source,omitempty"` // How capacity was determined
}
ResourceStatus represents the current state of a resource type.
type ResourceType ¶
type ResourceType string
ResourceType identifies a type of host resource.
const ( ResourceCPU ResourceType = "cpu" ResourceMemory ResourceType = "memory" ResourceDisk ResourceType = "disk" ResourceNetwork ResourceType = "network" )
type SourceType ¶
type SourceType string
SourceType identifies how a resource capacity was determined.
const ( SourceDetected SourceType = "detected" // Auto-detected from host hardware SourceConfigured SourceType = "configured" // Explicitly configured by operator )