ec2instancesinfo

README

ec2-instances-info

Golang library providing specs and pricing information about cloud resources such as:

• AWS EC2 instances
• AWS RDS databases
• AWS ElastiCache clusters
• AWS OpenSearch clusters
• Azure VM instances

It is based on the data that is also powering the comprehensive www.ec2instances.info instance comparison website, but made easier to consume from Go software.

This code is offered under the public domain/unlicense, but we also offer an API that automates data updates, available for a monthly subscription that helps support ongoing development of this library.

Reach out to us on Slack if you're interested in API access.

History

This used to be a part of my other project AutoSpotting which uses it intensively, but I decided to extract it into a dedicated project since it may be useful to someone else out there.

Some data fields that were not needed in AutoSpotting may not yet be exposed but they can be added upon demand.

Installation or update

You will need Go 1.16 or latest, then it's a matter of installing it as usual using go get

go get -u github.com/LeanerCloud/ec2-instances-info/...

Usage

AWS EC2 Usage

One-off usage, with static data

import "github.com/LeanerCloud/ec2-instances-info"

data, err := ec2instancesinfo.Data() // only needed once

// This would print all the available instance type names:
for _, i := range *data {
  fmt.Println("Instance type", i.InstanceType)
}

See the examples directory for a working code example.

One-off usage, with updated instance type data

import "github.com/LeanerCloud/ec2-instances-info"

key := "API_KEY" // API keys are available upon demand from contact@leanercloud.com, free of charge for personal use

err:= ec2instancesinfo.UpdateData(nil, &key);
if err!= nil{
   fmt.Println("Couldn't update instance type data, reverting to static compile-time data", err.Error())
}

data, err := ec2instancesinfo.Data() // needs to be called once after data updates

// This would print all the available instance type names:
for _, i := range *data {
  fmt.Println("Instance type", i.InstanceType)
}

Continuous usage, with instance type data updated every 2 days

import "github.com/LeanerCloud/ec2-instances-info"

key := "API_KEY"
go ec2instancesinfo.Updater(2, nil, &key); // use 0 or negative values for weekly updates

data, err := ec2instancesinfo.Data() // only needed once

// This would print all the available instance type names:
for _, i := range *data {
  fmt.Println("Instance type", i.InstanceType)
}

Azure VM Usage

Basic usage, with static data

import "github.com/LeanerCloud/ec2-instances-info"

data, err := ec2instancesinfo.AzureData() // only needed once

// This would print all the available Azure VM instance type names:
for _, i := range *data {
  fmt.Println("Azure VM instance type:", i.InstanceType)
}

One-off usage, with updated Azure VM data

import "github.com/LeanerCloud/ec2-instances-info"

key := "API_KEY" // API keys are available upon demand from contact@leanercloud.com

err := ec2instancesinfo.UpdateAzureData(nil, &key)
if err != nil {
   fmt.Println("Couldn't update Azure VM data, reverting to static compile-time data", err.Error())
}

data, err := ec2instancesinfo.AzureData() // needs to be called once after data updates

// This would print all the available Azure VM instance type names:
for _, i := range *data {
  fmt.Println("Azure VM instance type:", i.InstanceType)
}

Continuous usage, with Azure VM data updated every 2 days

import "github.com/LeanerCloud/ec2-instances-info"

key := "API_KEY"
go ec2instancesinfo.AzureUpdater(2, nil, &key); // use 0 or negative values for weekly updates

data, err := ec2instancesinfo.AzureData() // only needed once

// This would print all the available Azure VM instance type names:
for _, i := range *data {
  fmt.Println("Azure VM instance type:", i.InstanceType)
}

Contributing

Pull requests and feedback are welcome.

The data can be updated for new instance type coverage by running make.

Try it out on GCP Cloud Shell

• 

• Click on the Terminal then New Terminal in the top menu

• In the terminal run cd ~/cloudshell_open/ec2-instances-info/examples/instances/

• go run . will run the example EC2 code.

• For Azure VM data: cd ~/cloudshell_open/ec2-instances-info/examples/azure/ and go run .

Documentation

Overview

azure_vm.go with updated fields

Index

• func AzureData() (*[]AzureInstanceData, error)
• func AzureUpdater(refreshDays int, apiHost, apiKey *string) error
• func UpdateAzureData(apiHost, apiKey *string) error
• func UpdateData(apiHost, apiKey *string) error
• func Updater(refreshDays int, apiHost, apiKey *string) error
• type AzureInstanceData
• type AzureOSPricing
• type AzurePricing
• type AzureStorage
• type ElastiCacheInstance
• type ElastiCacheInstanceData
  • func ElastiCacheData() (*ElastiCacheInstanceData, error)
