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.openstack.nova;
20
21 import java.util.Set;
22 import java.util.concurrent.ExecutionException;
23 import java.util.concurrent.TimeUnit;
24
25 import javax.ws.rs.PathParam;
26
27 import org.jclouds.concurrent.Timeout;
28 import org.jclouds.openstack.nova.domain.Addresses;
29 import org.jclouds.openstack.nova.domain.Flavor;
30 import org.jclouds.openstack.nova.domain.Image;
31 import org.jclouds.openstack.nova.domain.RebootType;
32 import org.jclouds.openstack.nova.domain.Server;
33 import org.jclouds.openstack.nova.options.CreateServerOptions;
34 import org.jclouds.openstack.nova.options.ListOptions;
35 import org.jclouds.openstack.nova.options.RebuildServerOptions;
36 import org.jclouds.rest.ResourceNotFoundException;
37
38 import java.util.concurrent.Future;
39
40 /**
41 * Provides access to OpenStack Nova via their REST API.
42 * <p/>
43 * All commands return a Future of the result from OpenStack Nova. Any exceptions incurred
44 * during processing will be wrapped in an {@link ExecutionException} as documented in
45 * {@link Future#get()}.
46 *
47 * @see NovaAsyncClient
48 * @see <a href="http://wiki.openstack.org/OpenStackAPI_1-1" />
49 * @author Adrian Cole
50 */
51 @Timeout(duration = 60, timeUnit = TimeUnit.SECONDS)
52 public interface NovaClient {
53
54 /**
55 *
56 * List all servers (IDs and names only)
57 *
58 * This operation provides a list of servers associated with your identity. Servers that have been
59 * deleted are not included in this list.
60 * <p/>
61 * in order to retrieve all details, pass the option {@link ListOptions#withDetails()
62 * withDetails()}
63 */
64 Set<Server> listServers(ListOptions... options);
65
66 /**
67 *
68 * This operation returns details of the specified server.
69 *
70 * @return null, if the server is not found
71 * @see Server
72 */
73 Server getServer(@PathParam("id") int id);
74
75 /**
76 *
77 * This operation deletes a cloud server instance from the system.
78 * <p/>
79 * Note: When a server is deleted, all images created from that server are also removed.
80 *
81 * @return false if the server is not found
82 * @see Server
83 */
84 boolean deleteServer(@PathParam("id") int id);
85
86 /**
87 * The reboot function allows for either a soft or hard reboot of a server.
88 * <p/>
89 * Status Transition:
90 * <p/>
91 * ACTIVE - REBOOT - ACTIVE (soft reboot)
92 * <p/>
93 * ACTIVE - HARD_REBOOT - ACTIVE (hard reboot)
94 *
95 * @param rebootType
96 * With a soft reboot, the operating system is signaled to restart, which allows for a
97 * graceful shutdown of all processes. A hard reboot is the equivalent of power cycling
98 * the server.
99 */
100 void rebootServer(int id, RebootType rebootType);
101
102 /**
103 * The resize function converts an existing server to a different flavor, in essence, scaling the
104 * server up or down. The original server is saved for a period of time to allow rollback if
105 * there is a problem. All resizes should be tested and explicitly confirmed, at which time the
106 * original server is removed. All resizes are automatically confirmed after 24 hours if they are
107 * not confirmed or reverted.
108 * <p/>
109 * Status Transition:
110 * <p/>
111 * ACTIVE - QUEUE_RESIZE - PREP_RESIZE - VERIFY_RESIZE
112 * <p/>
113 * ACTIVE - QUEUE_RESIZE - ACTIVE (on error)
114 */
115 void resizeServer(int id, int flavorId);
116
117 /**
118 * The resize function converts an existing server to a different flavor, in essence, scaling the
119 * server up or down. The original server is saved for a period of time to allow rollback if
120 * there is a problem. All resizes should be tested and explicitly confirmed, at which time the
121 * original server is removed. All resizes are automatically confirmed after 24 hours if they are
122 * not confirmed or reverted.
123 * <p/>
124 * Status Transition:
125 * <p/>
126 * VERIFY_RESIZE - ACTIVE
127 */
128 void confirmResizeServer(int id);
129
130 /**
131 * The resize function converts an existing server to a different flavor, in essence, scaling the
132 * server up or down. The original server is saved for a period of time to allow rollback if
133 * there is a problem. All resizes should be tested and explicitly reverted, at which time the
134 * original server is removed. All resizes are automatically reverted after 24 hours if they are
135 * not reverted or reverted.
136 * <p/>
137 * Status Transition:
138 * <p/>
139 * VERIFY_RESIZE - ACTIVE
140 */
141 void revertResizeServer(int id);
142
143 /**
144 * This operation asynchronously provisions a new server. The progress of this operation depends
145 * on several factors including location of the requested image, network i/o, host load, and the
146 * selected flavor. The progress of the request can be checked by performing a GET on /server/id,
147 * which will return a progress attribute (0-100% completion). A password will be randomly
148 * generated for you and returned in the response object. For security reasons, it will not be
149 * returned in subsequent GET calls against a given server ID.
150 *
151 * @param options
152 * - used to specify extra files, metadata, or ip parameters during server creation.
153 */
154 Server createServer(String name, String imageRef, String flavorRef, CreateServerOptions... options);
155
156 /**
157 * The rebuild function removes all data on the server and replaces it with the specified image.
158 * Server ID and IP addresses remain the same.
159 * <p/>
160 * Status Transition:
161 * <p/>
162 * ACTIVE - REBUILD - ACTIVE
163 * <p/>
164 * ACTIVE - REBUILD - ERROR (on error)
165 * <p/>
166 *
167 * @param options
168 * - imageId is an optional argument. If it is not specified, the server is rebuilt
169 * with the original imageId.
170 */
171 void rebuildServer(int id, RebuildServerOptions... options);
172
173 /**
174 * This operation allows you to change the administrative password.
175 * <p/>
176 * Status Transition: ACTIVE - PASSWORD - ACTIVE
177 *
178 */
179 void changeAdminPass(int id, String adminPass);
180
181 /**
182 * This operation allows you to update the name of the server. This operation changes the name of
183 * the server in the OpenStack Nova system and does not change the server host name itself.
184 * <p/>
185 * Status Transition: ACTIVE - PASSWORD - ACTIVE
186 *
187 */
188 void renameServer(int id, String newName);
189
190 /**
191 *
192 * List available flavors (IDs and names only)
193 *
194 * in order to retrieve all details, pass the option {@link ListOptions#withDetails()
195 * withDetails()}
196 */
197 Set<Flavor> listFlavors(ListOptions... options);
198
199 /**
200 *
201 * This operation returns details of the specified flavor.
202 *
203 * @return null, if the flavor is not found
204 * @see Flavor
205 */
206 Flavor getFlavor(int id);
207
208 /**
209 *
210 * List available images (IDs and names only)
211 *
212 * in order to retrieve all details, pass the option {@link ListOptions#withDetails()
213 * withDetails()}
214 */
215 Set<Image> listImages(ListOptions... options);
216
217 /**
218 *
219 * This operation returns details of the specified image.
220 *
221 * @return null, if the image is not found
222 *
223 * @see Image
224 */
225 Image getImage(int id);
226
227 /**
228 *
229 * This operation deletes an image from the system.
230 * <p/>
231 * Note: Images are immediately removed. Currently, there are no state transitions to track the
232 * delete operation.
233 *
234 * @return false if the image is not found
235 * @see Image
236 */
237 boolean deleteImage(int id);
238
239 /**
240 *
241 * This operation creates a new image for the given server ID. Once complete, a new image will be
242 * available that can be used to rebuild or create servers. Specifying the same image name as an
243 * existing custom image replaces the image. The image creation status can be queried by
244 * performing a GET on /images/id and examining the status and progress attributes.
245 *
246 * Status Transition:
247 * <p/>
248 * QUEUED - PREPARING - SAVING - ACTIVE
249 * <p/>
250 * QUEUED - PREPARING - SAVING - FAILED (on error)
251 * <p/>
252 * Note: At present, image creation is an asynchronous operation, so coordinating the creation
253 * with data quiescence, etc. is currently not possible.
254 *
255 * @throws ResourceNotFoundException
256 * if the server is not found
257 * @see Image
258 */
259 Image createImageFromServer(String imageName, int serverId);
260
261 /**
262 * List all server addresses
263 *
264 * returns empty set if the server doesn't exist
265 */
266 Addresses getAddresses(int serverId);
267
268 /**
269 * List all public server addresses
270 *
271 * returns empty set if the server doesn't exist
272 */
273 Set<String> listPublicAddresses(int serverId);
274
275 /**
276 * List all private server addresses
277 *
278 * returns empty set if the server doesn't exist
279 */
280 Set<String> listPrivateAddresses(int serverId);
281
282 }