right_st

right_st

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.

• Installation
  • Configuration
• Managing RightScripts
  • RightScript Usage
• Managing ServerTemplates
  • ServerTemplate Usage
• Contributors
• License

Installation

Since 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

Configuration

Right ST interfaces with the RightScale API. Credentials for the API can be provided in two ways:

1. 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.yml for the first time. You will be prompted for the following fields:
   • Account ID - Numeric account number, such as 60073
   • API endpoint host - Hostname, typically my.rightscale.com
   • Refresh Token - Your personal OAuth token available from Settings > Account Settings > Refresh Token in the RightScale Cloud Management dashboard
2. 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_ID, RIGHT_ST_LOGIN_ACCOUNT_HOST, RIGHT_ST_LOGIN_ACCOUNT_REFRESH_TOKEN. These variables are equivalent to the ones described in the YAML section above.

Managing RightScripts

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:

Input definition format is as follows:

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

RightScript Usage

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: Append a prefix to RightScript's name when uploading. For 
                  creating dev/test versions of scripts.

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

Managing ServerTemplates

ServerTemplates are defined by a YAML format representing the ServerTemplate. The following keys are supported:

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:

1. '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.
2. 'Name' and 'Revision'.: Name/Revision of MCI in your local account. It will not attempt to be autoimported from the MultiCloud Marketplace.
3. 'Href': Href of the MCI in the account being uploaded. This is a fallback in case 1 or 2 doesn't work.
4. 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.

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 cpu-0/cpu-idle.
• ValueType is the metric type (value, count, etc - allowable values differ for each metric so look in the dashboard!).
• ComparisonOperator is >, >=, <, <=, ==, or !=
• Threshold is a numeric value such as 100 or 0.5 or NaN for all Metrics except for the RS/* ones. For the RS/* ones its a one of the following server states: pending, booting, operational, decommission, shutting-down, terminated
• 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.

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:
  - Name: RL10 Linux Setup Hostname
    Revision: 6
    Publisher: RightScale
  - 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 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
Alerts:
- 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
- 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

ServerTemplate Usage

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: Append a prefix to ServerTemplate and RightScript names when
                  uploading. For creating dev/test versions of ServerTemplates.

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

Contributors

This tool is maintained by Douglas Thrift (douglaswth), Peter Schroeter (psschroeter), and Lopaka Delp (lopaka).

License

The right_st source code is subject to the MIT license, see the LICENSE file.