catalog

Documentation

Overview

Package catalog provides instance type discovery, pricing information, and resource management. Each cloud provider has a unified interface for querying instance types, accelerators, costs, and resource availability. Instance and Resource are treated as logically equivalent concepts.

Index

• func Register(provider types.ResourceProvisionType, f Factory)
• type Catalog
  • func NewCatalog(provider types.ResourceProvisionType) (Catalog, error)
• type Factory
• type ListResourceFilter
• type PricingCatalog
• type RegionResource
• type RegionResourceItem
• type Resource
• type ResourceCatalog
• type ResourceItem
• type ResourceListOptions
• type ResourcePricing
• type ResourcePricingItem
• type ResourceStat
• type ResourceStatItem
• type ScheduledResourceItem
• type ScheduledResourceStatItem

Functions

func Register

func Register(provider types.ResourceProvisionType, f Factory)

Register adds a provider catalog factory. Intended to be called from a provider package's init(); last writer wins.

Types

type Catalog

type Catalog interface {
	// Provider returns the cloud provider this catalog is for.
	Provider() types.ResourceProvisionType

	// ResourceCatalog provides resource discovery.
	ResourceCatalog

	// PricingCatalog provides pricing information.
	PricingCatalog
}

Catalog provides resource discovery and pricing information.

func NewCatalog

func NewCatalog(provider types.ResourceProvisionType) (Catalog, error)

type Factory

type Factory func() (Catalog, error)