• type InstanceData
  • func Data() (*InstanceData, error)
• type OpenSearchInstance
• type OpenSearchInstanceData
  • func OpenSearchData() (*OpenSearchInstanceData, error)
• type OpenSearchRegionPricing
• type OpenSearchReservedPricing
• type Pricing
• type PricingDetail
• type RDSInstance
• type RDSInstanceData
  • func RDSData() (*RDSInstanceData, error)
• type RDSPricing
• type RDSRegionPrices
• type RDSReserved
• type RegionPrices
• type RegionPricing
• type Regions
• type Reserved
• type ReservedPricing
• type ServicePricing
• type StorageConfiguration

Functions

func AzureData

func AzureData() (*[]AzureInstanceData, error)

AzureData returns the Azure VM instance data, either from the in-memory cache or by loading the data from the JSON file

func AzureUpdater

func AzureUpdater(refreshDays int, apiHost, apiKey *string) error

AzureUpdater continuously updates the Azure VM instance data at the specified interval

func UpdateAzureData

func UpdateAzureData(apiHost, apiKey *string) error

UpdateAzureData updates the Azure VM instance data by downloading it from the API

func UpdateData

func UpdateData(apiHost, apiKey *string) error

func Updater

func Updater(refreshDays int, apiHost, apiKey *string) error

Types

type AzureInstanceData

type AzureInstanceData struct {
	ACU                   int                     `json:"ACU"`
	GPU                   string                  `json:"GPU"`
	AcceleratedNetworking bool                    `json:"accelerated_networking"`
	Arch                  []string                `json:"arch"`
	AvailabilityZones     map[string]interface{}  `json:"availability_zones"`
	CachedDisk            int                     `json:"cached_disk"`
	CapacitySupport       bool                    `json:"capacity_support"`
	Category              string                  `json:"category"`
	Confidential          interface{}             `json:"confidential"` // Can be false or "SNP"
	Encryption            bool                    `json:"encryption"`
	Family                string                  `json:"family"`
	Hibernation           interface{}             `json:"hibernation"`
	HypervGenerations     string                  `json:"hyperv_generations"`
	InstanceType          string                  `json:"instance_type"`
	IOPS                  interface{}             `json:"iops"`
	LowPriority           bool                    `json:"low_priority"`
	Memory                float64                 `json:"memory"`
	MemoryMaintenance     bool                    `json:"memory_maintenance"`
	PremiumIO             bool                    `json:"premium_io"`
	PrettyName            string                  `json:"pretty_name"`
	PrettyNameAzure       string                  `json:"pretty_name_azure"`
	Pricing               map[string]AzurePricing `json:"pricing"`
	RDMA                  bool                    `json:"rdma"`
	ReadIO                int                     `json:"read_io"`
	Size                  int                     `json:"size"`
	Storage               *AzureStorage           `json:"storage"`
	TrustedLaunch         interface{}             `json:"trusted_launch"`
	UltraSSD              bool                    `json:"ultra_ssd"`
	UncachedDisk          int                     `json:"uncached_disk"`
	UncachedDiskIO        int                     `json:"uncached_disk_io"`
	VCPU                  int                     `json:"vcpu"`
	VCPUsAvailable        int                     `json:"vcpus_available"`
	VCPUsPerCore          int                     `json:"vcpus_percore"`
	VMDeployment          string                  `json:"vm_deployment"`
	WriteIO               int                     `json:"write_io"`
}

AzureInstanceData represents data about a specific Azure VM instance type

type AzureOSPricing

type AzureOSPricing struct {
	Basic       float64                `json:"basic"`
	BasicSpot   float64                `json:"basic-spot"`
	LowPriority float64                `json:"lowpriority,omitempty"`
	OnDemand    float64                `json:"ondemand"`
	Reserved    map[string]interface{} `json:"reserved"`
	SpotMin     float64                `json:"spot_min"`
	// Windows specific
	HybridBenefit float64 `json:"hybridbenefit,omitempty"`
}

AzureOSPricing contains pricing details for a specific OS

type AzurePricing

type AzurePricing struct {
	Linux   AzureOSPricing `json:"linux"`
	Windows AzureOSPricing `json:"windows"`
}

