aws

package
v0.36.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 17 Imported by: 0

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

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 NewClient 

func NewClient(ctx context.Context) (*Client, error)

NewClient creates a new AWS client using the default credential chain.

func NewClientFromConfig 

func NewClientFromConfig(cfg aws.Config) *Client

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 

func (c *Client) GetAllRegions(ctx context.Context) ([]string, error)

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 

func (c *Client) GetEnabledRegions(ctx context.Context) ([]string, error)

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 

func (c *Client) GetInstanceTypes(ctx context.Context, region string) ([]string, error)

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) HourlyRate added in v0.36.2 

func (c *Client) HourlyRate(ctx context.Context, instanceType, region, model string) (float64, error)

HourlyRate returns the current $/hr for one instance type in one region under the given purchase model. It is a library-friendly convenience for embedders that want a single number rather than reducing a []SpotPriceResult by hand.

model is case-insensitive:

  • "on-demand" / "ondemand" / "" → the On-Demand rate.
  • "spot" → the minimum current Spot price across AZs in the region (Spot varies by AZ; the minimum is the best obtainable rate). Returns an error if no Spot price is currently published for the type.

"reserved" is not a point-in-time rate (it depends on term, payment option, and offering class) and is rejected; use the On-Demand rate as the baseline and apply your own reserved discount.

func (*Client) OnDemandPrice added in v0.36.2 

func (c *Client) OnDemandPrice(ctx context.Context, instanceType, region string) (float64, error)

OnDemandPrice returns the current On-Demand $/hr for one instance type in one region (Linux, shared tenancy). It is a thin accessor over the client's OnDemandPricer; see Client.HourlyRate for a purchase-model-aware helper.

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

func (*Client) SetOnDemandPricer added in v0.36.2 

func (c *Client) SetOnDemandPricer(p OnDemandPricer)

SetOnDemandPricer overrides the On-Demand price source used by this client. Pass nil to reset to the default AWS Price List pricer. This is primarily for embedders and tests that want deterministic prices or an offline source.

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 Finder added in v0.36.8 

type Finder interface {
	// GetEnabledRegions returns regions enabled for the caller's account.
	GetEnabledRegions(ctx context.Context) ([]string, error)

	// GetAllRegions returns all AWS regions (enabled or not).
	GetAllRegions(ctx context.Context) ([]string, error)

	// GetInstanceTypes returns all instance type names available in a region.
	GetInstanceTypes(ctx context.Context, region string) ([]string, error)

	// SearchInstanceTypes finds instance types matching a pattern across regions.
	SearchInstanceTypes(ctx context.Context, regions []string, matcher *regexp.Regexp, opts FilterOptions) ([]InstanceTypeResult, error)

	// GetSpotPricing retrieves current Spot pricing for instance types.
	GetSpotPricing(ctx context.Context, instances []InstanceTypeResult, opts SpotOptions) ([]SpotPriceResult, error)

	// GetCapacityReservations retrieves ODCRs across regions.
	GetCapacityReservations(ctx context.Context, regions []string, opts CapacityReservationOptions) ([]CapacityReservationResult, error)

	// GetCapacityBlocks retrieves Capacity Blocks for ML across regions.
	GetCapacityBlocks(ctx context.Context, regions []string, opts CapacityBlockOptions) ([]CapacityBlockResult, error)

	// OnDemandPrice returns the on-demand $/hr for an instance type in a region.
	OnDemandPrice(ctx context.Context, instanceType, region string) (float64, error)

	// HourlyRate returns $/hr under a given purchase model ("on-demand" or "spot").
	HourlyRate(ctx context.Context, instanceType, region, model string) (float64, error)
}

Finder is the read-only query interface for EC2 instance discovery. The concrete Client satisfies this interface. Downstream consumers should accept Finder in their function signatures to enable unit testing with [awsmock.Finder] or any custom implementation.

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
	SpawnSupported  bool     `json:"spawn_supported,omitempty" yaml:"spawn_supported,omitempty"`       // True if spawn can launch instances in this region
}

InstanceTypeResult represents an instance type's availability and specifications in a given region, as returned by Client.SearchInstanceTypes.

type OnDemandPricer added in v0.36.2 

type OnDemandPricer interface {
	// OnDemandPrice returns the On-Demand $/hr for instanceType in region.
	// It returns (0, error) when no price could be determined.
	OnDemandPrice(ctx context.Context, instanceType, region string) (float64, error)
}

OnDemandPricer resolves the On-Demand hourly rate ($/hr) for a Linux instance type in a region. Implementations should be safe for concurrent use.

truffle uses this to populate SpotPriceResult.OnDemandPrice and SpotPriceResult.SavingsPercent (when SpotOptions.ShowSavings is set) and to back the Client.HourlyRate convenience. The default implementation (NewAWSOnDemandPricer) queries the AWS Price List API and caches results; callers embedding truffle as a library can inject their own via Client.SetOnDemandPricer (e.g. a fixture in tests).

func NewAWSOnDemandPricer added in v0.36.2 

func NewAWSOnDemandPricer(cfg aws.Config) OnDemandPricer

NewAWSOnDemandPricer returns an OnDemandPricer backed solely by the AWS Price List API (no static fallback). Most callers want the client default; this is exported for embedders that want to control fallback behavior.

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.

Source Files

View all Source files

Directories

Path Synopsis
Package awsmock provides a configurable mock implementation of aws.Finder for unit testing downstream consumers of truffle's instance discovery API.
 Package awsmock provides a configurable mock implementation of aws.Finder for unit testing downstream consumers of truffle's instance discovery API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.