1 /**
2 * Copyright 2004-2014 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.common.aws.ec2.api;
17
18 import java.util.List;
19
20 import org.kuali.common.aws.ec2.model.CreateAMIRequest;
21 import org.kuali.common.aws.ec2.model.CreateVolumeRequest;
22 import org.kuali.common.aws.ec2.model.LaunchInstanceContext;
23 import org.kuali.common.aws.ec2.model.VolumeRequest;
24 import org.kuali.common.aws.ec2.model.security.KualiSecurityGroup;
25 import org.kuali.common.aws.ec2.model.security.Permission;
26 import org.kuali.common.aws.ec2.model.security.SetPermissionsResult;
27 import org.kuali.common.aws.ec2.model.status.InstanceStatusType;
28
29 import com.amazonaws.services.ec2.model.Image;
30 import com.amazonaws.services.ec2.model.Instance;
31 import com.amazonaws.services.ec2.model.SecurityGroup;
32 import com.amazonaws.services.ec2.model.Snapshot;
33 import com.amazonaws.services.ec2.model.Tag;
34 import com.amazonaws.services.ec2.model.Volume;
35 import com.google.common.base.Optional;
36
37 /**
38 * <p>
39 * This service provides a layer of abstraction around the EC2 API calls provided by Amazon that are useful for common tasks.
40 * </p>
41 *
42 * <p>
43 * For example, launchInstance() starts a single EC2 instance and waits until Amazon has confirmed that the instance is online and functioning.
44 * </p>
45 */
46 public interface EC2Service {
47
48 void terminateInstancesNoWait(List<String> instanceIds);
49
50 void terminateInstanceNoWait(String instanceId);
51
52 Volume getVolume(String volumeId);
53
54 List<Volume> listVolumes();
55
56 String deleteVolume(String volumeId);
57
58 String attachVolume(VolumeRequest request);
59
60 String detachVolume(VolumeRequest request);
61
62 String createVolume(String zone, int size);
63
64 String createVolume(CreateVolumeRequest request);
65
66 String getRegion();
67
68 String getAccessKey();
69
70 String copyAmi(String region, String ami, String name);
71
72 String copyAmi(String region, String ami);
73
74 Instance startInstance(String instanceId);
75
76 void stopInstance(String instanceId);
77
78 List<Image> getImages();
79
80 void deleteSnapshot(String snapshotId);
81
82 /**
83 * Deregister the AMI and delete any snapshots associated with it.
84 */
85 void purgeAmi(String imageId);
86
87 Image createAmi(CreateAMIRequest request);
88
89 /**
90 * Snapshot a volume. Blocks until the snapshot reaches the state "completed" or timeoutMillis has been exceeded
91 */
92 Snapshot createSnapshot(String volumeId, String description, int timeoutMillis);
93
94 /**
95 * Return a snapshot object, given a snapshot id
96 */
97 Snapshot getSnapshot(String snapshotId);
98
99 /**
100 * Return a list of all the AMI's you own.
101 */
102 List<Image> getMyImages();
103
104 /**
105 * Return an Image object given an image id
106 */
107 Image getImage(String imageId);
108
109 /**
110 * Launch a single Amazon EC2 instance and wait until Amazon confirms that the instance is online and functioning.
111 *
112 * @see terminateInstance
113 */
114 Instance launchInstance(LaunchInstanceContext context);
115
116 /**
117 * Terminate a single Amazon EC2 instance and wait until Amazon confirms that the instance has been terminated.
118 *
119 * @see launchInstance
120 */
121 void terminateInstance(String instanceId);
122
123 /**
124 * <p>
125 * This method returns true if the Amazon EC2 instance meets three conditions:
126 * </p>
127 *
128 * <ol>
129 * <li>The instance is in the <code>running</code> state.</li>
130 * <li>Amazon has verified that the instance is reachable. Amazon has verified that they are able to get network packets to the instance.</li>
131 * <li>Amazon has verified that the instance's operating system is accepting traffic.</li>
132 * </ol>
133 *
134 * <p>
135 * If this method returns false, the instance cannot be used in any meaningful way.
136 * </p>
137 */
138 boolean isOnline(String instanceId);
139
140 /**
141 * Set a flag that prevent's an Amazon EC2 instance from being terminated.
142 *
143 * @see allowTermination
144 */
145 void preventTermination(String instanceId);
146
147 /**
148 * Set a flag that allows an Amazon EC2 instance to be terminated. This does not terminate the instance. It just makes it possible for the instance to be terminated at some
149 * later point in time.
150 *
151 * @see preventTermination
152 */
153 void allowTermination(String instanceId);
154
155 /**
156 * Return an Amazon EC2 instance object given an instance id.
157 */
158 Instance getInstance(String instanceId);
159
160 List<Instance> getInstances(List<String> instanceIds);
161
162 List<Instance> getInstances();
163
164 /**
165 * Create tags on the indicated Amazon EC2 resource (instance, volume, snapshot, ami, etc).
166 */
167 void tag(String resourceId, List<Tag> tags);
168
169 /**
170 * Create tags on the indicated Amazon EC2 resource (instance, volume, snapshot, ami, etc).
171 */
172 void tag(String resourceId, Tag tag);
173
174 /**
175 * Return a list containing the names of all the security groups.
176 */
177 List<String> getSecurityGroupNames();
178
179 /**
180 * Return the security group object associated with <code>name</code>
181 */
182 Optional<SecurityGroup> getSecurityGroup(String name);
183
184 /**
185 * Return true if there is already a security group with the given name.
186 */
187 boolean isExistingSecurityGroup(String name);
188
189 /**
190 * <p>
191 * Make the permissions for the indicated security group match the list provided.
192 * <ul>
193 * <li>Any extra permissions are removed.</li>
194 * <li>Any missing permissions are created.</li>
195 * </ul>
196 * </p>
197 */
198 SetPermissionsResult setPermissions(String securityGroupName, List<Permission> permissions);
199
200 /**
201 * Create a new security group (it must not exist yet)
202 */
203 void createSecurityGroup(KualiSecurityGroup group);
204
205 /**
206 * Import the public key using the given name into Amazon.
207 */
208 String importKey(String keyName, String publicKey);
209
210 /**
211 * Return true if Amazon has a public key stored under this name.
212 */
213 boolean isExistingKey(String keyName);
214
215 /**
216 * <p>
217 * Each Amazon EC2 instance has a list of statuses associated with it.
218 * </p>
219 *
220 * <p>
221 * Each status has a name and value and is associated with either the ability of Amazon's internal systems to determine that status (external to the instance itself) or with
222 * the status of something going on internally to the instance.
223 * </p>
224 *
225 * <p>
226 * A SYSTEM status is analogous to saying "is powered on", or "is connected to the network", but says nothing about the state of any software running on the instance.
227 * </p>
228 *
229 * <p>
230 * An INSTANCE status indicates something about the state of software running on the instance, aka "is operating system running"
231 * </p>
232 */
233 String getStatus(String instanceId, InstanceStatusType type, String statusName);
234
235 }