right_st is a tool for managing RightScale ServerTemplate and RightScripts. The tool is able to download, upload, and show ServerTemplate and RightScripts using RightScale's API. This tool can easily be hooked into Travis CI or other build systems to manage these design objects if stored in Github. See below for usage examples.
- Managing RightScripts
- Managing ServerTemplates
right_st is written in Go it is compiled to a single static binary. Extract and run the executable below:
- Linux: v1/right_st-linux-amd64.tgz
- Mac OS X: v1/right_st-darwin-amd64.tgz
- Windows: v1/right_st-windows-amd64.zip
Right ST interfaces with the RightScale API. Credentials for the API can be provided in two ways:
- YAML-based configuration file - Run
right_st config account <name>, where name is a nickname for the account, to interactively write the configuration file into
$HOME/.right_st.ymlfor the first time. You will be prompted for the following fields:
- Account ID - Numeric account number, such as
- API endpoint host - Hostname, typically
- Refresh Token - Your personal OAuth token available from Settings > Account Settings > API Credentials in the RightScale Cloud Management dashboard
- Account ID - Numeric account number, such as
- Environment variables - These are meant to be used by build systems such as Travis CI. The following vars must be set:
RIGHT_ST_LOGIN_ACCOUNT_REFRESH_TOKEN. These variables are equivalent to the ones described in the YAML section above.
RightScripts consist of a script body, attachments, and metadata. Metadata is embedded in the script as a comment between the hashbang and script body in the RightScript Metadata Comments format. This allows a single script file to be a fully self-contained respresentation of a RightScript. Metadata comment format is as follows:
|RightScript Name||String||Name of RightScript. Name must be unique for your account.|
|Description||String||Description field for the RightScript. Free form text which can be Markdown|
|Inputs||Hash of String -> Input||The hash key is the input name. The hash value is an Input definition (defined below)|
|Attachments||Array of Strings||Each string is a filename of an attachment file. Relative or absolute paths supported. Relative paths will be placed in an "attachments/" subdirectory. For example "1/foo" will expect a file foo at "attachments/1/foo"|
Input definition format is as follows:
|Category||String||Category to group Input under|
|Description||String||Description field for the Input|
|Default||String||Default value. Value must be in Inputs 2.0 format from RightScale API which consists of a type followed by a colon then the value. I.e. "text:Foo", "ignore", "env:ENV_VAR"|
|Possible Values||Array of Strings||If supplied, a drop down list of values will be supplied in the UI for this input. Each string must be a text type in Inputs 2.0 format.|
Example RightScript is as follows. This RightScript has one attachment, which must be located at "attachments/foo" relative to the script.
#! /bin/bash -e # --- # RightScript Name: Run Foo Tool # Description: Runs attached foo executable with input # Inputs: # FOO_PARAM: # Category: RightScale # Description: A parameter to the foo tool # Input Type: single # Required: false # Advanced: true # Default: "text:foo1" # Possible Values: ["text:foo1", "text:foo2"] # Attachments: # - foo # ... # cp -f $RS_ATTACH_DIR/foo /usr/local/bin/foo chmod a+x /usr/local/bin/foo foo $FOO_PARAM
The following RightScript related commands are supported:
right_st rightscript show <name|href|id> Show a single RightScript and its attachments. right_st rightscript upload [<flags>] <path>... Upload a RightScript Flags: -f, --force: Force upload of RightScript despite lack of Metadata comments -x, --prefix <prefix>: Create dev/test version by adding prefix to name of all RightScripts uploaded right_st rightscript delete <path>... Delete dev/test RightScripts with a prefix. Flags: -x, --prefix <prefix>: Delete rightscripts specified in file with a prefix. This command acts to cleanup scripts created with upload --prefix. right_st rightscript download <name|href|id> [<path>] Download a RightScript to a file. Metadata comments will automatically be inserted into RightScripts that don't have it. right_st rightscript scaffold [<flags>] <path>... Add RightScript YAML metadata comments to a file or files Flags: -f, --force: Force regeneration of scaffold data. right_st rightscript validate <path>... Validate RightScript YAML metadata comments in a file or files
ServerTemplates are defined by a YAML format representing the ServerTemplate. The following keys are supported:
|Name||String||Name of the ServerTemplate. Name must be unique for your account.|
|Description||String||Description field for the ServerTemplate.|
|RightScripts||Hash of String -> Array of RightScripts||The hash key is the sequence type, one of "Boot", "Operational", or "Decommission". The hash value is a array of RightScripts. Each RightScript can be specified in one of three ways, as a 1. "local" managed 2. "published", or 3. "external" RightScript. A locally managed RightScript is specified as a pathname to a file on disk and the file contents are synchonized to the HEAD revision of a RightScript in your local account. Published RightScripts are links to pre-existing RightScripts shared in the MultiCloud marketplace and consist of a hash specifying a Name/Revision/Publisher to look up. External RightScripts are pre-existing RightScripts consisting of a Name/Revision pair and will not search the MultiCloud marketplace.|
|Inputs||Hash of String -> String||The hash key is the input name. The hash value is the default value. Note this inputs array is much simpler than the Input definition in RightScripts - only default values can be overridden in a ServerTemplate.|
|MultiCloudImages||Array of MultiCloudImages||An array of MultiCloudImage definitions and/or MultiCloudImage YAML file references. A MultiCloudImage definition is a hash of fields taking a few different formats. See section below for further details.|
|Alerts||Array of Alerts||An array of Alert definitions and/or Alert YAML file references, defined below.|
A MultiCloudImage definition allows you to specify an MCI in four different ways by supplying different hash keys. The first three combinations specified below allow you to use pre-existing MCIs. The fourth one allows you to fully manage an MCI in your local account:
- 'Name' and 'Revision' and 'Publisher': Name/Revision/Publisher of MCI available in the MultiCloud Marketplace. The MCI will be automatically imported into the account if it's not already there. Preferred. "latest" may be specified for the revision to get the latest revision.
- 'Name' and 'Revision'.: Name/Revision of MCI in your local account. It will not attempt to be autoimported from the MultiCloud Marketplace. "latest" or "head" may be specified to get the latest committed revision and "head" revision respectively.
- 'Href': Href of the MCI in the account being uploaded. This is a fallback in case 1 or 2 doesn't work.
- Fully specified. The following keys are supported:
- 'Name' - String - Name of the MCI
- 'Tags' - Array of Strings - Representing tags on the MCI. Typically 'rs_agent:type=right_link_lite' will be required.
- 'Description' - String - Optional description for the MCI
- 'Settings' - Array of Settings - A setting represents the following API resource: MultiCloudImageSettings. The following keys are used:
Cloud- String - Required - Name of cloud
Image- String - Required - resource_uid of image
Instance Type- String - Required - Name of instance type.
User Data- String - Optional - User Data template for this cloud/image combination.
A MultiCloudImage YAML file is referenced as a normal string in the MultiCloudImages array which is the realtaive path to a YAML file containing an individual MultiCloudImage definition.
An Alert definition consists of three fields: a Name, Definition, and Clause (all strings). Clause is a text description of the Alert with this exact format:
If <Metric>.<ValueType> <ComparisonOperator> <Threshold> for <Duration> minutes Then <Action> <ActionValue>:
- Metric is a collectd metric name such as
- ValueType is the metric type (
count, etc - allowable values differ for each metric so look in the dashboard!).
- ComparisonOperator is
- Threshold is a numeric value such as
NaNfor all Metrics except for the RS/* ones. For the RS/* ones its a one of the following server states:
- Duration is minutes and must be an integer greater than 0.
- Action is either "escalate" in which case the ActionValue is the name of the escalation. Or Action is "grow" or "shrink" in which case ActionValue is the custom tag value to use as the voting tag.
An Alert YAML file is referenced as a normal string in the Alerts array which is the relative path to a YAML file containing just the Alerts field with the same format as in the ServerTemplate YAML file.
Here is an example ServerTemplate YAML file:
Name: My ServerTemplate Description: This is an example Description Inputs: FIRST_INPUT: "text:overriding value" SECOND_INPUT: "env:RS_UUID" RightScripts: Boot: # Format 3: Name/Revision/Publisher: This specifies a RightScript from the Marketplace - Name: RL10 Linux Setup Hostname Revision: 6 Publisher: RightScale # Format 3: Name/Revision/Publisher: This specifies a RightScript from the Marketplace, latest revision - Name: RL10 Enable Monitoring Revision: latest Publisher: RightScale # Format 2: Name/Revision: A RightScript in your local account - Name: My Local RightScript Revision: 3 # Format 1: Locally managed scripts on disk, synced to RightScripts in your local account - path/to/script1.sh - path/to/script2.sh Operational: - path/to/script1.sh Decommission: - path/to/decom_script1.sh MultiCloudImages: # Format 1: Name/Revision/Publisher pair: This specifies a MCI from the Marketplace - Name: Ubuntu_12.04_x64 Revision: 18 Publisher: RightScale # Format 1 again: Name/Revision/Publisher pair: This specifies a latest MCI from the Marketplace - Name: Ubuntu_14.04_x64 Revision: latest Publisher: RightScale # Format 2: Name/Revision pair: This specifies a account-specific MCI, such as one cloned from a Marketplace MCI - Name: Ubuntu_14.04_x64_cloned Revision: 20 # Format 3: Href to an account-specific MCI - Href: /api/multi_cloud_images/403042003 # Format 4: Fully Managed MCI object specifying all clouds/images: - Name: MyUbuntu_14.04_x64 Description: My companies custom MCI Tags: - rs_agent:type=right_link_lite - rs_agent:mime_shellscript=https://rightlink.rightscale.com/rll/10/rightlink.boot.sh Settings: - Cloud: EC2 us-east-1 Instance Type: m3.medium Image: ami-5e91b936 - Cloud: EC2 eu-west-1 Instance Type: m3.medium Image: ami-b1841cc6 # MultiCloudImage file reference - ubuntu-1604-x64.yml Alerts: # Alert definition - Name: CPU Scale Down Description: Votes to shrink ServerArray by setting tag rs_vote:my_app_name=shrink Clause: If cpu-0/cpu-idle.value > '50' for 3 minutes Then shrink my_app_name # Alerts file reference - common-alerts.yml
Here is an example MultiCloudImage YAML file:
Name: Ubuntu 16.04 x64 Tags: - rs_agent:type=right_link_lite - rs_agent:mime_shellscript=https://rightlink.rightscale.com/rll/10/rightlink.boot.sh Settings: - Cloud: EC2 us-west-2 Instance Type: m3.medium Image: ami-45224425
Here is an example Alerts YAML file:
Alerts: - Name: Low memory warning Description: Runs escalation named "warning" if free memory drops to < 100MB Clause: If memory/memory-free.value < 100000000 for 5 minutes Then escalate warning
The following ServerTemplate related commands are supported:
right_st st show <name|href|id> Show a single ServerTemplate right_st st upload <path>... Upload a ServerTemplate specified by a YAML document Flags: -x, --prefix <prefix>: Create dev/test version by adding prefix to name of all RightScripts uploaded right_st st delete <path>... Delete dev/test ServerTemplates and RightScripts with a prefix Flags: -x, --prefix <prefix>: Delete with this prefix. This commands acts as a cleanup for ServerTepmlates uploaded with --prefix. right_st st download <name|href|id> [<path>] Download a ServerTemplate and all associated RightScripts/Attachments to disk Flags: -p, --published: When downloading RightScripts, first check if it's published in the MultiCloud marketplace and insert a link to the published script if so. -m, --mci-settings: When specifying MultiCloudImages, use Format 4. This fully specifies all cloud/image/instance type settings combinations to completely manage the MultiCloudImage in the YAML. -s, --script-path <script-path>: Download RightScripts and their attachments to a subdirectory relative to the download location. right_st st validate <path>... Validate a ServerTemplate YAML document
right_st source code is subject to the MIT license, see the