Class: AWS::EC2

Inherits:
Object
  • Object
show all
Includes:
Core::ServiceInterface
Defined in:
lib/aws/ec2.rb,
lib/aws/ec2/tag.rb,
lib/aws/ec2/vpc.rb,
lib/aws/ec2/image.rb,
lib/aws/ec2/client.rb,
lib/aws/ec2/errors.rb,
lib/aws/ec2/region.rb,
lib/aws/ec2/subnet.rb,
lib/aws/ec2/volume.rb,
lib/aws/ec2/request.rb,
lib/aws/ec2/instance.rb,
lib/aws/ec2/key_pair.rb,
lib/aws/ec2/resource.rb,
lib/aws/ec2/snapshot.rb,
lib/aws/ec2/attachment.rb,
lib/aws/ec2/collection.rb,
lib/aws/ec2/elastic_ip.rb,
lib/aws/ec2/export_task.rb,
lib/aws/ec2/network_acl.rb,
lib/aws/ec2/route_table.rb,
lib/aws/ec2/tagged_item.rb,
lib/aws/ec2/vpn_gateway.rb,
lib/aws/ec2/dhcp_options.rb,
lib/aws/ec2/security_group.rb,
lib/aws/ec2/tag_collection.rb,
lib/aws/ec2/vpc_collection.rb,
lib/aws/ec2/vpn_connection.rb,
lib/aws/ec2/has_permissions.rb,
lib/aws/ec2/config_transform.rb,
lib/aws/ec2/customer_gateway.rb,
lib/aws/ec2/image_collection.rb,
lib/aws/ec2/internet_gateway.rb,
lib/aws/ec2/availability_zone.rb,
lib/aws/ec2/network_acl/entry.rb,
lib/aws/ec2/network_interface.rb,
lib/aws/ec2/region_collection.rb,
lib/aws/ec2/route_table/route.rb,
lib/aws/ec2/subnet_collection.rb,
lib/aws/ec2/tagged_collection.rb,
lib/aws/ec2/volume_collection.rb,
lib/aws/ec2/reserved_instances.rb,
lib/aws/ec2/filtered_collection.rb,
lib/aws/ec2/instance_collection.rb,
lib/aws/ec2/key_pair_collection.rb,
lib/aws/ec2/snapshot_collection.rb,
lib/aws/ec2/attachment_collection.rb,
lib/aws/ec2/block_device_mappings.rb,
lib/aws/ec2/elastic_ip_collection.rb,
lib/aws/ec2/permission_collection.rb,
lib/aws/ec2/export_task_collection.rb,
lib/aws/ec2/network_acl_collection.rb,
lib/aws/ec2/route_table_collection.rb,
lib/aws/ec2/vpn_gateway/attachment.rb,
lib/aws/ec2/vpn_gateway_collection.rb,
lib/aws/ec2/dhcp_options_collection.rb,
lib/aws/ec2/network_acl/association.rb,
lib/aws/ec2/resource_tag_collection.rb,
lib/aws/ec2/route_table/association.rb,
lib/aws/ec2/vpn_connection/telemetry.rb,
lib/aws/ec2/security_group_collection.rb,
lib/aws/ec2/vpn_connection_collection.rb,
lib/aws/ec2/customer_gateway_collection.rb,
lib/aws/ec2/internet_gateway/attachment.rb,
lib/aws/ec2/internet_gateway_collection.rb,
lib/aws/ec2/reserved_instances_offering.rb,
lib/aws/ec2/availability_zone_collection.rb,
lib/aws/ec2/network_interface/attachment.rb,
lib/aws/ec2/network_interface_collection.rb,
lib/aws/ec2/security_group/ip_permission.rb,
lib/aws/ec2/reserved_instances_collection.rb,
lib/aws/ec2/reserved_instances_offering_collection.rb,
lib/aws/ec2/security_group/ip_permission_collection.rb

Overview

Provides an expressive, object-oriented interface to Amazon EC2.

Credentials

You can setup default credentials for all AWS services via AWS.config:

