Macro Reference Documentation

'pr_create' vs 'create'

There are two different ways to create a cloud resource or RightScale component.  Use the 'pr_create' prefix if you want the user to specify a name for the resource/component when the macro is executed.  A window prompt will appear and ask the user to specify a name before it creates the component.  You can either leave the parameter blank or specify a default value.

The 'pr_create' option is available on the following create actions:

• Deployment
• Server Array
• EC2 Security Group
• EC2 SSH Key
• EC2 Elastic IP
• SQS Queue
• S3 Bucket

See example code below.

 deployment_url = pr_create_deployment(
		{
		'nickname':'defaultvalue'
		'description':'This is a test deployment.'
		}
		);

Otherwise, you can use the regular 'create' option which will create the resource/object with the value specified in the code.  See example code below.

deployment_url = create_deployment(
		{
		'nickname': 'ProjectX',
		'description':'This is a test deployment.'
		}
		);

Using Brackets for Arrays

Use brackets to enclose any arrays.  For example, if you're assigning multiple tags or associating multiple security groups to a server, you must enclose all of the items in brackets.

'ec2_security_groups_href':[ec2_security_group_21212,ec2_security_group_34343],

-or-

'tags':[tag1,tag2],  

Generating Unique Components/Resources

Remember, each component that the macro creates, must be unique.  Therefore, if you're creating multiple components/resources of the same type, we recommend adding a different suffix identifier.  See example below:

Note:  In order to create a security group, you must at least provide one ingress rule. 

ec2_security_group_1234 = pr_create_ec2_security_group(
		{
		'aws_group_name':'defaultvalue'
                'aws_description':'Security Group for MyCompany',
		'cloud_id':'1'
		}
		);

ec2_security_group_5678 = pr_create_ec2_security_group(
		{
		'aws_group_name':'defaultvalue'
                'aws_description':'Security Group for MyCompany',
		'cloud_id':'1'
		}
		);

Specifying hrefs

There are two different ways to specify the href of a component/resource.  You can either explicitly list the href or reference a variable name.  See example below:

var ec2_security_group_1234 = 'https://my.rightscale.com/api/acct/<accountID>/ec2_security_groups/5678';
server_array = create_server_array(
                {
                'ec2_security_group_href':ec2_security_group_1234,
                }
                );

-or-

server_array = create_server_array(
                {
                'ec2_security_group_href':'https://my.rightscale.com/api/acct/<accountID>/ec2_security_groups/5678',
                }
                );

Variable Substitution

Use common Javascript calls to customize any macro. For example, you can define variables for input substitution.  If you run the macro code below, it will prompt you to define a value for the 'variablename' that will be used as the nickname of the created deployment.

var variablename = prompt("Name for the new Deployment","defaultvalue");
deployment_url = create_deployment( { 'nickname': variablename, 'description':'This is a test deployment.' } );

Adding a Timestamp

To help create components that are unique, you can add a timestamp as a suffix to the nickname of a created component.  The example code below will create an SSH Key with a timestamp in the namespace.  (e.g. my-name-here-1284681501203)  (5:02pm)

//Get timestamp 
var d = new Date();
var now = d.getTime();

ec2_ssh_key= create_ec2_ssh_key(
		{
		'cloud_id':'1',
		'aws_key_name':'my-name-here-' + now
		}
		);

AWS Cloud IDs

create_deployment

Create a deployment.  'pr_create' option is supported.  See 'pr_create' vs 'create'.

Example

deployment_url = create_deployment(
		{
		'nickname':''
		'description':'This is a test deployment.'
		}
		);

set_deployment_parameter

Defines input parameters at the Deployment level.  The first argument is the href to the deployment.  The second argument is a hash with the key's parameters.  See Understanding Inputs.

Example

set_deployment_parameter(deployment_href,
		{
		'parameters':
		{
		'MEMCACHED_STATS':'ignore:$ignore',
		'PRIVATE_SSH_KEY':'key:Gaming SSH Key:1',
		'DB_HOST_NAME':'text:master.mydeployment.com',
		'MASTER_DB_DNSID':'text:11111',
		'SLAVE_DB_DNSID':'text:11112',
		'WEBSITE_DNS':'env:EC2_PUBLIC_HOSTNAME'
		}
		}
		);

clone_server_template

Clone a ServerTemplate.

Example for server_template_href

var worker_template_href = 'https://my.rightscale.com/api/acct/1/ec2_server_templates/12345';
my_worker_template = clone_server_template(worker_template_href)

Example for server_template_library_id