AzurePricing contains pricing information for a region

type AzureStorage

type AzureStorage struct {
	Devices       interface{} `json:"devices"`
	MaxWriteDisks interface{} `json:"max_write_disks"`
	NVMeSSD       interface{} `json:"nvme_ssd"` // Can be string with numeric value or false
	Size          int64       `json:"size"`
}

AzureStorage contains Azure VM storage information

type ElastiCacheInstance

type ElastiCacheInstance struct {
	ServiceCode                                    string                    `json:"servicecode"`
	InstanceType                                   string                    `json:"instanceType"`
	CurrentGeneration                              string                    `json:"currentGeneration"`
	InstanceFamily                                 string                    `json:"instanceFamily"`
	Vcpu                                           int32                     `json:"vcpu,string"`
	Memory                                         float64                   `json:"memory,string"`
	NetworkPerformance                             string                    `json:"networkPerformance"`
	CacheEngine                                    string                    `json:"cacheEngine"`
	RegionCode                                     string                    `json:"regionCode"`
	Servicename                                    string                    `json:"servicename"`
	Network_performance                            string                    `json:"network_performance"`
	Family                                         string                    `json:"family"`
	Instance_type                                  string                    `json:"instance_type"`
	Pricing                                        map[string]ServicePricing `json:"pricing"`
	Regions                                        map[string]string         `json:"regions"`
	PrettyName                                     string                    `json:"pretty_name"`
	Memcached1_6_MaxCacheMemory                    string                    `json:"memcached1.6-max_cache_memory"`
	Memcached1_6_NumThreads                        string                    `json:"memcached1.6-num_threads"`
	Redis6xClientOutputBufferLimitReplicaHardLimit string                    `json:"redis6.x-client-output-buffer-limit-replica-hard-limit"`
	Redis6xClientOutputBufferLimitReplicaSoftLimit string                    `json:"redis6.x-client-output-buffer-limit-replica-soft-limit"`
	Redis6xMaxmemory                               string                    `json:"redis6.x-maxmemory"`
	MaxClients                                     string                    `json:"max_clients"`
}

ElastiCacheInstance represents the structure of each JSON object in the array.

type ElastiCacheInstanceData

type ElastiCacheInstanceData []ElastiCacheInstance

func ElastiCacheData

func ElastiCacheData() (*ElastiCacheInstanceData, error)

type InstanceData

type InstanceData []jsonInstance

InstanceData is a large data structure containing pricing and specs information about all the EC2 instance types from all AWS regions.

func Data

func Data() (*InstanceData, error)

Data generates the InstanceData object based on data sourced from ec2instances.info. The data is available there as a JSON blob, which is converted into golang source-code by the go-bindata tool and unmarshaled into a golang data structure by this library.

type OpenSearchInstance

type OpenSearchInstance struct {
	ServiceCode       string                             `json:"servicecode"`
	InstanceType      string                             `json:"instanceType"`
	CurrentGeneration string                             `json:"currentGeneration"`
	InstanceFamily    string                             `json:"instanceFamily"`
	Vcpu              int32                              `json:"vcpu,string"`
	MemoryGib         float64                            `json:"memoryGib,string"`
	RegionCode        string                             `json:"regionCode"`
	Servicename       string                             `json:"servicename"`
	Family            string                             `json:"family"`
	Instance_type     string                             `json:"instance_type"`
	Pricing           map[string]OpenSearchRegionPricing `json:"pricing"`
}

type OpenSearchInstanceData

type OpenSearchInstanceData []OpenSearchInstance

func OpenSearchData

func OpenSearchData() (*OpenSearchInstanceData, error)

type OpenSearchRegionPricing

type OpenSearchRegionPricing struct {
	OnDemand float64                   `json:"ondemand"`
	Reserved OpenSearchReservedPricing `json:"reserved"`
}

type OpenSearchReservedPricing

type OpenSearchReservedPricing struct {
	YrTerm3StandardPartialUpfront float64 `json:"yrTerm3Standard.partialUpfront"`
	YrTerm1StandardPartialUpfront float64 `json:"yrTerm1Standard.partialUpfront"`
	YrTerm3StandardAllUpfront     float64 `json:"yrTerm3Standard.allUpfront"`
	YrTerm1StandardNoUpfront      float64 `json:"yrTerm1Standard.noUpfront"`
	YrTerm3StandardNoUpfront      float64 `json:"yrTerm3Standard.noUpfront"`
}

