1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
# Copyright 2011-2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"). You
# may not use this file except in compliance with the License. A copy of
# the License is located at
#
# http://aws.amazon.com/apache2.0/
#
# or in the "license" file accompanying this file. This file is
# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
# ANY KIND, either express or implied. See the License for the specific
# language governing permissions and limitations under the License.
module AWS
class EC2
# Represents a collection of EC2 images. You can use this to
# find out which images exist with the characteristics you are
# interested in:
#
# ec2 = EC2.new
# all_images = ec2.images
# amazon_owned_images = all_images.with_owner('amazon')
# my_images = all_images.with_owner('self')
# tagged_amis = all_images.tagged('mytag')
# tagged_amis.map(&:id) # => ["ami-123", ...]
#
# You can also use it to create new images. For example:
#
# ec2.images.create(:instance_id => "i-123", :name => "my-image")
#
class ImageCollection < Collection
include TaggedCollection
include BlockDeviceMappings
# @api private
def initialize(options = {})
@owners = options[:owners] || []
@executable_users = options[:executable_users] || []
super(options)
end
# @return [Image] image_id The ID of the image.
def [] image_id
super
end
# @return [ImageCollection] A new collection that only includes
# images owned by one or more of the specified AWS accounts.
# The IDs `:amazon` and `:self` can be used to include AMIs
# owned by Amazon or AMIs owned by you, respectively.
#
# @param [Array of Strings] owners The AWS account IDs by
# which the new collection should be filtered.
def with_owner(*owners)
collection_with(:owners => @owners + owners)
end
# @return [ImageCollection] A new collection that only includes
# images for which the specified user ID has explicit launch
# permissions. The user ID can be an AWS account ID, `:self`
# to return AMIs for which the sender of the request has
# explicit launch permissions, or `:all` to return AMIs with
# public launch permissions.
#
# @param [Array of Strings] users The AWS account IDs by which
# the new collection should be filtered.
def executable_by(*users)
collection_with(:executable_users => @executable_users + users)
end
# @yield [image] Each image in the collection.
# @return [nil]
def each(opts = {}, &block)
opts[:owners] = @owners.map { |id| id.to_s } unless @owners.empty?
opts[:executable_users] = @executable_users.map { |id| id.to_s } unless
@executable_users.empty?
response = filtered_request(:describe_images, opts)
response.images_set.each do |i|
image = Image.new_from(:describe_images, i, i.image_id, :config => config)
yield(image)
end
nil
end
# Creates an AMI. There are several ways to create an AMI
# using this method; for detailed information on each strategy
# see [the EC2 Developer Guide](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami.html).
#
# @param [Hash] options Options for creating the image.
# `:name` is required, and you must also specify one of the
# following options:
#
# * `:instance_id`
# * `:image_location`
# * `:root_device_name`
#
# @option options [String] :instance_id The ID of a running
# instance. This instance will be rebooted unless
# `:no_reboot` is set to `true`.
#
# @option options [String] :description A description of the
# new image.
#
# @option options [Boolean] :no_reboot By default this
# option is set to `false`, which means Amazon EC2
# attempts to cleanly shut down the instance before image
# creation and reboots the instance afterwards. When the
# option is set to `true`, Amazon EC2 does not shut down
# the instance before creating the image. When this option
# is used, file system integrity on the created image cannot
# be guaranteed.
#
# *Note*: This option is only valid when used with
# `:instance_id`.
#
# @option options [String] :image_location Full path to your
# AMI manifest in Amazon S3 storage. This must be of the
# form "bucket_name/key".
#
# @option options [String] :architecture The architecture of
# the image. Valid values:
#
# * `:i386`
# * `:x86_64`
#
# *Note*: This option is only valid with `:image_location`
# or `:root_device_name`
#
# @option options [String] :kernel_id The ID of the kernel to
# select.
#
# *Note*: This option is only valid with `:image_location`
# or `:root_device_name`
#
# @option options [Image] :kernel The kernel image to use.
# Equivalent to passing `:kernel_id` with the ID of the
# image.
#
# *Note*: This option is only valid with `:image_location`
# or `:root_device_name`
#
# @option options [String] :ramdisk_id The ID of the RAM disk
# to select. Some kernels require additional drivers at
# launch. Check the kernel requirements for information on
# whether you need to specify a RAM disk. To find kernel
# requirements, refer to the Resource Center and search for
# the kernel ID.
#
# *Note*: This option is only valid with `:image_location`
# or `:root_device_name`
#
# @option options [Image] :ramdisk The ramdisk image to use.
# Equivalent to passing `:ramdisk_id` with the ID of the
# image.
#
# *Note*: This option is only valid with `:image_location`
# or `:root_device_name`
#
# @option options [String] :root_device_name The root device
# name (e.g., /dev/sda1, or xvda).
#
# @option options [Hash] :block_device_mappings This must be a
# hash; the keys are device names to map, and the value for
# each entry determines how that device is mapped. Valid
# values include:
#
# * A string, which is interpreted as a virtual device name.
# * A hash with any of the following options. One of
# `:snapshot`, `:snapshot_id` or `:volume_size` is
# required.
#
# * `:snapshot` - A snapshot to use when creating the block device.
# * `:snapshot_id` - The ID of a snapshot to use when creating
# the block device.
# * `:volume_size` -] The size of volume to create, in gigabytes.
# * `:delete_on_termination` - Setting this to true causes EC2
# to delete the volume when the instance is terminated.
# @return [Image]
def create options = {}
resp = case
when options[:instance_id]
client.create_image(options)
when options[:image_location] || options[:root_device_name]
if kernel = options.delete(:kernel)
options[:kernel_id] = kernel.id
end
if ramdisk = options.delete(:ramdisk)
options[:ramdisk_id] = ramdisk.id
end
options[:block_device_mappings] =
translate_block_device_mappings(options[:block_device_mappings]) if
options[:block_device_mappings]
client.register_image(options)
else
raise(ArgumentError,
"expected instance_id, image_location, " +
"or root_device_name")
end
Image.new(resp.image_id, :config => config)
end
# @api private
protected
def member_class
Image
end
# @api private
protected
def preserved_options
super.merge(:owners => @owners, :executable_users => @executable_users)
end
end
end
end
|
