Beginner E2E API Example

Authenticate

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="john.doe@example.com"   # 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.

If you have not registered with RightScale, sign up for FREE!  

List Clouds

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

Other Notes:

• You can specify the output as either ".json" or ".xml." By default, if you do not specify a URL suffix, the API will respond in JSON format.
• Querying for information (such as listing available clouds) requires an HTTP GET method.  Later, you'll modify resources that require other HTTP methods such as POST or DELETE in the URL construction. 
• Select the appropriate Cloud ID from the response.  For example, 1234 in the following sample output: <link href="/api/clouds/1234" rel="self"/>

Create a Deployment

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.

Create Deployment

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. 

Create a Security Group

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.

Create Security Group

Reminder: Requires 'security_manager' role on the account.

List Security Groups

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.

List Security Groups

Create a Security Group Rule

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. 

Create Security Group Rules by CIDR IPS

To enable browsing on HTTP port 80 you can simply:

• Copy the script above
• Change the start and end ports from 22 to 80
• Run the script

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.

List Instance Types

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). 

List Instance Types

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.

Create a Server

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.)

List all Servers in a Deployment

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.

List all Servers in a Deployment

Launch Server

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. 

Launch Server

No content is returned just a "HTTP/1.1 201 Created" message.

Run (Rinse and Repeat)

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.)

Terminate Server

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.) 

Terminate Server

Delete Deployment

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. 

Delete Deployment