Jeff Johnston [http://community.jboss.org/people/jjohnstn] modified the document: "DeltaCloud Tools 0.0.1 User Guide" To view the document, visit: http://community.jboss.org/docs/DOC-15882 -------------------------------------------------------------- h2. Introduction The DeltaCloud Tools provides a set of Eclipse plug-ins to manage clouds via one or more DeltaCloud servers.  The plug-ins use a REST interface to communicate with the DeltaCloud server which in turn communicates with a remote cloud. Each DeltaCloud server is started outside of Eclipse via the deltacloudd command and specifies the type of cloud it is accessing and the port one must communicate with.  For example, deltacloudd -i ec2 -p 3002 will start a server that will talk to an Amazon EC2 cloud and is accessed via port 3002 on the localhost.  By default, the DeltaCloud server will listen on port 3001.  It should be noted that the DeltaCloud server does not support ssh encryption so it is recommended that the server be run on the localhost or else behind a proxy such as is described at http://httpd.apache.org/docs/2.0/mod/mod_proxy.html http://httpd.apache.org/docs/2.0/mod/mod_proxy.html.  This is recommended due to the fact that a userid and password is communicated with the server for accessing the cloud. Under Eclipse, the DeltaCloud Tools has its own perspective which includes 4 views which will be discussed in more detail later: * Cloud View - tree view for displaying cloud connections to DeltaCloud servers * Instances View - for displaying instances of a particular cloud connection * Images View - for displaying images of a particular cloud connection * Properties View - general Eclipse view which displays properties of selected items in Cloud View Each view may be brought directly via Windows->Show View or the entire perspective may be brought up via Windows->Show Perspective->Other...->Delta Cloud h2. Connecting to a DeltaCloud Server To start accessing a cloud from Eclipse, select File->New->Other...->Delta Cloud and hit the Next button. This brings up the Cloud Connection dialog: http://community.jboss.org/servlet/JiveServlet/showImage/9353/cloudconnec... http://community.jboss.org/servlet/JiveServlet/downloadImage/9353/cloudco... The following fields are described: * Name - the name you wish to assign the connection.  This must be a unique name. * URL - the URL of the deltacloud server to use.  The server should already be started externally.  If the URL is invalid or does not point to an existing server, this is noted by the dialog. * Type - this field is filled in based upon the -i argument passed to the DeltaCloud server referenced. * Username - the username used to access the cloud.  For EC2, this is the Access Id.  Details regarding the EC2 access id can be found at: https://console.aws.amazon.com/ec2/home https://console.aws.amazon.com/ec2/home. * Password - the password used to access the cloud.  For EC2, this is the Access Secret Key.  Details regarding the EC2 access key can be found at: https://console.aws.amazon.com/ec2/home https://console.aws.amazon.com/ec2/home. When the URL, username, and password fields are filled in appropriately, you may press the Test button to verify if the values are valid for accessing the cloud. After all fields are filled in and the URL is valid, the Finish button can be pressed to complete the creation process. The values can be edited in the future if necessary from the Cloud View and this described later in this document.  Editing the connection is useful if the password was misentered or one wishes to use a different username/password combination or the server URL changes.  The connection is stored securely across an Eclipse session so reentering the data is not required if using an equivalent server instantiation (i.e. cloud type and URL are the same). h2. Cloud Viewer The Cloud Viewer shows the various cloud connections created in a Tree view format.  Cloud connections have Instances and Images as children.  The following shows an example of the Cloud View with two connections: http://community.jboss.org/servlet/JiveServlet/showImage/9355/cloudconnec... http://community.jboss.org/servlet/JiveServlet/downloadImage/9355/cloudco... This example also demonstrates the Properties View.  The Properties viewer will show properties details for any object selected in the Cloud Viewer.  In this particular instance, it is showing the properties of the cloud connection named "Red Hat Cloud".  Note that the properties are read-only in the viewer.  If instead an Instance or Image is selected in the tree view, appropriate details are provided for the Instance or Image specified. If a Cloud Connection is selected and right-clicked, a menu pops up that allows one to "Edit Connection" or to "Disconnect Cloud".  Both actions are obvious.  The Edit Connection menu-item brings up the Cloud Connection Dialog with all the current values filled in (including password hidden from view).  When the edit is complete, selecting Finish changes the values.  To abort, select Cancel. h2. Creating an Instance An Instance is a running system based upon an Image.  One way to think about this is that an Image is a template whereas an Instance is an instantiation of the template.  To launch an Instance, open up the tree view such that the desired Image to base upon is shown.  Select the Image and right-click on it.  This will bring up a popup menu which includes "Launch Instance".  Clicking on this menu item causes the Launch Instance dialog to appear. http://community.jboss.org/servlet/JiveServlet/showImage/9356/createInsta... http://community.jboss.org/servlet/JiveServlet/downloadImage/9356/createI... The dialog contains a number of fields to fill in: * Name - name you wish to give the Instance.  It should be noted that for Amazon EC2 clouds, this name is ignored and the name of the Image will be used instead.  It is possible to have multiple Instances with the same name.* Image - filled in based on the Image you chose to invoke this dialog for * Architecture - filled in with the architecture for the Image chosen * Realm - a list of available realms (locations) to launch the Instance * Key name - the name of an existing key file to use when creating the Instance.  This is required to access the Instance remotely such as through Remote System Explorer in Eclilpse.  Keys can be created or deleted via the Manage Keys dialog which is invoked by pressing the Manage button.  A key may be reused and by default, the last key used will be filled in for the dialog so that you may set up one key and not have to do so again.  Note that the key field will not appear for a mock cloud which doesn't use require or use keys. * Hardware Profile - a set of available hardware profiles for the Image.  When one is selected, this may bring up additional options such as the number of cpus, the amount of memory, or the disk storage available to the Instance.  Some of these values may be preset or will restrict the setting to a limited set or a range. Once the dialog is filled in, select Finish to complete the creation of the Instance.  A confirmation dialog is brought up to ensure the user wants to launch the Instance and perhaps start paying money.  This confirmation dialog has the option of never showing again and this can be modified later in the DeltaCloud preferences found via Window-:>Preferences->Delta Cloud. The Instance will appear in the Cloud Viewer for its parent Cloud Connection.  It should be noted that an Instance begins its life in Pending state.  This is due to the fact that starting of an Instance takes some time.  The state of the Instance can be found in the Properties View.  The Instance will also appear in the Instances View which we will discuss next. h2. Instances View The Instances View shows all Instances for a specified Cloud Connection in a Table view format.  Each row has columns detailing a separate Instance for the Cloud.  The following shows the view: http://community.jboss.org/servlet/JiveServlet/showImage/9357/instancesvi... http://community.jboss.org/servlet/JiveServlet/downloadImage/9357/instanc... At the top of the Instances View is a selector for the Cloud Connection.  This will contain the list of known Cloud connections shown in the Cloud Viewer. The Instances View table contains: * Name - name of the Instance (note for EC2, this is not the name chosen in the Launch Instance dialog) * ID - the unique Instance id * State - the state of the Instance which can be one of: (RUNNING, STOPPED, TERMINATED) * Public Hostname - for a running Instance, this is a URL that is used to connect to the Instance and access it For each Instance (row) selected, right-clicking brings up a set of available actions.  Actions are available only if pertinent to the current state of the Instance.  The actions include: * Start - start a stopped Instance (in some cases, such as EC2, stopping an Instance results in termination and it cannot be restarted) * Stop - stop a running Instance * Reboot - reboot an Instance * Destroy - stop and destroy an Instance (this is not always enabled, such as in the case of EC2 where stopping terminates the Instance) * Show in Remote System Explorer - this action creates an SSL connection to the Instance using the key specified earlier in the Launch Instance dialog.  Note: the key name corresponds to a file on the local system and this file must be placed on the list of private SSH2 keys prior to trying to connect to the Instance, otherwise the connection will fail.  To make the key file accessible, go to Window->Preferences->General->Network Connections->SSH2 and select the "Add Private Key" button. Actions requiring time may bring up a Progress Dialog which can be moved to the Background.  If the Progress Dialog is desired to be in the Foreground again, this can be achieved by accessing the preference found at: Windows->Preferences and selecting General. http://community.jboss.org/servlet/JiveServlet/showImage/9358/bgpreferenc... http://community.jboss.org/servlet/JiveServlet/downloadImage/9358/bgprefe... h2. RSE Perspective The Remote System Explorer perspective can be accessed by going to Windows->Show Perspectives The Eclipse RSE perspective allows one to access files on the remote Instance and to modify them, if desired.  The following image shows a remote file being accessed: http://community.jboss.org/servlet/JiveServlet/showImage/9359/rsecloud.png http://community.jboss.org/servlet/JiveServlet/downloadImage/9359/rseclou... Note how the file system can be accessed via the Sftp Files node in the Remote Systems tree view.  In this example, the remote fstab file has been selected and shows in the editor.  It can be edited and saved just as if it was a local file. For more details on Remote System Explorer, see http://dsdp.eclipse.org/help/latest/index.jsp?topic=/org.eclipse.rse.doc.... http://dsdp.eclipse.org/help/latest/index.jsp?topic=/org.eclipse.rse.doc.... or consult Help->Help Contents for your Eclipse session. h2. Images View The Images View is similiar to the Instances View in that it is a Table view of the Images of a particular Cloud connection.  Each row details information about an Image in the Cloud.  The following demonstrates: http://community.jboss.org/servlet/JiveServlet/showImage/9361/imagesview.png http://community.jboss.org/servlet/JiveServlet/downloadImage/9361/imagesv... Like the Instances View, the Cloud connection to use is specified by the Select Cloud drop-down.  For a selected Image (row), right-clicking allows one to Launch Instance.  This is identical to performing the action from the Cloud Viewer and this brings up the Launch Instance dialog. Each row contains details about the Images including: * Name - name of the Image * ID - unique id of the Image * Architecture - specified architecture for the Image * Description - free form text that describes the Image h2. Manage Keys The Manage Keys dialog is accessed via the Launch Instance dialog.  This dialog allows one to Create and Delete key files as well as to select which key to use for the current Instance launch. http://community.jboss.org/servlet/JiveServlet/showImage/9362/managekeys.png http://community.jboss.org/servlet/JiveServlet/downloadImage/9362/managek... The Directory field is where key files are stored.  To select a different directory, click on the Browse... button. To create a key, hit the "New..." button.  This brings up a simple dialog: http://community.jboss.org/servlet/JiveServlet/showImage/9363/createkey.png http://community.jboss.org/servlet/JiveServlet/downloadImage/9363/createk... where the key name is entered.  The name must be unique for the Cloud (i.e. not just the directory).  When OK is pressed, the key file will be created in the specified directory chosen for the Manage Keys dialog. -------------------------------------------------------------- Comment by going to Community [http://community.jboss.org/docs/DOC-15882] Create a new document in JBoss Tools at Community [http://community.jboss.org/choose-container!input.jspa?contentType=102&am...]