Documentation
¶
Overview ¶
Package aws provides EC2 capacity discovery for the truffle tool. It searches instance type availability, retrieves Spot pricing history, and queries On-Demand Capacity Reservations (ODCRs) and Capacity Blocks for ML workloads across one or more AWS regions concurrently.
Typical usage:
client, err := aws.NewClient(ctx)
results, err := client.SearchInstanceTypes(ctx, []string{"us-east-1"}, pattern, filterOpts)
prices, err := client.GetSpotPricing(ctx, results, aws.SpotOptions{ShowSavings: true})
Index ¶
- type CapacityBlockOptions
- type CapacityBlockResult
- type CapacityReservationOptions
- type CapacityReservationResult
- type Client
- func (c *Client) GetAllRegions(ctx context.Context) ([]string, error)
- func (c *Client) GetCapacityBlocks(ctx context.Context, regions []string, opts CapacityBlockOptions) ([]CapacityBlockResult, error)
- func (c *Client) GetCapacityReservations(ctx context.Context, regions []string, opts CapacityReservationOptions) ([]CapacityReservationResult, error)
- func (c *Client) GetEnabledRegions(ctx context.Context) ([]string, error)
- func (c *Client) GetInstanceTypes(ctx context.Context, region string) ([]string, error)
- func (c *Client) GetSpotPricing(ctx context.Context, instances []InstanceTypeResult, opts SpotOptions) ([]SpotPriceResult, error)
- func (c *Client) SearchInstanceTypes(ctx context.Context, regions []string, matcher *regexp.Regexp, ...) ([]InstanceTypeResult, error)
- type FilterOptions
- type InstanceTypeResult
- type SpotOptions
- type SpotPriceResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CapacityBlockOptions ¶
type CapacityBlockOptions struct {
InstanceTypes []string
MinDuration int32 // Minimum duration in hours
MaxDuration int32 // Maximum duration in hours
StartAfter string // ISO format datetime
StartBefore string // ISO format datetime
OnlyActive bool
Verbose bool
}
CapacityBlockOptions contains Capacity Block search options
type CapacityBlockResult ¶
type CapacityBlockResult struct {
CapacityBlockID string `json:"capacity_block_id" yaml:"capacity_block_id"`
InstanceType string `json:"instance_type" yaml:"instance_type"`
InstanceCount int32 `json:"instance_count" yaml:"instance_count"`
AvailabilityZone string `json:"availability_zone" yaml:"availability_zone"`
StartDate string `json:"start_date" yaml:"start_date"`
EndDate string `json:"end_date" yaml:"end_date"`
DurationHours int32 `json:"duration_hours" yaml:"duration_hours"`
State string `json:"state" yaml:"state"` // scheduled, active, completed, cancelled
ReservationFee float64 `json:"reservation_fee" yaml:"reservation_fee"`
UltraClusterPlacement bool `json:"ultra_cluster_placement" yaml:"ultra_cluster_placement"`
Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
}
CapacityBlockResult represents a Capacity Block for ML
type CapacityReservationOptions ¶
type CapacityReservationOptions struct {
InstanceTypes []string
OnlyAvailable bool // Only show reservations with available capacity
OnlyActive bool // Only show active reservations
IncludeExpired bool // Include expired reservations
MinCapacity int32 // Minimum available capacity
Verbose bool
}
CapacityReservationOptions contains ODCR search options
type CapacityReservationResult ¶
type CapacityReservationResult struct {
ReservationID string `json:"reservation_id" yaml:"reservation_id"`
InstanceType string `json:"instance_type" yaml:"instance_type"`
Region string `json:"region" yaml:"region"`
AvailabilityZone string `json:"availability_zone" yaml:"availability_zone"`
TotalCapacity int32 `json:"total_capacity" yaml:"total_capacity"`
AvailableCapacity int32 `json:"available_capacity" yaml:"available_capacity"`
UsedCapacity int32 `json:"used_capacity" yaml:"used_capacity"`
State string `json:"state" yaml:"state"`
Tenancy string `json:"tenancy" yaml:"tenancy"`
EBSOptimized bool `json:"ebs_optimized" yaml:"ebs_optimized"`
EndDate string `json:"end_date,omitempty" yaml:"end_date,omitempty"`
Platform string `json:"platform" yaml:"platform"`
Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
}
CapacityReservationResult represents an ODCR (On-Demand Capacity Reservation)
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps AWS SDK clients
func NewClientFromConfig ¶
NewClientFromConfig creates a new AWS client with an injected aws.Config. Use this in tests to point the client at a Substrate emulator.
func (*Client) GetAllRegions ¶
GetAllRegions is deprecated. Use GetEnabledRegions instead. This method is kept for backward compatibility.
func (*Client) GetCapacityBlocks ¶
func (c *Client) GetCapacityBlocks(ctx context.Context, regions []string, opts CapacityBlockOptions) ([]CapacityBlockResult, error)
GetCapacityBlocks retrieves Capacity Blocks for ML
func (*Client) GetCapacityReservations ¶
func (c *Client) GetCapacityReservations(ctx context.Context, regions []string, opts CapacityReservationOptions) ([]CapacityReservationResult, error)
GetCapacityReservations retrieves On-Demand Capacity Reservations (ODCRs)
func (*Client) GetEnabledRegions ¶
GetEnabledRegions returns AWS regions enabled for this account. This respects Service Control Policies (SCPs) that may restrict regions. Regions blocked by organizational SCPs will not appear in the returned list.
func (*Client) GetInstanceTypes ¶
GetInstanceTypes returns all instance types in a region
func (*Client) GetSpotPricing ¶
func (c *Client) GetSpotPricing(ctx context.Context, instances []InstanceTypeResult, opts SpotOptions) ([]SpotPriceResult, error)
GetSpotPricing retrieves current Spot pricing for instance types
func (*Client) SearchInstanceTypes ¶
func (c *Client) SearchInstanceTypes(ctx context.Context, regions []string, matcher *regexp.Regexp, opts FilterOptions) ([]InstanceTypeResult, error)
SearchInstanceTypes searches for instance types matching the pattern across regions
type FilterOptions ¶
type FilterOptions struct {
IncludeAZs bool // If true, populate InstanceTypeResult.AvailableAZs (one extra API call per type)
Architecture string // Filter to "x86_64" or "arm64"; empty matches both
MinVCPUs int // Minimum vCPU count; 0 disables this filter
MinMemory float64 // Minimum memory in GiB; 0 disables this filter
ExactVCPUs bool // If true, match exact vCPU count instead of minimum
ExactMemory bool // If true, match exact memory instead of minimum
InstanceFamily string // Restrict to a family prefix, e.g. "m6i"; empty matches all
Verbose bool // If true, log per-region progress to stderr
}
FilterOptions controls which instance types are returned by Client.SearchInstanceTypes.
type InstanceTypeResult ¶
type InstanceTypeResult struct {
InstanceType string `json:"instance_type" yaml:"instance_type"` // EC2 instance type, e.g. "m6i.2xlarge"
Region string `json:"region" yaml:"region"` // AWS region where this type is available
AvailableAZs []string `json:"availability_zones,omitempty" yaml:"availability_zones,omitempty"` // AZs with capacity; populated when FilterOptions.IncludeAZs is true
VCPUs int32 `json:"vcpus,omitempty" yaml:"vcpus,omitempty"` // Default vCPU count
MemoryMiB int64 `json:"memory_mib,omitempty" yaml:"memory_mib,omitempty"` // Memory in MiB
Architecture string `json:"architecture,omitempty" yaml:"architecture,omitempty"` // CPU architecture: "x86_64" or "arm64"
InstanceFamily string `json:"instance_family,omitempty" yaml:"instance_family,omitempty"` // Family prefix, e.g. "m6i"
GPUs int32 `json:"gpus,omitempty" yaml:"gpus,omitempty"` // Number of GPUs; 0 for non-GPU instances
GPUMemoryMiB int64 `json:"gpu_memory_mib,omitempty" yaml:"gpu_memory_mib,omitempty"` // Total GPU memory in MiB across all GPUs
GPUModel string `json:"gpu_model,omitempty" yaml:"gpu_model,omitempty"` // GPU model name, e.g. "A100"
GPUManufacturer string `json:"gpu_manufacturer,omitempty" yaml:"gpu_manufacturer,omitempty"` // GPU vendor, e.g. "nvidia"
OnDemandPrice float64 `json:"on_demand_price,omitempty" yaml:"on_demand_price,omitempty"` // On-demand $/hr; 0 if not yet fetched
}
InstanceTypeResult represents an instance type's availability and specifications in a given region, as returned by Client.SearchInstanceTypes.
type SpotOptions ¶
type SpotOptions struct {
MaxPrice float64 // Exclude results above this $/hr threshold; 0 disables
ShowSavings bool // Populate SpotPriceResult.SavingsPercent by comparing with on-demand price
LookbackHours int // Hours of price history to query; 0 uses the AWS default (typically 1 hour)
OnlyActive bool // Exclude price history entries with no current offering
Verbose bool // If true, log per-region progress to stderr
}
SpotOptions controls the behavior of Client.GetSpotPricing.
type SpotPriceResult ¶
type SpotPriceResult struct {
InstanceType string `json:"instance_type" yaml:"instance_type"` // EC2 instance type
Region string `json:"region" yaml:"region"` // AWS region
AvailabilityZone string `json:"availability_zone" yaml:"availability_zone"` // AZ where this price applies
SpotPrice float64 `json:"spot_price" yaml:"spot_price"` // Current Spot price in $/hr
OnDemandPrice float64 `json:"on_demand_price,omitempty" yaml:"on_demand_price,omitempty"` // On-demand $/hr for savings calculation; 0 if unavailable
SavingsPercent float64 `json:"savings_percent,omitempty" yaml:"savings_percent,omitempty"` // Discount vs on-demand: 100*(1-spot/ondemand); set when SpotOptions.ShowSavings is true
Timestamp string `json:"timestamp" yaml:"timestamp"` // RFC3339 timestamp of the price observation
ProductType string `json:"product_type,omitempty" yaml:"product_type,omitempty"` // OS description, e.g. "Linux/UNIX"
}
SpotPriceResult represents a Spot instance price observation for one AZ, as returned by Client.GetSpotPricing.