var my_local_worker_template_href = '
https://my.rightscale.com/api/acct/1/ec2_server_templates/12345'; #
template is not published
var my_published_worker_template_href = '
https://my.rightscale.com/api/acct/1/ec2_server_templates/67890';
var rs_marketplace_worker_template_href = '
https://my.rightscale.com/api/acct/2901/ec2_server_templates/13579';

var my_published_library_id = '34987'; # for my local template 67890
var rs_marketplace_template_id = '2346'; # the marketplace id for account
2901's template 13579

my_worker_template_1 = clone_server_template(my_local_worker_template_href);
my_worker_template_2 = clone_server_template(
my_published_worker_template_href, my_published_library_id);
my_worker_template_3 =
clone_server_template(rs_marketplace_worker_template_href,
rs_marketplace_template_id);

my_worker_template_1 = clone_server_template(my_local_worker_template_href,
'345678'); # or obviously set up a var for the library id

Note: If Account 1 was to publish this macro, then its ServerTemplate 12345 must first be published, and then the library_id of that new object in the marketplace must be used.

set_server_template_parameter

Defines input parameters at the ServerTemplate level.  The first argument is the href to the deployment.  The second argument is a hash with the key's parameters.

Example

set_server_template_parameter(server_template_href,
		{
		'parameters':
		{
                'MON_PROCESSES':'ignore:$ignore',                'CUSTOM_INPUT':'text:custom value',
		'GIT_PRIVATE_KEY':'cred:gitkey',
		'DBAPPLICATION_USER':'text:my_username',
		'CONFIG_FILE':'text:http://svn.mysite.com/app/1.0/',
		'SLAVE_DB_DNSNAME':'cred:DBREPLICATION_USER',
		'MASTER_DB_DNSNAME':'cred:DNSMADEEASY_USER',
		'DBAPPLICATION_PASSWORD':'text:my_password' 
		}
		}
		);

create_ec2_server

Create a Server.

Example

server_123456 = create_ec2_server(
		{
		'tags':['tag1','tag2'
			],
		'server_template_href':'https://my.rightscale.com/api/acct/1/ec2_server_templates/12345',
		'ec2_image_href':null,
		'ec2_elastic_ip_href':ec2_elastic_ip_1234,
		'deployment_href':'https://my.rightscale.com/api/acct/1/deployments/1234',
		'ec2_ssh_key_href':ec2_ssh_key_123456,
		'aki_image_href':null,
		'instance_type':null,
		'vpc_subnet_href':null,
		'ec2_security_groups_href':[ec2_security_group_12345
			],
		'ec2_availability_zone':'us-east-1b',
		'ari_image_href':null,
		'nickname':'MyServer',
		'cloud_id':'1'
		}
		);

set_ec2_server_parameter

Defines input parameters at the Server level.  The first argument is the href to the deployment.  The second argument is a hash with the key's parameters.  See Understanding Inputs.

Example

set_ec2_server_parameter(server_href,
		{
		'parameters':
		{
                'MON_PROCESSES':'ignore:$ignore',                'CUSTOM_INPUT':'text:custom value',
		'GIT_PRIVATE_KEY':'cred:gitkey',
		'DBAPPLICATION_USER':'text:my_username',
		'CONFIG_FILE':'text:http://svn.mysite.com/app/1.0/',
		'SLAVE_DB_DNSNAME':'cred:DBREPLICATION_USER',
		'MASTER_DB_DNSNAME':'cred:DNSMADEEASY_USER',
		'DBAPPLICATION_PASSWORD':'text:my_password' 
		}
		}
		);

create_alert

Create and attach an alert specification.  You can attach an alert specification to either a Server or ServerTemplate.

Example

alert_1 = create_alert(
                {
                'duration':'1',
                'subject_href':server_1233456,
                'threshold':'pending',
                'variable':'state',
                'file':'RS/server',
                'description':'monitoring server state',
                'condition':'>',
                'name':'alert name',
                'subject_type':'Server',
                'escalation_name':'default'
                }
                );

create_server_array

Create an alert-based or queue-based server array.  'pr_create' option is supported.  See 'pr_create' vs 'create'.

Example: Alert-based

server_array_1234 = create_server_array(
		{
		'tags':[
			],
		'indicator_href':null,
		'server_template_href':'https://my.rightscale.com/api/acct/1/ec2_server_templates/12345',
		'deployment_href':'https://my.rightscale.com/api/acct/1/deployments/23456',
		'elasticity_function':null,
		'array_type':'alert',
		'active':'false',
		'nickname':'My Alert-based Server Array',
		'cloud_id':'1',
		'elasticity':
		{
		'max_count':'20',
		'resize_down_by':'1',
		'min_count':'1',
		'resize_up_by':'1',
		'resize_calm_time':'5',
		'decision_threshold':'51'
		},
		'elasticity_params':
		{
                },

'ec2_security_groups_href':[ec2_security_group_10101], 'ec2_ssh_key_href':ec2_ssh_key_20202, 'audit_queue_href':null, 'description':null } );