AWS.config(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Or you can set them directly on the EC2 interface:

ec2 = AWS::EC2.new(
  :access_key_id => 'YOUR_ACCESS_KEY_ID',
  :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')

Instances

EC2 uses instances to run your software.

To run an instance:

ec2.instances.create(:image_id => "ami-8c1fece5")

To get an instance by ID:

i = ec2.instances["i-12345678"]
i.exists?

To get a list of instances:

ec2.instances.inject({}) { |m, i| m[i.id] = i.status; m }
# => { "i-12345678" => :running, "i-87654321" => :shutting_down }

Security Groups

A security group is a named collection of access rules. These access rules specify which ingress (i.e., incoming) network traffic should be delivered to your instance. All other ingress traffic will be discarded.

To create a security group:

websvr = ec2.security_groups.create('webservers')

Then you can add ingress authorizations. In the following example we add a rule that allows web traffic from the entire internet.

# web traffic
websvr.authorize_ingress(:tcp, 80)

You can also specify a port range. Here we are opening FTP traffic:

# ftp traffic
websvr.authorize_ingress(:tcp, 20..21)

If you want to limit an authorization to a particular CIDR IP address or list of address, just add them to the #authorize_ingress call.

# ssh access
websrvr.authorize_ingress(:tcp, 22, '1.1.1.1/0', '2.2.2.2/0')

You can also provide another security group instead of CIDR IP addresses. This allows incoming traffic from EC2 instances in the given security group(s).

# get two existing security groups
dbsvrs = ec2.security_groups.filter('group-name', 'db-servers').first
websvrs = ec2.security_groups.filter('group-name', 'web-servers').first

# allow instances in the 'web-servers' security group to connect
# to instances in the 'db-servers' security group over tcp port 3306
dbsvrs.authorize_ingress(:tcp, 3306, websvrs)

There are a few handy shortcuts for allowing pings:

wbsvrs.allow_ping

Just like with authorize_ingress you can pass a security group or a list of CIDR IP addresses to allow ping to limit where you can ping from.

You can also use the same parameters from the examples above to SecurityGroup#revoke_ingress and SecurityGroup#disallow_ping.

You can specify other protocols than :tcp, like :udp and :icmp.

Elastic IPs

You can allocate up to 5 elastic IP addresses for each account. You can associate those elastic IP addresses with EC2 instances:

instance = ec2.instances['i-12345678']
ip = ec2.elastic_ips.allocate

instance.ip_address                # 1.1.1.1
ip.ip_address                      # 2.2.2.2

instance.associate_elastic_ip(ip)
instance.ip_address                # 2.2.2.2

instance.disassociate_elastic_ip
instance.ip_address                # 1.1.1.1

When you are done with an elastic IP address you should release it. In the following example we release all elastic IP addresses that are not currently associated with an instance:

ec2.select{|ip| !ip.associated? }.each(&:release)

Key Pairs

Public Amazon Machine Image (AMI) instances have no password, and you need a public/private key pair to log in to them. The public key half of this pair is embedded in your instance, allowing you to use the private key to log in securely without a password.

You can generate a key pair yourself and then send the public part to EC2 using KeyPairCollection#import. For example:

key_pair =
  ec2.key_pairs.import("mykey", File.read("~/.ssh/identity.pub"))

You can also ask EC2 to generate a key pair for you. For example:

key_pair = ec2.key_pairs.create("mykey")
File.open("~/.ssh/ec2", "w") do |f|
  f.write(key_pair.private_key)
end

Filtering and Tagging

Any of the collections in the interface may be filtered by a number of different parameters. For example, to get all the windows images owned by amazon where the description includes the string “linux”, you can do this:

ec2.images.with_owner("amazon").
  filter("platform", "windows").
  filter("description", "*linux*")

Similarly, you can tag images, instances, security groups, snapshots, and volumes with free-form key-value metadata and filter on that metadata. For example:

ec2.images["ami-123"].tags << "myapp"
ec2.images.tagged("myapp")             # will include ami-123

Regions

Amazon has data centers in different areas of the world (e.g., North America, Europe, Asia, etc.). Correspondingly, EC2 is available to use in different Regions. By launching instances in separate Regions, you can design your application to be closer to specific customers or to meet legal or other requirements. Prices for Amazon EC2 usage vary by Region (for more information about pricing by Region, go to the Amazon EC2 Pricing page). You can use the Ruby SDK to see which regions are available for your account:

ec2.regions.map(&:name)            # => ["us-east-1", ...]

The default region is us-east-1; you can access other regions like this:

ec2_us_west = ec2.regions["us-west-1"]
# starts an instance in eu-west-1
ec2_us_west.instances.create(:image_id => 'ami-3bc9997e')

This makes a call to EC2’s DescribeRegions API to find the endpoint for “us-west-1” – if you just want to configure a different endpoint without making a call to EC2, you can do it like this:

ec2 = AWS::EC2.new(:ec2_endpoint =>
                           "ec2.us-west-1.amazonaws.com")

Availability Zones

Each Region contains multiple distinct locations called Availability Zones. Each Availability Zone is engineered to be isolated from failures in other Availability zones and to provide inexpensive, low-latency network connectivity to other zones in the same Region. By launching instances in separate Availability Zones, you can protect your applications from the failure of a single location.

You can use the #availability_zones collection to get information about the available zones available to your account. For example:

ec2.availability_zones.map(&:name)   # => ["us-east-1a", ...]

Images

An Amazon Machine Image (AMI) contains all information necessary to boot instances of your software. For example, an AMI might contain all the software to act as a web server (e.g., Linux, Apache, and your web site) or it might contain all the software to act as a Hadoop node (e.g., Linux, Hadoop, and a custom application).

You can use the #images collection to get information about the images available to your account. For example:

ec2.images.with_owner("amazon").map(&:name)

You can also use the images collection to create new images:

ec2.images.create(:image_location => "mybucket/manifest.xml",
                  :name => "my-image")

Defined Under Namespace

Modules: Errors, FilteredCollection, HasPermissions, TaggedCollection, TaggedItem Classes: Attachment, AttachmentCollection, AvailabilityZone, AvailabilityZoneCollection, Client, Collection, CustomerGateway, CustomerGatewayCollection, DHCPOptions, DHCPOptionsCollection, ElasticIp, ElasticIpCollection, ExportTask, ExportTaskCollection, Image, ImageCollection, Instance, InstanceCollection, InternetGateway, InternetGatewayCollection, KeyPair, KeyPairCollection, NetworkACL, NetworkACLCollection, NetworkInterface, NetworkInterfaceCollection, PermissionCollection, Region, RegionCollection, ReservedInstances, ReservedInstancesCollection, ReservedInstancesOffering, ReservedInstancesOfferingCollection, ResourceObject, ResourceTagCollection, RouteTable, RouteTableCollection, SecurityGroup, SecurityGroupCollection, Snapshot, SnapshotCollection, Subnet, SubnetCollection, Tag, TagCollection, VPC, VPCCollection, VPNConnection, VPNConnectionCollection, VPNGateway, VPNGatewayCollection, Volume, VolumeCollection

Instance Method Summary collapse

Methods included from Core::ServiceInterface

#initialize, #inspect

Instance Method Details

#availability_zones ⇒ AvailabilityZoneCollection

Returns A collection representing all EC2 availability zones.

Returns:



338
339
340
 
# File 'lib/aws/ec2.rb', line 338

def availability_zones
  AvailabilityZoneCollection.new(:config => config)
end

#customer_gateways ⇒ CustomerGatewayCollection

Returns a collection that represents all of the customer gateways for this account.

Returns:



410
411
412
 
# File 'lib/aws/ec2.rb', line 410

def customer_gateways
  CustomerGatewayCollection.new(:config => config)
end

#dhcp_options ⇒ DHCPOptionsCollection

Returns a collection that represents all of the dhcp options for this account.

Returns:

  • (DHCPOptionsCollection) —

    Returns a collection that represents all of the dhcp options for this account.



422
423
424
 
# File 'lib/aws/ec2.rb', line 422

def dhcp_options
  DHCPOptionsCollection.new(:config => config)
end

#elastic_ips ⇒ ElasticIpCollection

Returns A collection representing all elastic IP addresses for this account.

Returns:

  • (ElasticIpCollection) —

    A collection representing all elastic IP addresses for this account.



315
316
317
 
# File 'lib/aws/ec2.rb', line 315

def elastic_ips
  ElasticIpCollection.new(:config => config)
end

#export_tasks ⇒ ExportTaskCollection

Returns:



433
434
435
 
# File 'lib/aws/ec2.rb', line 433

def export_tasks
  ExportTaskCollection.new(:config => config)
end

#images ⇒ ImageCollection

Returns A collection representing all Amazon Machine Images available to your account.

Returns:

  • (ImageCollection) —

    A collection representing all Amazon Machine Images available to your account.



344
345
346
 
# File 'lib/aws/ec2.rb', line 344

def images
  ImageCollection.new(:config => config)
end

#instances ⇒ InstanceCollection

Returns A collection representing all instances.

Returns:



303
304
305
 
# File 'lib/aws/ec2.rb', line 303

def instances
  InstanceCollection.new(:config => config)
end

#internet_gateways ⇒ InternetGatewayCollection

Returns a collection that represents all of the internet gateways for this account.

Returns:



404
405
406
 
# File 'lib/aws/ec2.rb', line 404

def internet_gateways
  InternetGatewayCollection.new(:config => config)
end

#key_pairs ⇒ KeyPairCollection

Returns A collection representing all key pairs.

Returns:



320
321
322
 
# File 'lib/aws/ec2.rb', line 320

def key_pairs
  KeyPairCollection.new(:config => config)
end

#network_acls ⇒ NetworkACLCollection

Returns a collection that represents all of the network ACLs for this account.

Returns:

  • (NetworkACLCollection) —

    Returns a collection that represents all of the network ACLs for this account.



386
387
388
 
# File 'lib/aws/ec2.rb', line 386

def network_acls
  NetworkACLCollection.new(:config => config)
end

#network_interfaces ⇒ NetworkInterfaceCollection

Returns a collection that represents all of the network interfaces for this account.

Returns:



398
399
400
 
# File 'lib/aws/ec2.rb', line 398

def network_interfaces
  NetworkInterfaceCollection.new(:config => config)
end

#regions ⇒ RegionCollection

Returns A collection representing all EC2 regions.

Returns:



332
333
334
 
# File 'lib/aws/ec2.rb', line 332

def regions
  RegionCollection.new(:config => config)
end

#reserved_instances ⇒ ReservedInstancesCollection

Returns A collection representing all purchased reserved instance offerings.

Returns:



356
357
358
 
# File 'lib/aws/ec2.rb', line 356

def reserved_instances
  ReservedInstancesCollection.new(:config => config)
end

#reserved_instances_offerings ⇒ ReservedInstancesOfferingCollection

Returns A collection representing all reserved instance offerings that may be purchased.

Returns:



362
363
364
 
# File 'lib/aws/ec2.rb', line 362

def reserved_instances_offerings
  ReservedInstancesOfferingCollection.new(:config => config)
end

#route_tables ⇒ RouteTableCollection

Returns a collection that represents all of the route tables for this account.

Returns:

  • (RouteTableCollection) —

    Returns a collection that represents all of the route tables for this account.



392
393
394
 
# File 'lib/aws/ec2.rb', line 392

def route_tables
  RouteTableCollection.new(:config => config)
end

#security_groups ⇒ SecurityGroupCollection

Returns A collection representing all security groups.

Returns:



309
310
311
 
# File 'lib/aws/ec2.rb', line 309

def security_groups
  SecurityGroupCollection.new(:config => config)
end

#snapshots ⇒ SnapshotCollection

Returns A collection representing all EBS snapshots available to your account.

Returns:

  • (SnapshotCollection) —

    A collection representing all EBS snapshots available to your account.



368
369
370
 
# File 'lib/aws/ec2.rb', line 368

def snapshots
  SnapshotCollection.new(:config => config)
end

#subnets ⇒ SubnetCollection

Returns a collection that represents all of the subnets associated with this account (across all VPCs).

Returns:

  • (SubnetCollection) —

    Returns a collection that represents all of the subnets associated with this account (across all VPCs).



380
381
382
 
# File 'lib/aws/ec2.rb', line 380

def subnets
  SubnetCollection.new(:config => config)
end

#tags ⇒ TagCollection

Returns A collection representing all EC2 tags for all resource types.

Returns:

  • (TagCollection) —

    A collection representing all EC2 tags for all resource types.



326
327
328
 
# File 'lib/aws/ec2.rb', line 326

def tags
  TagCollection.new(:config => config)
end

#volumes ⇒ VolumeCollection

Returns A collection representing all EBS volumes available to your account.

Returns:

  • (VolumeCollection) —

    A collection representing all EBS volumes available to your account.



350
351
352
 
# File 'lib/aws/ec2.rb', line 350

def volumes
  VolumeCollection.new(:config => config)
end

#vpcs ⇒ VPCCollection

Returns A collection representing all VPCs in your account.

Returns:

  • (VPCCollection) —

    A collection representing all VPCs in your account.



374
375
376
 
# File 'lib/aws/ec2.rb', line 374

def vpcs
  VPCCollection.new(:config => config)
end

#vpn_connections ⇒ VPNConnections

Returns a collection that represents all of vpn connections for this account.

Returns:

  • (VPNConnections) —

    Returns a collection that represents all of vpn connections for this account.



428
429
430
 
# File 'lib/aws/ec2.rb', line 428

def vpn_connections
  VPNConnectionCollection.new(:config => config)
end

#vpn_gateways ⇒ VPNGatewayCollection

Returns a collection that represents all of the vpn gateways for this account.

Returns:

  • (VPNGatewayCollection) —

    Returns a collection that represents all of the vpn gateways for this account.



416
417
418
 
# File 'lib/aws/ec2.rb', line 416

def vpn_gateways
  VPNGatewayCollection.new(:config => config)
end