To create a basic RightScript, layer on complexity using Inputs, and then develop more advanced RightScripts touching on most of the features used within the Dashboard. Several best practices are also covered along the way.
Table of Contents
An operational Linux based Server and basic understanding of bash scripting. The examples in this tutorial use the Unix shell (bash), but you could develop similar scripts in a different scripting language. (For example, Perl, Ruby, or a different shell such as Bourne, csh or ksh.)
The focus of this tutorial is understanding and developing RightScripts, not Chef Cookbooks. Although many of our ServerTemplates come with fully functioning RightScripts (that we encourage using "as is"), we realize the need for customization or even writing your own from scratch. If you can work through this tutorial from end to end, you will have a solid foundation for developing your own RightScripts.
#!/bin/bash -ex echo "Hello World!" exit 0 # Graceful exit
You now have the most basic of RightScripts. This RightScript can be added to a ServerTemplate and run in any one of the three phases (boot, operational or decommission). More on this later...
Recall that Inputs are environment variables in all CAPS that are parsed out of RightScripts. Before adding one, test the Identify action button.
There are no environment variables in the script.
echo "Nice to be here, my name is $FIRSTNAME"
This example uses AWS EC2 Input values.
echo "Instance Size: $EC2_INSTANCE_TYPE" echo "Public IP addr: $EC2_PUBLIC_IPV4"
******************************************************************************** *RS> Running RightScript <GD: Hello World> **** *RS> script starting at: Mon May 10 19:59:45 -0400 2010 + echo 'Hello World!' Hello World! + echo 'Nice to be here, my name is GregDoe' Nice to be here, my name is GregDoe + echo 'Instance Size: m1.small' Instance Size: m1.small + echo 'Public IP addr: 188.8.131.52' Public IP addr: 184.108.40.206 + exit 0 *RS> script duration: 0.005064 seconds
echo "RightScale Server Name: $RS_SERVER_NAME"
Again, you would have seen a "null" value for RS_SERVER_NAME unless it was evaluated as part of a RightScript, which is accomplished by mapping a standard Input to an RightScale environment Input. The same behavior holds true for RS_DEPLOYMENT_NAME and RS_SERVER_TEMPLATE_NAME as well.
In this part of the tutorial you will develop a more practical RightScript that checks port status, using various types of Inputs. You will also learn more about RightScript descriptions (which support Markdown) and Input descriptions.
Note: This section of the tutorial is less verbose, unless covering a new step that merits additional explanation. Refer to the Basic RightScript section if you forget any step details.
Tip: Until now, we have developed the RightScript within the RightScale Dashboard. Those familiar with a Unix editor such as vi may want to develop RightScripts by SSHing into the instance and working through the development process there. (Or SSH into the instance and use that in concert with development straight in the Dashboard.) Use what process works best for you, but be careful not to get confused if you let your RightScripts get out of sync with each other (instance version versus the Dashboard version). Important! If you do any development on the instance itself (for example, creating and working in /tmp/test.sh) if you terminate the instance your work will be lost. Make sure you save anything you need by transferring the file elsewhere, or copy/pasting into a RightScript within the Dashboard.
#!/bin/bash -ex echo "" lsof -P -i | grep -i "$STATE" echo "Done (port state)." exit 0
Recall that Credentials are essentially secure key/value pairs stored within the RightScale Dashboard (database).
Now you will create a new Credential in the RightScale Credential store, and verify against that credential before the core of your port checker RightScript is executed.
#!/bin/bash -ex echo "" if [ "$MYCREDS" = "GregDoe" ] then echo "Credentials validated. Port states are:" lsof -P -i | grep -i "$STATE" echo "Done (port state)." exit 0 # Graceful exit fi echo ">>> Credential AUTHORIZATION FAILED! <<<" exit 1 # Ungraceful exit, Credential check failed
Note: If the Credential check fails the RightScript will exit. If it passes, the port status is displayed.
First, lets simply add the port logic and hard code the port number to check for. Once satisfied, we'll create a configuration file, attach it to our script so it gets its port value from an external file when the script runs.
lsof -P -i | grep $PORT echo "Done (port connection status)."
Assuming all has gone well, you are now ready to include the port number to check connection status on as a value in a RightScript Attachment.
port=$(<"$ATTACH_DIR"/port.conf) echo Port "$port" connection status: lsof -P -i | grep :"$port" | grep -i "$STATE"
This will assign the value "22" from your attached port.conf file to the variable "port", and parse out any and all occurrences of ":22" in the output of your lsof command.
Important! Notice that the first part of this section uses $PORT in your RightScript. Later, that is replaced with $port, which is read in from an external file attachment. RightScript Input naming conventions mandate Inputs be in all CAPS. Hence $PORT is an Input and you will be prompted for a value when you run the RightScript. Later, when reading the value for "port" from the port.conf file, you will not be prompted for a value. "port" is simply a variable in your RightScript, that is populated from an external file, not an actual RightScript Input.
This may not be the most helpful RightScript ever written, but layer upon layer it touches most of the main points you must learn in order to develop RightScripts, work with various types of Inputs, Credentials and Attachments. Of course the example configuration file was as basic as it could be, but it could have been a more complex configuration file, or perhaps an Apache httpd.conf file that you run sed against in order to change a default configuration setting, etc. Read the Post Tutorial Steps for a list of additional tasks you may want to perform in order to continue your learning curve.
The focus of this tutorial was to touch on many areas with respect to developing RightScripts and learning more about how they work. Once you have finished active development, there are several post tutorial steps that are considered best practice.
RightScripts that we publish in theare considered "reboot safe". Towards the top of the script they contain a code block similar to the one shown below. To understand why this is important, note that if you reboot a Server and an installation/configuration script runs again, you can end up with undesired results. In most cases, you will want to make your scripts reboot safe. (Note: Under most circumstances we consider it best practice to relaunch Servers rather than reboot them. In this instance, being reboot safe is moot.)
# # Test for a reboot, if this is a reboot just skip this script. # if test "$RS_REBOOT" = "true" ; then echo "Skip HTTPERF installation on REBOOT." logger -t RightScale "Skip HTTPERF installation on REBOOT." exit 0 # Leave with a smile ... fi
As a best practice, in addition to any in-line documentation, you should document the RightScript and any Inputs as well. Note that markdown is supported, and is encourged to make your RightScript description more readable.
Click here to see a good cheat sheet for common markdown syntax.
**Purpose** - Uses standard Unix utility lsof (list system open files) to check port state and connection status based on several supplied Inputs: * **MYCREDS** - If **MYCREDS** is not validated, then exit gracefully with a no-op. * **STATE** - User supplied standard Input to check all port **states** against. * **port** - Specific **port** to check status on. _Note:_ **port** is a variable (not Input) supplied from within the attached configuration file.
*Note: If you have a finite set of options for legal values, you can make the Input Value Type "drop-down" not "any". Then fill out all legal values for the Input.
The next time you run your RightScript, when filling out the missing Inputs, notice your Input description will be displayed when your mouse hovers over the blue information icon. (This is sometimes referred to as "hover text"). For example:
Once your debugging efforts are complete, you may want to turn off the scripts verbosity. This trims up what is saved in your Audit Entries. Change the preamble so it does not contain the "-x" option to bash. For example:
Note: The "-e" command line option to bash causes an exit if something goes wrong in a RightScript. This is generally considered a best practice, particularly with boot phase RightScripts. When a Server boots up and runs various installation and configuration RightScripts, if one fails miserably, it is best to exit than continue attempting to install other packages, modify configuration files, etc. You do have the option to force an non-operational Server to be Operational, and attempt to debug the boot phase RightScripts manually/iteratively.
Name your RightScript something descriptive. For example, "Acme Co - Port State Checker" is better than simply "Port State".
In this tutorial we developed several RightScripts from scratch. Although RightScripts can be used in "stand-alone" fasion, they are usually created to work within a ServerTemplate. Normally, you would add the RightScript to a ServerTemplate that is used to configure a Server or Servers in a Deployment, etc.
Commit your RightScript. ServerTemplates and the RightScripts in them should be commited. Working on a HEAD revision is recommended only during development, and it is considered a best practice to use our version control capabilities. See the ServerTemplate Versioning section of our Lifecycle Management Guide for more information.
© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.