type Pricing

type Pricing struct {
	OnDemand float64  `json:"ondemand,string"`
	SpotMin  float64  `json:"spot_min,string"`
	SpotMax  float64  `json:"spot_max,string"`
	Reserved Reserved `json:"reserved"`
}

type PricingDetail

type PricingDetail struct {
	OnDemand float64         `json:"ondemand"`
	Reserved ReservedPricing `json:"reserved"`
}

PricingDetail represents the pricing information for each term.

type RDSInstance

type RDSInstance struct {
	Arch                        string `json:"arch,omitempty"`
	ClockSpeed                  string `json:"clockSpeed,omitempty"`
	CurrentGenerationRaw        string `json:"currentGeneration,omitempty"`
	CurrentGeneration           bool
	DedicatedEbsThroughput      string                     `json:"dedicatedEbsThroughput,omitempty"`
	EbsBaselineBandwidth        float64                    `json:"ebs_baseline_bandwidth,omitempty"`
	EbsBaselineIops             float64                    `json:"ebs_baseline_iops,omitempty"`
	EbsBaselineThroughput       float64                    `json:"ebs_baseline_throughput,omitempty"`
	EbsIops                     float64                    `json:"ebs_iops,omitempty"`
	EbsMaxBandwidth             float64                    `json:"ebs_max_bandwidth,omitempty"`
	EbsOptimized                bool                       `json:"ebs_optimized,omitempty"`
	EbsOptimizedByDefault       bool                       `json:"ebs_optimized_by_default,omitempty"`
	EbsThroughput               float64                    `json:"ebs_throughput,omitempty"`
	EnhancedNetworkingSupported string                     `json:"enhancedNetworkingSupported,omitempty"`
	Family                      string                     `json:"family,omitempty"`
	InstanceFamily              string                     `json:"instanceFamily,omitempty"`
	InstanceType                string                     `json:"instance_type,omitempty"`
	InstanceTypeFamily          string                     `json:"instanceTypeFamily,omitempty"`
	Memory                      float32                    `json:"memory,omitempty,string"`
	NetworkPerformance          string                     `json:"network_performance,omitempty"`
	NormalizationSizeFactor     string                     `json:"normalizationSizeFactor,omitempty"`
	PhysicalProcessor           string                     `json:"physicalProcessor,omitempty"`
	PrettyName                  string                     `json:"pretty_name,omitempty"`
	Pricing                     map[string]RDSRegionPrices `json:"pricing,omitempty"`
	ProcessorArchitecture       string                     `json:"processorArchitecture,omitempty"`
	RegionCode                  string                     `json:"regionCode,omitempty"`
	Regions                     Regions                    `json:"regions,omitempty"`
	Servicecode                 string                     `json:"servicecode,omitempty"`
	Servicename                 string                     `json:"servicename,omitempty"`
	Storage                     string                     `json:"storage,omitempty"`
	Vcpu                        int32                      `json:"vcpu,omitempty,string"`
}

type RDSInstanceData

type RDSInstanceData []RDSInstance

func RDSData

func RDSData() (*RDSInstanceData, error)

type RDSPricing

type RDSPricing struct {
	OnDemand float64     `json:"ondemand"`
	Reserved RDSReserved `json:"reserved"`
}

type RDSRegionPrices

type RDSRegionPrices struct {
	AuroraPostgreSQL             RDSPricing `json:"Aurora PostgreSQL,omitempty"`
	PostgreSQL                   RDSPricing `json:"PostgreSQL,omitempty"`
	SQLServer                    RDSPricing `json:"SQL Server,omitempty"`
	SQLServerOnPremiseForOutpost RDSPricing `json:"SQL Server (on-premise for Outpost),omitempty"`
	Oracle                       RDSPricing `json:"Oracle,omitempty"`
	MariaDB                      RDSPricing `json:"MariaDB,omitempty"`
	AuroraMySQL                  RDSPricing `json:"Aurora MySQL,omitempty"`
	MySQL                        RDSPricing `json:"MySQL,omitempty"`
}

type RDSReserved

