Combine several commonly used API calls into a practical end-to-end example that helps facilitate learning the RightScale API.
Table of Contents
This example leverages several stand-alone scripts that invoke the RightScale API via HTTP/curl calls. Each script has a "preamble" whereby it sets up the type of script and defines environment variables specific to the environment. For example, use the Bourne shell (/bin/sh) and set the Cloud ID to 2112. You may choose to change up your environment. That is, use C or Bash not the Bourne shell, or create a single script with one preamble where you set the shell type and define all required variables for all subsequent API calls. Whether you use a single script or several, your cloud resources are unique and you must identify them correctly. You may either obtain their ID's from the Dashboard (when available¹) or invoke the API and parse the output.
Note that this format allows you to copy/paste example scripts, set the variables for your environment, and run them as is.
Reminder: API examples are meant as a learning tool, and should be utilized with the following additional resources:
¹ Although you can discover many resource ID's by simply navigating the the RightScale Dashboard (helpful for learning and exploring the API), not all resources are available via the Dashboard. Most notably, specific cloud resources must be obtained from API queries. For example, when navigating to Clouds > CloudName all resources supported by that cloud must be obtained via API queries. Lifting the number from the URL will not work.
Before you can use the RightScale API, you must authenticate yourself as a Dashboard user. It is presumed you already have registered with RightScale, have access to a private or public cloud, and are able to log in (https://my.rightscale.com) and navigate around the UI. Running the following will authenticate you and deposit a session cookie in the file 'mycookie'. This cookie is valid for approximately two hours. Once authenticated, you can run additional API commands without authenticating again (for the life of the session cookie).
#!/bin/sh -e email="firstname.lastname@example.org" # The email address for your RightScale User in the Dashboard pswd="SomeSecurePassword" # Your User's password account="1234" # Account ID, easily obtained from navigation in the Dashboard curl -i -H X_API_VERSION:1.5 -c mycookie -X POST --data-urlencode "email=$email" --data-urlencode "password=$pswd" -d account_href=/api/accounts/"$account" https://my.rightscale.com/api/session
Note: Although OAuth is preferred for production environments, the Examples section of the API guide uses standard user/pass authentication for simplicity sake.
Now that you have authenticated, you can tap into the power of the RightScale API. Lets start with a simple query for Cloud ID's. When you log into the RightScale Dashboard, your RightScale user and account only have access to some clouds, not all clouds. The List Clouds example below lists the Cloud ID's you have access too. Before you can create and launch a Server, you need to specify which cloud it should run in... hence listing clouds is a good place to start. In addition, listing resources is generally easier than creating them, so this is a good way to ease into using the API.
#!/bin/sh -e curl -i -H X_API_VERSION:1.5 -b mycookie -X GET https://my.rightscale.com/api/clouds.xml
Deployments are a great way to organize your cloud assets. Lets create a deployment that you can later add servers to, launch those servers, etc. Note that a deployment is not cloud-specific, so there is no need to specify the Cloud ID for this example.
Upon receiving a "HTTP/1.1 201 Created" response, you are ready to start creating cloud assets in your new deployment.
Note: The example above uses a "\" as a line continuation character for readability sake. Your scripts can do the same. Either way, Its important to know that the curl command issued must be interpreted by the shell as a single command.
Although not all clouds support security groups, they are quite common and a simple way to provide ingress security measures. First, you'll need to create the security group itself, then add any security group rules that should be enforced. Because security groups are cloud specific, a Cloud ID is required. Again, you can obtain your Cloud ID via the URL in the Dashboard (Clouds > CloudName) or by querying the API for it.
Reminder: Requires 'security_manager' role on the account.
Security groups are cloud specific and a cloud resource who's ID is not obtainable from navigation within the RightScale Dashboard. In order to create security group rules you will have to provide the security group ID the rules apply to. Hence, listing the security group before creating individual rules is required.
In the same way that a deployment is a container for cloud assets, a security group is a container for security group rules. In and of themselves, a deployment does not actually do anything, neither does a security group. Creating a security group rule is done either by group or IP. This example is CIDR IP based. (The Examples section of the RightScale API Guide includes an example of creating one by group.)
Warning: Although its tempting to specify multiple start/end port combinations to allow access on additional ports, you cannot do that with a single API call.
First, this example will open up port 22 allowing SSH access.
To enable browsing on HTTP port 80 you can simply:
You can add additional ports that should be opened up with similar logic. For example, to enable SSL change the start/stop port of 80 to 443, etc.
At this point its tempting to create and launch a server. However, there are two more parameters we'll need: the instance type and MCI (Multi Cloud Image). The instance type is a cloud specific resource that you will have to query the API for the correct ID. The MCI can be queried via the API using the MultiCloudImage resource, or using the Dashboard (click the MultiCloud Image link for the ServerTemplate your server is based on).
Example instance types are small, medium and large (referring primarily to the memory and compute power). You'll need the instance type ID from the output looking similar to: <link href="/api/clouds/2112/instance_types/8E7KP200RBRU5" rel="self"/>
Note: Above example output is XML.
Actually creating the server is arguably one of the more difficult API calls due to the number of parameters specified. Having obtained all of the information needed to create a server from either the API or navigating in the Dashboard, you are ready to invoke the API and create the "next instance" of the server. Tip: See other API Examples to help with your learning and getting additional resource information as needed.
Note: A "\" character has been added to allow a single curl command to continue for several lines in the editor. This is for readability sake. The shell will interpret the script's curl command as a single line.
#!/bin/sh -e DEPLOYMENT="306795001" # Deployment to add Server to CLOUD="2112" # Specify Cloud to add Server to ST="250769001" # Set the ServerTemplate the Server will be based on SG="DEU7O32167MJ4" # Set the Security Group MCI="240802001" # Set MultiCloud Image (MCI) ITYPE="9F6N6MA39F7E9" # Set the Instance Type for this Sever, this cloud, ... curl -i -H X_API_VERSION:1.5 -b mycookie -X POST \ -d server[name]=my_app_server \ -d server[description]=my_app_server_description \ -d server[deployment_href]=/api/deployments/$DEPLOYMENT \ -d server[instance][cloud_href]=/api/clouds/$CLOUD \ -d server[instance][server_template_href]=/api/server_templates/$ST \ -d server[instance][multi_cloud_image_href]=/api/multi_cloud_images/$MCI \ -d server[instance][instance_type_href]=/api/clouds/$CLOUD/instance_types/$ITYPE \ -d server[instance][security_group_hrefs]=/api/clouds/$CLOUD/security_groups/$SG \ https://my.rightscale.com/api/servers
Although no content is generated, you should recive a "HTTP/1.1 201 Created" response. If the server cannot be created, API responses are quite good at indicating what the issue is. (Usually this is tied to missing or improperly specified parameters.)
Its simple to list all servers in a deployment. If there are multiple servers they all get displayed. Note that for each server there will always be a "next instance". This is all of the "DNA" or "blueprint" of information pertaining to the next server launched. There is also a "current instance" if the server has an a running instance as well. Although often times the current and next server are effectively the same, they do not have be. Consider any server level input changes... those are based on the next server, not the current one. Hence after server level input changes the current and next servers will differ. Similarly if you change the instance type, MCI, Datacenter / Zone, machine tags, etc.
Now that the server ID is known a server can be launched. Recall that all specifics for a server (including the cloud, deployment, MCI, etc.) are specified when created, so only the server ID is required to launch.
No content is returned just a "HTTP/1.1 201 Created" message.
At this point in the end-to-end example, you have learned how to authenticate, GET (list) information, POST (create) resources, etc. Your API "sandbox" has a deployment with a server up and running in your cloud of choice. If there are other aspects of the API you want to explore, now is a good time to do that. With these Examples and the Online Reference, you should be able to use the API for most tasks. Recall that several examples include a Supplemental section that often use filters to help narrow in on more specific content in the response. The next steps in this tutorial will shutdown and wrap up the deployment. (Reminder: If you have been creating temporary scripts on a server in the cloud using the servers local (ephemoral) storage, when terminating the server you will lose those scripts. If you want to retain them for future use remember to back them up... even it it's a simple copy/paste into local files on your PC, or a backup to a remote object store.)
Warning! If you create shell scripts to test the API using local storage on a server in the cloud, when you terminate the server the scripts will be lost. That is not a permanent storage solution, but only exists for the life of the server. Because the sample scripts are so short, if you do need to terminate your server you can simply copy/paste the contents of the scripts into files stored on your local hard drive for future use.
Of course the one piece of information required to terminate a server is the server ID itself. This can be obtained from either navigating in the Dashboard or querying the API. (See Show Server or List all Servers in a Deployment above for examples.)
Warning! You can delete an unlocked deployment, even if it has servers in it (provided the servers are not operational). Non-operational servers will get deleted along with the unlocked deployment.
One use case for deleting a deployment is general cleanup. In fact, a use case for this entire end-to-end example (or something very similar) is automating the spin-up of a basic environment for people to get acquainted with the cloud and using the RightScale Dashboard. Although you could List Deployments in your enterprise training account, parse the output and delete them all programatically when the class is over, this example simply deletes a specific deployment.
© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.