Home > Guides > Cloud Workflow Developer Guide > Mapping Resources to the RightScale APIs

Mapping Resources to the RightScale APIs

Table of Contents	Sections
Mapping Resources to the RightScale APIs Resource Actions Required roles Parameters Resource Fields Resource Links Resource Type Actions get() index Required roles Parameters Filters create() and update() create Required roles Required settings Parameters	RCL - RightScale Cloud Workflow Language Resources Definitions Variables Attributes and Error Handling Branching and Looping Processes Functions Operators Mapping Resources to the RightScale APIs Glossary

Mapping Resources to the RightScale APIs

The RightScale API reference documentation lists all the available resource types in the rs namespace and corresponding media types. This section describes how to use that documentation to use the corresponding resources in a cloud workflow.

Resource Actions

Resource actions are listed in the corresponding media type document under the Actions section. The required arguments are described in the resource document itself. For example, the media type for the instances resource is described in the corresponding document and the actions are:

(from http://reference.rightscale.com/api1.5/media_types/MediaTypeInstance.html#actions)

Actions

run_executable: Runs a script or recipe on the instance
terminate: Terminates the instance
reboot: Reboots a running instance
launch: Launches this instance with the current configuration

The details on how to call the actions are described in the instances resource document, taking the launch() action as example:

(from http://reference.rightscale.com/api1.5/resources/ResourceInstances.html#launch)

launch

Launches an instance using the parameters that this instance has been configured with.
Note that this action can only be performed in "next" instances, and not on instances that are already running.

URLs: POST /api/clouds/:cloud_id/instances/:id/launch; POST /api/servers/:server_id/launch; POST /api/server_arrays/:server_array_id/launch
HTTP response code: 201 Created
Location: Href of the launched Instance

Required roles

actor

Parameters

Name	Required	Type	Values	regexp	Blank?	Description
inputs	no	Array	*	*	no
inputs[][name]	yes	String	*	*	no	The input name.
inputs[][value]	yes	String	*	*	no	The value of that input. Should be of the form 'text:my_value' or 'cred:MY_CRED', etc.

Note that the engine will automatically map the Location response header to a resource collection and will make that resource collection the return value of the action. The action takes a single parameter inputs which is an array of hashes. Each hash should contain two elements: name and value. So the launch() action can be called in RCL using:


@running = @next_instance.launch(inputs: [{ "name": "ADMIN_EMAIL", "value": "text:admin@rightscale.com" },
                                          { "name": "PASSWORD",    "value": "cred:PASSWORD" }])

Resource Fields

Resource fields are listed in the corresponding media type document under the Attributes section. Look at the documentation for the media type of the instances resource:

(from http://reference.rightscale.com/api1.5/media_types/MediaTypeInstance.html)

Attributes

private_dns_names
updated_at
monitoring_server
actions
terminated_at
inputs
os_platform
inherited_sources
description
public_ip_addresses
links
monitoring_id
private_ip_addresses
user_data
name
public_dns_names
resource_uid
security_groups
state
created_at

Resource Links

Resources links are listed in the corresponding media type document under the Relationships section. Look at the documentation for the media type of the instances resource:

(from http://reference.rightscale.com/api1.5/media_types/MediaTypeInstance.html)

Relationships

parent: Parent Object (Server/ServerArray)
self: Href of itself
datacenter: Associated datacenter
multi_cloud_image: Associated multi cloud image
inputs: List of configuration inputs
server_template: Associated ServerTemplate
ramdisk_image: Associated ramdisk image
volume_attachments: Associated volume attachments
instance_type: Associated instance type
monitoring_metrics: Associated monitoring metrics
kernel_image: Associated kernel image
ssh_key: Associated ssh key
image: Associated image
deployment: Associated Deployment
cloud: Associated Cloud

Note that some links yield individual resources while others yield a collection. In the example above server_template() returns a single resource while volume_attachments() returns a collection. The possible link parameters are given by the description of the show request of the link resource if the link is for a single resource. Otherwise, they are given by the description of the index request. In the example above, the server_templates resource show request described in the resource documentation lists one potential parameter view which can be used in RCL as follows:


@instance.server_template(view: "default")

Resource Type Actions

get()

The resource types get() action map to a index request on the corresponding resource. The parameters are thus described in the resources index request documentation. For example, for instances:

(from http://reference.rightscale.com/api1.5/resources/ResourceInstances.html#index)

index

Lists instances of a given cloud.

Using the available filters, it is possible to craft powerful queries about which instances to retrieve. For example, one can easily list:

instances that have names that contain "app"
all instances of a given deployment
instances belonging to a given server array (i.e., have the same parent_url)

URLs: GET /api/clouds/:cloud_id/instances; GET /api/server_arrays/:server_array_id/current_instances
HTTP response code: 200 OK
Content-type: application/vnd.rightscale.instance;type=collection

Required roles

observer

Parameters

Name	Required	Type	Values	regexp	Blank?	Description
filter	no	Array	*	*	no	See below for valid filter parameters.
view	no	String	default, extended, full	*	no	Specifies how many attributes and/or expanded nested relationships to include.

Filters

Name	partial_match?	Description
datacenter_href	no	The href of the datacenter to filter on.
deployment_href	no	The href of the deployment to filter on.
name	yes	Name of the Instance to filter on.
os_platform	yes	The OS platform to filter on.
parent_href	no	The href of the parent to filter on.
private_dns_name	yes	The private dns name to filter on.
private_ip_address	yes	The private ip address to filter on.
public_dns_name	yes	The public dns name to filter on.
public_ip_address	yes	The public ip address to filter on.
resource_uid	no	Resource Unique IDentifier for the Instance to filter on.
server_template_href	no	The href of the ServerTemplate to filter on.
state	no	The state of Instances to filter on.

Filters are given in the filter parameter which corresponds to an array of filter expressions. A filter expression consists of a filter name (from the table above) and a comparison to a value using either == or <>. For example, to retrieve all instances in the account whose name is not master_db one could write:


@instances = rs.instances.get(filter: ["name <> master_db"])

create() and update()

Possible parameters for the resource types create() and update() actions are described by the corresponding resource request documentation. Looking at the deployments resource as an example, the corresponding documentation for the create request is:

(from http://reference.rightscale.com/api1.5/resources/ResourceDeployments.html#create)

create

Creates a new deployment with the given parameters.

URLs: POST /api/deployments
HTTP response code: 201 Created
Location: Href of the created deployment

Required roles

actor

Required settings

premium_deployments

Parameters

Name	Required	Type	Values	regexp	Blank?	Description
deployment	yes	Hash	*	*	no
deployment[description]	no	String	*	*	yes	The description of the deployment to be created.
deployment[name]	yes	String	*	*	no	The name of the deployment to be created.

So a deployment create() action takes a single hash argument named deployment which consists of a hash with two keys: name and description. A deployment can thus be created in RCL using:


rs.deployments.create(deployment: { "name": "LAMP Stack",
                                    "description": "Servers making up the LAMP Stack application" })