Factory constructs a Catalog for a provider. Providers self-register their factory from init() (see resource_manager/provider/*), so the dependency points provider -> catalog only, never the reverse.

type ListResourceFilter

type ListResourceFilter struct {
	// ResourceSelector selects resources.
	ResourceSelectors []types.Selector `json:"resourceSelectors"`
}

ListResourceFilter contains filters for listing resources.

type PricingCatalog

type PricingCatalog interface {
	// ListPricing returns pricing information for instance types.
	ListPricing(ctx context.Context, opts *ResourceListOptions) ([]ResourcePricing, error)

	// ListPricingPredictions lists pricing predictions for the options.
	ListPricingPredictions(ctx context.Context, opts *ResourceListOptions) (map[string]ResourcePricing, error)
}

PricingCatalog provides pricing information.

type RegionResource

type RegionResource struct {
	// Region is the region identifier, provider-specific.
	Region *types.RegionSpec `json:"region"`

	// "overview": [
	//     {
	//         "key": "xxx.kubernetes.io/minipod",
	//         "stat": {
	//             "spot" : {
	//                 "allocated": {
	//                     "gpu": {
	//                         "NVIDIA-H20": "2118"
	//                     },
	//                     "instance": {
	//                         "ae5.sx-nvidia.h20.96g.1x": "12",
	//                         "age5.2x-nvidia.h20.96g.8x": "2",
	//                         "are7.1xl-nvidia.h20.96g.4x": "4",
	//                         "are7.2xl-nvidia.h20.96g.8x": "228",
	//                         "are8.sx-nvidia.h20.96g.2x": "125"
	//                     }
	//                 },
	//                 "allocatable": {
	//                     "gpu": {
	//                         "NVIDIA-H20": "898"
	//                     }
	//                 },
	//                 "supply": {
	//                     "gpu": {
	//                         "NVIDIA-H20": "3016"
	//                     }
	//                 },
	//             },
	//         },
	//         "value": "abc-fcten9xi29f9dxas9e21",
	//     }
	// ]
	Overview []RegionResourceItem `json:"overview"`

	Breakdown map[string][]RegionResourceItem `json:"breakdown,omitempty"`
}

RegionResource contains region-level resource information.

type RegionResourceItem

type RegionResourceItem struct {
	// NextLevel provides next-level resource statistics.
	NextLevel []RegionResourceItem `json:"nextLevel,omitempty"`

	// Key is the resource key (e.g., minipod, bigpod).
	Key string `json:"key"`

	// Value is the resource value.
	Value string `json:"value"`

	// Stat contains detailed resource statistics.
	Stat ResourceStat `json:"stat"`
}

RegionResourceItem represents a single resource item statistics.

type Resource

type Resource struct {
	RegionResource

	// Provider is the cloud provider.
	Provider types.ResourceProvisionType `json:"provider"`
}

Resource

type ResourceCatalog

type ResourceCatalog interface {
	// ListRegions lists available regions for the catalog.
	ListRegions(ctx context.Context) ([]types.RegionSpec, error)

	// ListInstanceTypes lists available instance types for the catalog.
	ListInstanceTypes(ctx context.Context, region *types.RegionSpec) ([]types.InstanceTypeSpec, error)

	// ListResources lists available resources matching the options.
	ListResources(ctx context.Context, opts *ResourceListOptions) ([]Resource, error)

	// ListResourcePredictions lists resource predictions for the options.
	ListResourcePredictions(ctx context.Context, opts *ResourceListOptions) (map[string]Resource, error)
}

ResourceCatalog provides resource discovery.

type ResourceItem

type ResourceItem map[string]map[string]string

ResourceItem maps resource names to quantities (resource type -> resource name -> quantity).

type ResourceListOptions

type ResourceListOptions struct {
	// Region is the region identifier, provider-specific.
	Region types.RegionSpec `json:"region"`

	// Only used for historical and future resource listing
	StartTime *time.Time `json:"start_time,omitempty"` // format 2026-03-07T03:29:00Z, UTC time
	EndTime   *time.Time `json:"end_time,omitempty"`   // format 2026-03-07T03:29:00Z, UTC time

	// Filter contains the resource filters.
	Filter *ListResourceFilter `json:"filter,omitempty"`
}

ResourceListOptions contains options for listing resources.

type ResourcePricing

type ResourcePricing struct {
	// Region is the region identifier, provider-specific.
	Region types.RegionSpec `json:"region"`

	// Items contains pricing items for each resource type.
	Items map[string]ResourcePricingItem `json:"items"`
}

ResourcePricing contains pricing information for a region.

type ResourcePricingItem

type ResourcePricingItem struct {
	// OnDemandPrice is the hourly on-demand price in USD.
	OnDemandPrice *float64 `json:"onDemandPrice,omitempty"`

	// SpotPrice is the hourly spot price in USD.
	SpotPrice *float64 `json:"spotPrice,omitempty"`

	// ScheduledPrice is the hourly scheduled price in USD.
	ScheduledPrice *float64 `json:"scheduledPrice,omitempty"`
}

type ResourceStat

type ResourceStat struct {
	// OnDemand contains on-demand resource statistics.
	OnDemand *ResourceStatItem `json:"onDemand,omitempty"`

	// Spot contains spot resource statistics.
	Spot *ResourceStatItem `json:"spot,omitempty"`

	// Scheduled contains scheduled resource statistics.
	Scheduled *ScheduledResourceStatItem `json:"scheduled,omitempty"`
}

ResourceStat contains detailed resource allocation statistics.

type ResourceStatItem

type ResourceStatItem struct {
	// Allocated resources.
	Allocated ResourceItem `json:"allocated"`

	// Supply resources.
	Supply ResourceItem `json:"supply"`

	// Allocatable resources.
	Allocatable ResourceItem `json:"allocatable"`
}

type ScheduledResourceItem

type ScheduledResourceItem map[string]ResourceItem

ScheduledResourceItem maps timestamps to ResourceItem.

type ScheduledResourceStatItem

type ScheduledResourceStatItem struct {
	// Allocated resources.
	Allocated ScheduledResourceItem `json:"allocated"`

	// Supply resources.
	Supply ScheduledResourceItem `json:"supply"`

	// Allocatable resources.
	Allocatable ScheduledResourceItem `json:"allocatable"`
}