type RDSReserved struct {
	StandardNoUpfront1Year          float64 `json:"yrTerm1Standard.noUpfront"`
	StandardNoUpfront3Years         float64 `json:"yrTerm3Standard.noUpfront"`
	StandardPartiallUpfront1Year    float64 `json:"yrTerm1Standard.partialUpfront"`
	StandardPartialUpfront3Years    float64 `json:"yrTerm3Standard.partialUpfront"`
	StandardAllUpfront1Year         float64 `json:"yrTerm1Standard.allUpfront"`
	StandardAllUpfront3Years        float64 `json:"yrTerm3Standard.allUpfront"`
	ConvertibleNoUpfront1Year       float64 `json:"yrTerm1Convertible.noUpfront"`
	ConvertibleNoUpfront3Years      float64 `json:"yrTerm3Convertible.noUpfront"`
	ConvertiblePartiallUpfront1Year float64 `json:"yrTerm1Convertible.partialUpfront"`
	ConvertiblePartialUpfront3Years float64 `json:"yrTerm3Convertible.partialUpfront"`
	ConvertibleAllUpfront1Year      float64 `json:"yrTerm1Convertible.allUpfront"`
	ConvertibleAllUpfront3Years     float64 `json:"yrTerm3Convertible.allUpfront"`
}

type RegionPrices

type RegionPrices struct {
	Linux              Pricing `json:"linux"`
	LinuxSQL           Pricing `json:"linuxSQL"`
	LinuxSQLEnterprise Pricing `json:"linuxSQLEnterprise"`
	LinuxSQLWeb        Pricing `json:"linuxSQLWeb"`
	MSWin              Pricing `json:"mswin"`
	MSWinSQL           Pricing `json:"mswinSQL"`
	MSWinSQLEnterprise Pricing `json:"mswinSQLEnterprise"`
	MSWinSQLWeb        Pricing `json:"mswinSQLWeb"`
	RHEL               Pricing `json:"rhel"`
	SLES               Pricing `json:"sles"`
	EBSSurcharge       float64 `json:"ebs,string"`
}

type RegionPricing

type RegionPricing struct {
	Region map[string]ServicePricing `json:"region"`
}

RegionPricing represents the pricing information for each region.

type Regions

type Regions map[string]string

type Reserved

type Reserved struct {
	StandardNoUpfront1Year          float64 `json:"yrTerm1Standard.noUpfront,string"`
	StandardNoUpfront3Years         float64 `json:"yrTerm3Standard.noUpfront,string"`
	StandardPartiallUpfront1Year    float64 `json:"yrTerm1Standard.partialUpfront,string"`
	StandardPartialUpfront3Years    float64 `json:"yrTerm3Standard.partialUpfront,string"`
	StandardAllUpfront1Year         float64 `json:"yrTerm1Standard.allUpfront,string"`
	StandardAllUpfront3Years        float64 `json:"yrTerm3Standard.allUpfront,string"`
	ConvertibleNoUpfront1Year       float64 `json:"yrTerm1Convertible.noUpfront,string"`
	ConvertibleNoUpfront3Years      float64 `json:"yrTerm3Convertible.noUpfront,string"`
	ConvertiblePartiallUpfront1Year float64 `json:"yrTerm1Convertible.partialUpfront,string"`
	ConvertiblePartialUpfront3Years float64 `json:"yrTerm3Convertible.partialUpfront,string"`
	ConvertibleAllUpfront1Year      float64 `json:"yrTerm1Convertible.allUpfront,string"`
	ConvertibleAllUpfront3Years     float64 `json:"yrTerm3Convertible.allUpfront,string"`
}

type ReservedPricing

type ReservedPricing struct {
	YrTerm3StandardPartialUpfront float64 `json:"yrTerm3Standard.partialUpfront"`
	YrTerm1StandardPartialUpfront float64 `json:"yrTerm1Standard.partialUpfront"`
	YrTerm3StandardAllUpfront     float64 `json:"yrTerm3Standard.allUpfront"`
	YrTerm1StandardNoUpfront      float64 `json:"yrTerm1Standard.noUpfront"`
	YrTerm3StandardNoUpfront      float64 `json:"yrTerm3Standard.noUpfront"`
}

type ServicePricing

type ServicePricing struct {
	Memcached PricingDetail `json:"Memcached"`
	Redis     PricingDetail `json:"Redis"`
	Valkey    PricingDetail `json:"Valkey"`
}

ServicePricing represents the pricing for a particular service (e.g., Memcached, Redis, Valkey).

type StorageConfiguration

type StorageConfiguration struct {
	SSD     bool    `json:"ssd"`
	Devices int     `json:"devices"`
	Size    float32 `json:"size"`
	NVMeSSD bool    `json:"nvme_ssd"`
}