1 /**
2 *
3 * Copyright (C) 2011 Cloud Conscious, LLC. <info@cloudconscious.com>
4 *
5 * ====================================================================
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 * ====================================================================
18 */
19 package org.jclouds.compute;
20
21 import java.util.Map;
22 import java.util.NoSuchElementException;
23 import java.util.Set;
24
25 import org.jclouds.compute.domain.ComputeMetadata;
26 import org.jclouds.compute.domain.ExecResponse;
27 import org.jclouds.compute.domain.Hardware;
28 import org.jclouds.compute.domain.Image;
29 import org.jclouds.compute.domain.NodeMetadata;
30 import org.jclouds.compute.domain.Template;
31 import org.jclouds.compute.domain.TemplateBuilder;
32 import org.jclouds.compute.internal.BaseComputeService;
33 import org.jclouds.compute.options.RunScriptOptions;
34 import org.jclouds.compute.options.TemplateOptions;
35 import org.jclouds.domain.Location;
36 import org.jclouds.io.Payload;
37 import org.jclouds.scriptbuilder.domain.Statement;
38
39 import com.google.common.base.Predicate;
40 import com.google.inject.ImplementedBy;
41
42 /**
43 * Provides portable access to launching compute instances.
44 *
45 * @author Adrian Cole
46 * @author Ivan Meredith
47 */
48 @ImplementedBy(BaseComputeService.class)
49 public interface ComputeService {
50
51 /**
52 * @return a reference to the context that created this ComputeService.
53 */
54 ComputeServiceContext getContext();
55
56 /**
57 * Makes a new template builder for this service
58 */
59 TemplateBuilder templateBuilder();
60
61 /**
62 * Makes a new set of options for running nodes
63 */
64 TemplateOptions templateOptions();
65
66 /**
67 * The list hardware profiles command shows you the options including virtual cpu count, memory,
68 * and disks. cpu count is not a portable quantity across clouds, as they are measured
69 * differently. However, it is a good indicator of relative speed within a cloud. memory is
70 * measured in megabytes and disks in gigabytes.
71 *
72 * @return a map of hardware profiles by ID, conceding that in some clouds the "id" is not used.
73 */
74 Set<? extends Hardware> listHardwareProfiles();
75
76 /**
77 * Images define the operating system and metadata related to a node. In some clouds, Images are
78 * bound to a specific region, and their identifiers are different across these regions. For this
79 * reason, you should consider matching image requirements like operating system family with
80 * TemplateBuilder as opposed to choosing an image explicitly. The getImages() command returns a
81 * map of images by id.
82 */
83 Set<? extends Image> listImages();
84
85 /**
86 * all nodes available to the current user by id. If possible, the returned set will include
87 * {@link NodeMetadata} objects.
88 */
89 Set<? extends ComputeMetadata> listNodes();
90
91 /**
92 * The list locations command returns all the valid locations for nodes. A location has a scope,
93 * which is typically region or zone. A region is a general area, like eu-west, where a zone is
94 * similar to a datacenter. If a location has a parent, that implies it is within that location.
95 * For example a location can be a rack, whose parent is likely to be a zone.
96 */
97 Set<? extends Location> listAssignableLocations();
98
99 /**
100 *
101 * The compute api treats nodes as a group based on the name you specify. Using this group, you
102 * can choose to operate one or many nodes as a logical unit without regard to the implementation
103 * details of the cloud.
104 * <p/>
105 *
106 * The set that is returned will include credentials you can use to ssh into the nodes. The "key"
107 * part of the credentials is either a password or a private key. You have to inspect the value
108 * to determine this.
109 *
110 * <pre>
111 * if (node.getCredentials().key.startsWith("-----BEGIN RSA PRIVATE KEY-----"))
112 * // it is a private key, not a password.
113 * </pre>
114 *
115 * <p/>
116 * Note. if all you want to do is execute a script at bootup, you should consider use of the
117 * runscript option.
118 * <p/>
119 * If resources such as security groups are needed, they will be reused or created for you.
120 * Inbound port 22 will always be opened up.
121 *
122 * @param group
123 * - common identifier to group nodes by, cannot contain hyphens
124 * @param count
125 * - how many to fire up.
126 * @param template
127 * - how to configure the nodes
128 * @return all of the nodes the api was able to launch in a running state.
129 *
130 * @throws RunNodesException
131 * when there's a problem applying options to nodes. Note that successful and failed
132 * nodes are a part of this exception, so be sure to inspect this carefully.
133 */
134 Set<? extends NodeMetadata> createNodesInGroup(String group, int count, Template template) throws RunNodesException;
135
136 /**
137 * Like {@link ComputeService#createNodesInGroup(String,int,Template)}, except that the template
138 * is default, equivalent to {@code templateBuilder().any().options(templateOptions)}.
139 */
140 Set<? extends NodeMetadata> createNodesInGroup(String group, int count, TemplateOptions templateOptions)
141 throws RunNodesException;
142
143 /**
144 * Like {@link ComputeService#createNodesInGroup(String,int,TemplateOptions)}, except that the
145 * options are default, as specified in {@link ComputeService#templateOptions}.
146 */
147 Set<? extends NodeMetadata> createNodesInGroup(String group, int count) throws RunNodesException;
148
149 /**
150 * @see #createNodesInGroup(String , int , Template )
151 */
152 @Deprecated
153 Set<? extends NodeMetadata> runNodesWithTag(String tag, int count, Template template) throws RunNodesException;
154
155 /**
156 * @see #createNodesInGroup(String , int , TemplateOptions )
157 */
158 @Deprecated
159 Set<? extends NodeMetadata> runNodesWithTag(String tag, int count, TemplateOptions templateOptions)
160 throws RunNodesException;
161
162 /**
163 * @see #createNodesInGroup(String , int )
164 */
165 @Deprecated
166 Set<? extends NodeMetadata> runNodesWithTag(String tag, int count) throws RunNodesException;
167
168 /**
169 * resume the node from {@link org.jclouds.compute.domain.NodeState#SUSPENDED suspended} state,
170 * given its id.
171 *
172 * <h4>note</h4>
173 *
174 * affected nodes may not resume with the same IP address(es)
175 */
176 void resumeNode(String id);
177
178 /**
179 * nodes matching the filter are treated as a logical set. Using the resume command, you can save
180 * time by resumeing the nodes in parallel.
181 *
182 * <h4>note</h4>
183 *
184 * affected nodes may not resume with the same IP address(es)
185 *
186 * @throws UnsupportedOperationException
187 * if the underlying provider doesn't support suspend/resume
188 * @throws NoSuchElementException
189 * if no nodes matched the predicate specified
190 */
191 void resumeNodesMatching(Predicate<NodeMetadata> filter);
192
193 /**
194 * suspend the node, given its id. This will result in
195 * {@link org.jclouds.compute.domain.NodeState#SUSPENDED suspended} state.
196 *
197 * <h4>note</h4>
198 *
199 * affected nodes may not resume with the same IP address(es)
200 *
201 * @throws UnsupportedOperationException
202 * if the underlying provider doesn't support suspend/resume
203 */
204 void suspendNode(String id);
205
206 /**
207 * nodes matching the filter are treated as a logical set. Using the suspend command, you can
208 * save time by suspending the nodes in parallel.
209 *
210 * <h4>note</h4>
211 *
212 * affected nodes may not resume with the same IP address(es)
213 *
214 * @throws UnsupportedOperationException
215 * if the underlying provider doesn't support suspend/resume
216 * @throws NoSuchElementException
217 * if no nodes matched the predicate specified
218 */
219 void suspendNodesMatching(Predicate<NodeMetadata> filter);
220
221 /**
222 * destroy the node, given its id. If it is the only node in a tag set, the dependent resources
223 * will also be destroyed.
224 */
225 void destroyNode(String id);
226
227 /**
228 * nodes matching the filter are treated as a logical set. Using the delete command, you can save
229 * time by removing the nodes in parallel. When the last node in a set is destroyed, any indirect
230 * resources it uses, such as keypairs, are also destroyed.
231 *
232 * @return list of nodes destroyed
233 */
234 Set<? extends NodeMetadata> destroyNodesMatching(Predicate<NodeMetadata> filter);
235
236 /**
237 * reboot the node, given its id.
238 */
239 void rebootNode(String id);
240
241 /**
242 * nodes matching the filter are treated as a logical set. Using this command, you can save time
243 * by rebooting the nodes in parallel.
244 *
245 * @throws NoSuchElementException
246 * if no nodes matched the predicate specified
247 */
248 void rebootNodesMatching(Predicate<NodeMetadata> filter);
249
250 /**
251 * Find a node by its id.
252 */
253 NodeMetadata getNodeMetadata(String id);
254
255 /**
256 * get all nodes including details such as image and ip addresses even if it incurs extra
257 * requests to the service.
258 *
259 * @param filter
260 * how to select the nodes you are interested in details on.
261 */
262 Set<? extends NodeMetadata> listNodesDetailsMatching(Predicate<ComputeMetadata> filter);
263
264 /**
265 * @see org.jclouds.io.Payloads
266 * @see ComputeService#runScriptOnNodesMatching(Predicate, Statement, RunScriptOptions)
267 */
268 @Deprecated
269 Map<? extends NodeMetadata, ExecResponse> runScriptOnNodesMatching(Predicate<NodeMetadata> filter, Payload runScript)
270 throws RunScriptOnNodesException;
271
272 /**
273 * @see org.jclouds.io.Payloads
274 * @see ComputeService#runScriptOnNodesMatching(Predicate, Statement, RunScriptOptions)
275 */
276 @Deprecated
277 Map<? extends NodeMetadata, ExecResponse> runScriptOnNodesMatching(Predicate<NodeMetadata> filter,
278 Payload runScript, RunScriptOptions options) throws RunScriptOnNodesException;
279
280 /**
281 *
282 * @see ComputeService#runScriptOnNodesMatching(Predicate, Statement, RunScriptOptions)
283 */
284 Map<? extends NodeMetadata, ExecResponse> runScriptOnNodesMatching(Predicate<NodeMetadata> filter, String runScript)
285 throws RunScriptOnNodesException;
286
287 /**
288 *
289 * @see ComputeService#runScriptOnNodesMatching(Predicate, Statement, RunScriptOptions)
290 */
291 Map<? extends NodeMetadata, ExecResponse> runScriptOnNodesMatching(Predicate<NodeMetadata> filter,
292 Statement runScript) throws RunScriptOnNodesException;
293
294 /**
295 *
296 * @see ComputeService#runScriptOnNodesMatching(Predicate, Statement, RunScriptOptions)
297 */
298 Map<? extends NodeMetadata, ExecResponse> runScriptOnNodesMatching(Predicate<NodeMetadata> filter, String runScript,
299 RunScriptOptions options) throws RunScriptOnNodesException;
300
301 /**
302 * Run the script on all nodes with the specific predicate.
303 *
304 * @param filter
305 * Predicate-based filter to define on which nodes the script is to be executed
306 * @param runScript
307 * statement containing the script to run
308 * @param options
309 * nullable options to how to run the script, whether to override credentials
310 * @return map with node identifiers and corresponding responses
311 * @throws NoSuchElementException
312 * if no nodes matched the predicate specified
313 * @throws RunScriptOnNodesException
314 * if anything goes wrong during script execution
315 *
316 * @see org.jclouds.compute.predicates.NodePredicates#runningWithTag(String)
317 * @see org.jclouds.scriptbuilder.domain.Statements
318 */
319 Map<? extends NodeMetadata, ExecResponse> runScriptOnNodesMatching(Predicate<NodeMetadata> filter,
320 Statement runScript, RunScriptOptions options) throws RunScriptOnNodesException;
321
322 }