Example: Queue-based

server_array_5511 = create_server_array(
		{
		'tags':[
			],
		'elasticity':
		{
		'max_count':'20',
		'resize_down_by':null,
		'min_count':'1',
		'resize_up_by':null,
		'resize_calm_time':'5',
		'decision_threshold':'51'
		},
		'elasticity_function':'sqs_queue_size',
		'ec2_ssh_key_href':ec2_ssh_key_10101,
		'deployment_href':'https://my.rightscale.com/api/acct/1/deployments/12345',
		'audit_queue_href':queue_22222,
		'indicator_href':queue_33333,
		'ec2_security_groups_href':[ec2_security_group_44444],
		'server_template_href':'https://my.rightscale.com/api/acct/1/ec2_server_templates/23456',
		'active':'false',
		'nickname':'My Queue-based Server Array',
		'cloud_id':'1',
		'elasticity_params':
		{
		'items_per_instance':'5'
		},
		'array_type':'queue',
		'description':null
		}
		);

append_status_panel(msg)

create_ec2_security_group

Create an EC2 Security Group.  'pr_create' option is supported.  See 'pr_create' vs 'create'.  

Note: In order to create a new EC2 Security Group you must provide at least one ingress rule.

Example

ec2_security_group_12345 = create_ec2_security_group(
		{
		'aws_group_name':'defaultvalue'
                'aws_description':'Security Group for MyCompany',
		'cloud_id':'1'
		}
		);

add_ingress_rule

Defines the access permissions of an EC2 Security Group.  The first argument is the href to the security group.  The second argument is a hash with the key's parameters. 

Example

add_ingress_rule(ec2_security_group_12345,
		{
		'owner':'123412341234',
		'group':'default'
		}
		);

add_ingress_rule(ec2_security_group_12345,
		{
		'protocol':'tcp',
		'cidr_ips':'0.0.0.0/0',
		'from_port':'22',
		'to_port':'22'
		}
		);
add_ingress_rule(ec2_security_group_12345,
		{
		'protocol':'tcp',
		'cidr_ips':'0.0.0.0/0',
		'from_port':'80',
		'to_port':'80'
		}
		);

create_ec2_ssh_key

User will be prompted to specify an 'aws_key_name' when creating the SSH Key.  'pr_create' option is supported.  See 'pr_create' vs 'create'.

Example

ec2_ssh_key_1234 = create_ec2_ssh_key(
		{
		'aws_key_name':'defaultvalue'
                'cloud_id':'1'
                }
		);

create_ec2_elastic_ip

User will NOT be prompted to specify a nickname when creating the Elastic IP.  'pr_create' option is supported.  See 'pr_create' vs 'create'.

Example

ec2_elastic_ip_12345 = create_ec2_elastic_ip(
		{
                'nickname':'MyElasticIP',
                'cloud_id':'3'
		}
		);

create_ec2_ebs_volume

Create an EBS Volume.

Example

ec2_ebs_volume_12345 = create_ec2_ebs_volume(
		{
                'nickname':'MyVolume',
                'description':'Some marcom data',
		'cloud_id':'1',
                'ec2_availability_zone':'us-east-1a',
		'aws_size':'1'
		}
		);

attach_ec2_ebs_volume

Attach an EBS Volume to a server.

Example

attach_ec2_ebs_volume(
		{
		'mount':'boot',
		'ec2_ebs_volume_href':ec2_ebs_volume_1234,
		'component_href':server_111222,
		'device':'/dev/sdj'
		}
		);

start_server

Launch a server.

Example

start_server(server_href);

stop_server

Terminate a server.

Example

stop_server(server_href);

create_queue

Create an SQS Queue.  'pr_create' option is supported.  See 'pr_create' vs 'create'.

Example

queue_12345 = create_queue(
		{
		'name':'RightGrid_Demo_App_Input_123451234512345',
		'description':null,
		'visibility_timeout':'30',
		'api_generation':'2'
		}
		);

create_bucket

Create an S3 bucket.  'pr_create' option is supported.  See 'pr_create' vs 'create'.

Example

bucket_12345 = create_bucket(
		{
		'name':'mybuck',
                'cloud_id':1
		}
		);